@hydranium/core 1.0.0-next.33 → 1.0.0-next.331

package/src/langium/composite-ast-reflection.ts

@@ -0,0 +1,112 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { AbstractAstReflection, type AstMetaData, type AstReflection, type PropertyMetaData, type TypeMetaData } from '@hydranium/langium';
+import { assertSingleLangiumCopy } from './single-langium-copy.js';
+
+/**
+ * One `AstReflection` over the reflections of separately generated language
+ * packages. The shared `AstReflection` slot holds a single reflection, so
+ * binding each package's generated shared module keeps only the last one's
+ * types; bind this over all of them instead.
+ *
+ * A name several reflections share is taken to be one type, reached through a
+ * shared imported grammar, and keeps every super type any of them gives it:
+ * each grammar may declare its own union over the type. Only properties that
+ * differ in name, reference type or default value throw; two unrelated unions,
+ * or same-shaped interfaces, that share a name merge silently, so keep other
+ * type names distinct across packages.
+ *
+ * Only each reflection's `types` is read, so behaviour a reflection overrides
+ * is lost. Each package's generated `isX` guards keep using that package's own
+ * reflection and answer false for subtypes only another package declares.
+ *
+ * Each reflection is checked with {@link assertSingleLangiumCopy}, because the
+ * composite itself extends the framework copy's base whichever copy they use.
+ *
+ * The protected merge methods run from the constructor, so an override cannot
+ * read its own class's fields.
+ */
+export class CompositeAstReflection extends AbstractAstReflection {
+   override readonly types: AstMetaData = {};
+
+   constructor(reflections: readonly AstReflection[]) {
+      super();
+      const firstDefinedAt = new Map<string, number>();
+      reflections.forEach((reflection, index) => {
+         assertSingleLangiumCopy(reflection, () => this.formatReflection(reflections, index));
+         for (const [type, metaData] of Object.entries(reflection.types)) {
+            const ownerIndex = firstDefinedAt.get(type);
+            if (ownerIndex === undefined) {
+               this.types[type] = metaData;
+               firstDefinedAt.set(type, index);
+            } else {
+               this.types[type] = this.mergeTypeMetaData(
+                  this.types[type],
+                  metaData,
+                  this.formatReflection(reflections, ownerIndex),
+                  this.formatReflection(reflections, index)
+               );
+            }
+         }
+      });
+   }
+
+   protected mergeTypeMetaData(known: TypeMetaData, added: TypeMetaData, knownFrom: string, addedFrom: string): TypeMetaData {
+      const properties: TypeMetaData['properties'] = {};
+      const propertyNames = new Set([...Object.keys(known.properties), ...Object.keys(added.properties)]);
+      for (const property of propertyNames) {
+         const knownProperty = known.properties[property];
+         const addedProperty = added.properties[property];
+         if (!knownProperty || !addedProperty || !this.sameProperty(knownProperty, addedProperty)) {
+            throw new Error(
+               `[hydranium] ${knownFrom} and ${addedFrom} define the type ` +
+                  `'${known.name}' differently (property '${property}'). A name the composed reflections share must ` +
+                  'denote one type, so rename one of them, or have every grammar take the type unchanged from one ' +
+                  'shared imported grammar.'
+            );
+         }
+         properties[property] = addedProperty.optional && !knownProperty.optional ? addedProperty : knownProperty;
+      }
+      // `Required` so a field Langium adds fails compilation until this merge decides on it.
+      const merged: Required<TypeMetaData> = {
+         name: known.name,
+         properties,
+         superTypes: [...new Set([...known.superTypes, ...added.superTypes])]
+      };
+      return merged;
+   }
+
+   protected sameProperty(left: PropertyMetaData, right: PropertyMetaData): boolean {
+      return COMPARED_PROPERTY_FIELDS.every(field => JSON.stringify(left[field]) === JSON.stringify(right[field]));
+   }
+
+   /**
+    * Names `reflections[index]` for the composite's errors: its position and
+    * class name. The position is needed because minified bundles and scaffolds
+    * sharing a project name leave class names that do not tell reflections
+    * apart. An override can name the package each reflection came from.
+    */
+   protected formatReflection(reflections: readonly AstReflection[], index: number): string {
+      return `reflections[${index}] (${reflections[index].constructor?.name ?? 'no constructor'})`;
+   }
+}
+
+/** How the merge treats each property field; a field Langium adds fails compilation here until decided. */
+const PROPERTY_FIELDS = {
+   name: 'compared',
+   referenceType: 'compared',
+   defaultValue: 'compared',
+   // Older generators emit no `optional`, so its absence proves nothing.
+   optional: 'merged'
+} as const satisfies Record<keyof PropertyMetaData, 'compared' | 'merged'>;
+
+const COMPARED_PROPERTY_FIELDS = (Object.keys(PROPERTY_FIELDS) as Array<keyof PropertyMetaData>).filter(
+   field => PROPERTY_FIELDS[field] === 'compared'
+);

