@hydranium/core 1.0.0-next.5 → 1.0.0-next.51

package/src/documents/hydranium-text-documents.ts

@@ -644,18 +644,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       if (this.isOpenInClient(uri, clientId)) {
          // Already open for this client under this canonical identity. If this is a
          // NEW client-facing URI for the same file (a second tab reached via a
-         // divergent path, e.g. a symlink and its real path), record it and baseline
-         // its shadow so outbound edits reach this tab too — but do NOT re-fire
-         // open/rebuild; the document is already live.
+         // divergent path, e.g. a symlink and its real path), record it so outbound
+         // edits reach this tab too — but do NOT re-fire open/rebuild; the document
+         // is already live.
          if (clientId === LANGUAGE_CLIENT_ID) {
             const clientFacing = this.toLanguageClientUri(td.uri);
             const record = this.__documents.get(uri);
             if (record && !record.languageClientUris?.has(clientFacing)) {
                (record.languageClientUris ??= new Set<LanguageClientUri>()).add(clientFacing);
-               const open = this.__syncedDocuments.get(uri);
-               if (open) {
-                  this.__shadow.set(clientFacing, open.getText());
-               }
+               // This tab's own buffer, NOT the synced text: a second tab is a second
+               // client model, read from disk, so a server-authored write already
+               // applied to the first tab leaves it BEHIND the synced document. Keying
+               // a diff to the synced text here addresses lines this tab does not have
+               // and drops content it does.
+               this.__shadow.setOpenedText(clientFacing, td.text);
             }
          }
          return;
@@ -694,7 +696,18 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // Baseline the shadow to what Monaco just opened so the next outbound
             // applyEditToLanguageClient diffs against the right starting point. Keyed by the
             // language-client URI (what Monaco holds), not the canonical document key.
-            this.__shadow.set(this.toLanguageClientUri(td.uri), document.getText());
+            //
+            // The CLIENT's declared text, never the synced document: staged content
+            // consumed above leaves the two different, and a baseline asserting the
+            // client already holds the staged text suppresses the one sync that would
+            // deliver it. Skipped entirely when a push is already outstanding for this
+            // URI — an `applyEdit` to a closed file has the client open from disk and
+            // apply afterwards, so that shadow records what it is about to hold and
+            // disk text would key the next diff to a buffer nobody has.
+            const clientFacing = this.toLanguageClientUri(td.uri);
+            if (this.__shadow.get(clientFacing) === undefined) {
+               this.__shadow.set(clientFacing, td.text);
+            }
          }
          const toFire = Object.freeze({ document, clientId });
          this.__onDidOpen.fire(toFire);
@@ -706,6 +719,14 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             `Attach client: ${clientId} joined existing document (version ${document.version}, ` +
                `now open in: ${[...existingClients, clientId].join(', ')})`
          );
+         if (clientId === LANGUAGE_CLIENT_ID) {
+            // Monaco's own buffer, which on this path is NOT the synced text — another
+            // client opened the document and may already have changed it. Recorded as
+            // an equality-only baseline (never a diff one, see `setOpenedText`) so the
+            // refresh below does not push a full replace of content Monaco already
+            // holds, which would dirty the file on open.
+            this.__shadow.setOpenedText(this.toLanguageClientUri(td.uri), td.text);
+         }
          this.refreshContent(uri, clientId);
       }
    }
@@ -985,9 +1006,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // it is exactly what the caller retries with after a rejection, so
             // gating it there would refuse the recovery too.
             const version = isFullReplace(edits) ? UNKNOWN_CLIENT_VERSION : this.languageClientVersion(uri);
