@hydranium/core 1.0.0-next.10

package/src/langium/diagnostics/hydranium-langium-profiler.ts

@@ -0,0 +1,187 @@
+/********************************************************************************
+ * 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, Logger, type Tracer } from '@hydranium/protocol';
+import {
+   DefaultLangiumProfiler,
+   DocumentState,
+   MultiMap,
+   type ProfilingCategory,
+   type ProfilingRecord,
+   ProfilingTask
+} from '@hydranium/langium';
+import { type LogNameOptions } from './logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+
+/** Langium's full profiling-category set — the default window {@link HydraniumLangiumProfiler.flush} aggregates. */
+const ALL_CATEGORIES: readonly ProfilingCategory[] = ['parsing', 'linking', 'validating'];
+
+/** Construction options for {@link HydraniumLangiumProfiler}. */
+export interface LangiumProfilerOptions extends LogNameOptions {
+   /**
+    * Categories profiled while active. Defaults (via the base
+    * {@link DefaultLangiumProfiler}) to Langium's full set when omitted.
+    */
+   readonly activeCategories?: Set<ProfilingCategory>;
+   /**
+    * Priority of the per-build flush pass at the `Validated` phase. The flush is
+    * normally the only pass at `Validated`, so order is immaterial; the option
+    * exists for symmetry with the other framework passes. Default
+    * {@link PROFILER_FLUSH_PASS_PRIORITY}.
+    */
+   readonly flushPriority?: number;
+}
+
+/** Default priority of the profiler's per-build flush pass (see {@link LangiumProfilerOptions.flushPriority}). */
+export const PROFILER_FLUSH_PASS_PRIORITY = 0;
+
+/**
+ * Framework adapter over Langium's {@link DefaultLangiumProfiler} that is
+ * **trace-gated** and emits a single **aggregated** per-category breakdown
+ * once per build through the framework {@link Tracer}, instead of one
+ * `console.table` dump per document.
+ *
+ *  - **Aggregate, not per-document.** Langium creates one profiling task per
+ *    document (`createTask('validating', languageId)`) and the stock
+ *    {@link DefaultLangiumProfiler.dumpRecord} prints each as it completes —
+ *    dozens of near-identical blocks, all labelled with the language id (the
+ *    task identifier), so the per-document records carry no distinguishing
+ *    information anyway. We instead accumulate records in {@link records} and
+ *    {@link flush} one breakdown per category — self-time and invocation counts
+ *    summed per `$type` across the whole build — on the terminal `Validated`
+ *    build phase (self-registered in the constructor). One report per build, not
+ *    one per file.
+ *  - **Transport safety.** The stock per-record dump uses `console.table`, which
+ *    is NOT in the set `patchConsole` reroutes; under `vscode-languageserver`'s
+ *    `--stdio` transport `process.stdout` *is* the JSON-RPC channel, so the
+ *    native ASCII grid corrupts the protocol stream. {@link createTask} bypasses
+ *    `dumpRecord` entirely (records are stored, never grid-printed); {@link flush}
+ *    emits one {@link Tracer} line per row.
+ *  - **Opt-in / no production cost.** {@link isActive} is gated on the global
+ *    `trace` threshold, so at the default `info` level (and even at `debug`)
+ *    every Langium parse/link/validate guard (`profiler?.isActive(category)`)
+ *    short-circuits to `false` and no task is ever created. The per-`$type`
+ *    self-time is high-volume diagnostic detail, so it sits at the `trace` tier
+ *    deliberately — `debug` keeps the readable one-line-per-phase
+ *    `DocumentBuilder` overview without this spam. The gate is evaluated per
+ *    call, so flipping the level at runtime turns profiling on/off without a
+ *    restart. Langium's own `start`/`stop` category selection still applies *on
+ *    top of* the trace gate.
+ *
+ * Registered eagerly (see `DEFAULT_EAGER_SERVICES`) so its `Validated`-phase
+ * flush pass is registered before the first build. Gives the per-grammar-rule /
+ * per-`$type` parse/link/validate self-time the framework's own
+ * `ServerTracer` / `ProfileSession` passes
+ * cannot produce (those cover the framework's passes *outside* Langium's
+ * parse/link/validate categories).
+ */
+export class HydraniumLangiumProfiler extends DefaultLangiumProfiler {
+   /** Component-tagged tracer (`LangiumProfiler`); the per-category tag is added per flush. */
+   protected readonly tracer: Tracer;
+
+   constructor(services: ServerSharedServicesMinimal, options: LangiumProfilerOptions = {}) {
+      super(options.activeCategories);
+      this.tracer = services.Tracer.for(options.logName ?? 'LangiumProfiler').trace('instantiated');
+      // Flush once per build on the terminal phase rather than once per document.
+      // By `Validated`, every parse/link/validate record for the batch is in.
+      // Registered as a build-phase pass (not a direct onBuildPhase listener) so
+      // every framework + adopter build-phase reaction shares one dispatcher.
+      services.workspace.BuildPhasePassService.register({
+         id: 'framework:langium-profiler:flush',
+         state: DocumentState.Validated,
+         priority: options.flushPriority ?? PROFILER_FLUSH_PASS_PRIORITY,
+         run: () => this.flush()
+      });
+   }
+
+   /**
+    * A category profiles only while the global threshold admits `trace` *and*
+    * Langium's category selection has it active. The trace gate is the master
+    * switch (zero cost at `info`/`debug`); the category set is the sub-selection.
+    */
+   override isActive(category: ProfilingCategory): boolean {
+      return Logger.isLevelEnabled('trace') && super.isActive(category);
+   }
+
+   /**
+    * Accumulate each completed task's record in {@link records} for the
+    * end-of-build {@link flush}. Bypasses the base's `console.table`
+    * {@link DefaultLangiumProfiler.dumpRecord} (the `--stdio` hazard) — records
+    * are stored, never grid-printed.
+    */
+   override createTask(category: ProfilingCategory, taskId: string): ProfilingTask {
+      if (!this.isActive(category)) {
+         throw new Error(`Category "${category}" is not active.`);
+      }
+      return new ProfilingTask(record => this.records.add(category, this.captureRecord(record)), taskId);
+   }
+
+   /**
+    * Snapshot a completed record's `entries` into an independent {@link MultiMap}.
+    * {@link ProfilingTask.stop} clears its `entries` immediately after invoking
+    * this callback, and the record holds that map by reference — so the read
+    * MUST happen now (the stock `dumpRecord` reads synchronously here too).
+    * Deferring to {@link flush} without this copy would see emptied entries.
+    */
+   protected captureRecord(record: ProfilingRecord): ProfilingRecord {
+      const entries = new MultiMap<string, number>();
+      for (const key of record.entries.keys()) {
+         for (const value of record.entries.get(key)) {
+            entries.add(key, value);
+         }
+      }
+      return { ...record, entries };
+   }
+
+   /**
+    * Emit one aggregated breakdown per category — self-time and invocation
+    * counts summed per `<languageId>.<$type>` across every record collected
+    * this build — then clear the window. Self-registered as a `Validated`-phase
+    * build pass, so it fires once per build, not per document. Pass explicit
+    * categories to flush a subset; defaults to all.
+    *
+    * `flush` is the sole reset point: because it clears each flushed category,
+    * memory is bounded per completed build. A build cancelled before `Validated`
+    * leaves its partial records to roll into the next build's flush (slightly
+    * inflated counts, self-correcting) rather than accumulating without bound.
+    */
+   flush(...categories: ProfilingCategory[]): void {
+      const toFlush = categories.length > 0 ? categories : ALL_CATEGORIES;
+      for (const category of toFlush) {
+         const records = this.getRecords(category).toArray();
+         if (records.length === 0) {
+            continue;
+         }
+         const totals = new Map<string, { count: number; selfMs: number }>();
+         let totalMs = 0;
+         for (const record of records) {
+            totalMs += record.duration;
+            for (const key of record.entries.keys()) {
+               const name = `${record.identifier}.${key}`;
+               const values = record.entries.get(key);
+               const aggregate = totals.get(name) ?? { count: 0, selfMs: 0 };
+               aggregate.count += values.length;
+               aggregate.selfMs += values.reduce((sum, value) => sum + value, 0);
+               totals.set(name, aggregate);
+            }
+         }
+         const rows = [...totals.entries()]
+            .map(([name, aggregate]) => ({ name, ...aggregate }))
+            .sort((left, right) => right.selfMs - left.selfMs);
+
+         const log = this.tracer.sub(category);
+         log.trace(`${category}: ${records.length} docs, ${Format.elapsed(totalMs)} total`);
+         for (const row of rows) {
+            const pct = totalMs > 0 ? Math.round((100 * row.selfMs) / totalMs) : 0;
+            log.trace(`${row.name} ×${row.count} ${pct}% ${Format.elapsed(row.selfMs)}`);
+         }
+         this.records.delete(category);
+      }
+   }
+}