package/src/langium/config/configuration-provider.ts

@@ -0,0 +1,119 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 ConfigurationInitializedParams, DefaultConfigurationProvider } from '@hydranium/langium';
+import type { ConfigurationItem, DidChangeConfigurationRegistrationOptions } from 'vscode-languageserver';
+
+/**
+ * Configuration provider that asks the client about a section the first time
+ * something reads it.
+ *
+ * Langium's base requests one section per registered language, named after the
+ * language id, and never asks again. A read of any other section — including
+ * whatever `lsp.configurationRoot` is bound to — then resolves `undefined` with
+ * no request on the wire, which is indistinguishable from a setting the user has
+ * not set.
+ *
+ * Asking on first read rather than from a list collected up front: a reader
+ * names its section during DI, after `initialized` has taken its one-shot pass,
+ * so a list would have to be complete before the server initialized.
+ */
+export class HydraniumConfigurationProvider extends DefaultConfigurationProvider {
+   /**
+    * The client-facing hooks, captured because they arrive once as arguments to
+    * {@link initialized} and are needed on every later read. Absent in a
+    * headless composition, which has no connection to ask.
+    */
+   protected registerForSection?: (params: DidChangeConfigurationRegistrationOptions) => void;
+   protected fetchSections?: (items: ConfigurationItem[]) => Promise<unknown>;
+
+   /**
+    * Sections already dealt with, holding the in-flight work so concurrent
+    * readers share one round trip. Entries stay after they settle: they record
+    * that the section was HANDLED, and without that an unset section is
+    * re-requested on every read, "unset" and "not fetched" being the same
+    * absence in the store.
+    *
+    * A section the client's capabilities ruled out counts as handled, having
+    * been settled by asking nothing.
+    */
+   protected readonly requestedSections = new Map<string, Promise<void>>();
+
+   override async initialized(params: ConfigurationInitializedParams): Promise<void> {
+      this.registerForSection = params.register;
+      this.fetchSections = params.fetchConfiguration;
+      await super.initialized(params);
+   }
+
+   /**
+    * The `ready` await precedes the emptiness check: the base resolves it at the
+    * end of its own initial fetch, so testing the store first calls every
+    * language section missing and re-requests what is already on its way.
+    */
+   override async getConfiguration(language: string, configuration: string): Promise<unknown> {
+      await this.ready;
+      const section = this.toSectionName(language);
+      if (this.settings[section] === undefined) {
+         await this.requestSection(section);
+      }
+      return super.getConfiguration(language, configuration);
+   }
+
+   /** Ask about `section` once, sharing the request with any concurrent reader. */
+   protected requestSection(section: string): Promise<void> {
+      const existing = this.requestedSections.get(section);
+      if (existing) {
+         return existing;
+      }
+      const request = this.doRequestSection(section);
+      this.requestedSections.set(section, request);
+      return request;
+   }
+
+   /**
+    * The hooks are gated on the client having declared `workspace.configuration`.
+    * A connection binds them whatever the client said, so their presence is not
+    * consent: calling them sends a `client/registerCapability` and a
+    * `workspace/configuration` to a client that advertised support for neither,
+    * which is entitled to answer either with a method-not-found and may drop the
+    * connection.
+    *
+    * That flag is exact for the fetch and KNOWINGLY coarse for the registration,
+    * which the spec governs by
+    * `workspace.didChangeConfiguration.dynamicRegistration`. The base registers
+    * under `workspace.configuration` alone before any of this runs, so gating
+    * the registration on the narrower flag here would withhold a request whose
+    * twin has already gone out, sparing the client nothing. A client declaring
+    * `workspace.configuration` without dynamic registration is still registered
+    * for, by the base and by this; closing that means changing the base's pass,
+    * not this gate.
+    *
+    * Registering before fetching, so an edit landing between the two arrives as
+    * a notification instead of being lost; the reverse order drops it.
+    *
+    * A `null` result is left out of the store rather than written, so the
+    * section reads as unset, and no `onConfigurationSectionUpdate` fires — the
+    * value goes to the caller that asked for it, and an event would announce a
+    * change that is only this provider catching up.
+    */
+   protected async doRequestSection(section: string): Promise<void> {
+      if (!this.workspaceConfig) {
+         return;
+      }
+      this.registerForSection?.({ section });
+      if (!this.fetchSections) {
+         return;
+      }
+      const fetched = await this.fetchSections([{ section }]);
+      const value = Array.isArray(fetched) ? fetched[0] : fetched;
+      if (value !== null && value !== undefined) {
+         this.updateSectionConfiguration(section, value);
+      }
+   }
+}

