@hydranium/core 1.0.0-next.10

package/lib/lsp/start-language-server.js

@@ -0,0 +1,60 @@
+/********************************************************************************
+ * 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 } 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) {
+    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, serviceRequirements = {}) {
+    assertLspHeadComposed(services);
+    startLangiumLanguageServer(services, serviceRequirements);
+}
+//# sourceMappingURL=start-language-server.js.map

package/lib/lsp/start-language-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-language-server.js","sourceRoot":"","sources":["../../src/lsp/start-language-server.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,mBAAmB,IAAI,0BAA0B,EAGnD,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,8BAA8B,EAAE,MAAM,wCAAwC,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAA+B;IAClE,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC;QAC7B,OAAO;IACV,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACnD,IAAI,CAAC,CAAC,OAAO,YAAY,8BAA8B,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACZ,oGAAoG;YACjG,IAAI,OAAO,EAAE,WAAW,EAAE,IAAI,IAAI,SAAS,uEAAuE;YAClH,kHAAkH;YAClH,kGAAkG;YAClG,4GAA4G;YAC5G,4CAA4C,CACjD,CAAC;IACL,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA+B,EAAE,sBAAoD,EAAE;IACxH,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAChC,0BAA0B,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;AAC7D,CAAC"}

package/lib/node/ast-ground-truth.d.ts

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * 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 ServerSharedServicesMinimal } from '../langium/shared-services.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 declare function collectAstGroundTruth(options: AstGroundTruthOptions): Promise<AstGroundTruth>;
+/**
+ * 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 declare function tallyAstGroundTruth(shared: ServerSharedServicesMinimal): AstGroundTruth;
+//# sourceMappingURL=ast-ground-truth.d.ts.map

package/lib/node/ast-ground-truth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-ground-truth.d.ts","sourceRoot":"","sources":["../../src/node/ast-ground-truth.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAGjF,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACnC;;;OAGG;IACH,cAAc,EAAE,MAAM;QAAE,MAAM,EAAE,2BAA2B,CAAA;KAAE,CAAC;IAC9D,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC5B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAInG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,2BAA2B,GAAG,cAAc,CAWvF"}

package/lib/node/ast-ground-truth.js

@@ -0,0 +1,46 @@
+/********************************************************************************
+ * 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 { buildWorkspaceProgrammatically } from '../langium/workspace/initialize-workspace.js';
+/**
+ * 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) {
+    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) {
+    const documents = shared.workspace.LangiumDocuments.all.toArray();
+    const byType = {};
+    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 };
+}
+//# sourceMappingURL=ast-ground-truth.js.map

package/lib/node/ast-ground-truth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-ground-truth.js","sourceRoot":"","sources":["../../src/node/ast-ground-truth.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AA6B9F;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAA8B;IACvE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAC5C,MAAM,8BAA8B,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAChE,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAmC;IACpE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAClE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACjE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACnD,aAAa,IAAI,CAAC,CAAC;QACtB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AACjE,CAAC"}

package/lib/node/event-loop-monitor.d.ts

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * 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 { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+export declare const DEFAULT_EVENT_LOOP_THRESHOLD_MS = 100;
+export declare const DEFAULT_EVENT_LOOP_INTERVAL_MS = 1000;
+export declare 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 declare function startEventLoopMonitor(shared: ServerSharedServicesMinimal, options?: EventLoopMonitorOptions): () => void;
+//# sourceMappingURL=event-loop-monitor.d.ts.map

package/lib/node/event-loop-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-loop-monitor.d.ts","sourceRoot":"","sources":["../../src/node/event-loop-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAGjF,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,eAAO,MAAM,8BAA8B,OAAO,CAAC;AACnD,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAExD,MAAM,WAAW,uBAAuB;IACrC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,2BAA2B,EAAE,OAAO,GAAE,uBAA4B,GAAG,MAAM,IAAI,CA2C5H"}

package/lib/node/event-loop-monitor.js

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * 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 { 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;
+/**
+ * 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, options = {}) {
+    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) => 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();
+    };
+}
+//# sourceMappingURL=event-loop-monitor.js.map

package/lib/node/event-loop-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-loop-monitor.js","sourceRoot":"","sources":["../../src/node/event-loop-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AACnD,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AACnD,MAAM,CAAC,MAAM,oCAAoC,GAAG,GAAG,CAAC;AAqBxD;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAmC,EAAE,UAAmC,EAAE;IAC7G,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,WAAW,CAAC,CAAC;IACjE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,+BAA+B,CAAC;IAC3E,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,8BAA8B,CAAC;IACxE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,oCAAoC,CAAC;IACxF,MAAM,eAAe,GAClB,OAAO,CAAC,eAAe;QACvB,CAAC,CAAC,KAAa,EAAE,EAAE,CAChB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAC9B,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,gBAAgB,EAAE,0BAA0B,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CACvG,CAAC,CAAC;IACT,MAAM,SAAS,GAAG,qBAAqB,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5D,SAAS,CAAC,MAAM,EAAE,CAAC;IACnB,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;QAC/B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,GAAG,GAAG,CAAC;QAClC,IAAI,KAAK,IAAI,WAAW,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;YAC7C,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,GAAG,GAAG,CAAC;YACpC,oFAAoF;YACpF,MAAM,CAAC,IAAI,CACR,0BAA0B,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK;gBAC7C,WAAW,UAAU,KAAK;gBAC1B,QAAQ,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM;gBAC/B,QAAQ,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;gBAC/B,GAAG,YAAY,EAAE,GAAG,CACzB,CAAC;YACF,IAAI,KAAK,IAAI,eAAe,EAAE,CAAC;gBAC5B,4EAA4E;gBAC5E,IAAI,CAAC;oBACF,eAAe,CAAC,KAAK,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACd,MAAM,CAAC,IAAI,CAAC,0BAA0B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACnG,CAAC;YACJ,CAAC;QACJ,CAAC;QACD,SAAS,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC,EAAE,UAAU,CAAC,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;IACnB,OAAO,GAAG,EAAE;QACT,aAAa,CAAC,QAAQ,CAAC,CAAC;QACxB,SAAS,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC,CAAC;AACL,CAAC"}

package/lib/node/index.d.ts

@@ -0,0 +1,29 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+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';
+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';
+//# sourceMappingURL=index.d.ts.map

package/lib/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAgBlF,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AAQxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC"}

package/lib/node/index.js

@@ -0,0 +1,50 @@
+/********************************************************************************
+ * 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();
+//# sourceMappingURL=index.js.map

package/lib/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,iFAAiF;AACjF,6EAA6E;AAC7E,iFAAiF;AACjF,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,mBAAmB;AACnB,iFAAiF;AACjF,iFAAiF;AACjF,8CAA8C;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAEvE,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AAExC,8EAA8E;AAC9E,+EAA+E;AAC/E,0EAA0E;AAC1E,sEAAsE;AACtE,6EAA6E;AAC7E,sCAAsC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AAExC,sBAAsB,EAAE,CAAC;AACzB,yBAAyB,EAAE,CAAC"}

package/lib/node/latency-from-env.d.ts

@@ -0,0 +1,32 @@
+/********************************************************************************
+ * 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 declare const DEFAULT_LATENCY_ENV = "HYDRANIUM_LATENCY";
+/** True when the latency env flag is set to a non-empty value. */
+export declare function isLatencyEnabled(): boolean;
+/**
+ * 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 declare function latencyFromEnv(clock?: Clock): LatencyCollector | undefined;
+//# sourceMappingURL=latency-from-env.d.ts.map

package/lib/node/latency-from-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency-from-env.d.ts","sourceRoot":"","sources":["../../src/node/latency-from-env.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD,kEAAkE;AAClE,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,gBAAgB,GAAG,SAAS,CAE1E"}

package/lib/node/latency-from-env.js

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * 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 { 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() {
+    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) {
+    return isLatencyEnabled() ? new LatencyCollector(clock) : undefined;
+}
+//# sourceMappingURL=latency-from-env.js.map

package/lib/node/latency-from-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency-from-env.js","sourceRoot":"","sources":["../../src/node/latency-from-env.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAc,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAEvD,kEAAkE;AAClE,MAAM,UAAU,gBAAgB;IAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IACzC,OAAO,gBAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC"}

package/lib/node/lint-grammar.d.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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 AstReflection } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { type ReflectableLanguageServices } from './reflect-grammar.js';
+/** The severity of a grammar-convention lint finding. */
+export type LintSeverity = 'error' | 'warning';
+/** One grammar-convention violation, flattened to a serialisable shape. */
+export interface LintFinding {
+    /** Stable rule id — a consumer may key on it, so it is part of the JSON contract. */
+    rule: string;
+    severity: LintSeverity;
+    message: string;
+    /** The language id the finding is scoped to, when language-specific. */
+    language?: string;
+    /** The AST node type the finding is about, when type-specific. */
+    type?: string;
+}
+/** Per-severity tally — drives the exit code and the summary line. */
+export interface LintCounts {
+    error: number;
+    warning: number;
+}
+/** The full result of a grammar-convention lint. */
+export interface GrammarLintResult {
+    /** Every violation found, in rule/discovery order. */
+    findings: LintFinding[];
+    counts: LintCounts;
+    /** How many distinct cross-reference target types were checked for nameability. */
+    checkedReferenceTargets: number;
+    /** The name properties the lint treated as satisfying the nameability convention. */
+    nameProperties: string[];
+}
+/** Options for {@link lintGrammar}. */
+export interface LintGrammarOptions {
+    /**
+     * 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;
+    };
+    /**
+     * Property names that satisfy the nameability convention. Defaults to the
+     * framework default `['name']`; a head whose grammar carries the identifier on
+     * a different property (e.g. `id`) passes its own set.
+     */
+    nameProperties?: readonly string[];
+}
+/**
+ * Lint a head's grammar against the framework's conventions. Pure over its inputs
+ * (the shared {@link AstReflection}, the per-language grammar services, and the
+ * configured name properties) so it unit-tests without booting a grammar;
+ * {@link lintGrammar} is the thin boot wrapper.
+ *
+ * Checks:
+ * - **`reference-target-unnameable`** — every concrete (leaf) type reachable as a
+ *   cross-reference target must carry a name property. Langium enforces that a
+ *   referenced type *exists*, but not that it is *nameable*; the framework's
+ *   name-based scoping can only resolve a reference to a named target, so an
+ *   unnameable concrete target means references to it silently never resolve. Only
+ *   leaves (no subtypes) are flagged — an abstract super type is not instantiated,
+ *   so its own name property is irrelevant, and flagging it would be a false positive.
+ * - **`no-entry-rule`** — a language whose grammar declares no entry parser rule
+ *   cannot parse. Langium enforces this at grammar-generation time; the lint
+ *   re-asserts it as a framework expectation for a completeness gate.
+ */
+export declare function collectGrammarLint(reflection: AstReflection, languages: readonly ReflectableLanguageServices[], nameProperties?: readonly string[]): GrammarLintResult;
+/**
+ * Headless grammar-convention lint — checks a head's grammar against the framework's
+ * expectations (nameable cross-reference targets, an entry rule), no workspace build
+ * required (the reflection and grammar are static once the head registers its
+ * language). Boots a head's Langium services in-process, then runs
+ * {@link collectGrammarLint}.
+ *
+ * Backs `hydranium-cli lint-grammar`, whose non-zero exit on errors makes it a CI
+ * gate. Like the other headless harnesses the only language-specific input is the
+ * service factory, so the framework code stays head-neutral.
+ */
+export declare function lintGrammar(options: LintGrammarOptions): GrammarLintResult;
+//# sourceMappingURL=lint-grammar.d.ts.map

package/lib/node/lint-grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-grammar.d.ts","sourceRoot":"","sources":["../../src/node/lint-grammar.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,aAAa,EAAc,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAExE,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IACzB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAClB;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAC/B,sDAAsD;IACtD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,mFAAmF;IACnF,uBAAuB,EAAE,MAAM,CAAC;IAChC,qFAAqF;IACrF,cAAc,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAChC;;;OAGG;IACH,cAAc,EAAE,MAAM;QAAE,MAAM,EAAE,2BAA2B,CAAA;KAAE,CAAC;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAuCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAC/B,UAAU,EAAE,aAAa,EACzB,SAAS,EAAE,SAAS,2BAA2B,EAAE,EACjD,cAAc,GAAE,SAAS,MAAM,EAA4B,GAC3D,iBAAiB,CAqDnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAG1E"}