@hydranium/protocol 1.0.0-next.198 → 1.0.0-next.200

package/README.md

@@ -60,13 +60,15 @@ names, a worked example — is in
 @hydranium/protocol               # transfer documents, references, RPC machinery
 @hydranium/protocol/data          # DataServerProtocol / DataClientProtocol
 @hydranium/protocol/client        # the host-neutral client tier
+@hydranium/protocol/node          # process memory and heap-snapshot helpers
 @hydranium/protocol/testing       # test doubles, waiters, catalogue audit
 @hydranium/protocol/testing/node  # the Node-only doubles
 ```
 
 The root barrel re-exports `data` and `client`, so those two subpaths buy a
-narrower surface rather than reach; `testing` is only reachable by its own
-specifier, which is what keeps the doubles out of a production bundle. The RPC
+narrower surface rather than reach; `node` and `testing` are only reachable by
+their own specifiers, which keeps `node:*` imports out of a browser bundle and
+the doubles out of a production bundle. The RPC
 machinery documents itself in [`src/rpc/README.md`](./src/rpc/README.md).
 
 ### Auditing a translation catalogue

package/lib/node/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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 './process-memory';
+//# 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;AAMlF,cAAc,kBAAkB,CAAC"}

package/lib/node/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Subpath barrel for `@hydranium/protocol/node` — the diagnostics helpers that
+// need a Node runtime, kept out of the root barrel so the root stays
+// bundleable for a browser.
+__exportStar(require("./process-memory"), exports);
+//# 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,+EAA+E;AAC/E,qEAAqE;AACrE,4BAA4B;AAE5B,mDAAiC"}

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

@@ -0,0 +1,66 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Format a one-shot memory snapshot of the CURRENT process (heap, rss, external, V8 limit).
+ * Suited to a process that hosts no Langium documents (e.g. a host backend); for the
+ * language-server process with document counts, see `formatServerState`.
+ */
+export declare function formatProcessMemory(label: string): string;
+/**
+ * Compose an absolute artifact file path of the form `<prefix>[-<label>].<ext>` inside
+ * {@link directory} (e.g. the workspace folder, so it lands on the persistent volume in cloud and
+ * is visible in the file explorer), falling back to the OS temp dir when the directory is missing
+ * or does not exist. The {@link prefix} carries the origin-first stem (e.g. `server-cpu`) and, when
+ * a non-empty {@link label} is given (a named capture window), it is sanitised (non-word characters
+ * → `_`, truncated to 40 chars) and appended as `-<label>`; an empty label yields the bare
+ * `<prefix>.<ext>` so the manifest `kind` equals the filename stem. No timestamp — a fresh session
+ * directory per run keeps names stable and collision-free. Shared by the heap-snapshot writer and
+ * the sampled-profile capture so heap / CPU / allocation artefacts land identically, differing only
+ * by extension.
+ */
+export declare function snapshotFilePath(directory: string | undefined, label: string, prefix: string, ext: string): string;
+/**
+ * Write a V8 heap snapshot of the CURRENT process to {@link directory}, falling back to the OS temp
+ * dir when it is missing (see {@link snapshotFilePath}). `v8.writeHeapSnapshot` runs a full GC first and
+ * briefly pauses the process; it also transiently inflates RSS while serialising. Returns the
+ * absolute file path. The {@link prefix} (default `server-heap`, the origin-first stem) and
+ * {@link label} are folded into the name.
+ */
+export declare function writeHeapSnapshotToDir(directory: string | undefined, label: string, prefix?: string): string;
+/** A readable role for a process, whether it belongs to the app, and whether exactly one is expected. */
+export interface ProcessRole {
+    /** Human-readable role shown in the snapshot. */
+    role: string;
+    /** Whether this process is part of the application (vs. tooling/debugger), counted in the app total. */
+    isApp: boolean;
+    /**
+     * Set when at most one instance of this role should exist; `formatPodMemory` warns when more than
+     * one is found (e.g. a duplicated/ghost language server).
+     */
+    singletonExpected?: boolean;
+}
+/** Map a raw command line to a {@link ProcessRole}. A head supplies this to label its own processes. */
+export type ProcessClassifier = (cmdline: string) => ProcessRole;
+/** Options for {@link formatPodMemory}. */
+export interface PodMemoryOptions {
+    /** Map a process command line to a readable role; lets a head label its own processes. */
+    classify?: ProcessClassifier;
+    /** Heading for the in-app process group (default `Application`). */
+    appLabel?: string;
+}
+/**
+ * Format a pod/container-level memory snapshot read from the cgroup this process belongs to
+ * (cgroup v2 `memory.current`/`peak`/`max`/`stat`, falling back to cgroup v1). This is the figure
+ * the Kubernetes OOM-killer watches — it covers every process in the pod plus page cache and kernel
+ * memory, so it is higher than any single `process.memoryUsage().rss`. Also sums per-process RSS so
+ * the per-process split is visible. Explains itself when no cgroup memory controller is present
+ * (e.g. local dev outside a container).
+ */
+export declare function formatPodMemory(options?: PodMemoryOptions): string;
+//# sourceMappingURL=process-memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"process-memory.d.ts","sourceRoot":"","sources":["../../src/node/process-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAelF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKlH;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,SAAgB,GAAG,MAAM,CAInH;AA8CD,yGAAyG;AACzG,MAAM,WAAW,WAAW;IACzB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,KAAK,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wGAAwG;AACxG,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,WAAW,CAAC;AA2EjE,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC9B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CA6EtE"}

package/lib/node/process-memory.js

@@ -0,0 +1,291 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatProcessMemory = formatProcessMemory;
+exports.snapshotFilePath = snapshotFilePath;
+exports.writeHeapSnapshotToDir = writeHeapSnapshotToDir;
+exports.formatPodMemory = formatPodMemory;
+/*
+ * Node-only process- and pod-level memory introspection plus heap-snapshot
+ * writing. Everything here is generic OS-level code (V8 stats, cgroup v2/v1,
+ * `/proc`); the only host-specific part is naming the processes, which a head
+ * supplies through a `ProcessClassifier`.
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const v8 = __importStar(require("node:v8"));
+const logger_1 = require("../logger");
+/**
+ * Format a one-shot memory snapshot of the CURRENT process (heap, rss, external, V8 limit).
+ * Suited to a process that hosts no Langium documents (e.g. a host backend); for the
+ * language-server process with document counts, see `formatServerState`.
+ */
+function formatProcessMemory(label) {
+    const mem = process.memoryUsage();
+    const heap = v8.getHeapStatistics();
+    const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+    return [
+        `${label}:`,
+        `  heap      ${logger_1.Format.bytes(mem.heapUsed)} used / ${logger_1.Format.bytes(mem.heapTotal)} total / ` +
+            `${logger_1.Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`,
+        `  rss       ${logger_1.Format.bytes(mem.rss)}, external ${logger_1.Format.bytes(mem.external)}, arrayBuffers ${logger_1.Format.bytes(mem.arrayBuffers)}`,
+        `  uptime    ${Math.round(process.uptime())}s, pid ${process.pid}`
+    ].join('\n');
+}
+/**
+ * Compose an absolute artifact file path of the form `<prefix>[-<label>].<ext>` inside
+ * {@link directory} (e.g. the workspace folder, so it lands on the persistent volume in cloud and
+ * is visible in the file explorer), falling back to the OS temp dir when the directory is missing
+ * or does not exist. The {@link prefix} carries the origin-first stem (e.g. `server-cpu`) and, when
+ * a non-empty {@link label} is given (a named capture window), it is sanitised (non-word characters
+ * → `_`, truncated to 40 chars) and appended as `-<label>`; an empty label yields the bare
+ * `<prefix>.<ext>` so the manifest `kind` equals the filename stem. No timestamp — a fresh session
+ * directory per run keeps names stable and collision-free. Shared by the heap-snapshot writer and
+ * the sampled-profile capture so heap / CPU / allocation artefacts land identically, differing only
+ * by extension.
+ */
+function snapshotFilePath(directory, label, prefix, ext) {
+    const safeLabel = label ? label.replace(/[^\w.-]+/g, '_').slice(0, 40) : '';
+    const dir = directory && fs.existsSync(directory) ? directory : os.tmpdir();
+    const stem = safeLabel ? `${prefix}-${safeLabel}` : prefix;
+    return path.join(dir, `${stem}.${ext}`);
+}
+/**
+ * Write a V8 heap snapshot of the CURRENT process to {@link directory}, falling back to the OS temp
+ * dir when it is missing (see {@link snapshotFilePath}). `v8.writeHeapSnapshot` runs a full GC first and
+ * briefly pauses the process; it also transiently inflates RSS while serialising. Returns the
+ * absolute file path. The {@link prefix} (default `server-heap`, the origin-first stem) and
+ * {@link label} are folded into the name.
+ */
+function writeHeapSnapshotToDir(directory, label, prefix = 'server-heap') {
+    const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
+    v8.writeHeapSnapshot(filePath);
+    return filePath;
+}
+const CGROUP_ROOT = '/sys/fs/cgroup';
+function readNumber(file) {
+    try {
+        const text = fs.readFileSync(file, 'utf8').trim();
+        if (text === 'max') {
+            return Number.POSITIVE_INFINITY;
+        }
+        const value = Number(text);
+        return Number.isFinite(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse a `key value` per-line file (cgroup memory.stat) into a map. */
+function readKeyedBytes(file) {
+    const out = {};
+    try {
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+            const [key, value] = line.trim().split(/\s+/);
+            if (key && value !== undefined) {
+                const num = Number(value);
+                if (Number.isFinite(num)) {
+                    out[key] = num;
+                }
+            }
+        }
+    }
+    catch {
+        // file absent or unreadable; caller handles the empty map.
+    }
+    return out;
+}
+/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
+const defaultProcessClassifier = cmdline => ({ role: cmdline ? cmdline.slice(0, 60) : 'process', isApp: true });
+/** Read /proc for every visible process: pid, ppid, RSS, and a command label. */
+function readAllProcs() {
+    const procs = [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync('/proc');
+    }
+    catch {
+        return procs;
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry)) {
+            continue;
+        }
+        let status = '';
+        try {
+            status = fs.readFileSync(`/proc/${entry}/status`, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const rssMatch = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
+        if (!rssMatch) {
+            continue;
+        }
+        const ppid = Number(status.match(/^PPid:\s+(\d+)/m)?.[1] ?? 0);
+        let label = '';
+        try {
+            label = fs.readFileSync(`/proc/${entry}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+        }
+        catch {
+            // fall back to the process name from status below.
+        }
+        if (!label) {
+            label = status.match(/^Name:\s+(.+)$/m)?.[1] ?? `pid ${entry}`;
+        }
+        procs.push({ pid: Number(entry), ppid, rssBytes: Number(rssMatch[1]) * 1024, label });
+    }
+    return procs;
+}
+/**
+ * Sum and list per-process RSS. When {@link rootPid} is given, restrict to that process and its
+ * descendants (the app's own process tree), which keeps the figure meaningful in local dev where
+ * /proc otherwise shows the whole machine. In a container's PID namespace the tree is effectively
+ * all the pod's processes anyway.
+ */
+function collectProcessRss(rootPid) {
+    const all = readAllProcs();
+    let selected = all;
+    let scoped = false;
+    if (rootPid !== undefined) {
+        const childrenByPpid = new Map();
+        for (const proc of all) {
+            (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)).push(proc);
+        }
+        const tree = [];
+        const queue = all.filter(proc => proc.pid === rootPid);
+        while (queue.length > 0) {
+            const proc = queue.shift();
+            tree.push(proc);
+            queue.push(...(childrenByPpid.get(proc.pid) ?? []));
+        }
+        if (tree.length > 0) {
+            selected = tree;
+            scoped = true;
+        }
+    }
+    const total = selected.reduce((sum, proc) => sum + proc.rssBytes, 0);
+    selected.sort((a, b) => b.rssBytes - a.rssBytes);
+    return { total, processes: selected, scoped };
+}
+/**
+ * Format a pod/container-level memory snapshot read from the cgroup this process belongs to
+ * (cgroup v2 `memory.current`/`peak`/`max`/`stat`, falling back to cgroup v1). This is the figure
+ * the Kubernetes OOM-killer watches — it covers every process in the pod plus page cache and kernel
+ * memory, so it is higher than any single `process.memoryUsage().rss`. Also sums per-process RSS so
+ * the per-process split is visible. Explains itself when no cgroup memory controller is present
+ * (e.g. local dev outside a container).
+ */
+function formatPodMemory(options = {}) {
+    const classify = options.classify ?? defaultProcessClassifier;
+    const appLabel = options.appLabel ?? 'Application';
+    const lines = ['Pod memory snapshot:'];
+    const v2Current = path.join(CGROUP_ROOT, 'memory.current');
+    const v1Usage = path.join(CGROUP_ROOT, 'memory', 'memory.usage_in_bytes');
+    if (fs.existsSync(v2Current)) {
+        const current = readNumber(v2Current);
+        const peak = readNumber(path.join(CGROUP_ROOT, 'memory.peak'));
+        const max = readNumber(path.join(CGROUP_ROOT, 'memory.max'));
+        const stat = readKeyedBytes(path.join(CGROUP_ROOT, 'memory.stat'));
+        lines.push('  cgroup    v2');
+        lines.push(`  current   ${current !== undefined ? logger_1.Format.bytes(current) : 'n/a'}`);
+        lines.push(`  peak      ${peak !== undefined ? logger_1.Format.bytes(peak) : 'n/a (kernel too old for memory.peak)'}`);
+        lines.push(`  limit     ${max === Number.POSITIVE_INFINITY ? 'unlimited' : max !== undefined ? logger_1.Format.bytes(max) : 'n/a'}`);
+        if (Object.keys(stat).length > 0) {
+            lines.push(`  breakdown anon ${logger_1.Format.bytes(stat.anon ?? 0)} (heaps/stacks), file ${logger_1.Format.bytes(stat.file ?? 0)} (page cache), ` +
+                `kernel ${logger_1.Format.bytes(stat.kernel ?? stat.slab ?? 0)}, sock ${logger_1.Format.bytes(stat.sock ?? 0)}`);
+        }
+    }
+    else if (fs.existsSync(v1Usage)) {
+        const v1 = path.join(CGROUP_ROOT, 'memory');
+        const current = readNumber(v1Usage);
+        const peak = readNumber(path.join(v1, 'memory.max_usage_in_bytes'));
+        const limit = readNumber(path.join(v1, 'memory.limit_in_bytes'));
+        const stat = readKeyedBytes(path.join(v1, 'memory.stat'));
+        lines.push('  cgroup    v1');
+        lines.push(`  current   ${current !== undefined ? logger_1.Format.bytes(current) : 'n/a'}`);
+        lines.push(`  peak      ${peak !== undefined ? logger_1.Format.bytes(peak) : 'n/a'}`);
+        // v1 reports a huge sentinel for "unlimited"; treat anything >= 2^60 as unlimited.
+        lines.push(`  limit     ${limit !== undefined && limit < 2 ** 60 ? logger_1.Format.bytes(limit) : 'unlimited'}`);
+        if (Object.keys(stat).length > 0) {
+            lines.push(`  breakdown rss ${logger_1.Format.bytes(stat.rss ?? 0)}, cache ${logger_1.Format.bytes(stat.cache ?? 0)} (page cache), ` +
+                `kernel ${logger_1.Format.bytes(stat.kernel ?? 0)}`);
+        }
+    }
+    else {
+        lines.push('  cgroup    no memory controller under /sys/fs/cgroup (not running in a container?)');
+    }
+    // Root at this process so local dev reports only the app's tree, not the whole machine.
+    const { processes } = collectProcessRss(process.pid);
+    if (processes.length > 0) {
+        const classified = processes.map(proc => ({ ...proc, ...classify(proc.label) }));
+        const appProcs = classified.filter(proc => proc.isApp);
+        const otherProcs = classified.filter(proc => !proc.isApp);
+        const appTotal = appProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+        lines.push('');
+        lines.push(`  ${appLabel}: ${logger_1.Format.bytes(appTotal)} across ${appProcs.length} process(es)`);
+        for (const proc of appProcs) {
+            lines.push(`    ${logger_1.Format.bytes(proc.rssBytes).padStart(10)}  ${proc.role}  (pid ${proc.pid})`);
+        }
+        const singletonCounts = new Map();
+        for (const proc of appProcs) {
+            if (proc.singletonExpected) {
+                singletonCounts.set(proc.role, (singletonCounts.get(proc.role) ?? 0) + 1);
+            }
+        }
+        for (const [role, count] of singletonCounts) {
+            if (count > 1) {
+                lines.push(`  WARNING: ${count} instances of "${role}" running - likely ghost process(es); expected 1`);
+            }
+        }
+        if (otherProcs.length > 0) {
+            const otherTotal = otherProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+            lines.push(`  Other (tooling/debugger, not counted above): ${logger_1.Format.bytes(otherTotal)} across ${otherProcs.length} process(es)`);
+        }
+        lines.push('  Note: in a real pod the cgroup figure above is the OOM ceiling; this per-process');
+        lines.push('  split is for attribution. Local dev may include debugger processes (excluded here).');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=process-memory.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.198",
+  "version": "1.0.0-next.200",
   "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
   "keywords": [
     "hydranium",
@@ -56,6 +56,14 @@
       "types": "./lib/messages/index.d.ts",
       "default": "./lib/messages/index.js"
     },
+    "./node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
+    "./lib/node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
     "./testing": {
       "types": "./lib/testing/index.d.ts",
       "default": "./lib/testing/index.js"

package/src/node/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Subpath barrel for `@hydranium/protocol/node` — the diagnostics helpers that
+// need a Node runtime, kept out of the root barrel so the root stays
+// bundleable for a browser.
+
+export * from './process-memory';

package/src/node/process-memory.ts

@@ -0,0 +1,299 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/*
+ * Node-only process- and pod-level memory introspection plus heap-snapshot
+ * writing. Everything here is generic OS-level code (V8 stats, cgroup v2/v1,
+ * `/proc`); the only host-specific part is naming the processes, which a head
+ * supplies through a `ProcessClassifier`.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as v8 from 'node:v8';
+import { Format } from '../logger';
+
+/**
+ * Format a one-shot memory snapshot of the CURRENT process (heap, rss, external, V8 limit).
+ * Suited to a process that hosts no Langium documents (e.g. a host backend); for the
+ * language-server process with document counts, see `formatServerState`.
+ */
+export function formatProcessMemory(label: string): string {
+   const mem = process.memoryUsage();
+   const heap = v8.getHeapStatistics();
+   const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+   return [
+      `${label}:`,
+      `  heap      ${Format.bytes(mem.heapUsed)} used / ${Format.bytes(mem.heapTotal)} total / ` +
+         `${Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`,
+      `  rss       ${Format.bytes(mem.rss)}, external ${Format.bytes(mem.external)}, arrayBuffers ${Format.bytes(mem.arrayBuffers)}`,
+      `  uptime    ${Math.round(process.uptime())}s, pid ${process.pid}`
+   ].join('\n');
+}
+
+/**
+ * Compose an absolute artifact file path of the form `<prefix>[-<label>].<ext>` inside
+ * {@link directory} (e.g. the workspace folder, so it lands on the persistent volume in cloud and
+ * is visible in the file explorer), falling back to the OS temp dir when the directory is missing
+ * or does not exist. The {@link prefix} carries the origin-first stem (e.g. `server-cpu`) and, when
+ * a non-empty {@link label} is given (a named capture window), it is sanitised (non-word characters
+ * → `_`, truncated to 40 chars) and appended as `-<label>`; an empty label yields the bare
+ * `<prefix>.<ext>` so the manifest `kind` equals the filename stem. No timestamp — a fresh session
+ * directory per run keeps names stable and collision-free. Shared by the heap-snapshot writer and
+ * the sampled-profile capture so heap / CPU / allocation artefacts land identically, differing only
+ * by extension.
+ */
+export function snapshotFilePath(directory: string | undefined, label: string, prefix: string, ext: string): string {
+   const safeLabel = label ? label.replace(/[^\w.-]+/g, '_').slice(0, 40) : '';
+   const dir = directory && fs.existsSync(directory) ? directory : os.tmpdir();
+   const stem = safeLabel ? `${prefix}-${safeLabel}` : prefix;
+   return path.join(dir, `${stem}.${ext}`);
+}
+
+/**
+ * Write a V8 heap snapshot of the CURRENT process to {@link directory}, falling back to the OS temp
+ * dir when it is missing (see {@link snapshotFilePath}). `v8.writeHeapSnapshot` runs a full GC first and
+ * briefly pauses the process; it also transiently inflates RSS while serialising. Returns the
+ * absolute file path. The {@link prefix} (default `server-heap`, the origin-first stem) and
+ * {@link label} are folded into the name.
+ */
+export function writeHeapSnapshotToDir(directory: string | undefined, label: string, prefix = 'server-heap'): string {
+   const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
+   v8.writeHeapSnapshot(filePath);
+   return filePath;
+}
+
+const CGROUP_ROOT = '/sys/fs/cgroup';
+
+function readNumber(file: string): number | undefined {
+   try {
+      const text = fs.readFileSync(file, 'utf8').trim();
+      if (text === 'max') {
+         return Number.POSITIVE_INFINITY;
+      }
+      const value = Number(text);
+      return Number.isFinite(value) ? value : undefined;
+   } catch {
+      return undefined;
+   }
+}
+
+/** Parse a `key value` per-line file (cgroup memory.stat) into a map. */
+function readKeyedBytes(file: string): Record<string, number> {
+   const out: Record<string, number> = {};
+   try {
+      for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+         const [key, value] = line.trim().split(/\s+/);
+         if (key && value !== undefined) {
+            const num = Number(value);
+            if (Number.isFinite(num)) {
+               out[key] = num;
+            }
+         }
+      }
+   } catch {
+      // file absent or unreadable; caller handles the empty map.
+   }
+   return out;
+}
+
+interface ProcInfo {
+   pid: number;
+   rssBytes: number;
+   label: string;
+}
+
+interface RawProc extends ProcInfo {
+   ppid: number;
+}
+
+/** A readable role for a process, whether it belongs to the app, and whether exactly one is expected. */
+export interface ProcessRole {
+   /** Human-readable role shown in the snapshot. */
+   role: string;
+   /** Whether this process is part of the application (vs. tooling/debugger), counted in the app total. */
+   isApp: boolean;
+   /**
+    * Set when at most one instance of this role should exist; `formatPodMemory` warns when more than
+    * one is found (e.g. a duplicated/ghost language server).
+    */
+   singletonExpected?: boolean;
+}
+
+/** Map a raw command line to a {@link ProcessRole}. A head supplies this to label its own processes. */
+export type ProcessClassifier = (cmdline: string) => ProcessRole;
+
+/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
+const defaultProcessClassifier: ProcessClassifier = cmdline => ({ role: cmdline ? cmdline.slice(0, 60) : 'process', isApp: true });
+
+/** Read /proc for every visible process: pid, ppid, RSS, and a command label. */
+function readAllProcs(): RawProc[] {
+   const procs: RawProc[] = [];
+   let entries: string[] = [];
+   try {
+      entries = fs.readdirSync('/proc');
+   } catch {
+      return procs;
+   }
+   for (const entry of entries) {
+      if (!/^\d+$/.test(entry)) {
+         continue;
+      }
+      let status = '';
+      try {
+         status = fs.readFileSync(`/proc/${entry}/status`, 'utf8');
+      } catch {
+         continue;
+      }
+      const rssMatch = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
+      if (!rssMatch) {
+         continue;
+      }
+      const ppid = Number(status.match(/^PPid:\s+(\d+)/m)?.[1] ?? 0);
+      let label = '';
+      try {
+         label = fs.readFileSync(`/proc/${entry}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+      } catch {
+         // fall back to the process name from status below.
+      }
+      if (!label) {
+         label = status.match(/^Name:\s+(.+)$/m)?.[1] ?? `pid ${entry}`;
+      }
+      procs.push({ pid: Number(entry), ppid, rssBytes: Number(rssMatch[1]) * 1024, label });
+   }
+   return procs;
+}
+
+/**
+ * Sum and list per-process RSS. When {@link rootPid} is given, restrict to that process and its
+ * descendants (the app's own process tree), which keeps the figure meaningful in local dev where
+ * /proc otherwise shows the whole machine. In a container's PID namespace the tree is effectively
+ * all the pod's processes anyway.
+ */
+function collectProcessRss(rootPid?: number): { total: number; processes: ProcInfo[]; scoped: boolean } {
+   const all = readAllProcs();
+   let selected: RawProc[] = all;
+   let scoped = false;
+   if (rootPid !== undefined) {
+      const childrenByPpid = new Map<number, RawProc[]>();
+      for (const proc of all) {
+         (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)!).push(proc);
+      }
+      const tree: RawProc[] = [];
+      const queue = all.filter(proc => proc.pid === rootPid);
+      while (queue.length > 0) {
+         const proc = queue.shift()!;
+         tree.push(proc);
+         queue.push(...(childrenByPpid.get(proc.pid) ?? []));
+      }
+      if (tree.length > 0) {
+         selected = tree;
+         scoped = true;
+      }
+   }
+   const total = selected.reduce((sum, proc) => sum + proc.rssBytes, 0);
+   selected.sort((a, b) => b.rssBytes - a.rssBytes);
+   return { total, processes: selected, scoped };
+}
+
+/** Options for {@link formatPodMemory}. */
+export interface PodMemoryOptions {
+   /** Map a process command line to a readable role; lets a head label its own processes. */
+   classify?: ProcessClassifier;
+   /** Heading for the in-app process group (default `Application`). */
+   appLabel?: string;
+}
+
+/**
+ * Format a pod/container-level memory snapshot read from the cgroup this process belongs to
+ * (cgroup v2 `memory.current`/`peak`/`max`/`stat`, falling back to cgroup v1). This is the figure
+ * the Kubernetes OOM-killer watches — it covers every process in the pod plus page cache and kernel
+ * memory, so it is higher than any single `process.memoryUsage().rss`. Also sums per-process RSS so
+ * the per-process split is visible. Explains itself when no cgroup memory controller is present
+ * (e.g. local dev outside a container).
+ */
+export function formatPodMemory(options: PodMemoryOptions = {}): string {
+   const classify = options.classify ?? defaultProcessClassifier;
+   const appLabel = options.appLabel ?? 'Application';
+   const lines: string[] = ['Pod memory snapshot:'];
+
+   const v2Current = path.join(CGROUP_ROOT, 'memory.current');
+   const v1Usage = path.join(CGROUP_ROOT, 'memory', 'memory.usage_in_bytes');
+
+   if (fs.existsSync(v2Current)) {
+      const current = readNumber(v2Current);
+      const peak = readNumber(path.join(CGROUP_ROOT, 'memory.peak'));
+      const max = readNumber(path.join(CGROUP_ROOT, 'memory.max'));
+      const stat = readKeyedBytes(path.join(CGROUP_ROOT, 'memory.stat'));
+      lines.push('  cgroup    v2');
+      lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
+      lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a (kernel too old for memory.peak)'}`);
+      lines.push(`  limit     ${max === Number.POSITIVE_INFINITY ? 'unlimited' : max !== undefined ? Format.bytes(max) : 'n/a'}`);
+      if (Object.keys(stat).length > 0) {
+         lines.push(
+            `  breakdown anon ${Format.bytes(stat.anon ?? 0)} (heaps/stacks), file ${Format.bytes(stat.file ?? 0)} (page cache), ` +
+               `kernel ${Format.bytes(stat.kernel ?? stat.slab ?? 0)}, sock ${Format.bytes(stat.sock ?? 0)}`
+         );
+      }
+   } else if (fs.existsSync(v1Usage)) {
+      const v1 = path.join(CGROUP_ROOT, 'memory');
+      const current = readNumber(v1Usage);
+      const peak = readNumber(path.join(v1, 'memory.max_usage_in_bytes'));
+      const limit = readNumber(path.join(v1, 'memory.limit_in_bytes'));
+      const stat = readKeyedBytes(path.join(v1, 'memory.stat'));
+      lines.push('  cgroup    v1');
+      lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
+      lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a'}`);
+      // v1 reports a huge sentinel for "unlimited"; treat anything >= 2^60 as unlimited.
+      lines.push(`  limit     ${limit !== undefined && limit < 2 ** 60 ? Format.bytes(limit) : 'unlimited'}`);
+      if (Object.keys(stat).length > 0) {
+         lines.push(
+            `  breakdown rss ${Format.bytes(stat.rss ?? 0)}, cache ${Format.bytes(stat.cache ?? 0)} (page cache), ` +
+               `kernel ${Format.bytes(stat.kernel ?? 0)}`
+         );
+      }
+   } else {
+      lines.push('  cgroup    no memory controller under /sys/fs/cgroup (not running in a container?)');
+   }
+
+   // Root at this process so local dev reports only the app's tree, not the whole machine.
+   const { processes } = collectProcessRss(process.pid);
+   if (processes.length > 0) {
+      const classified = processes.map(proc => ({ ...proc, ...classify(proc.label) }));
+      const appProcs = classified.filter(proc => proc.isApp);
+      const otherProcs = classified.filter(proc => !proc.isApp);
+      const appTotal = appProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+
+      lines.push('');
+      lines.push(`  ${appLabel}: ${Format.bytes(appTotal)} across ${appProcs.length} process(es)`);
+      for (const proc of appProcs) {
+         lines.push(`    ${Format.bytes(proc.rssBytes).padStart(10)}  ${proc.role}  (pid ${proc.pid})`);
+      }
+      const singletonCounts = new Map<string, number>();
+      for (const proc of appProcs) {
+         if (proc.singletonExpected) {
+            singletonCounts.set(proc.role, (singletonCounts.get(proc.role) ?? 0) + 1);
+         }
+      }
+      for (const [role, count] of singletonCounts) {
+         if (count > 1) {
+            lines.push(`  WARNING: ${count} instances of "${role}" running - likely ghost process(es); expected 1`);
+         }
+      }
+      if (otherProcs.length > 0) {
+         const otherTotal = otherProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+         lines.push(`  Other (tooling/debugger, not counted above): ${Format.bytes(otherTotal)} across ${otherProcs.length} process(es)`);
+      }
+      lines.push('  Note: in a real pod the cgroup figure above is the OOM ceiling; this per-process');
+      lines.push('  split is for attribution. Local dev may include debugger processes (excluded here).');
+   }
+
+   return lines.join('\n');
+}