package/src/langium/config/index.ts

@@ -7,4 +7,5 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './configuration-provider.js';
 export * from './settings.js';

package/src/langium/diagnostics/console-tee.ts

@@ -0,0 +1,151 @@
+/********************************************************************************
+ * Copyright (c) 2026 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, LEVEL_LABELS, type LogLevel, SystemClock } from '@hydranium/protocol';
+import { formatLogArg } from './format-log-arg.js';
+import { teeLogLine } from './logger.js';
+import { hasProcessStderr } from '../../util/environment.js';
+import { isConnectionGoneError } from '../../util/connection-liveness.js';
+
+/** The `console` methods {@link installConsoleTee} wraps, with the level and label each line is written at. */
+const CONSOLE_TEE: ReadonlyArray<readonly ['error' | 'warn' | 'info' | 'log' | 'debug', LogLevel, string]> = [
+   ['error', 'error', LEVEL_LABELS.error],
+   ['warn', 'warn', LEVEL_LABELS.warn],
+   ['info', 'info', LEVEL_LABELS.info],
+   ['log', 'info', 'Log'],
+   ['debug', 'debug', LEVEL_LABELS.debug]
+];
+
+/** The wrappers this copy installed, so installing again wraps only a method that is none of them. */
+const tees = new WeakSet<object>();
+/**
+ * Whether a line is being written or handed on: a console call made meanwhile,
+ * by a sink or a library wrapper between two installs, is only handed on.
+ */
+let handling = false;
+/**
+ * What a line is stamped with: not a logger's injected clock, whose service a
+ * console call made while another service is built could resolve into a cycle.
+ */
+const systemClock = new SystemClock();
+/**
+ * How a line's arguments are rendered, Node's `util.format` where the `./node`
+ * entry set it: unlike JSON, it runs no ordinary getter and no proxy trap of an
+ * argument it inspects, the traps a services container builds a service in.
+ */
+let format: ((...args: unknown[]) => string) | undefined;
+
+/** Render console lines with `render`, as `installNodeLogFileSink` does with Node's `util.format`. */
+export function setConsoleFormat(render: (...args: unknown[]) => string): void {
+   format = render;
+}
+
+/**
+ * Write each line sent through a {@link CONSOLE_TEE} method, as Langium
+ * reports a linker or validator failure, to this copy's log file under a
+ * `console` component, then hand it to the method it replaced, even when
+ * writing the file fails. The file goes first because the method a stdio
+ * connection installs throws once the connection is closed, unless its remote
+ * console catches that, as `withHydraniumLspFeatures`'s does.
+ *
+ * Node only: in a browser no file is written, and a wrapper would only stand
+ * between devtools and the call site. Called by the first `LspLogger`, and by
+ * `startLanguageServer`, which wraps again where a logger existed before a
+ * stdio connection replaced `error`, `warn`, `log` and `debug`. A console
+ * replaced after that is not wrapped again, and each copy of this package
+ * wraps the console itself, so a file two copies share gets a line twice.
+ */
+export function installConsoleTee(): void {
+   if (!hasProcessStderr()) {
+      return;
+   }
+   for (const [method, level, label] of CONSOLE_TEE) {
+      try {
+         wrap(method, level, label);
+      } catch {
+         // A host whose console is read-only, or throws when read, keeps its methods, unwritten.
+      }
+   }
+}
+
+/** Replace `console[method]` by a tee writing its lines at `level` under `label`, unless it is already one of this copy's tees. */
+function wrap(method: (typeof CONSOLE_TEE)[number][0], level: LogLevel, label: string): void {
+   const passOn = console[method];
+   if (tees.has(passOn)) {
+      return;
+   }
+   const tee = (...args: unknown[]): void => {
+      if (handling) {
+         Reflect.apply(passOn, console, args);
+         return;
+      }
+      handling = true;
+      try {
+         try {
+            const [lineLevel, lineLabel] = isDebugLine(args)
+               ? (['debug', LEVEL_LABELS.debug] as const)
+               : level === 'error' && isNodeWarning(args)
+                 ? (['warn', LEVEL_LABELS.warn] as const)
+                 : [level, label];
+            // As `AbstractLogger.formatLinePrefix` starts a line.
+            teeLogLine(
+               lineLevel,
+               () => `[${lineLabel.padEnd(5)} - ${Format.timestamp(new Date(systemClock.now()))}] [console] ${formatArgs(args)}`
+            );
+         } catch {
+            // A failing log sink must not propagate, nor keep the line from `passOn`.
+         }
+         Reflect.apply(passOn, console, args);
+      } finally {
+         handling = false;
+      }
+   };
+   console[method] = tee;
+   tees.add(tee);
+}
+
+/** `args` as the console prints them, or by {@link formatLogArg} where that throws, as for an error whose stack throws when read. */
+function formatArgs(args: unknown[]): string {
+   if (format) {
+      try {
+         return format(...args);
+      } catch {
+         // Described below instead.
+      }
+   }
+   return args.map(formatLogArg).join(' ');
+}
+
+/**
+ * How Node's default warning handler starts what it prints through
+ * `console.error`: the runtime's release name and pid, the warning's code if
+ * it has one, and its type, as `(node:42) [DEP0005] DeprecationWarning: `.
+ */
+const NODE_WARNING = /^\([\w-]+:\d+\) (\[\w+\] )?\w*Warning: /;
+
+/** Whether `args` is a Node process warning, a deprecation say, which is written at `warn`. */
+function isNodeWarning(args: readonly unknown[]): boolean {
+   return args.length === 1 && typeof args[0] === 'string' && NODE_WARNING.test(args[0]);
+}
+
+/** What Langium's `initialized` handler logs when a service's start rejects. */
+const LANGIUM_START_FAILURES = new Set<unknown>([
+   'Error in ConfigurationProvider initialization:',
+   'Error in WorkspaceManager initialization:'
+]);
+
+/**
+ * Whether `args` reports routine teardown, which is written at `debug`:
+ * Langium's failed configuration or workspace start whose connection has gone.
+ * `vscode-languageserver`'s `Sending log message failed` is not, since it
+ * carries no reason; `withHydraniumLspFeatures` keeps teardown from printing it.
+ */
+function isDebugLine(args: readonly unknown[]): boolean {
+   return args.length === 2 && LANGIUM_START_FAILURES.has(args[0]) && isConnectionGoneError(args[1]);
+}

