@hydranium/core 1.0.0-next.10

package/lib/node/lint-grammar.js

@@ -0,0 +1,124 @@
+/********************************************************************************
+ * 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 { GrammarAST } from '@hydranium/langium';
+/** The framework's default name property (mirrors `NameProviderOptions.nameProperties`). */
+const DEFAULT_NAME_PROPERTIES = ['name'];
+/** Invert every type's `superTypes` into a direct-subtype adjacency map. */
+function directSubTypeMap(reflection) {
+    const map = new Map();
+    for (const name of reflection.getAllTypes()) {
+        for (const superType of reflection.getTypeMetaData(name).superTypes) {
+            const children = map.get(superType) ?? [];
+            children.push(name);
+            map.set(superType, children);
+        }
+    }
+    return map;
+}
+/** The transitive closure `{ root } ∪ subtypes(root)`, walked over `directSubTypes` (cycle-safe). */
+function typeClosure(root, directSubTypes) {
+    const seen = new Set();
+    const queue = [root];
+    while (queue.length) {
+        const current = queue.shift();
+        if (seen.has(current)) {
+            continue;
+        }
+        seen.add(current);
+        queue.push(...(directSubTypes.get(current) ?? []));
+    }
+    return [...seen];
+}
+/** True when `type` declares at least one of the configured name properties. */
+function isNameable(reflection, type, nameProperties) {
+    const properties = reflection.getTypeMetaData(type).properties;
+    return nameProperties.some(property => property in properties);
+}
+/**
+ * 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 function collectGrammarLint(reflection, languages, nameProperties = DEFAULT_NAME_PROPERTIES) {
+    const findings = [];
+    for (const services of languages) {
+        const hasEntryRule = services.Grammar.rules.some(rule => GrammarAST.isParserRule(rule) && rule.entry === true);
+        if (!hasEntryRule) {
+            findings.push({
+                rule: 'no-entry-rule',
+                severity: 'error',
+                message: `Grammar '${services.LanguageMetaData.languageId}' declares no entry parser rule.`,
+                language: services.LanguageMetaData.languageId
+            });
+        }
+    }
+    const directSubTypes = directSubTypeMap(reflection);
+    // Collect every distinct cross-reference target type across all properties.
+    const referenceTargets = new Set();
+    for (const type of reflection.getAllTypes()) {
+        for (const property of Object.values(reflection.getTypeMetaData(type).properties)) {
+            if (property.referenceType !== undefined) {
+                referenceTargets.add(property.referenceType);
+            }
+        }
+    }
+    // Flag every unnameable concrete leaf reachable from a reference target (deduped).
+    const unnameableLeaves = new Set();
+    for (const target of referenceTargets) {
+        for (const candidate of typeClosure(target, directSubTypes)) {
+            const isLeaf = (directSubTypes.get(candidate) ?? []).length === 0;
+            if (isLeaf && !isNameable(reflection, candidate, nameProperties)) {
+                unnameableLeaves.add(candidate);
+            }
+        }
+    }
+    for (const leaf of [...unnameableLeaves].sort((left, right) => left.localeCompare(right))) {
+        findings.push({
+            rule: 'reference-target-unnameable',
+            severity: 'error',
+            message: `Type '${leaf}' is a cross-reference target but carries no name property ` +
+                `(expected one of: ${nameProperties.join(', ')}); references to it cannot resolve.`,
+            type: leaf
+        });
+    }
+    const counts = { error: 0, warning: 0 };
+    for (const finding of findings) {
+        counts[finding.severity] += 1;
+    }
+    return { findings, counts, checkedReferenceTargets: referenceTargets.size, nameProperties: [...nameProperties] };
+}
+/**
+ * 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 function lintGrammar(options) {
+    const { shared } = options.createServices();
+    return collectGrammarLint(shared.AstReflection, shared.ServiceRegistry.all, options.nameProperties);
+}
+//# sourceMappingURL=lint-grammar.js.map

package/lib/node/lint-grammar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-grammar.js","sourceRoot":"","sources":["../../src/node/lint-grammar.ts"],"names":[],"mappings":"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"}

package/lib/node/log-file-sink.d.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * 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 LogFileSink } from '../langium/diagnostics/logger.js';
+/**
+ * `node:fs`-backed {@link LogFileSink}. Synchronous (`appendFileSync`) so log
+ * lines preserve emission order; all errors are swallowed because a failing
+ * log sink must never propagate.
+ */
+export declare const nodeLogFileSink: LogFileSink;
+/**
+ * Install the Node file-tee sink so a configured `HYDRANIUM_LOG_FILE` target
+ * is honoured. Idempotent. Called once at `@hydranium/core/node` load so any
+ * Node host that imports the entry gets the file-tee for free.
+ */
+export declare function installNodeLogFileSink(): void;
+//# sourceMappingURL=log-file-sink.d.ts.map