package/src/langium/diagnostics/index.ts

@@ -0,0 +1,19 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+// Node-only diagnostics (`event-loop-monitor`, `memory-monitor`,
+// `server-state-snapshot`) live in `@hydranium/core/node` — they pull
+// `node:perf_hooks` / `node:v8`. `logger`/`lsp-logger`/`log-preamble` stay
+// portable here (the file-tee + Node runtime details are injected, so the
+// barrel stays browser-executable).
+export * from './hydranium-langium-profiler.js';
+export * from './log-preamble.js';
+export * from './logger.js';
+export * from './lsp-logger.js';
+export * from './server-tracer.js';

package/src/langium/diagnostics/log-file-token.ts

@@ -0,0 +1,26 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Dependency-light on purpose: no Langium / vscode-* imports, so a Playwright
+// test helper (which correlates server logs to a workspace) can reuse the exact
+// same token derivation without pulling the language-server module graph. The
+// env-var-name conventions it pairs with live in `@hydranium/protocol`.
+
+/**
+ * Derive the `{workspace}` placeholder token from a workspace folder URI or
+ * filesystem path: its basename, with filename-unsafe characters replaced by
+ * `_`. The server (file-tee) and a log-correlating test harness call this on
+ * the same workspace path so they agree on the file name.
+ */
+export function toLogFileWorkspaceToken(uriOrPath: string): string {
+   const trimmed = uriOrPath.replace(/[/\\]+$/, '');
+   const lastSep = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+   const base = trimmed.slice(lastSep + 1);
+   return base.replace(/[^A-Za-z0-9._-]/g, '_') || 'workspace';
+}

