@hydranium/core 1.0.0-next.23 → 1.0.0-next.232

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/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. */
@@ -119,9 +119,15 @@ function flushPendingLogLines(): void {
  * until every token is supplied via {@link resolveLogFilePlaceholder}.
  * 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;
@@ -173,13 +179,14 @@ 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
+ * 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 — 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) {
+export function teeLogLine(level: LogLevel, formatted: string): void {
+   if (!logFileTemplate || LEVEL_ORDER[level] > LEVEL_ORDER[Logger.getFileLevel() ?? Logger.getLevel()]) {
       return;
    }
    const line = `${formatted}\n`;

package/src/langium/diagnostics/lsp-logger.ts

@@ -11,7 +11,9 @@ import {
    AbstractLogger,
    type Clock,
    DEFAULT_LOG_FILE_ENV,
+   DEFAULT_LOG_FILE_LEVEL_ENV,
    DEFAULT_LOG_LEVEL_ENV,
+   LEVEL_ORDER,
    Logger,
    type LogLevel,
    type LogThreshold,
@@ -79,9 +81,10 @@ export class LspLogger extends AbstractLogger implements Logger {
       options: LspLoggerOptions = {}
    ) {
       super(options.component);
-      // Apply the framework env baselines (`HYDRANIUM_LOG_LEVEL` and
-      // `HYDRANIUM_LOG_FILE`) exactly once, on the first logger construction,
-      // before any setting is read. Unconditional and process-global, so it
+      // Apply the framework env baselines (`HYDRANIUM_LOG_LEVEL`,
+      // `HYDRANIUM_LOG_FILE` and `HYDRANIUM_LOG_FILE_LEVEL`) exactly once, on
+      // the first logger construction, before any setting is read.
+      // Unconditional and process-global, so it
       // needs no root detection and is never re-applied by derived children —
       // which would otherwise clobber a live setting. These are the single env
       // vars for level / file-tee (an adopter brands them by renaming the
@@ -92,13 +95,20 @@ export class LspLogger extends AbstractLogger implements Logger {
          // a Node concern; skip it cleanly there.
          const env = processEnv();
          if (env) {
-            const envLevel = parseLogLevel(env[DEFAULT_LOG_LEVEL_ENV]);
-            if (envLevel) {
-               Logger.setLevel(envLevel);
-            }
+            // The file-tee target FIRST: the other order writes the level
+            // announcement before the sink exists, losing the one line that says
+            // which threshold the rest of the file was written at.
             const envLogFile = env[DEFAULT_LOG_FILE_ENV];
             if (envLogFile) {
-               setLogFilePath(envLogFile);
+               const fileLevel = parseLogLevel(env[DEFAULT_LOG_FILE_LEVEL_ENV]);
+               setLogFilePath(envLogFile, fileLevel);
+               if (fileLevel) {
+                  this.logAt(fileLevel, `Log file level ${fileLevel} (${DEFAULT_LOG_FILE_LEVEL_ENV})`);
+               }
+            }
+            const envLevel = parseLogLevel(env[DEFAULT_LOG_LEVEL_ENV]);
+            if (envLevel) {
+               this.applyLevel(envLevel, DEFAULT_LOG_LEVEL_ENV);
             }
          }
       }
@@ -109,16 +119,48 @@ export class LspLogger extends AbstractLogger implements Logger {
       if (options.logThreshold !== undefined) {
          const level = ObservableValue.from(options.logThreshold);
          if (level.value) {
-            Logger.setLevel(level.value);
+            this.applyLevel(level.value, 'setting');
          }
          level.onChange(next => {
             if (next) {
-               Logger.setLevel(next);
+               this.applyLevel(next, 'setting');
             }
          });
       }
    }
 
+   /**
+    * Set the process-wide threshold and announce the transition under whichever
+    * of the two thresholds can carry the notice, so a reader sees every change
+    * and its absence means the threshold never moved.
+    *
+    * `error` and `off` admit no notice of their own — `off` nothing at all, and
+    * an error-severity line is read as a fault, which a client that marks its
+    * log as having seen an error keeps for the session. Entering either is
+    * therefore announced BEFORE the switch, under the outgoing threshold; every
+    * other change is announced after it, at the level being entered. Leaving
+    * `error` or `off` for one of those two says nothing, both thresholds being
+    * unable to carry it.
+    *
+    * Only on a real transition: the bound setting re-fires for configuration
+    * changes that leave the value alone.
+    */
+   protected applyLevel(next: LogThreshold, source: string): void {
+      const previous = Logger.getLevel();
+      if (previous === next) {
+         return;
+      }
+      const message = `Log level ${previous} → ${next} (${source})`;
+      const announceFirst = next === 'error' || next === 'off';
+      if (announceFirst && previous !== 'error') {
+         this.logAt(previous, message);
+      }
+      Logger.setLevel(next);
+      if (!announceFirst) {
+         this.logAt(next, message);
+      }
+   }
+
    /**
     * Route logger timing and timestamps through the injected framework
     * {@link Clock} (the dedicated `shared.Clock` slot) so server-side log time
@@ -145,9 +187,7 @@ export class LspLogger extends AbstractLogger implements Logger {
    }
 
    protected emit(level: LogLevel, label: string, message: string, args: readonly unknown[]): void {
-      const component = this.component ? ` [${this.component}]` : '';
-      // Pad to the widest label (5 chars — 'Error'/'Debug'/'Trace') so timestamps line up.
-      const prefix = `[${label.padEnd(5)} - ${this.timestamp()}]${component}`;
+      const prefix = this.formatLinePrefix(label);
       const combined = args.length === 0 ? message : `${message} ${args.map(formatLogArg).join(' ')}`;
       const formatted = `${prefix} ${combined}`;
       const connection = this.services.lsp.Connection;
@@ -165,7 +205,11 @@ export class LspLogger extends AbstractLogger implements Logger {
       // shutdown diagnostics and the workspace manager's own
       // unhandled-rejection handler. A log sink that throws turns a diagnostic
       // into a crash, so a dead channel degrades to stderr instead.
-      if (!connection || !sendViaConnection(connection, level, formatted)) {
+      //
+      // `send` admits a line either threshold takes, so the client sink checks
+      // its own; the file-tee filters for itself.
+      const toClient = LEVEL_ORDER[level] <= LEVEL_ORDER[Logger.getLevel()];
+      if (toClient && (!connection || !sendViaConnection(connection, level, formatted))) {
          if (!writeStderr(`${formatted}\n`)) {
             // Browser only. In Node every level goes to STDERR, including the
             // three that `console.*` would put on stdout (`info` / `debug` /
@@ -180,7 +224,7 @@ export class LspLogger extends AbstractLogger implements Logger {
       }
       // File-tee fan-out for headless capture (see `setLogFilePath`). Always runs
       // in addition to the LSP/console sink — log sinks fan out, they don't replace.
-      teeLogLine(formatted);
+      teeLogLine(level, formatted);
    }
 
    protected derive(component: string): this {

package/src/langium/document-builder/build-pipeline-integration.ts

@@ -31,13 +31,24 @@ const AST_EXTENSION_PHASES: readonly DocumentState[] = [
 ];
 
 /**
- * Build phases at which the `BuildPhasePassService` is driven. Same useful
- * set as {@link AST_EXTENSION_PHASES}: a pass registered at any other state
- * never fires (the listener is not wired), mirroring the AST-extension contract.
+ * Build phases at which the `BuildPhasePassService` is driven. A pass
+ * registered at any other state never fires (the listener is not wired), and
  * `runPasses` no-ops at a phase with no registered pass, so wiring the full set
  * unconditionally costs only an empty-bucket check per phase.
+ *
+ * `IndexedContent` belongs here and NOT in {@link AST_EXTENSION_PHASES}, so the
+ * two cannot be collapsed. Per document it carries nothing `Parsed` does; per
+ * BATCH it is the only phase meaning the global index is whole again, which
+ * batch work keyed on a complete index has nowhere else to run.
  */
-const BUILD_PHASE_PASS_STATES: readonly DocumentState[] = AST_EXTENSION_PHASES;
+const BUILD_PHASE_PASS_STATES: readonly DocumentState[] = [
+   DocumentState.Parsed,
+   DocumentState.IndexedContent,
+   DocumentState.ComputedScopes,
+   DocumentState.Linked,
+   DocumentState.IndexedReferences,
+   DocumentState.Validated
+];
 
 /**
  * Default priority of the framework integrity passes. Integrity mutates / cleans
@@ -65,6 +76,19 @@ export interface BuildPipelineIntegrationOptions {
    readonly integrityPriority?: number;
 }
 
+/**
+ * The build-pipeline slot. Empty because nothing calls this service — it wires
+ * itself in its constructor and every seam it offers is `protected`.
+ *
+ * Typing the slot by the class instead would stop an adopter's subclass
+ * satisfying it, since a class carries its `protected` members into the check
+ * and they compare by declaration rather than by shape. The cost of the empty
+ * shape is that any non-null value satisfies it, so a mis-bound slot compiles
+ * and the framework's phase listeners are then never attached.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the slot has no public member to name
+export interface BuildPipelineIntegration {}
+
 /**
  * Wires the framework's build-time features (integrity rules, AST
  * enrichment) into Langium's document-build pipeline. The single shared
@@ -90,7 +114,7 @@ export interface BuildPipelineIntegrationOptions {
  * Eagerly constructed (via `DEFAULT_EAGER_SERVICES`) so the listeners are
  * attached before the first build cycle.
  */
-export class BuildPipelineIntegration {
+export class DefaultBuildPipelineIntegration implements BuildPipelineIntegration {
    constructor(
       protected readonly services: ServerSharedServices,
       options: BuildPipelineIntegrationOptions = {}
@@ -128,6 +152,14 @@ export class BuildPipelineIntegration {
          );
       }
 
+      // Per DOCUMENT as well: `reparseAndRelink` re-indexes one document from
+      // inside the `Linked` phase and fires no build-phase notification, so a
+      // batch-level listener cannot see the AST it replaced.
+      builder.onDocumentPhase(
+         DocumentState.IndexedContent,
+         labelPhaseListener(() => this.clearScopeCaches(), 'BuildPipeline.clearScopeCaches')
+      );
+
       // AST enrichment stays per-document (onDocumentPhase) and node-granular —
       // unchanged by the build-phase-pass registry, which is batch-granular. The
       // listener calls the `extendAst` seam directly (the document-phase analog of
@@ -174,6 +206,19 @@ export class BuildPipelineIntegration {
       }
    }
 
+   /**
+    * Drop the cached scopes of every REGISTERED language, not of those owning a
+    * document in the batch. The index a scope is built from is
+    * workspace-global, so narrowing to the batch with
+    * {@link groupDocumentsByLanguage}, the way {@link callIntegrity} does,
+    * leaves a cross-grammar reference resolving against a mid-rebuild scope.
+    */
+   protected clearScopeCaches(): void {
+      for (const languageServices of this.services.ServiceRegistry.all) {
+         languageServices.references.ScopeProvider.clearScopeCaches();
+      }
+   }
+
    /** Run AST enrichment for a single document at `phase` via its language service. */
    protected extendAst(document: LangiumDocument, phase: DocumentState, cancelToken: CancellationToken): void {
       this.services.ServiceRegistry.getServices(document.uri).ast.AstExtensionService.extendDocument(document, phase, cancelToken);

package/src/langium/document-builder/build-session.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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 URI } from '@hydranium/langium';
+
+/** What a build is about, handed to `HydraniumDocumentBuilder.createBuildSession`. */
+export interface BuildSessionContext {
+   /**
+    * Which entry point opened the build: `'build'` is the workspace-wide pass
+    * (initialization), `'update'` an incremental rebuild. A subclass deriving
+    * cascade state skips the work for `'build'`, where every document is in the
+    * set already and `shouldRelink` is never consulted.
+    */
+   readonly kind: 'build' | 'update';
+   /** Formatted description of what caused the build — a URI, a count summary. */
+   readonly trigger: string;
+   /** True when {@link trigger} already states the document count. */
+   readonly triggerCountsDocs: boolean;
+   /** URIs the build was asked to rebuild, already flattened and canonicalized. */
+   readonly changed: readonly URI[];
+   /** URIs the build was asked to delete, already expanded by `collectDeletedURIs`. Empty for a `build` call. */
+   readonly deleted: readonly URI[];
+}
+
+/**
+ * One rebuild, treated as a correlated unit.
+ *
+ * Everything a build phase needs to know about the build it belongs to — what
+ * triggered it, when it started, whether it was cancelled, and the log lines it
+ * has produced so far. A `HydraniumDocumentBuilder` opens one per `update` /
+ * `build` call and holds it for the duration, so a per-phase hook can reach
+ * build-wide facts that no per-line formatting hook could.
+ *
+ * **Identity is the object, not {@link traceId}.** `Tracer.time` short-circuits
+ * when its log level is suppressed and never calls `captureId`, so `traceId` is
+ * `undefined` on every build in a production configuration that logs above
+ * `debug`. A teardown guard keyed on the id would then compare `undefined`
+ * against `undefined` and let a preempted build clear its successor's state.
+ * Reference equality against `HydraniumDocumentBuilder.activeSession` holds in
+ * both configurations, which is why nothing here is keyed on the id.
+ *
+ * Adopters carrying build-scoped state of their own subclass this and return it
+ * from `HydraniumDocumentBuilder.createBuildSession`, narrowing with an
+ * `instanceof` where they read it back. That buys them the framework's
+ * preemption-correct teardown rather than a second copy of it.
+ */
+export class BuildSession {
+   /**
+    * `Tracer.time` correlation id, so a phase line and the build line share a
+    * `#N`. `undefined` until the timer starts, and permanently `undefined` when
+    * the timing line is suppressed.
+    */
+   traceId?: number;
+   /** Set when the build ended in `OperationCancelled`, so the successor can tag itself "cancels #N". */
+   cancelled = false;
+   /** Phase-reached lines produced so far; the first one measures from {@link startMs} rather than from the previous phase. */
+   phasesLogged = 0;
+   /** Lines held back by {@link detailThresholdMs}; flushed or dropped when the build ends. */
+   readonly bufferedLines: string[] = [];
+
+   constructor(
+      /** Millisecond timestamp the build started at, on the same clock as `performance.now()`. */
+      readonly startMs: number,
+      /** What caused this build — a formatted URI, a count summary, or an adopter label. */
+      readonly trigger: string,
+      /** True when {@link trigger} already states the document count, so a phase line must not repeat it. */
+      readonly triggerCountsDocs: boolean,
+      /**
+       * Build duration at or above which the buffered lines are emitted; `0`
+       * disables buffering entirely. Captured per session so the flush decision
+       * uses the same value the buffering decision did, even if the underlying
+       * observable changed mid-build.
+       */
+      readonly detailThresholdMs: number
+   ) {}
+
+   /** True while lines are being held rather than emitted as they are produced. */
+   get buffers(): boolean {
+      return this.detailThresholdMs > 0;
+   }
+}