+            // A full `ApplyWorkspaceEditParams`, `edit` and all — NOT a bare
+            // `WorkspaceEdit` with a `label` beside it. `applyEdit` takes
+            // `ApplyWorkspaceEditParams | WorkspaceEdit` and discriminates on
+            // `!!value.edit`, so `{ label, documentChanges }` is wrapped as
+            // `{ edit: { label, documentChanges } }` — putting the label inside
+            // the edit, where LSP defines no such field and no client reads it.
+            // The union is also what hides it at compile time: excess-property
+            // checking admits a property present in EITHER member, so an object
+            // matching neither type-checks against the union.
             const result = await connection.workspace.applyEdit({
                label: options?.label,
-               documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               edit: {
+                  documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               }
             });
             if (result && result.applied === false) {
                this.__shadow.invalidate(targetUri);

package/src/documents/language-client-text-shadow.ts

@@ -57,12 +57,23 @@ export function isFullReplace(edits: readonly TextEdit[]): boolean {
  *  - {@link computeEdits} after each outgoing server→client sync (updates the shadow optimistically).
  *  - {@link set} when the server receives a `didChange` from the language client (the client now
  *    holds that text; we shouldn't resend it).
+ *  - {@link setOpenedText} when the client opens a document the server did not baseline for it —
+ *    an equality-only baseline, since that text is a snapshot rather than a tracked one.
  *  - {@link invalidate} when the client rejects an edit (`applied=false`) or a doc is closed —
  *    the shadow is now stale and the next sync must fall back to a full replace.
  */
 export class LanguageClientTextShadow {
    protected shadow = new Map<string, string>();
 
+   /**
+    * Per URI, the text the client declared it opened the document with, held
+    * only until a real baseline exists. Consulted by {@link computeEdits} when
+    * there is no shadow, and dropped on {@link invalidate}: a snapshot that
+    * outlived what the client holds would let the equality check skip an edit
+    * the client still needs.
+    */
+   protected opened = new Map<string, string>();
+
    /**
     * @param onFallback invoked when {@link computeEdits} falls back to a full-range replace due to
     *    apply-verify mismatch. Useful for logging regressions.
@@ -84,6 +95,20 @@ export class LanguageClientTextShadow {
       this.shadow.set(uri, text);
    }
 
+   /**
+    * Record the buffer the language client declared at `didOpen`, for a URI
+    * with no baseline yet.
+    *
+    * Deliberately NOT a {@link set}: this text is only ever compared for
+    * EQUALITY, never diffed against. A line-keyed diff is position-dependent,
+    * so keying one to a `didOpen` snapshot the client may have moved past
+    * splices its buffer — the failure {@link computeEdits}'s full-replace
+    * fallback exists to avoid.
+    */
+   setOpenedText(uri: string, text: string): void {
+      this.opened.set(uri, text);
+   }
+
    /**
     * The text the language client is believed to hold, or `undefined` when
     * there is no baseline (first sync, or after an {@link invalidate}).
@@ -102,6 +127,11 @@ export class LanguageClientTextShadow {
    /** Forget the shadow for a URI; next {@link computeEdits} falls back to a full-document replace. */
    invalidate(uri: string): void {
       this.shadow.delete(uri);
+      // Drops the opened snapshot too, and this is the only place that has to:
+      // `computeEdits` clears it whenever it consults it, so the sole way it can
+      // outlive what the client holds is surviving under a live shadow until that
+      // shadow is dropped here.
+      this.opened.delete(uri);
    }
 
    /**
@@ -109,7 +139,9 @@ export class LanguageClientTextShadow {
     * the tracked shadow to `newText`. Updates the shadow to `newText` so subsequent calls diff
     * against it.
     *
-    *  - Empty array when the shadow already equals `newText` (caller should skip the RPC).
+    *  - Empty array when the shadow already equals `newText` (caller should skip the RPC),
+    *    or when there is no shadow and the client opened the document with exactly `newText`
+    *    (see {@link setOpenedText}) — pushing it anyway dirties the client's buffer on open.
     *  - Full-range replace when there is no shadow (first sync or post-{@link invalidate}).
     *  - Line-level diff otherwise. Before returning, we locally reconstruct `newText` by applying
     *    the diff to `old`; if that doesn't match, we fall back to a full-range replace and notify
@@ -124,7 +156,11 @@ export class LanguageClientTextShadow {
       this.shadow.set(uri, newText);
       const fullReplace: TextEdit = { range: FULL_RANGE, newText };
       if (old === undefined) {
-         return [fullReplace];
+         // The opened snapshot has served its purpose either way: the shadow above
+         // is now the baseline, so leaving it would only risk a later stale match.
+         const openedText = this.opened.get(uri);
+         this.opened.delete(uri);
+         return openedText === newText ? [] : [fullReplace];
       }
       const edits = diffToEdits(old, newText);
       const verifyDoc = this.documents.create(uri, 'plaintext', 0, old);

package/src/documents/self-save-registry.ts

@@ -22,10 +22,32 @@ export interface SelfSaveRegistryOptions {
 /**
  * Tracks `mtime` of files written by the server itself so the echo
  * `didChangeWatchedFiles` event from the OS file watcher can be suppressed,
- * avoiding redundant rebuilds after each save. Entries are matched by mtime
- * (not by a time window) and expire after a TTL.
+ * avoiding redundant rebuilds after each save.
  */
-export class SelfSaveRegistry {
+export interface SelfSaveRegistry {
+   /**
+    * Record a self-write, and drop any registration already past its TTL.
+    *
+    * Keyed by `fsPath` rather than URI string, because the two sides of a
+    * suppression see different URI forms for one file.
+    */
+   register(fsPath: string, mtimeMs: number): void;
+
+   /**
+    * Whether `fsPath` carries a live registration at exactly `mtimeMs`.
+    *
+    * A registration expires after the TTL, so a write recorded longer ago than
+    * that answers `false` — the caller's decision holds only while the echo it
+    * suppresses could still be in flight. A query never mutates the registry.
+    */
+   isRegistered(fsPath: string, mtimeMs: number): boolean;
+}
+
+/**
+ * Compares entries by mtime rather than by a time window, so the echo of a
+ * save whose content is unchanged is still recognised.
+ */
+export class DefaultSelfSaveRegistry implements SelfSaveRegistry {
    protected readonly entries = new Map<string, { mtimeMs: number; registeredAt: number }>();
    /**
     * Read time through the shared {@link Clock} rather than `Date.now()`: the
@@ -59,23 +81,40 @@ export class SelfSaveRegistry {
       return isCaseInsensitiveFileSystem() ? fsPath.toLowerCase() : fsPath;
    }
 
-   /** Record a self-write. Key by `fsPath` (not URI string) to avoid URI-form mismatches. */
    register(fsPath: string, mtimeMs: number): void {
+      this.evictExpired();
       this.entries.set(this.key(fsPath), { mtimeMs, registeredAt: this.clock.now() });
    }
 
-   /** True if `mtimeMs` matches a recent self-write. Evicts stale entries. Not consumed on match. */
-   matches(fsPath: string, mtimeMs: number): boolean {
-      const key = this.key(fsPath);
-      const entry = this.entries.get(key);
-      if (!entry) {
-         return false;
-      }
-      if (this.clock.now() - entry.registeredAt > this.ttlMs) {
-         this.entries.delete(key);
+   isRegistered(fsPath: string, mtimeMs: number): boolean {
+      const entry = this.entries.get(this.key(fsPath));
+      if (!entry || this.isExpired(entry.registeredAt)) {
          return false;
       }
       // Accept mtime equality (some filesystems have 1-second precision).
       return entry.mtimeMs === mtimeMs;
    }
+
+   /**
+    * Drop every expired registration.
+    *
+    * On the WRITE path, so the query stays free of side effects. Evicting from
+    * the query instead reaches only the keys something happens to ask about,
+    * and a path written once and never queried again is then retained for the
+    * life of the process. Bounded by the paths self-written inside one TTL
+    * window, so the sweep is over a handful of entries and sits behind a file
+    * write either way.
+    */
+   protected evictExpired(): void {
+      for (const [key, entry] of this.entries) {
+         if (this.isExpired(entry.registeredAt)) {
+            this.entries.delete(key);
+         }
+      }
+   }
+
+   /** Strictly greater, so an entry aged exactly to the TTL is still eligible. */
+   protected isExpired(registeredAt: number): boolean {
+      return this.clock.now() - registeredAt > this.ttlMs;
+   }
 }

package/src/index.ts

@@ -35,5 +35,10 @@ export * from './langium/workspace/index.js';
 export * from './langium/service-registry.js';
 export * from './langium/language-types.js';
 export * from './launcher/index.js';
+export * from './locale/index.js';
+// The renderer only. The `./messages` subpath additionally enumerates this
+// package's own declarations, which the root barrel already re-exports through
+// the modules that raise them.
+export * from './messages/renderer.js';
 export * from './documents/index.js';
 export * from './util/index.js';

package/src/langium/ast-extension/ast-node-builder.ts

@@ -78,15 +78,13 @@ export type AstNodeBuilder<TMap> = <TType extends string & keyof TMap>(
  * AST-interface mapping, so call sites get full inference from the type
  * constant alone — no explicit generic parameter at every call site.
  *
- * Runtime behaviour: reads `reflection.getTypeMetaData(type).properties` and,
- * for every property whose metadata carries a `defaultValue`, pre-fills the
- * result before merging the caller's `init`. Array defaults are materialised
- * as a fresh `[]` per call (never shared with the metadata's array instance,
- * which downstream callers mutate); scalar defaults (`false`, `0`, `''`, …)
- * are copied as-is since they're immutable. Grammar-generated containment
- * lists and `?=`-style boolean flags therefore default automatically;
- * TS-augmented fields (declared via `declare module './generated/ast.js'`)
- * are unaffected by the runtime defaulting but remain typed at call sites.
+ * Runtime behaviour: pre-fills every grammar-declared default (see
+ * {@link withTypeDefaults}) before merging the caller's `init`, so containment
+ * lists and `?=`-style boolean flags default automatically. TS-augmented fields
+ * (declared via `declare module './generated/ast.js'`) are unaffected by the
+ * runtime defaulting but remain typed at call sites.
+ *
+ * Use {@link buildAstNode} instead when the type name is only known at runtime.
  *
  * The init shape only relaxes array-typed fields to optional (via
  * {@link ArrayKeys}) — there is no equivalent structural signal for "this
@@ -101,19 +99,7 @@ export function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuil
       init: AstNodeInit<Extract<TMap[TType], AstNode>>,
       extras?: Record<string, unknown>
    ): Extract<TMap[TType], AstNode> {
-      const meta = reflection.getTypeMetaData(typeConstant.$type);
-      const result: Record<string, unknown> = { $type: typeConstant.$type };
-      if (meta?.properties) {
-         for (const [propName, propInfo] of Object.entries(meta.properties)) {
-            const defaultValue = propInfo.defaultValue;
-            if (defaultValue === undefined) {
-               continue;
-            }
-            // Arrays are duplicated so each node carries its own mutable instance;
-            // scalars are immutable and safe to copy by reference.
-            result[propName] = Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
-         }
-      }
+      const result = withTypeDefaults(reflection, typeConstant.$type);
       Object.assign(result, init);
       if (extras) {
          // Extras win over init: this is the explicit escape hatch, so when a
@@ -123,3 +109,61 @@ export function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuil
       return result as unknown as Extract<TMap[TType], AstNode>;
    };
 }
+
+/**
+ * Build a node whose type is only known as a RUNTIME string.
+ *
+ * The typed {@link makeAstNodeBuilder} cannot express this: its `TMap` generic
+ * resolves the AST interface from a `$type` literal, and a type name that
+ * arrives over the wire — a protocol-layer reference request naming a node that
+ * does not exist yet — has no literal to resolve from. Callers that DO know the
+ * type at compile time want the typed builder, which checks their mandatory
+ * fields; this one checks nothing beyond the reflection lookup.
+ *
+ * Applies the same reflection-driven defaulting, so a node built here carries
+ * grammar-declared containment arrays rather than leaving them `undefined`. An
+ * unknown type name yields a node with `$type` and whatever `init` supplied,
+ * because reflection answers no metadata for it and refusing would turn a
+ * permissive lookup into a throw at a call site that can only guess.
+ *
+ * **The `type` argument is authoritative: `init` cannot rebind `$type`.** The
+ * typed builder gets this for free — `AstNodeInit` omits `$type`, so a call site
+ * cannot reach it — but here `init` is loosely typed, and the case that needs
+ * the guarantee is RETYPING: a caller spreading an existing node to produce one
+ * of a different type (`{ ...source }`) carries the SOURCE's `$type` in, which
+ * would silently win over the type actually requested and hand back a node of
+ * the wrong type with no error anywhere.
+ */
+export function buildAstNode<TAst extends AstNode = AstNode>(
+   reflection: AstReflection,
+   type: string,
+   init?: Partial<AstNode> & Record<string, unknown>
+): TAst {
+   const result = withTypeDefaults(reflection, type);
+   if (init) {
+      Object.assign(result, init);
+      result.$type = type;
+   }
+   return result as unknown as TAst;
+}
+
+/**
+ * Seed a node with `$type` plus every property the grammar declares a default
+ * for. Array defaults are materialised as a fresh `[]` per call — never shared
+ * with the metadata's own array instance, which downstream callers mutate —
+ * while scalar defaults are copied as-is since they are immutable.
+ */
+function withTypeDefaults(reflection: AstReflection, type: string): Record<string, unknown> {
+   const result: Record<string, unknown> = { $type: type };
+   const meta = reflection.getTypeMetaData(type);
+   if (meta?.properties) {
+      for (const [propName, propInfo] of Object.entries(meta.properties)) {
+         const defaultValue = propInfo.defaultValue;
+         if (defaultValue === undefined) {
+            continue;
+         }
+         result[propName] = Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
+      }
+   }
+   return result;
+}

package/src/langium/bootstrap.ts

@@ -12,15 +12,15 @@ import { type LangiumSharedCoreServices } from '@hydranium/langium';
 import { type LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
 import type { ServerSharedServicesMinimal } from './shared-services.js';
 import { collectProducibleTypes } from './language-types.js';
-import { AstDocumentManager } from '../documents/ast-document-manager.js';
+import { DefaultAstDocumentManager } from '../documents/ast-document-manager.js';
 import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
-import { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
+import { DefaultBuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
 import { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
-import { ModelService } from './model-service/model-service.js';
+import { DefaultModelService } from './model-service/model-service.js';
 import { HydraniumScopeComputation } from './scope/hydranium-scope-computation.js';
 import { HydraniumScopeProvider } from './scope/hydranium-scope-provider.js';
 import { processEnv } from '../util/environment.js';
-import { TransferEncoder } from './transfer/transfer-encoder.js';
+import { DefaultTransferEncoder } from './transfer/transfer-encoder.js';
 import { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
 
 /**
@@ -73,7 +73,14 @@ const EXPECTED_SHARED_SLOTS: readonly ExpectedSlot[] = [
       side: 'shared',
       path: 'workspace.BuildPipelineIntegration',
       get: services => nested(services, 'workspace', 'BuildPipelineIntegration')
-   }
+   },
+   // Unbound, this fails where the cause is least visible: the render pass runs
+   // inside the `Validated` phase, so a `TypeError` there propagates out of
+   // `notifyDocumentPhase` and the document reaches `Validated` with Langium's
+   // publisher never invoked — the client receives no diagnostics for the file
+   // and the stack names the document builder.
+   { side: 'shared', path: 'MessageRenderer', get: services => nested(services, 'MessageRenderer') },
+   { side: 'shared', path: 'ServerLocale', get: services => nested(services, 'ServerLocale') }
 ];
 
 /**
@@ -199,17 +206,17 @@ const STRICT_SHARED_SLOTS: readonly StrictSlot[] = [
    {
       side: 'shared',
       path: 'workspace.AstDocumentManager',
-      base: AstDocumentManager,
+      base: DefaultAstDocumentManager,
       get: s => nested(s, 'workspace', 'AstDocumentManager')
    },
    {
       side: 'shared',
       path: 'workspace.BuildPipelineIntegration',
-      base: BuildPipelineIntegration,
+      base: DefaultBuildPipelineIntegration,
       get: s => nested(s, 'workspace', 'BuildPipelineIntegration')
    },
-   { side: 'shared', path: 'model.TransferEncoder', base: TransferEncoder, get: s => nested(s, 'model', 'TransferEncoder') },
-   { side: 'shared', path: 'model.ModelService', base: ModelService, get: s => nested(s, 'model', 'ModelService') }
+   { side: 'shared', path: 'model.TransferEncoder', base: DefaultTransferEncoder, get: s => nested(s, 'model', 'TransferEncoder') },
+   { side: 'shared', path: 'model.ModelService', base: DefaultModelService, get: s => nested(s, 'model', 'ModelService') }
 ];
 
 const STRICT_LANGUAGE_SLOTS: readonly StrictSlot[] = [

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

@@ -65,6 +65,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 +103,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 = {}

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;
+   }
+}