package/src/langium/diagnostics/log-preamble.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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 { DEFER_START_MS, type Logger } from '@hydranium/protocol';
+
+const DIVIDER = '───────────────────────────────────────────────────────────────────';
+
+export interface LogPreambleOptions {
+   /** Product name shown in the session header. */
+   productName: string;
+   /** Resolved product version. */
+   version: string;
+   /**
+    * Threshold (ms) above which the framework emits per-phase rebuild detail in
+    * its document builder. Used in the format-conventions section so log readers
+    * know which timings expand into sub-phases. Defaults to 50.
+    */
+   phaseDetailThresholdMs?: number;
+   /**
+    * Extra session-info lines appended to the header block (e.g. Node
+    * runtime / platform / pid / heap-limit / host). Empty on portable hosts;
+    * `@hydranium/core/node`'s `nodeSystemInfoLines()` supplies them on Node.
+    */
+   systemInfoLines?: readonly string[];
+   /**
+    * Extra format-convention lines appended to the conventions block (e.g. the
+    * Node-only `[EventLoop]` / `[Memory]` monitor + memory-suffix behaviour).
+    * Empty on portable hosts; `@hydranium/core/node`'s `nodeConventionLines()`
+    * supplies them on Node.
+    */
+   conventionLines?: readonly string[];
+}
+
+/**
+ * Emits session info and log format conventions. The body is portable
+ * (browser-safe); Node-specific runtime details and monitor conventions are
+ * injected via {@link LogPreambleOptions.systemInfoLines} /
+ * {@link LogPreambleOptions.conventionLines} (see `@hydranium/core/node`).
+ */
+export function logPreamble(logger: Logger, options: LogPreambleOptions): void {
+   logSessionInfo(logger, options.productName, options.version, options.systemInfoLines ?? []);
+   logFormatConventions(logger, options.phaseDetailThresholdMs ?? 50, options.conventionLines ?? []);
+}
+
+function logSessionInfo(logger: Logger, productName: string, version: string, systemInfoLines: readonly string[]): void {
+   const now = new Date();
+   const dateStr = now.toISOString().slice(0, 10); // YYYY-MM-DD, unambiguous across midnight
+   const lines = [
+      DIVIDER,
+      `${productName} server session`,
+      DIVIDER,
+      `date        ${dateStr}`,
+      `version     ${version}`,
+      ...systemInfoLines,
+      DIVIDER
+   ];
+   for (const line of lines) {
+      logger.info(line);
+   }
+}
+
+function logFormatConventions(logger: Logger, phaseDetailThresholdMs: number, conventionLines: readonly string[]): void {
+   const lines = [
+      'Log format conventions',
+      DIVIDER,
+      '• Timing pairs:   "<op> [#N start]"  ->  "<op> [#N done|cancelled|failed, Nms]"',
+      '• Rebuild tags:   contextual metadata lives inside the status brackets, e.g.',
+      '                  "[#N start, event: didChangeContent, cancels #M]"',
+      `• Quiet ops:      operations under ${DEFER_START_MS}ms are silent; lifecycle ops (save, load) always log`,
+      '                  (failures/cancels always log, even below the threshold - in that case',
+      '                  [start] is emitted retroactively so timestamps may be back-to-back while',
+      '                  the reported Nms is the real elapsed time)',
+      `• Phase detail:   Parsed/IndexedContent/.../Validated shown only for rebuilds >=${phaseDetailThresholdMs}ms;`,
+      '                  workspace init always emits per-phase lines live',
+      ...conventionLines,
+      DIVIDER
+   ];
+   for (const line of lines) {
+      logger.info(line);
+   }
+}