package/src/langium/diagnostics/format-log-arg.ts

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { describeErrorWithStack } from '@hydranium/protocol';
+
+/**
+ * Render a log argument for the single string a line carries, to the LSP
+ * `window/logMessage` channel and the log file: a string as it is, an error by
+ * its stack and causes, another object as JSON, and anything else, what JSON
+ * renders as nothing or cannot render included, by its description. Never
+ * throws, since a log call that throws loses the line and interrupts its
+ * caller. A `%s`-style specifier is not substituted.
+ */
+export function formatLogArg(value: unknown): string {
+   if (typeof value === 'string') {
+      return value;
+   }
+   if (typeof value === 'object' && value !== null) {
+      try {
+         // `undefined` where `toJSON` returns nothing.
+         const json: string | undefined = value instanceof Error ? undefined : JSON.stringify(value);
+         if (json !== undefined) {
+            return json;
+         }
+      } catch {
+         // Cyclic, not serialisable, or a revoked proxy; described below instead.
+      }
+   }
+   return describeErrorWithStack(value);
+}

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

@@ -8,14 +8,7 @@
  ********************************************************************************/
 
 import { Format, Logger, type Tracer } from '@hydranium/protocol';
-import {
-   DefaultLangiumProfiler,
-   DocumentState,
-   MultiMap,
-   type ProfilingCategory,
-   type ProfilingRecord,
-   ProfilingTask
-} from '@hydranium/langium';
+import { DefaultLangiumProfiler, MultiMap, type ProfilingCategory, type ProfilingRecord, ProfilingTask } from '@hydranium/langium';
 import { type LogNameOptions } from './logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 
