@hydranium/core 1.0.0-next.10

package/lib/node/memory-monitor.js

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * 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 { Format } from '@hydranium/protocol';
+import * as v8 from 'node:v8';
+/** Heap usage ratio (heapUsed / heap_size_limit) above which we emit a warning. */
+export const DEFAULT_MEMORY_WARN_THRESHOLD = 0.85;
+/** Heap usage ratio above which we emit an error-level warning (imminent OOM likely). */
+export const DEFAULT_MEMORY_CRITICAL_THRESHOLD = 0.95;
+/** Cooldown between repeated warnings at the same level, in ms. */
+export const DEFAULT_COOLDOWN_MS = 30_000;
+/** Default heap-sampling interval, in ms. */
+export const DEFAULT_MEMORY_INTERVAL_MS = 5_000;
+/**
+ * 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 function startMemoryMonitor(shared, options = {}) {
+    const logger = shared.Logger.for(options.logName ?? 'Memory');
+    const warnThreshold = options.warnThreshold ?? DEFAULT_MEMORY_WARN_THRESHOLD;
+    const criticalThreshold = options.criticalThreshold ?? DEFAULT_MEMORY_CRITICAL_THRESHOLD;
+    const intervalMs = options.intervalMs ?? DEFAULT_MEMORY_INTERVAL_MS;
+    const cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    let lastSeverity = 'ok';
+    let lastEmittedAt = 0;
+    const severityFor = (ratio) => {
+        if (ratio >= criticalThreshold) {
+            return 'critical';
+        }
+        if (ratio >= warnThreshold) {
+            return 'warn';
+        }
+        return 'ok';
+    };
+    const check = () => {
+        const mem = process.memoryUsage();
+        const heapLimit = v8.getHeapStatistics().heap_size_limit;
+        const ratio = mem.heapUsed / heapLimit;
+        const severity = severityFor(ratio);
+        if (severity === 'ok' && lastSeverity === 'ok') {
+            return;
+        }
+        const now = Date.now();
+        const shouldEmit = severity !== lastSeverity || now - lastEmittedAt >= cooldownMs;
+        if (!shouldEmit) {
+            return;
+        }
+        const percent = Math.round(ratio * 100);
+        const message = `Heap usage ${percent}% (${Format.bytes(mem.heapUsed)} / ${Format.bytes(heapLimit)} limit), rss ${Format.bytes(mem.rss)}` +
+            (severity === 'critical'
+                ? ' - imminent out-of-memory possible, server may crash'
+                : severity === 'warn'
+                    ? ' - garbage collection pressure may slow operations'
+                    : ' - recovered below warning threshold');
+        if (severity === 'critical') {
+            logger.error(message);
+        }
+        else if (severity === 'warn') {
+            logger.warn(message);
+        }
+        else {
+            logger.info(message);
+        }
+        lastSeverity = severity;
+        lastEmittedAt = now;
+    };
+    const interval = setInterval(check, intervalMs);
+    interval.unref?.();
+    return () => clearInterval(interval);
+}
+//# sourceMappingURL=memory-monitor.js.map

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

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

package/lib/node/node-file-system-provider.d.ts

@@ -0,0 +1,112 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { URI } from '@hydranium/langium';
+import { NodeFileSystemProvider } from '@hydranium/langium/node';
+import { type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import { type SelfSaveRegistry } from '../documents/self-save-registry.js';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+/**
+ * Node-based default {@link WritableFileSystemProvider}. Extends Langium's
+ * {@link NodeFileSystemProvider} with an async {@link writeFile} that
+ * creates parent directories on demand, replaces the target indivisibly unless
+ * that would break a hard link, and registers the resulting mtime with the
+ * {@link SelfSaveRegistry} bound at `services.workspace.SelfSaveRegistry` — so
+ * consumers can suppress the `didChangeWatchedFiles` echo for their own writes.
+ *
+ * Server-only (`@hydranium/core/node`): pulls `node:fs`. The portable `.`
+ * entry binds `DefaultEmptyFileSystemProvider` by default, so a Node host
+ * must rebind this slot — through `context.fileSystemProvider` or directly — to
+ * get real disk I/O.
+ */
+export declare class DefaultFileSystemProvider extends NodeFileSystemProvider implements WritableFileSystemProvider {
+    protected readonly services: ServerSharedServicesMinimal;
+    readonly selfSaveRegistry: SelfSaveRegistry;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerSharedServicesMinimal, options?: LogNameOptions);
+    readFile(uri: URI): Promise<string>;
+    readFileSync(uri: URI): string;
+    /**
+     * Write `content` to `uri` via a staging file and a `rename` — or, onto a
+     * destination carrying more than one hard link, in place — then register the
+     * resulting mtime with the {@link SelfSaveRegistry}.
+     *
+     * The rename is what makes the replacement indivisible: a concurrent reader
+     * observes either the previous complete file or the new one. An in-place
+     * overwrite cannot offer that, because the target is truncated before the
+     * first byte lands, so a reader in that window gets a short or empty file —
+     * and a model file that fails to parse is worse than one holding a previous
+     * good revision. It does NOT serialise writers: two writers still race, and
+     * the loser's content is replaced wholesale rather than interleaved.
+     *
+     * The destination is the RESOLVED path, via {@link realpath}: a `rename`
+     * onto a symlink replaces the link itself with a regular file and leaves the
+     * file it pointed at holding the previous revision, where an in-place write
+     * would have followed the link. A URI that resolves to nothing is the create
+     * case and stages beside its own path — which includes a DANGLING link,
+     * matching {@link realpath}, whose `undefined` there is the same "absent"
+     * answer the document-identity policy acts on.
+     *
+     * Three constraints on the staging file. It is a sibling of the RESOLVED
+     * DESTINATION and not of `uri` — `rename` is only indivisible within one
+     * filesystem, and a link can point across one. Its name carries the pid and
+     * a random component, so two writers cannot select the same path and destroy
+     * each other's staging copy. And it ends in a suffix no grammar claims, so a
+     * workspace scan crossing the window cannot mistake it for a document.
+     *
+     * Replacing a file carries its permission bits over, and the staging file is
+     * created no wider than them so the pending content is never briefly more
+     * readable than what it replaces. Ownership, extended attributes and ACLs are
+     * NOT carried over, so a target relying on any of them must not be written
+     * through here: an owner cannot be restored by a process that does not own
+     * it, and Node exposes no API to read the other two, so copying them would
+     * mean shelling out.
+     *
+     * A destination with more than one hard link is written IN PLACE instead,
+     * keeping the inode. Renaming over such a path gives it a NEW inode, so
+     * every other name silently keeps the previous revision — the same stale-read
+     * outcome the staging file exists to prevent, and it happens on every write
+     * rather than only under contention. Keeping the inode preserves all its
+     * names, plus the mode, owner, extended attributes and ACLs that hang off it,
+     * for free; what it gives up is indivisibility, so that one write CAN be read
+     * torn by a concurrent reader. Breaking a link is certain where tearing is
+     * only possible, which is what settles the trade.
+     */
+    writeFile(uri: URI, content: string): Promise<void>;
+    mtimeMs(uri: URI): Promise<number | undefined>;
+    /**
+     * Real on-disk identity of `uri` via `fs.realpathSync` — symlinks collapsed,
+     * `..`/`.` walked, case-folded on case-insensitive filesystems. A non-`file:`
+     * URI cannot be statted, so it passes through unchanged (treated as present).
+     * A resolution failure (missing / unreadable) returns `undefined` — the
+     * filesystem's "absent" signal the document-identity policy depends on.
+     *
+     * Uncached on purpose: `realpathSync` is a syscall, but the kernel caches the
+     * dentry/inode lookups it walks, so repeated resolution of a live path is
+     * cheap. A userspace cache would add a staleness hazard (a re-pointed symlink
+     * resolving to its old target with no invalidation) for no measured gain.
+     */
+    realpath(uri: URI): URI | undefined;
+}
+/**
+ * Module fragment that binds the writable Node {@link DefaultFileSystemProvider},
+ * spread into the services context on a Node host.
+ *
+ * The framework counterpart to Langium's `NodeFileSystem` (`langium/node`): same
+ * role, but supplies the *writable* provider (`writeFile` + `mtimeMs`) the
+ * framework slot requires. Langium's fragment cannot stand in for it — its
+ * provider carries no `writeFile`, so the slot silently falls back to
+ * `DefaultEmptyFileSystemProvider` and the host gets no-op writes and a
+ * throwing `readFile` instead of disk access.
+ */
+export declare const NodeFileSystem: {
+    fileSystemProvider: (services: unknown) => DefaultFileSystemProvider;
+};
+//# sourceMappingURL=node-file-system-provider.d.ts.map