package/lib/node/log-file-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-file-sink.d.ts","sourceRoot":"","sources":["../../src/node/log-file-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,kCAAkC,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,WAe7B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/lib/node/log-file-sink.js

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * 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 { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { setLogFileSink } from '../langium/diagnostics/logger.js';
+/**
+ * `node:fs`-backed {@link LogFileSink}. Synchronous (`appendFileSync`) so log
+ * lines preserve emission order; all errors are swallowed because a failing
+ * log sink must never propagate.
+ */
+export const nodeLogFileSink = {
+    append(path, data) {
+        try {
+            appendFileSync(path, data);
+        }
+        catch {
+            // A failing log sink must not propagate.
+        }
+    },
+    ensureDir(path) {
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        catch {
+            // ignore — the write attempt will simply fail and be swallowed too.
+        }
+    }
+};
+/**
+ * Install the Node file-tee sink so a configured `HYDRANIUM_LOG_FILE` target
+ * is honoured. Idempotent. Called once at `@hydranium/core/node` load so any
+ * Node host that imports the entry gets the file-tee for free.
+ */
+export function installNodeLogFileSink() {
+    setLogFileSink(nodeLogFileSink);
+}
+//# sourceMappingURL=log-file-sink.js.map

package/lib/node/log-file-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-file-sink.js","sourceRoot":"","sources":["../../src/node/log-file-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAoB,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgB;IACzC,MAAM,CAAC,IAAY,EAAE,IAAY;QAC9B,IAAI,CAAC;YACF,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACN,yCAAyC;QAC5C,CAAC;IACJ,CAAC;IACD,SAAS,CAAC,IAAY;QACnB,IAAI,CAAC;YACF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACN,oEAAoE;QACvE,CAAC;IACJ,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IACnC,cAAc,CAAC,eAAe,CAAC,CAAC;AACnC,CAAC"}

package/lib/node/log-preamble-node.d.ts

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * 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 LogPreambleOptions } from '../langium/diagnostics/log-preamble.js';
+/**
+ * Node runtime / host lines for {@link LogPreambleOptions.systemInfoLines}.
+ * Pulls `node:os` / `node:v8` / `process` — server-only.
+ */
+export declare 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.
+ */
+export declare function nodeConventionLines(phaseDetailThresholdMs?: number): string[];
+/**
+ * Convenience bundle of the Node `logPreamble` sections — spread into
+ * the portable `logPreamble`'s options on a Node host:
+ * `logPreamble(logger, { productName, version, ...nodeLogPreambleSections() })`.
+ */
+export declare function nodeLogPreambleSections(phaseDetailThresholdMs?: number): Pick<LogPreambleOptions, 'systemInfoLines' | 'conventionLines'>;
+//# sourceMappingURL=log-preamble-node.d.ts.map

package/lib/node/log-preamble-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-preamble-node.d.ts","sourceRoot":"","sources":["../../src/node/log-preamble-node.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAYlF,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAQ9C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,sBAAsB,SAAK,GAAG,MAAM,EAAE,CAYzE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,sBAAsB,SAAK,GAAG,IAAI,CAAC,kBAAkB,EAAE,iBAAiB,GAAG,iBAAiB,CAAC,CAEpI"}

package/lib/node/log-preamble-node.js