package/src/langium/diagnostics/logger.ts

@@ -0,0 +1,246 @@
+/********************************************************************************
+ * 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 { currentMemoryUsage, onProcessEvent, processPid } from '../../util/environment.js';
+
+/** Only append a memory suffix when the heap has moved by at least this much since the last log line. */
+export const MEMORY_DELTA_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Pluggable file-tee sink. The file-tee's only platform coupling is the
+ * actual disk write + directory create; routing those through an injected
+ * sink keeps this module free of `node:fs` so it stays on the portable `.`
+ * entry. `@hydranium/core/node` installs a `node:fs`-backed sink (see
+ * `installNodeLogFileSink`); when
+ * no sink is installed (browser / in-memory hosts) the file-tee is inert and
+ * lines fan out only to the LSP/console destination. Configuring a tee target
+ * (`HYDRANIUM_LOG_FILE`) is itself Node-only, so the inert path is never hit
+ * in a browser.
+ */
+export interface LogFileSink {
+   /** Append already-formatted text to the file at `path`. Must not throw. */
+   append(path: string, data: string): void;
+   /** Best-effort create of the parent directory for `path`. Must not throw. */
+   ensureDir(path: string): void;
+}
+
+let fileSink: LogFileSink | undefined;
+
+/** Install (or clear, with `undefined`) the file-tee sink. Idempotent. */
+export function setLogFileSink(sink: LogFileSink | undefined): void {
+   fileSink = sink;
+}
+
+/**
+ * File-tee state for `LspLogger`'s emit. When
+ * non-empty, every formatted log line is appended to the path in addition to
+ * its LSP `window/logMessage` / console destination (see {@link teeLogLine}).
+ * Diagnostic surface only — once the LSP connection binds, server logs route
+ * through `connection.console.*` and disappear from any pipe watching backend
+ * stdout; setting this path makes them visible to a headless test harness
+ * without scraping the client's Output view.
+ *
+ * The sink writes synchronously, so log lines preserve emission order; errors
+ * are swallowed because a failing log sink must not propagate.
+ * Append-only — the path is the consumer's responsibility to truncate / rotate.
+ *
+ * Raw configured target — may contain `{placeholder}` tokens (e.g.
+ * `{workspace}`) that are not known at module-load time.
+ */
+let logFileTemplate: string | undefined;
+/** Fully-resolved target (no remaining placeholders). `undefined` while pending. */
+let resolvedLogFilePath: string | undefined;
+/** Placeholder values supplied so far via {@link resolveLogFilePlaceholder}. */
+const logFilePlaceholders = new Map<string, string>();
+/**
+ * Lines emitted while the target is still pending (placeholders unresolved).
+ * Flushed verbatim — preserving emission order — once the target resolves, so
+ * no startup line is ever dropped. Each entry already carries its trailing `\n`.
+ */
+const pendingLogLines: string[] = [];
+
+/** Matches any remaining `{name}` placeholder token. */
+const PLACEHOLDER_PATTERN = /\{[^}]+\}/;
+
+/**
+ * Recompute {@link resolvedLogFilePath} from the template + known placeholders.
+ * Resolves (and flushes the pending buffer) only once no `{...}` token remains.
+ */
+function tryResolveLogFilePath(): void {
+   if (!logFileTemplate) {
+      resolvedLogFilePath = undefined;
+      return;
+   }
+   let path = logFileTemplate;
+   for (const [name, value] of logFilePlaceholders) {
+      path = path.split(`{${name}}`).join(value);
+   }
+   if (PLACEHOLDER_PATTERN.test(path)) {
+      resolvedLogFilePath = undefined;
+      // Target is pending — guarantee the buffer is flushed even if the process
+      // exits before the remaining placeholders are ever supplied.
+      ensureFallbackHandler();
+      return;
+   }
+   resolvedLogFilePath = path;
+   ensureLogDir(path);
+   flushPendingLogLines();
+}
+
+/**
+ * Best-effort create of the target's parent directory. Covers the headless-test
+ * case where the runner wipes the output directory before the server writes its
+ * log under it. Failures are swallowed — a log sink must never propagate.
+ */
+function ensureLogDir(filePath: string): void {
+   // No-op when no sink is installed (browser); the Node sink swallows its own errors.
+   fileSink?.ensureDir(filePath);
+}
+
+/** Append the buffered lines to the resolved target, then clear the buffer. */
+function flushPendingLogLines(): void {
+   if (!resolvedLogFilePath || pendingLogLines.length === 0) {
+      return;
+   }
+   fileSink?.append(resolvedLogFilePath, pendingLogLines.join(''));
+   pendingLogLines.length = 0;
+}
+
+/**
+ * Set the file-tee target programmatically. Pass `undefined` to disable. The
+ * path may contain `{placeholder}` tokens (e.g. `{workspace}`); lines buffer
+ * until every token is supplied via {@link resolveLogFilePlaceholder}.
+ * Called by the `LspLogger` constructor's
+ * one-time `HYDRANIUM_LOG_FILE` env baseline (and by tests).
+ */
+export function setLogFilePath(path: string | undefined): void {
+   logFileTemplate = path && path.length > 0 ? path : undefined;
+   logFilePlaceholders.clear();
+   pendingLogLines.length = 0;
+   resolvedLogFilePath = undefined;
+   tryResolveLogFilePath();
+}
+
+/**
+ * Supply a value for a `{name}` placeholder in the configured target. Once the
+ * last placeholder is supplied the target resolves and any lines buffered while
+ * it was pending are flushed in emission order.
+ */
+export function resolveLogFilePlaceholder(name: string, value: string): void {
+   logFilePlaceholders.set(name, value);
+   tryResolveLogFilePath();
+}
+
+/**
+ * Last-resort flush for the case where the target never resolves (e.g. the
+ * server crashed before the workspace was known). Substitutes any remaining
+ * `{...}` token with a process-unique `_startup-<pid>` segment and flushes the
+ * buffer, so startup / failure lines are never lost. No-op when the target is
+ * already resolved or there is nothing buffered. Registered on `process.exit`
+ * as soon as an unresolved target is configured.
+ */
+export function flushLogFileFallback(): void {
+   if (!logFileTemplate || resolvedLogFilePath || pendingLogLines.length === 0) {
+      return;
+   }
+   resolvedLogFilePath = logFileTemplate.replace(/\{[^}]+\}/g, `_startup-${processPid() ?? 'unknown'}`);
+   ensureLogDir(resolvedLogFilePath);
+   flushPendingLogLines();
+}
+
+/** Registered at most once; flushes any pending buffer on process teardown. */
+let fallbackHandlerRegistered = false;
+function ensureFallbackHandler(): void {
+   if (fallbackHandlerRegistered) {
+      return;
+   }
+   fallbackHandlerRegistered = true;
+   // Node-only teardown flush; a no-op in a browser worker (no `exit` event).
+   onProcessEvent('exit', () => flushLogFileFallback());
+}
+
+/** Current resolved file-tee target. `undefined` when disabled or still pending. */
+export function getLogFilePath(): string | undefined {
+   return resolvedLogFilePath;
+}
+
+/**
+ * Fan a single already-formatted log line out to the file-tee target, if one is
+ * configured. Called by `LspLogger`'s emit in
+ * addition to the LSP/console sink — log sinks fan out, they don't replace.
+ * While the target is still pending (unresolved `{placeholder}`), the line is
+ * buffered instead of dropped.
+ */
+export function teeLogLine(formatted: string): void {
+   if (!logFileTemplate) {
+      return;
+   }
+   const line = `${formatted}\n`;
+   if (resolvedLogFilePath) {
+      // The sink swallows its own errors; recursing into the logger here would
+      // re-enter emit and loop. The LSP/console sink already delivered the line.
+      fileSink?.append(resolvedLogFilePath, line);
+   } else {
+      pendingLogLines.push(line);
+   }
+}
+
+// Re-exported so the token derivation is reachable from the diagnostics barrel.
+// It is defined in a standalone, dependency-light module so a Playwright test
+// helper can import it directly without pulling the barrel's module graph.
+export { toLogFileWorkspaceToken } from './log-file-token.js';
+
+/**
+ * Shared options-base for every framework-bound service that derives a
+ * `Tracer` (or
+ * `Logger`) from its `services`
+ * constructor parameter. Carries the `logName` label used to identify the
+ * service in its log / trace output and in the startup instantiation trace.
+ *
+ * The field name reads from the adopter's perspective — `logName` is "the
+ * name this service appears under in the log". Distinct from
+ * `LspLoggerOptions.component`, which is the logger's own identity field
+ * (matches `AbstractLogger.component` and `Logger.for`'s argument).
+ *
+ * A framework service's constructor stores a tracer named by `logName` and
+ * emits a single instantiation trace. The fallback used when `logName` is
+ * absent is chosen per service: a fixed curated string where the slot has one
+ * canonical implementation, or `this.constructor.name` where it has swappable
+ * strategy bindings, so the log shows which implementation ran. The
+ * framework's default `Logger` level is `'info'`, so those trace lines are
+ * no-ops in production; raising the level to `trace` — directly or via the
+ * LSP-config-bound setting — before workspace load makes startup
+ * instantiation visible.
+ */
+export interface LogNameOptions {
+   /**
+    * Name passed to `Tracer.for(...)` / `Logger.for(...)` — the label the
+    * service appears under in its log / trace output. Optional; each
+    * service supplies its own default (a fixed curated string, or
+    * `this.constructor.name`). Override when the runtime class name is
+    * generic (anonymous adopter subclass) or when multiple instances of
+    * the same class are bound to distinct slots and the adopter wants to
+    * disambiguate them in the log.
+    */
+   readonly logName?: string;
+}
+
+/**
+ * Format current memory as "heap used/total, rss N". Returns `''` where
+ * `process.memoryUsage` is unavailable (browser) so callers can append it
+ * unconditionally.
+ */
+export function formatMemory(): string {
+   const mem = currentMemoryUsage();
+   if (!mem) {
+      return '';
+   }
+   return `heap ${Format.bytes(mem.heapUsed)}/${Format.bytes(mem.heapTotal)}, rss ${Format.bytes(mem.rss)}`;
+}