package/lib/node/node-file-system-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-file-system-provider.d.ts","sourceRoot":"","sources":["../../src/node/node-file-system-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAY,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAIjE,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAuB,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAGtG;;;;;;;;;;;;GAYG;AACH,qBAAa,yBAA0B,SAAQ,sBAAuB,YAAW,0BAA0B;IAKrG,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAJ3D,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,cAAmB;IAStB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnC,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM;IAIvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACG,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCnD,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAUpD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS;CAUrC;AAsED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;;CAE1B,CAAC"}

package/lib/node/node-file-system-provider.js

@@ -0,0 +1,230 @@
+/********************************************************************************
+ * 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 { URI, UriUtils } from '@hydranium/langium';
+import { NodeFileSystemProvider } from '@hydranium/langium/node';
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import { serverSharedFactory } from '../langium/shared-services.js';
+import { serveVirtualDocument } from '../langium/workspace/virtual-document.js';
+/**
+ * Node-based default {@link WritableFileSystemProvider}. Extends Langium's
+ * {@link NodeFileSystemProvider} with an async {@link writeFile} that
+ * creates parent directories on demand, replaces the target indivisibly unless
+ * that would break a hard link, and registers the resulting mtime with the
+ * {@link SelfSaveRegistry} bound at `services.workspace.SelfSaveRegistry` — so
+ * consumers can suppress the `didChangeWatchedFiles` echo for their own writes.
+ *
+ * Server-only (`@hydranium/core/node`): pulls `node:fs`. The portable `.`
+ * entry binds `DefaultEmptyFileSystemProvider` by default, so a Node host
+ * must rebind this slot — through `context.fileSystemProvider` or directly — to
+ * get real disk I/O.
+ */
+export class DefaultFileSystemProvider extends NodeFileSystemProvider {
+    services;
+    selfSaveRegistry;
+    tracer;
+    constructor(services, options = {}) {
+        super();
+        this.services = services;
+        this.selfSaveRegistry = services.workspace.SelfSaveRegistry;
+        this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    // Serve virtual documents from the registered document before touching disk
+    // (a virtual URI has no `fsPath` backing); delegate everything else to Node.
+    readFile(uri) {
+        const served = serveVirtualDocument(this.services, uri);
+        return served !== undefined ? Promise.resolve(served) : super.readFile(uri);
+    }
+    readFileSync(uri) {
+        return serveVirtualDocument(this.services, uri) ?? super.readFileSync(uri);
+    }
+    /**
+     * Write `content` to `uri` via a staging file and a `rename` — or, onto a
+     * destination carrying more than one hard link, in place — then register the
+     * resulting mtime with the {@link SelfSaveRegistry}.
+     *
+     * The rename is what makes the replacement indivisible: a concurrent reader
+     * observes either the previous complete file or the new one. An in-place
+     * overwrite cannot offer that, because the target is truncated before the
+     * first byte lands, so a reader in that window gets a short or empty file —
+     * and a model file that fails to parse is worse than one holding a previous
+     * good revision. It does NOT serialise writers: two writers still race, and
+     * the loser's content is replaced wholesale rather than interleaved.
+     *
+     * The destination is the RESOLVED path, via {@link realpath}: a `rename`
+     * onto a symlink replaces the link itself with a regular file and leaves the
+     * file it pointed at holding the previous revision, where an in-place write
+     * would have followed the link. A URI that resolves to nothing is the create
+     * case and stages beside its own path — which includes a DANGLING link,
+     * matching {@link realpath}, whose `undefined` there is the same "absent"
+     * answer the document-identity policy acts on.
+     *
+     * Three constraints on the staging file. It is a sibling of the RESOLVED
+     * DESTINATION and not of `uri` — `rename` is only indivisible within one
+     * filesystem, and a link can point across one. Its name carries the pid and
+     * a random component, so two writers cannot select the same path and destroy
+     * each other's staging copy. And it ends in a suffix no grammar claims, so a
+     * workspace scan crossing the window cannot mistake it for a document.
+     *
+     * Replacing a file carries its permission bits over, and the staging file is
+     * created no wider than them so the pending content is never briefly more
+     * readable than what it replaces. Ownership, extended attributes and ACLs are
+     * NOT carried over, so a target relying on any of them must not be written
+     * through here: an owner cannot be restored by a process that does not own
+     * it, and Node exposes no API to read the other two, so copying them would
+     * mean shelling out.
+     *
+     * A destination with more than one hard link is written IN PLACE instead,
+     * keeping the inode. Renaming over such a path gives it a NEW inode, so
+     * every other name silently keeps the previous revision — the same stale-read
+     * outcome the staging file exists to prevent, and it happens on every write
+     * rather than only under contention. Keeping the inode preserves all its
+     * names, plus the mode, owner, extended attributes and ACLs that hang off it,
+     * for free; what it gives up is indivisibility, so that one write CAN be read
+     * torn by a concurrent reader. Breaking a link is certain where tearing is
+     * only possible, which is what settles the trade.
+     */
+    async writeFile(uri, content) {
+        await fsp.mkdir(UriUtils.dirname(uri).fsPath, { recursive: true });
+        const destination = this.realpath(uri)?.fsPath ?? uri.fsPath;
+        const replaced = await replacedFile(destination);
+        if (replaced !== undefined && replaced.links > 1) {
+            // Keeping the inode is the only way this write reaches the other names.
+            await fsp.writeFile(destination, content);
+        }
+        else {
+            const staging = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+            try {
+                const mode = replaced?.mode;
+                await fsp.writeFile(staging, content, { mode });
+                if (mode !== undefined) {
+                    // `open` masks its mode argument with the umask, so the create
+                    // above can only under-permit; an explicit chmod is what makes
+                    // the carried mode exact.
+                    await fsp.chmod(staging, mode);
+                }
+                await renameOverOpenReaders(staging, destination);
+            }
+            catch (err) {
+                // A failed write must not leave the staging file behind for the next
+                // workspace scan or a later `--force` cleanup to trip over.
+                await fsp.rm(staging, { force: true });
+                throw err;
+            }
+        }
+        const mtimeMs = await this.mtimeMs(uri);
+        if (mtimeMs !== undefined) {
+            this.selfSaveRegistry.register(uri.fsPath, mtimeMs);
+        }
+    }
+    async mtimeMs(uri) {
+        try {
+            const stat = await fsp.stat(uri.fsPath);
+            return stat.mtimeMs;
+        }
+        catch {
+            // Missing file / stat failure — caller treats as "unknown".
+            return undefined;
+        }
+    }
+    /**
+     * Real on-disk identity of `uri` via `fs.realpathSync` — symlinks collapsed,
+     * `..`/`.` walked, case-folded on case-insensitive filesystems. A non-`file:`
+     * URI cannot be statted, so it passes through unchanged (treated as present).
+     * A resolution failure (missing / unreadable) returns `undefined` — the
+     * filesystem's "absent" signal the document-identity policy depends on.
+     *
+     * Uncached on purpose: `realpathSync` is a syscall, but the kernel caches the
+     * dentry/inode lookups it walks, so repeated resolution of a live path is
+     * cheap. A userspace cache would add a staleness hazard (a re-pointed symlink
+     * resolving to its old target with no invalidation) for no measured gain.
+     */
+    realpath(uri) {
+        if (uri.scheme !== 'file') {
+            return uri;
+        }
+        try {
+            return URI.file(realpathSync(uri.fsPath));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Facts about the regular file `path` replaces, or `undefined` when there is
+ * nothing to replace — the path is absent (a create, which takes the process
+ * default mode and has no other name), or is not a regular file (a directory,
+ * where the write is about to fail anyway).
+ */
+async function replacedFile(path) {
+    try {
+        const stat = await fsp.stat(path);
+        return stat.isFile() ? { mode: stat.mode & 0o777, links: stat.nlink } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Errno values a rename reports on Windows when another handle holds the
+ * destination open. POSIX renames are unaffected by open handles, so this
+ * cannot fire there and the retry below costs nothing.
+ */
+const RENAME_CONTENTION_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+/**
+ * `rename` the staged content over `destination`, retrying while Windows
+ * reports the destination as held open.
+ *
+ * The staging file exists so a reader never sees a half-written file, and on
+ * Windows the very presence of that reader is what makes the replacing rename
+ * fail — so the indivisible write breaks under exactly the contention it was
+ * built for, and it breaks intermittently, which is worse than never working.
+ * A reader's handle is released in milliseconds, so waiting turns a spurious
+ * failure into a slightly later success.
+ *
+ * BOUNDED, not open-ended: a genuine permission fault raises the same errno and
+ * is distinguishable from contention only by never clearing, so an unbounded
+ * wait would convert a hard error into a hang. Exhausting the budget rethrows
+ * the last failure, leaving the caller's cleanup and error contract unchanged.
+ */
+async function renameOverOpenReaders(staging, destination) {
+    const deadline = Date.now() + 2_000;
+    for (let attempt = 0;; attempt++) {
+        try {
+            await fsp.rename(staging, destination);
+            return;
+        }
+        catch (err) {
+            const code = err instanceof Error && 'code' in err ? String(err.code) : undefined;
+            if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || Date.now() >= deadline) {
+                throw err;
+            }
+            // Backs off to keep a long contention window from spinning, capped so
+            // a late attempt still lands promptly once the handle is released.
+            await new Promise(resolve => setTimeout(resolve, Math.min(2 ** attempt, 50)));
+        }
+    }
+}
+/**
+ * Module fragment that binds the writable Node {@link DefaultFileSystemProvider},
+ * spread into the services context on a Node host.
+ *
+ * The framework counterpart to Langium's `NodeFileSystem` (`langium/node`): same
+ * role, but supplies the *writable* provider (`writeFile` + `mtimeMs`) the
+ * framework slot requires. Langium's fragment cannot stand in for it — its
+ * provider carries no `writeFile`, so the slot silently falls back to
+ * `DefaultEmptyFileSystemProvider` and the host gets no-op writes and a
+ * throwing `readFile` instead of disk access.
+ */
+export const NodeFileSystem = {
+    fileSystemProvider: serverSharedFactory(services => new DefaultFileSystemProvider(services))
+};
+//# sourceMappingURL=node-file-system-provider.js.map

package/lib/node/node-file-system-provider.js.map

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

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"}