@@ -0,0 +1,55 @@
+/********************************************************************************
+ * 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 { Format } from '@hydranium/protocol';
+import * as os from 'node:os';
+import * as v8 from 'node:v8';
+import { DEFAULT_EVENT_LOOP_INTERVAL_MS, DEFAULT_EVENT_LOOP_SNAPSHOT_ABOVE_MS, DEFAULT_EVENT_LOOP_THRESHOLD_MS } 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';
+/**
+ * Node runtime / host lines for {@link LogPreambleOptions.systemInfoLines}.
+ * Pulls `node:os` / `node:v8` / `process` — server-only.
+ */
+export function nodeSystemInfoLines() {
+    return [
+        `node        ${process.version}`,
+        `platform    ${process.platform} ${process.arch}`,
+        `pid         ${process.pid}`,
+        `heap limit  ${Format.bytes(v8.getHeapStatistics().heap_size_limit)}`,
+        `host        ${os.hostname()}`
+    ];
+}
+/**
+ * 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.
+ */
+export function nodeConventionLines(phaseDetailThresholdMs = 50) {
+    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);
+    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`
+    ];
+}
+/**
+ * Convenience bundle of the Node `logPreamble` sections — spread into
+ * the portable `logPreamble`'s options on a Node host:
+ * `logPreamble(logger, { productName, version, ...nodeLogPreambleSections() })`.
+ */
+export function nodeLogPreambleSections(phaseDetailThresholdMs = 50) {
+    return { systemInfoLines: nodeSystemInfoLines(), conventionLines: nodeConventionLines(phaseDetailThresholdMs) };
+}
+//# sourceMappingURL=log-preamble-node.js.map

package/lib/node/log-preamble-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-preamble-node.js","sourceRoot":"","sources":["../../src/node/log-preamble-node.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EACJ,8BAA8B,EAC9B,oCAAoC,EACpC,+BAA+B,EACjC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,iCAAiC,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAGvG;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IAChC,OAAO;QACJ,eAAe,OAAO,CAAC,OAAO,EAAE;QAChC,eAAe,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE;QACjD,eAAe,OAAO,CAAC,GAAG,EAAE;QAC5B,eAAe,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,eAAe,CAAC,EAAE;QACrE,eAAe,EAAE,CAAC,QAAQ,EAAE,EAAE;KAChC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,sBAAsB,GAAG,EAAE;IAC5D,MAAM,aAAa,GAAG,kBAAkB,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACzD,MAAM,eAAe,GAAG,8BAA8B,GAAG,IAAI,CAAC;IAC9D,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,6BAA6B,GAAG,GAAG,CAAC,CAAC;IACpE,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,iCAAiC,GAAG,GAAG,CAAC,CAAC;IAC5E,OAAO;QACJ,uEAAuE,aAAa,oBAAoB;QACxG,mDAAmD,sBAAsB,sCAAsC;QAC/G,0CAA0C,+BAA+B,2BAA2B,eAAe,WAAW;QAC9H,8BAA8B,oCAAoC,mDAAmD;QACrH,6BAA6B,WAAW,qCAAqC,eAAe,qBAAqB;KACnH,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,sBAAsB,GAAG,EAAE;IAChE,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,EAAE,eAAe,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,EAAE,CAAC;AACnH,CAAC"}

package/lib/node/measure-memory.d.ts

@@ -0,0 +1,86 @@
+/********************************************************************************
+ * 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';
+import { type ProfileCaptureOptions } from './profile-capture.js';
+/** Options for {@link measureModelMemory}. */
+export interface MeasureModelMemoryOptions {
+    /**
+     * Create the language's shared services in-process. Invoked AFTER the empty
+     * baseline so the delta to after-build is exactly what parsing/building the
+     * workspace adds. 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;
+    /** Re-run `DocumentBuilder.update` this many times to probe for retention (default 0 = skip). */
+    editCycles?: number;
+    /** Documents to churn per cycle (default 25). */
+    editDocs?: number;
+    /** Only churn documents whose URI path ends with this suffix (default: any document). */
+    churnDocSuffix?: string;
+    /**
+     * Wait this many milliseconds after the build before the after-build reading
+     * (default 0 = no wait). Needed to measure timer-driven residency policies
+     * (e.g. `CstResidencyService`'s
+     * `shed-closed-when-idle`): shedding fires on a `Clock` timer *after* the build
+     * returns, so without a settle the reading is taken before any CST is shed.
+     * Pass a value comfortably above the policy's `idleMs`.
+     */
+    settleMs?: number;
+    /** Write a `.heapsnapshot` after the build (default false). */
+    writeSnapshot?: boolean;
+    /** Snapshot path (default `<cwd>/<workspace-basename>.heapsnapshot`). */
+    snapshotPath?: string;
+    /**
+     * Capture sampled profiles around the build and (when `editCycles > 0`) the
+     * churn, writing a full profiling session (manifest + digests) via
+     * {@link ProfilingRun}. Off unless set. The two windows are the multiplier:
+     * the churn allocation profile isolates what a *rebuild* re-allocates, which a
+     * one-shot capture cannot.
+     */
+    profile?: ProfileCaptureOptions;
+    /** Parent directory for the profiling session folder (default: OS temp dir). Only used with {@link profile}. */
+    sessionOut?: string;
+    /** Progress-line sink (default: no output — the result object carries the numbers). */
+    log?: (line: string) => void;
+}
+/** Structured result of {@link measureModelMemory}. */
+export interface MeasureModelMemoryResult {
+    documentCount: number;
+    buildMs: number;
+    emptyHeapBytes: number;
+    afterBuildHeapBytes: number;
+    /** Heap growth across the rebuild-churn cycles; present only when `editCycles > 0`. */
+    churnGrowthBytes?: number;
+    /** Absolute path of the written heap snapshot; present only when `writeSnapshot`. */
+    snapshotPath?: string;
+    /** Absolute path of the profiling session directory (manifest + digests); present only when `profile` was set. */
+    profilingSession?: string;
+}
+/**
+ * Headless model-store memory measurement — the browser-/socket-free counterpart
+ * to the in-app "dump server state" command. Boots a head's Langium services
+ * in-process via {@link MeasureModelMemoryOptions.createServices}, builds a
+ * workspace, and reports the model-store memory across scenarios:
+ *   - empty baseline   : services created, no documents loaded.
+ *   - after build      : parse + link + validate + index of the whole workspace.
+ *   - rebuild churn     : re-run `DocumentBuilder.update` on unchanged content N
+ *                        times; any monotonic growth is retention (a leak), not
+ *                        new data — the "memory creeps up while editing" probe.
+ *
+ * Measures only the language-server / model layer (the dominant pod consumer);
+ * not the Theia backend, GLSP GModel, or worker heaps. Pass `--expose-gc` to the
+ * node process so the readings are post-GC. Pure framework code: the only
+ * language-specific input is the service factory.
+ */
+export declare function measureModelMemory(options: MeasureModelMemoryOptions): Promise<MeasureModelMemoryResult>;
+//# sourceMappingURL=measure-memory.d.ts.map

package/lib/node/measure-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-memory.d.ts","sourceRoot":"","sources":["../../src/node/measure-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAOlF,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAGjF,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGlE,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACvC;;;;;OAKG;IACH,cAAc,EAAE,MAAM;QAAE,MAAM,EAAE,2BAA2B,CAAA;KAAE,CAAC;IAC9D,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,gHAAgH;IAChH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED,uDAAuD;AACvD,MAAM,WAAW,wBAAwB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kHAAkH;IAClH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA2F9G"}

package/lib/node/measure-memory.js

@@ -0,0 +1,128 @@
+/********************************************************************************
+ * 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 * 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 { buildWorkspaceProgrammatically } from '../langium/workspace/initialize-workspace.js';
+import { tallyAstGroundTruth } from './ast-ground-truth.js';
+import { ProfilingRun } from './profiling-run.js';
+function gcAndHeap() {
+    const gc = globalThis.gc;
+    if (gc) {
+        // Two passes so the reading is post-GC (the second collects what the first freed).
+        gc();
+        gc();
+    }
+    return process.memoryUsage();
+}
+/**
+ * Headless model-store memory measurement — the browser-/socket-free counterpart
+ * to the in-app "dump server state" command. Boots a head's Langium services
+ * in-process via {@link MeasureModelMemoryOptions.createServices}, builds a
+ * workspace, and reports the model-store memory across scenarios:
+ *   - empty baseline   : services created, no documents loaded.
+ *   - after build      : parse + link + validate + index of the whole workspace.
+ *   - rebuild churn     : re-run `DocumentBuilder.update` on unchanged content N
+ *                        times; any monotonic growth is retention (a leak), not
+ *                        new data — the "memory creeps up while editing" probe.
+ *
+ * Measures only the language-server / model layer (the dominant pod consumer);
+ * not the Theia backend, GLSP GModel, or worker heaps. Pass `--expose-gc` to the
+ * node process so the readings are post-GC. Pure framework code: the only
+ * language-specific input is the service factory.
+ */
+export async function measureModelMemory(options) {
+    const log = options.log ?? (() => undefined);
+    const report = (label) => {
+        const mem = gcAndHeap();
+        log(`[${label}] heapUsed=${Format.bytes(mem.heapUsed)} rss=${Format.bytes(mem.rss)} external=${Format.bytes(mem.external)}`);
+        return mem;
+    };
+    report('before-services');
+    // Start the profiling session BEFORE creating services: it points
+    // `HYDRANIUM_LOG_FILE` at the session's server.log, which the head's logger
+    // reads only at construction time (inside createServices).
+    const profilingRun = options.profile
+        ? await ProfilingRun.start({ directory: options.sessionOut, mode: 'harness', workspace: options.workspace, capture: options.profile })
+        : undefined;
+    const { shared } = options.createServices();
+    const empty = report('after-services-empty');
+    const start = performance.now();
+    const build = () => buildWorkspaceProgrammatically(shared, options.workspace);
+    await (profilingRun ? profilingRun.window('build', build) : build());
+    const buildMs = performance.now() - start;
+    const docs = shared.workspace.LangiumDocuments.all.toArray();
+    const settleMs = options.settleMs ?? 0;
+    if (settleMs > 0) {
+        // Let timer-driven residency (idle eviction) fire before the reading.
+        await new Promise(resolve => setTimeout(resolve, settleMs));
+        log(`(settled ${settleMs} ms for timer-driven residency before measuring)`);
+    }
+    const afterBuild = report('after-build');
+    const adds = afterBuild.heapUsed - empty.heapUsed;
+    log(`Documents: ${docs.length}, build ${Math.round(buildMs)} ms`);
+    // An empty workspace is an accepted input, so the per-document figure is
+    // omitted rather than divided by a substituted 1 — a `/doc` reading for no
+    // documents is not a smaller number, it is a meaningless one.
+    const perDoc = docs.length > 0 ? ` (~${Format.bytes(adds / docs.length)}/doc)` : '';
+    log(`Workspace build adds ${Format.bytes(adds)} heap${perDoc}`);
+    const result = {
+        documentCount: docs.length,
+        buildMs,
+        emptyHeapBytes: empty.heapUsed,
+        afterBuildHeapBytes: afterBuild.heapUsed
+    };
+    const editCycles = options.editCycles ?? 0;
+    if (editCycles > 0) {
+        const suffix = options.churnDocSuffix;
+        const uris = docs
+            .filter(doc => (suffix ? doc.uri.path.endsWith(suffix) : true))
+            // The churn re-runs `DocumentBuilder.update`, which re-reads each URI from
+            // the file system. Only file-backed documents survive that — synthetic /
+            // built-in docs (string-backed, served in-memory during the build, e.g. a
+            // head's built-in type definitions) have no file and would ENOENT. Restrict
+            // the churn set to documents that actually exist on disk.
+            .filter(doc => doc.uri.scheme === 'file' && fs.existsSync(doc.uri.fsPath))
+            .slice(0, options.editDocs ?? 25)
+            .map(doc => doc.uri);
+        log(`Rebuild churn: ${editCycles} cycles x ${uris.length} docs (unchanged content)...`);
+        const churn = async () => {
+            const collected = [];
+            for (let cycle = 1; cycle <= editCycles; cycle++) {
+                await shared.workspace.DocumentBuilder.update(uris, []);
+                collected.push(gcAndHeap().heapUsed);
+            }
+            return collected;
+        };
+        const heaps = await (profilingRun ? profilingRun.window('churn', churn) : churn());
+        const growth = heaps[heaps.length - 1] - heaps[0];
+        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}`);
+    }
+    if (options.writeSnapshot) {
+        const snapshotPath = options.snapshotPath ?? path.resolve(process.cwd(), `${path.basename(options.workspace)}.heapsnapshot`);
+        v8.writeHeapSnapshot(snapshotPath);
+        result.snapshotPath = snapshotPath;
+        log(`Heap snapshot: ${snapshotPath}`);
+    }
+    if (profilingRun) {
+        // Fold the non-profile artefacts the manifest catalogues into the same
+        // session folder, from data already in hand (no extra build).
+        profilingRun.attach('server-ast', 'server-ast.json', tallyAstGroundTruth(shared));
+        profilingRun.attach('server-memory-report', 'server-memory-report.json', result);
+        await profilingRun.finish();
+        result.profilingSession = profilingRun.directory;
+        log(`Profiling session: ${profilingRun.directory}`);
+    }
+    return result;
+}
+//# sourceMappingURL=measure-memory.js.map