@@ -29,18 +22,8 @@ export interface LangiumProfilerOptions extends LogNameOptions {
     * {@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
@@ -54,9 +37,8 @@ export const PROFILER_FLUSH_PASS_PRIORITY = 0;
  *    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.
+ *    summed per `$type` across the whole build — when the build ends
+ *    (subscribed 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
@@ -74,8 +56,8 @@ export const PROFILER_FLUSH_PASS_PRIORITY = 0;
  *    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 /
+ * Registered eagerly (see `DEFAULT_EAGER_SERVICES`) so its flush is
+ * subscribed 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
@@ -88,16 +70,11 @@ export class HydraniumLangiumProfiler extends DefaultLangiumProfiler {
    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()
-      });
+      // Flush once per build when it ends rather than once per document. Not at
+      // a `Validated` pass: that phase stays silent for a build that validates
+      // nothing, the workspace's initial one among them, and the records would
+      // then wait for a build that does.
+      services.workspace.DocumentBuilder.onBuildEnded(() => this.flush());
    }
 
    /**
@@ -142,14 +119,13 @@ export class HydraniumLangiumProfiler extends DefaultLangiumProfiler {
    /**
     * 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.
+    * this build — then clear the window. Called when a build ends, 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.
+    * memory is bounded per build. Builds that throw share one flush, once the
+    * lock has drained after them.
     */
    flush(...categories: ProfilingCategory[]): void {
       const toFlush = categories.length > 0 ? categories : ALL_CATEGORIES;

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

@@ -50,7 +50,7 @@ export function logPreamble(logger: Logger, options: LogPreambleOptions): void {
 
 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 dateStr = now.toISOString().slice(0, 10); // YYYY-MM-DD in UTC, which can differ from the reader's local date
    const lines = [
       DIVIDER,
       `${productName} server session`,

package/src/langium/diagnostics/logger.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Format } from '@hydranium/protocol';
+import { Format, LEVEL_ORDER, type LogLevel, Logger, type LogThreshold } 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. */
@@ -39,7 +39,7 @@ export function setLogFileSink(sink: LogFileSink | undefined): void {
 }
 
 /**
- * File-tee state for `LspLogger`'s emit. When
+ * File-tee state for `LspLogger`'s emit and the console tee. 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
@@ -69,6 +69,28 @@ const pendingLogLines: string[] = [];
 /** Matches any remaining `{name}` placeholder token. */
 const PLACEHOLDER_PATTERN = /\{[^}]+\}/;
 
+/**
+ * `template` with `{pid}` replaced by the process id, known from the start, and
+ * each placeholder supplied so far by its value.
+ */
+function substituteLogFilePlaceholders(template: string): string {
+   let path = template.split('{pid}').join(String(processPid() ?? 'unknown'));
+   for (const [name, value] of logFilePlaceholders) {
+      path = path.split(`{${name}}`).join(value);
+   }
+   return path;
+}
+
+/**
+ * Expand `template` the way the file-tee names its file: `{pid}` and each
+ * supplied placeholder by its value, each one still missing by
+ * `_startup-<pid>`. A file written beside the log, such as the CPU profile,
+ * names itself through this so both carry the same workspace token.
+ */
+export function expandLogFilePlaceholders(template: string): string {
+   return substituteLogFilePlaceholders(template).replace(new RegExp(PLACEHOLDER_PATTERN, 'g'), `_startup-${processPid() ?? 'unknown'}`);
+}
+
 /**
  * Recompute {@link resolvedLogFilePath} from the template + known placeholders.
  * Resolves (and flushes the pending buffer) only once no `{...}` token remains.
@@ -78,10 +100,7 @@ function tryResolveLogFilePath(): void {
       resolvedLogFilePath = undefined;
       return;
    }
-   let path = logFileTemplate;
-   for (const [name, value] of logFilePlaceholders) {
-      path = path.split(`{${name}}`).join(value);
-   }
+   const path = substituteLogFilePlaceholders(logFileTemplate);
    if (PLACEHOLDER_PATTERN.test(path)) {
       resolvedLogFilePath = undefined;
       // Target is pending — guarantee the buffer is flushed even if the process
@@ -116,12 +135,19 @@ function flushPendingLogLines(): void {
 /**
  * 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}.
+ * until every token is supplied via {@link resolveLogFilePlaceholder}, except
+ * `{pid}`, which is the process id from the start.
  * Called by the `LspLogger` constructor's
  * one-time `HYDRANIUM_LOG_FILE` env baseline (and by tests).
+ *
+ * `level` becomes `Logger.setFileLevel`, cleared with the target and when
+ * omitted. Setting the file level apart from the target lets it outlive the
+ * file, and every sender keeps building lines above the process threshold
+ * that nothing writes.
  */
-export function setLogFilePath(path: string | undefined): void {
+export function setLogFilePath(path: string | undefined, level?: LogThreshold): void {
    logFileTemplate = path && path.length > 0 ? path : undefined;
+   Logger.setFileLevel(logFileTemplate ? level : undefined);
    logFilePlaceholders.clear();
    pendingLogLines.length = 0;
    resolvedLogFilePath = undefined;
@@ -150,7 +176,7 @@ export function flushLogFileFallback(): void {
    if (!logFileTemplate || resolvedLogFilePath || pendingLogLines.length === 0) {
       return;
    }
-   resolvedLogFilePath = logFileTemplate.replace(/\{[^}]+\}/g, `_startup-${processPid() ?? 'unknown'}`);
+   resolvedLogFilePath = expandLogFilePlaceholders(logFileTemplate);
    ensureLogDir(resolvedLogFilePath);
    flushPendingLogLines();
 }
@@ -173,20 +199,28 @@ export function getLogFilePath(): string | undefined {
 
 /**
  * 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.
+ * configured and `level` is within the file's threshold
+ * (`Logger.getFileLevel() ?? Logger.getLevel()`). Called by `LspLogger`'s emit in
+ * addition to the LSP/console sink, and by the console tee before the console
+ * method it wraps — log sinks fan out, they don't replace.
  * While the target is still pending (unresolved `{placeholder}`), the line is
- * buffered instead of dropped.
+ * buffered instead of dropped. Where no sink is installed, as in a process
+ * that never loaded `@hydranium/core/node`, nothing is built or buffered,
+ * since nothing will write it. A caller whose line is costly to build passes
+ * a function, called only when the file takes the line.
  */
-export function teeLogLine(formatted: string): void {
-   if (!logFileTemplate) {
+export function teeLogLine(level: LogLevel, formatted: string | (() => string)): void {
+   if (!logFileTemplate || LEVEL_ORDER[level] > LEVEL_ORDER[Logger.getFileLevel() ?? Logger.getLevel()]) {
+      return;
+   }
+   if (!fileSink) {
       return;
    }
-   const line = `${formatted}\n`;
+   const line = `${typeof formatted === 'string' ? formatted : 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);
+      // re-enter emit and loop. The caller delivers the line to its other sink.
+      fileSink.append(resolvedLogFilePath, line);
    } else {
       pendingLogLines.push(line);
    }