@hydranium/core 1.0.0-next.10

package/src/node/profiling-run.ts

@@ -0,0 +1,236 @@
+/********************************************************************************
+ * 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,
+   type LatencyCollector,
+   type ProfilingArtifact,
+   type ProfilingArtifactKind,
+   type ProfilingEnvironment,
+   type ProfilingManifest
+} from '@hydranium/protocol';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { profileWorkload, type ProfileCaptureOptions, type ProfileReport } from './profile-capture.js';
+import { digestAllocationProfile, digestCpuProfile, type AllocationProfile, type CpuProfile } 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 };
+export type { ProfilingArtifact, ProfilingEnvironment, ProfilingManifest };
+
+/** Options for a {@link ProfilingRun}. Environment fields are injectable so a run is reproducible in tests. */
+export interface ProfilingRunOptions {
+   /** Parent directory for the session folder; falls back to the OS temp dir when missing. */
+   directory?: string;
+   /** Session id / folder name; defaults to `profiling-<timestamp>`. */
+   sessionId?: string;
+   /** `harness` (default) for a headless run, `app` for a real deployment. */
+   mode?: 'harness' | 'app';
+   /** Override the cgroup auto-detection (mainly for tests). */
+   container?: boolean;
+   commit?: string;
+   workspace?: string;
+   /** Which dimensions each window captures (default-off, per {@link ProfileCaptureOptions}). */
+   capture?: ProfileCaptureOptions;
+   /**
+    * Optional latency collector. When present, {@link ProfilingRun.finish} writes
+    * its report to `server-latency.json` and records a `server-latency` manifest artefact. A
+    * head feeds it via the RPC binding / `instrumentLspConnection`; a pure
+    * headless build with no request traffic leaves it empty.
+    */
+   latency?: LatencyCollector;
+}
+
+/** A cgroup memory controller signals we are inside a container/pod. */
+function detectContainer(): boolean {
+   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 {
+   readonly directory: string;
+   protected readonly sessionId: string;
+   protected readonly reports: Record<string, ProfileReport> = {};
+   protected readonly artifacts: ProfilingArtifact[] = [];
+   protected readonly windows: { label: string; ms: number }[] = [];
+   protected finished = false;
+   /** The `HYDRANIUM_LOG_FILE` value seen before this run pointed it at the session (restored on {@link finish}). */
+   protected readonly previousLogFileEnv?: string;
+   /** Absolute path of the session's teed server log. */
+   readonly serverLogPath: string;
+
+   protected constructor(
+      protected readonly options: ProfilingRunOptions,
+      directory: string,
+      sessionId: string
+   ) {
+      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: ProfilingRunOptions = {}): Promise<ProfilingRun> {
+      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: ProfilingArtifactKind, filename: string, data: unknown): void {
+      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<T>(label: string, run: () => Promise<T>): Promise<T> {
+      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 as CpuProfile))
+         );
+      }
+      if (report.allocationProfilePath) {
+         this.artifacts.push(
+            this.artifactWithDigest('server-alloc', report.allocationProfilePath, label, raw =>
+               digestAllocationProfile(raw as AllocationProfile)
+            )
+         );
+      }
+      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. */
+   protected artifactWithDigest(
+      kind: ProfilingArtifactKind,
+      file: string,
+      window: string,
+      digest: (raw: unknown) => string
+   ): ProfilingArtifact {
+      const artifact: ProfilingArtifact = { kind, path: path.basename(file), window };
+      try {
+         const raw: unknown = 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(): Promise<ProfilingManifest> {
+      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: ProfilingManifest = {
+         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: string, label: string, report: ProfileReport): void {
+   fs.mkdirSync(directory, { recursive: true });
+   const file = path.join(directory, 'server-summary.json');
+   let summary: Record<string, ProfileReport> = {};
+   try {
+      const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (parsed && typeof parsed === 'object') {
+         summary = parsed as Record<string, ProfileReport>;
+      }
+   } catch {
+      // No existing summary (or unreadable) — start fresh.
+   }
+   summary[label || 'app'] = report;
+   fs.writeFileSync(file, JSON.stringify(summary, undefined, 2));
+}

package/src/node/reflect-grammar.ts

@@ -0,0 +1,182 @@
+/********************************************************************************
+ * 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, GrammarAST, GrammarUtils } 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;
+}
+
+/** Resolve a terminal rule's pattern source, tolerating rules `terminalRegex` cannot compile. */
+function terminalPattern(rule: GrammarAST.TerminalRule): string | undefined {
+   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: ReflectableLanguageServices): LanguageReflection {
+   const { Grammar: grammar, LanguageMetaData: meta } = services;
+   const terminals: TerminalReflection[] = grammar.rules.filter(GrammarAST.isTerminalRule).map(rule => ({
+      name: rule.name,
+      pattern: terminalPattern(rule),
+      hidden: rule.hidden === true
+   }));
+   const entryRule = grammar.rules.find((rule): rule is GrammarAST.ParserRule => 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: AstReflection, languages: readonly ReflectableLanguageServices[]): GrammarReflection {
+   const typeNames = [...reflection.getAllTypes()].sort((left, right) => left.localeCompare(right));
+
+   // Invert superTypes → direct subtypes in one pass.
+   const directSubTypes = new Map<string, string[]>();
+   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: TypeReflection[] = typeNames.map(name => {
+      const meta = reflection.getTypeMetaData(name);
+      const properties: PropertyReflection[] = 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: ReflectGrammarOptions): GrammarReflection {
+   const { shared } = options.createServices();
+   return collectGrammarReflection(shared.AstReflection, shared.ServiceRegistry.all);
+}

package/src/node/server-diagnostics.ts

@@ -0,0 +1,63 @@
+/********************************************************************************
+ * 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, logPreamble } from '../langium/diagnostics/log-preamble.js';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { type EventLoopMonitorOptions, startEventLoopMonitor } from './event-loop-monitor.js';
+import { nodeLogPreambleSections } from './log-preamble-node.js';
+import { type MemoryMonitorOptions, startMemoryMonitor } 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 function startServerDiagnostics(shared: ServerSharedServicesMinimal, options: ServerDiagnosticsOptions): () => void {
+   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();
+   };
+}

package/src/node/server-state-snapshot.ts

@@ -0,0 +1,192 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { Format } from '@hydranium/protocol';
+import { DocumentState, type LangiumDocuments } from '@hydranium/langium';
+import { isCstShed } from '../langium/residency/cst-residency-service.js';
+import { performance } from 'node:perf_hooks';
+import * as v8 from 'node:v8';
+
+/** Cumulative samples kept across calls so each snapshot can report deltas. */
+interface DeltaState {
+   atMs: number;
+   cpu: NodeJS.CpuUsage;
+   elu: { idle: number; active: number };
+}
+let lastSample: DeltaState | undefined;
+
+/**
+ * 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 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 function formatServerState(documents?: LangiumDocuments, label?: string, options?: ServerStateSnapshotOptions): string {
+   const now = performance.now();
+   const mem = process.memoryUsage();
+   const heap = v8.getHeapStatistics();
+   const cpu = process.cpuUsage();
+   const elu = (performance as { eventLoopUtilization?: () => { idle: number; active: number } }).eventLoopUtilization?.() ?? {
+      idle: 0,
+      active: 0
+   };
+
+   const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+   const lines: string[] = [];
+   lines.push(label ? `Server state snapshot (${label}):` : 'Server state snapshot:');
+   lines.push(`  uptime    ${formatDuration(process.uptime() * 1000)}`);
+   lines.push(
+      `  heap      ${Format.bytes(mem.heapUsed)} used / ${Format.bytes(mem.heapTotal)} total / ` +
+         `${Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`
+   );
+   lines.push(
+      `  rss       ${Format.bytes(mem.rss)}, external ${Format.bytes(mem.external)}, arrayBuffers ${Format.bytes(mem.arrayBuffers)}`
+   );
+   lines.push(
+      `  v8        malloced ${Format.bytes(heap.malloced_memory)}, peak ${Format.bytes(heap.peak_malloced_memory)}, ` +
+         `native contexts ${heap.number_of_native_contexts}, detached contexts ${heap.number_of_detached_contexts}`
+   );
+   if (lastSample) {
+      const wallMs = now - lastSample.atMs;
+      const userMs = (cpu.user - lastSample.cpu.user) / 1000;
+      const systemMs = (cpu.system - lastSample.cpu.system) / 1000;
+      const cpuPct = wallMs > 0 ? Math.round(((userMs + systemMs) / wallMs) * 100) : 0;
+      const idleDelta = elu.idle - lastSample.elu.idle;
+      const activeDelta = elu.active - lastSample.elu.active;
+      const eluTotal = idleDelta + activeDelta;
+      const eluPct = eluTotal > 0 ? Math.round((activeDelta / eluTotal) * 100) : 0;
+      lines.push(
+         `  cpu       user ${Math.round(userMs)}ms, system ${Math.round(systemMs)}ms ` + `in last ${Math.round(wallMs)}ms (${cpuPct}%)`
+      );
+      lines.push(
+         `  loop      utilization ${eluPct}% (active ${Math.round(activeDelta)}ms / ` +
+            `idle ${Math.round(idleDelta)}ms since last snapshot)`
+      );
+   } else {
+      lines.push(
+         `  cpu       user ${Math.round(cpu.user / 1000)}ms, system ${Math.round(cpu.system / 1000)}ms ` +
+            '(cumulative since process start)'
+      );
+      const eluTotal = elu.idle + elu.active;
+      const eluPct = eluTotal > 0 ? Math.round((elu.active / eluTotal) * 100) : 0;
+      lines.push(`  loop      utilization ${eluPct}% (cumulative since process start)`);
+   }
+   if (documents) {
+      const counts = countDocumentsByState(documents);
+      const total = Object.values(counts).reduce((sum, n) => sum + n, 0);
+      const breakdown = Object.entries(counts)
+         .filter(([, n]) => n > 0)
+         .map(([state, n]) => `${state}: ${n}`)
+         .join(', ');
+      lines.push(`  documents ${total} tracked${breakdown ? ` (${breakdown})` : ''}`);
+      // CST-residency breakdown — only meaningful (and only emitted) once a residency
+      // policy has shed at least one document; silent under the always-keep default.
+      const residency = countCstResidency(documents);
+      if (residency.shed > 0) {
+         lines.push(`  cst       ${residency.resident} resident, ${residency.shed} shed`);
+      }
+   }
+   const openDocuments = options?.openDocuments;
+   if (openDocuments !== undefined) {
+      const listCap = options?.openDocumentsListCap ?? DEFAULT_OPEN_DOCUMENTS_LIST_CAP;
+      lines.push(`  open      ${openDocuments.length} document(s) held by a client (excluded from CST shedding)`);
+      for (const { uri, clients } of openDocuments.slice(0, listCap)) {
+         lines.push(`            ${uri} [${clients.join(', ')}]`);
+      }
+      if (openDocuments.length > listCap) {
+         lines.push(`            … and ${openDocuments.length - listCap} more`);
+      }
+   }
+
+   lastSample = { atMs: now, cpu, elu };
+   return lines.join('\n');
+}
+
+/**
+ * Count documents whose CST is resident vs. shed by a residency policy
+ * ({@link isCstShed}). A document can also be in neither bucket — not-yet-parsed
+ * or a synthetic placeholder with no `$cstNode` at all (nothing to be "resident"
+ * or "shed") — which is intentionally counted as neither; `resident + shed` is
+ * therefore ≤ total tracked, with the remainder explained by the state breakdown
+ * on the preceding `documents` line.
+ */
+function countCstResidency(documents: LangiumDocuments): { resident: number; shed: number } {
+   let resident = 0;
+   let shed = 0;
+   for (const doc of documents.all) {
+      if (isCstShed(doc)) {
+         shed++;
+      } else if (doc.parseResult?.value?.$cstNode !== undefined) {
+         resident++;
+      }
+      // else: unparsed / synthetic — no CST, so neither resident nor shed.
+   }
+   return { resident, shed };
+}
+
+function countDocumentsByState(documents: LangiumDocuments): Record<string, number> {
+   const counts: Record<string, number> = {};
+   for (const doc of documents.all) {
+      const stateName = DocumentState[doc.state] ?? `Unknown(${doc.state})`;
+      counts[stateName] = (counts[stateName] ?? 0) + 1;
+   }
+   return counts;
+}
+
+function formatDuration(ms: number): string {
+   if (ms < 1000) {
+      return `${Math.round(ms)}ms`;
+   }
+   const totalSeconds = Math.floor(ms / 1000);
+   const seconds = totalSeconds % 60;
+   const totalMinutes = Math.floor(totalSeconds / 60);
+   const minutes = totalMinutes % 60;
+   const hours = Math.floor(totalMinutes / 60);
+   if (hours > 0) {
+      return `${hours}h ${minutes}m ${seconds}s`;
+   }
+   if (minutes > 0) {
+      return `${minutes}m ${seconds}s`;
+   }
+   return `${seconds}s`;
+}