package/lib/node/measure-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-memory.js","sourceRoot":"","sources":["../../src/node/measure-memory.ts"],"names":[],"mappings":"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"}

package/lib/node/memory-monitor.d.ts

@@ -0,0 +1,42 @@
+/********************************************************************************
+ * 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';
+/** Heap usage ratio (heapUsed / heap_size_limit) above which we emit a warning. */
+export declare const DEFAULT_MEMORY_WARN_THRESHOLD = 0.85;
+/** Heap usage ratio above which we emit an error-level warning (imminent OOM likely). */
+export declare const DEFAULT_MEMORY_CRITICAL_THRESHOLD = 0.95;
+/** Cooldown between repeated warnings at the same level, in ms. */
+export declare const DEFAULT_COOLDOWN_MS = 30000;
+/** Default heap-sampling interval, in ms. */
+export declare const DEFAULT_MEMORY_INTERVAL_MS = 5000;
+export interface MemoryMonitorOptions {
+    /** Heap-usage ratio (0..1) above which a warning is emitted. Default {@link DEFAULT_MEMORY_WARN_THRESHOLD}. */
+    warnThreshold?: number;
+    /** Heap-usage ratio above which an error is emitted (imminent OOM likely). Default {@link DEFAULT_MEMORY_CRITICAL_THRESHOLD}. */
+    criticalThreshold?: number;
+    /** Sample interval, in ms. Default {@link DEFAULT_MEMORY_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Cooldown between repeats at the same severity, in ms. Default {@link DEFAULT_COOLDOWN_MS}. */
+    cooldownMs?: number;
+    /** Log-name label derived from `shared.Logger`. Default `'Memory'`. */
+    logName?: string;
+}
+/**
+ * Monitors V8 heap usage and emits a warning when the heap approaches its configured limit.
+ *
+ * Rate-limits repeated warnings at the same severity by `cooldownMs`, and always re-emits
+ * on a transition (ok→warn, warn→critical, or back down). Uses `v8.getHeapStatistics().heap_size_limit`
+ * which respects Node's `--max-old-space-size` flag. Warnings give you a chance to correlate slowdowns,
+ * GC pressure, or imminent OOM failures with a specific operation in the accompanying timing logs.
+ *
+ * Follows the framework `(services, options)` shape: derives its own `'Memory'`
+ * component logger from `shared.Logger`.
+ */
+export declare function startMemoryMonitor(shared: ServerSharedServicesMinimal, options?: MemoryMonitorOptions): () => void;
+//# sourceMappingURL=memory-monitor.d.ts.map

package/lib/node/memory-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-monitor.d.ts","sourceRoot":"","sources":["../../src/node/memory-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAEjF,mFAAmF;AACnF,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAClD,yFAAyF;AACzF,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,6CAA6C;AAC7C,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAIhD,MAAM,WAAW,oBAAoB;IAClC,+GAA+G;IAC/G,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iIAAiI;IACjI,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,2BAA2B,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,IAAI,CAsDtH"}