@hydranium/core 1.0.0-next.10

package/lib/node/profiling-run.js

@@ -0,0 +1,183 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/*
+ * The profiling session orchestrator: one run = one timestamped folder holding
+ * the captured artefacts and a self-describing `manifest.json`. This is the seam
+ * that makes "everything from a single run" true without a god-object — each
+ * collector shares only the session directory + manifest. This run drives the
+ * server-side sampled-profile capture over one or more named windows and, when
+ * given a collector, the latency report; browser-origin collectors append their
+ * own manifest entries the same way, from the Playwright side.
+ */
+import { DEFAULT_LOG_FILE_ENV, PROFILING_SCHEMA_VERSION } from '@hydranium/protocol';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { profileWorkload } from './profile-capture.js';
+import { digestAllocationProfile, digestCpuProfile } from './profile-digest.js';
+// The manifest schema lives in `@hydranium/protocol` so a Playwright-side
+// assembler can share the shape without a Node-only dependency chain;
+// re-export it here so `@hydranium/core/node` consumers keep one import site.
+export { PROFILING_SCHEMA_VERSION };
+/** A cgroup memory controller signals we are inside a container/pod. */
+function detectContainer() {
+    return fs.existsSync('/sys/fs/cgroup/memory.current') || fs.existsSync('/sys/fs/cgroup/memory/memory.usage_in_bytes');
+}
+/**
+ * A profiling session: create it, run one or more named windows through it, then
+ * {@link finish} to write `server-summary.json` + `manifest.json` and get the manifest.
+ * Windows run sequentially (the underlying capture is a single inspector session).
+ */
+export class ProfilingRun {
+    options;
+    directory;
+    sessionId;
+    reports = {};
+    artifacts = [];
+    windows = [];
+    finished = false;
+    /** The `HYDRANIUM_LOG_FILE` value seen before this run pointed it at the session (restored on {@link finish}). */
+    previousLogFileEnv;
+    /** Absolute path of the session's teed server log. */
+    serverLogPath;
+    constructor(options, directory, sessionId) {
+        this.options = options;
+        this.directory = directory;
+        this.sessionId = sessionId;
+        this.serverLogPath = path.join(directory, 'server.log');
+        // Point the log-file tee at the session so the head's structured logs
+        // (build phases, warnings, and — in an app run — the interleaved browser
+        // console) land in the bundle beside the profiles. Done via the
+        // `HYDRANIUM_LOG_FILE` env, which every `@hydranium/core` copy reads when
+        // its logger is CONSTRUCTED — so `ProfilingRun.start` must run before the
+        // head's services are created (as `measureModelMemory` does). This is the
+        // only mechanism that crosses a yalc'd adopter's separate core copy; a
+        // process-local `setLogFilePath` would only reach this module's own copy.
+        this.previousLogFileEnv = process.env[DEFAULT_LOG_FILE_ENV];
+        process.env[DEFAULT_LOG_FILE_ENV] = this.serverLogPath;
+    }
+    static async start(options = {}) {
+        const sessionId = options.sessionId ?? `profiling-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        // Honour an explicitly requested directory (created recursively); only fall
+        // back to the OS temp dir when none was given.
+        const directory = path.join(options.directory ?? os.tmpdir(), sessionId);
+        fs.mkdirSync(directory, { recursive: true });
+        return new ProfilingRun(options, directory, sessionId);
+    }
+    /**
+     * Write an already-collected artefact (e.g. `server-ast.json`,
+     * `server-memory-report.json`) into the session directory and record it in the
+     * manifest. For non-profile inputs a head/harness already has in hand.
+     */
+    attach(kind, filename, data) {
+        if (this.finished) {
+            throw new Error('ProfilingRun.attach called after finish().');
+        }
+        fs.writeFileSync(path.join(this.directory, filename), JSON.stringify(data, undefined, 2));
+        this.artifacts.push({ kind, path: filename });
+    }
+    /** Capture {@link run} as a named window, recording its artefacts + duration. Returns the block's result. */
+    async window(label, run) {
+        if (this.finished) {
+            throw new Error('ProfilingRun.window called after finish().');
+        }
+        if (this.reports[label] !== undefined) {
+            throw new Error(`ProfilingRun.window called twice with label '${label}'; window labels must be unique.`);
+        }
+        const { result, report } = await profileWorkload({ ...(this.options.capture ?? {}), directory: this.directory, label }, run);
+        this.reports[label] = report;
+        this.windows.push({ label, ms: report.durationMs });
+        if (report.cpuProfilePath) {
+            this.artifacts.push(this.artifactWithDigest('server-cpu', report.cpuProfilePath, label, raw => digestCpuProfile(raw)));
+        }
+        if (report.allocationProfilePath) {
+            this.artifacts.push(this.artifactWithDigest('server-alloc', report.allocationProfilePath, label, raw => digestAllocationProfile(raw)));
+        }
+        if (report.heapSnapshotPath) {
+            // No inline digest: a heap snapshot's digest is the retained-size analyzer's report.
+            this.artifacts.push({ kind: 'server-heap', path: path.basename(report.heapSnapshotPath), window: label });
+        }
+        return result;
+    }
+    /** Build the artefact entry, emitting a `<profile>.txt` digest beside the profile; a digest failure is non-fatal. */
+    artifactWithDigest(kind, file, window, digest) {
+        const artifact = { kind, path: path.basename(file), window };
+        try {
+            const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+            const digestPath = `${file}.txt`;
+            fs.writeFileSync(digestPath, digest(raw));
+            artifact.digest = path.basename(digestPath);
+        }
+        catch {
+            // The raw profile is still in the bundle; a skill can fall back to it.
+        }
+        return artifact;
+    }
+    /** Write `server-summary.json` + `manifest.json` into the session directory and return the manifest. */
+    async finish() {
+        this.finished = true;
+        // Restore the prior log-file env, then record the log as an artefact only
+        // if the run actually produced one.
+        if (this.previousLogFileEnv === undefined) {
+            delete process.env[DEFAULT_LOG_FILE_ENV];
+        }
+        else {
+            process.env[DEFAULT_LOG_FILE_ENV] = this.previousLogFileEnv;
+        }
+        if (fs.existsSync(this.serverLogPath)) {
+            this.artifacts.push({ kind: 'server-log', path: 'server.log' });
+        }
+        fs.writeFileSync(path.join(this.directory, 'server-summary.json'), JSON.stringify(this.reports, undefined, 2));
+        if (this.options.latency) {
+            fs.writeFileSync(path.join(this.directory, 'server-latency.json'), JSON.stringify(this.options.latency.report(), undefined, 2));
+            this.artifacts.push({ kind: 'server-latency', path: 'server-latency.json' });
+        }
+        const manifest = {
+            schemaVersion: PROFILING_SCHEMA_VERSION,
+            sessionId: this.sessionId,
+            environment: {
+                mode: this.options.mode ?? 'harness',
+                container: this.options.container ?? detectContainer(),
+                commit: this.options.commit,
+                workspace: this.options.workspace,
+                node: process.version,
+                windows: this.windows
+            },
+            artifacts: [...this.artifacts, { kind: 'server-summary', path: 'server-summary.json' }]
+        };
+        fs.writeFileSync(path.join(this.directory, 'manifest.json'), JSON.stringify(manifest, undefined, 2));
+        return manifest;
+    }
+}
+/**
+ * Merge one window's {@link ProfileReport} into `<directory>/server-summary.json`
+ * (read-modify-write, keyed by window label). Lets the interactive / RPC capture path
+ * — which stops a single window at a time via the data-server `stopProfiling`, with no
+ * {@link ProfilingRun} to collect the reports — accrue the same `server-summary`
+ * artefact the headless {@link ProfilingRun.finish} writes in one pass. An empty label
+ * is keyed `app`; a malformed or absent existing file is treated as empty. Creates the
+ * directory if needed, so a caller-supplied path that does not yet exist does not throw.
+ */
+export function recordServerSummaryEntry(directory, label, report) {
+    fs.mkdirSync(directory, { recursive: true });
+    const file = path.join(directory, 'server-summary.json');
+    let summary = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed && typeof parsed === 'object') {
+            summary = parsed;
+        }
+    }
+    catch {
+        // No existing summary (or unreadable) — start fresh.
+    }
+    summary[label || 'app'] = report;
+    fs.writeFileSync(file, JSON.stringify(summary, undefined, 2));
+}
+//# sourceMappingURL=profiling-run.js.map

package/lib/node/profiling-run.js.map

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

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

@@ -0,0 +1,109 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type AstReflection, type Grammar, type LanguageMetaData } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+/** One terminal rule of a language's grammar, flattened for the reflection dump. */
+export interface TerminalReflection {
+    /** The terminal rule name. */
+    name: string;
+    /** The compiled pattern source, when it could be resolved to a `RegExp`. */
+    pattern?: string;
+    /** Hidden terminals (e.g. whitespace, comments) are lexed but not parsed. */
+    hidden: boolean;
+}
+/** A single registered language's grammar surface. */
+export interface LanguageReflection {
+    /** The language id from `LanguageMetaData` (matches the LSP `languageId`). */
+    languageId: string;
+    /** File extensions the language claims, each with a leading dot. */
+    fileExtensions: string[];
+    /** The grammar's entry parser rule name, when one is marked `entry`. */
+    entryRule?: string;
+    /** Terminal rules, in grammar declaration order. */
+    terminals: TerminalReflection[];
+}
+/** A property of an AST node type, as the runtime reflection exposes it. */
+export interface PropertyReflection {
+    /** The property name on the AST node. */
+    name: string;
+    /** For a cross-reference property, the target type name; absent for containment/values. */
+    referenceType?: string;
+    /** True when the property is a (possibly-empty) array — reflection defaults it to `[]`. */
+    array: boolean;
+    /**
+     * True when the reflection carries a default value for the property (arrays default to
+     * `[]`, some scalars to a literal). Reflection cannot distinguish optional from
+     * mandatory beyond this, so the dump reports only what it can prove.
+     */
+    hasDefault: boolean;
+}
+/** One AST node type from the shared reflection (the superset across all languages). */
+export interface TypeReflection {
+    /** The `$type` value / grammar rule or interface name. */
+    name: string;
+    /** Declared super types (grammar `returns` / interface `extends`). */
+    superTypes: string[];
+    /** Types whose `superTypes` list this type directly (inverted, so a hierarchy tree is buildable). */
+    directSubTypes: string[];
+    /** Properties with their reflection meta data, sorted by name. */
+    properties: PropertyReflection[];
+}
+/**
+ * The full grammar/AST reflection of a head — a serialisable snapshot of the
+ * type system and per-language grammar surface. This is the JSON contract
+ * `hydranium-cli reflect --json` emits; it is independent of the Langium runtime
+ * types so tooling reads a stable schema and the CLI needs no runtime
+ * `@hydranium/core` dependency.
+ */
+export interface GrammarReflection {
+    /** Every registered language's grammar surface, in registration order. */
+    languages: LanguageReflection[];
+    /** Every AST node type (the shared reflection superset), sorted by name. */
+    types: TypeReflection[];
+}
+/** Options for {@link reflectGrammar}. */
+export interface ReflectGrammarOptions {
+    /**
+     * Create the language's shared services in-process. This is the only
+     * language-specific input — a head passes its own `create<Lang>Services(fileSystem)`.
+     */
+    createServices: () => {
+        shared: ServerSharedServicesMinimal;
+    };
+}
+/** The language-service shape {@link collectGrammarReflection} reads (grammar + meta data). */
+export interface ReflectableLanguageServices {
+    Grammar: Grammar;
+    LanguageMetaData: LanguageMetaData;
+}
+/**
+ * Flatten a head's runtime reflection + registered languages into a serialisable
+ * {@link GrammarReflection}. Pure over its inputs (the shared {@link AstReflection}
+ * and the per-language grammar/meta-data services) so it unit-tests without booting
+ * a grammar; {@link reflectGrammar} is the thin boot wrapper.
+ *
+ * `directSubTypes` is derived by inverting every type's `superTypes` — the runtime
+ * reflection only exposes the transitive `getAllSubTypes`, and direct edges make a
+ * hierarchy tree buildable without re-deriving it.
+ */
+export declare function collectGrammarReflection(reflection: AstReflection, languages: readonly ReflectableLanguageServices[]): GrammarReflection;
+/**
+ * Headless grammar/AST reflection — a static snapshot of a head's type system and
+ * grammar surface, no workspace build required (the reflection and grammar are
+ * available as soon as {@link ReflectGrammarOptions.createServices} registers the
+ * language). Boots a head's Langium services in-process, then flattens the shared
+ * {@link AstReflection} and every registered language's grammar into a serialisable
+ * {@link GrammarReflection}.
+ *
+ * Backs `hydranium-cli reflect`. Like the other headless harnesses the only
+ * language-specific input is the service factory, so the framework code stays
+ * head-neutral.
+ */
+export declare function reflectGrammar(options: ReflectGrammarOptions): GrammarReflection;
+//# sourceMappingURL=reflect-grammar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-grammar.d.ts","sourceRoot":"","sources":["../../src/node/reflect-grammar.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,OAAO,EAAE,KAAK,gBAAgB,EAA4B,MAAM,oBAAoB,CAAC;AACvH,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAEjF,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IAChC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,OAAO,CAAC;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAChC,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,SAAS,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IAChC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2FAA2F;IAC3F,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;CACtB;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC5B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,qGAAqG;IACrG,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kEAAkE;IAClE,UAAU,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC/B,0EAA0E;IAC1E,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,4EAA4E;IAC5E,KAAK,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACnC;;;OAGG;IACH,cAAc,EAAE,MAAM;QAAE,MAAM,EAAE,2BAA2B,CAAA;KAAE,CAAC;CAChE;AAED,+FAA+F;AAC/F,MAAM,WAAW,2BAA2B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,gBAAgB,CAAC;CACrC;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,2BAA2B,EAAE,GAAG,iBAAiB,CAmCxI;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,CAGhF"}

package/lib/node/reflect-grammar.js

@@ -0,0 +1,96 @@
+/********************************************************************************
+ * 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, GrammarUtils } from '@hydranium/langium';
+/** Resolve a terminal rule's pattern source, tolerating rules `terminalRegex` cannot compile. */
+function terminalPattern(rule) {
+    try {
+        return GrammarUtils.terminalRegex(rule).source;
+    }
+    catch {
+        // Some terminal rules (e.g. those referencing not-yet-resolvable fragments) can't be
+        // compiled to a standalone RegExp; the dump still lists the terminal, just pattern-less.
+        return undefined;
+    }
+}
+/** Flatten one language's grammar to its {@link LanguageReflection}. */
+function reflectLanguage(services) {
+    const { Grammar: grammar, LanguageMetaData: meta } = services;
+    const terminals = grammar.rules.filter(GrammarAST.isTerminalRule).map(rule => ({
+        name: rule.name,
+        pattern: terminalPattern(rule),
+        hidden: rule.hidden === true
+    }));
+    const entryRule = grammar.rules.find((rule) => GrammarAST.isParserRule(rule) && rule.entry === true);
+    return {
+        languageId: meta.languageId,
+        fileExtensions: [...meta.fileExtensions],
+        entryRule: entryRule?.name,
+        terminals
+    };
+}
+/**
+ * Flatten a head's runtime reflection + registered languages into a serialisable
+ * {@link GrammarReflection}. Pure over its inputs (the shared {@link AstReflection}
+ * and the per-language grammar/meta-data services) so it unit-tests without booting
+ * a grammar; {@link reflectGrammar} is the thin boot wrapper.
+ *
+ * `directSubTypes` is derived by inverting every type's `superTypes` — the runtime
+ * reflection only exposes the transitive `getAllSubTypes`, and direct edges make a
+ * hierarchy tree buildable without re-deriving it.
+ */
+export function collectGrammarReflection(reflection, languages) {
+    const typeNames = [...reflection.getAllTypes()].sort((left, right) => left.localeCompare(right));
+    // Invert superTypes → direct subtypes in one pass.
+    const directSubTypes = new Map();
+    for (const name of typeNames) {
+        for (const superType of reflection.getTypeMetaData(name).superTypes) {
+            const children = directSubTypes.get(superType) ?? [];
+            children.push(name);
+            directSubTypes.set(superType, children);
+        }
+    }
+    const types = typeNames.map(name => {
+        const meta = reflection.getTypeMetaData(name);
+        const properties = Object.values(meta.properties)
+            .map(property => ({
+            name: property.name,
+            referenceType: property.referenceType,
+            array: Array.isArray(property.defaultValue),
+            hasDefault: property.defaultValue !== undefined
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name));
+        return {
+            name,
+            superTypes: [...meta.superTypes],
+            directSubTypes: (directSubTypes.get(name) ?? []).sort((left, right) => left.localeCompare(right)),
+            properties
+        };
+    });
+    return {
+        languages: languages.map(reflectLanguage),
+        types
+    };
+}
+/**
+ * Headless grammar/AST reflection — a static snapshot of a head's type system and
+ * grammar surface, no workspace build required (the reflection and grammar are
+ * available as soon as {@link ReflectGrammarOptions.createServices} registers the
+ * language). Boots a head's Langium services in-process, then flattens the shared
+ * {@link AstReflection} and every registered language's grammar into a serialisable
+ * {@link GrammarReflection}.
+ *
+ * Backs `hydranium-cli reflect`. Like the other headless harnesses the only
+ * language-specific input is the service factory, so the framework code stays
+ * head-neutral.
+ */
+export function reflectGrammar(options) {
+    const { shared } = options.createServices();
+    return collectGrammarReflection(shared.AstReflection, shared.ServiceRegistry.all);
+}
+//# sourceMappingURL=reflect-grammar.js.map

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

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

package/lib/node/server-diagnostics.d.ts

@@ -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 { type LogPreambleOptions } from '../langium/diagnostics/log-preamble.js';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { type EventLoopMonitorOptions } from './event-loop-monitor.js';
+import { type MemoryMonitorOptions } from './memory-monitor.js';
+export interface ServerDiagnosticsOptions {
+    /**
+     * Session-preamble branding + thresholds. The Node runtime/host lines and
+     * monitor conventions are added automatically (see {@link nodeLogPreambleSections}),
+     * so adopters supply only their branding.
+     */
+    preamble: Pick<LogPreambleOptions, 'productName' | 'version' | 'phaseDetailThresholdMs'>;
+    /** Emit a one-shot `Initial Memory` line at startup. Default `true`. */
+    logInitialMemory?: boolean;
+    /** Overrides forwarded verbatim to {@link startEventLoopMonitor}. */
+    eventLoop?: EventLoopMonitorOptions;
+    /** Overrides forwarded verbatim to {@link startMemoryMonitor}. */
+    memory?: MemoryMonitorOptions;
+}
+/**
+ * The standard **Node** server-observability bringup: logs the session preamble
+ * (with Node runtime lines), an initial memory line, and starts the event-loop +
+ * heap monitors. Returns a teardown that stops both monitors.
+ *
+ * Node-only by nature — it owns the `perf_hooks` / `v8` monitors. A browser
+ * server has no such monitors; it just calls the portable
+ * {@link logPreamble} directly (no Node sections), so there is no browser
+ * counterpart to wrap.
+ *
+ * Option groups are nested (`preamble` / `eventLoop` / `memory`) and forwarded
+ * untouched to each primitive — the primitives stay usable standalone, and the
+ * groups avoid colliding on shared field names (e.g. both monitors take an
+ * `intervalMs`).
+ */
+export declare function startServerDiagnostics(shared: ServerSharedServicesMinimal, options: ServerDiagnosticsOptions): () => void;
+//# sourceMappingURL=server-diagnostics.d.ts.map

package/lib/node/server-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-diagnostics.d.ts","sourceRoot":"","sources":["../../src/node/server-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,kBAAkB,EAAe,MAAM,wCAAwC,CAAC;AAC9F,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,KAAK,uBAAuB,EAAyB,MAAM,yBAAyB,CAAC;AAE9F,OAAO,EAAE,KAAK,oBAAoB,EAAsB,MAAM,qBAAqB,CAAC;AAEpF,MAAM,WAAW,wBAAwB;IACtC;;;;OAIG;IACH,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,GAAG,SAAS,GAAG,wBAAwB,CAAC,CAAC;IACzF,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,kEAAkE;IAClE,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,2BAA2B,EAAE,OAAO,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAiBzH"}

package/lib/node/server-diagnostics.js

@@ -0,0 +1,46 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { logPreamble } from '../langium/diagnostics/log-preamble.js';
+import { startEventLoopMonitor } from './event-loop-monitor.js';
+import { nodeLogPreambleSections } from './log-preamble-node.js';
+import { startMemoryMonitor } from './memory-monitor.js';
+/**
+ * The standard **Node** server-observability bringup: logs the session preamble
+ * (with Node runtime lines), an initial memory line, and starts the event-loop +
+ * heap monitors. Returns a teardown that stops both monitors.
+ *
+ * Node-only by nature — it owns the `perf_hooks` / `v8` monitors. A browser
+ * server has no such monitors; it just calls the portable
+ * {@link logPreamble} directly (no Node sections), so there is no browser
+ * counterpart to wrap.
+ *
+ * Option groups are nested (`preamble` / `eventLoop` / `memory`) and forwarded
+ * untouched to each primitive — the primitives stay usable standalone, and the
+ * groups avoid colliding on shared field names (e.g. both monitors take an
+ * `intervalMs`).
+ */
+export function startServerDiagnostics(shared, options) {
+    const { productName, version, phaseDetailThresholdMs } = options.preamble;
+    logPreamble(shared.Logger.for('LogFormat'), {
+        productName,
+        version,
+        phaseDetailThresholdMs,
+        ...nodeLogPreambleSections(phaseDetailThresholdMs)
+    });
+    if (options.logInitialMemory ?? true) {
+        shared.Tracer.for('Process').memory('Initial Memory');
+    }
+    const stopEventLoop = startEventLoopMonitor(shared, options.eventLoop);
+    const stopMemory = startMemoryMonitor(shared, options.memory);
+    return () => {
+        stopEventLoop();
+        stopMemory();
+    };
+}
+//# sourceMappingURL=server-diagnostics.js.map

package/lib/node/server-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-diagnostics.js","sourceRoot":"","sources":["../../src/node/server-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA2B,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAE9F,OAAO,EAAgC,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC9F,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAA6B,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAiBpF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAmC,EAAE,OAAiC;IAC1G,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC1E,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE;QACzC,WAAW;QACX,OAAO;QACP,sBAAsB;QACtB,GAAG,uBAAuB,CAAC,sBAAsB,CAAC;KACpD,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,gBAAgB,IAAI,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,aAAa,GAAG,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACvE,MAAM,UAAU,GAAG,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,OAAO,GAAG,EAAE;QACT,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,CAAC;IAChB,CAAC,CAAC;AACL,CAAC"}

package/lib/node/server-state-snapshot.d.ts

@@ -0,0 +1,48 @@
+/********************************************************************************
+ * 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 LangiumDocuments } from '@hydranium/langium';
+/**
+ * A document held open by one or more clients, as reported by
+ * `HydraniumTextDocuments.openDocuments()` (whose `OpenDocument` entries are
+ * structurally assignable). The `uri` is pre-formatted by the caller (canonical
+ * URI or a shortened form — the snapshot prints it as given).
+ */
+export interface OpenDocumentEntry {
+    readonly uri: string;
+    readonly clients: readonly string[];
+}
+/** Default for {@link ServerStateSnapshotOptions.openDocumentsListCap}. */
+export declare const DEFAULT_OPEN_DOCUMENTS_LIST_CAP = 25;
+/** Optional snapshot sections and their tuning knobs. */
+export interface ServerStateSnapshotOptions {
+    /**
+     * Documents currently held open with the client ids holding them (from
+     * `HydraniumTextDocuments.openDocuments()`). When set, the snapshot lists
+     * them — the observable for client-release bugs: a document that lingers
+     * here after its editor closed names the client that failed to close it,
+     * and under a shedding policy it is exactly the set excluded from CST
+     * shedding.
+     */
+    readonly openDocuments?: readonly OpenDocumentEntry[];
+    /**
+     * Open-document entries printed individually before the list is elided to
+     * `… and N more`. Default {@link DEFAULT_OPEN_DOCUMENTS_LIST_CAP}.
+     */
+    readonly openDocumentsListCap?: number;
+}
+/**
+ * Format a multi-line server-state snapshot — heap, rss, V8 stats, event-loop
+ * utilisation, CPU usage, and document counts — and return it. Pure (the caller
+ * logs the result, e.g. `tracer.info(formatServerState(...))`), matching
+ * `formatProcessMemory` / `formatPodMemory`. Tracks deltas across calls so
+ * subsequent snapshots show "since last snapshot" rates. Optional sections are
+ * requested via `options` ({@link ServerStateSnapshotOptions}).
+ */
+export declare function formatServerState(documents?: LangiumDocuments, label?: string, options?: ServerStateSnapshotOptions): string;
+//# sourceMappingURL=server-state-snapshot.d.ts.map

package/lib/node/server-state-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-state-snapshot.d.ts","sourceRoot":"","sources":["../../src/node/server-state-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAa1E;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,2EAA2E;AAC3E,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,0BAA0B;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtD;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,MAAM,CA+E5H"}