@hydranium/core 1.0.0-next.9 → 1.0.0-next.90

package/lib/langium/document-builder/document-builder.d.ts

@@ -7,12 +7,14 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { type Clock, type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
-import { type BuildOptions, DefaultDocumentBuilder, type DocumentPhaseListener, DocumentState, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type AstNode, type BuildOptions, DefaultDocumentBuilder, type DocumentPhaseListener, DocumentState, type LangiumDocument, type URI } from '@hydranium/langium';
 import { CancellationToken } from 'vscode-languageserver-protocol';
 import { type LogNameOptions } from '../diagnostics/logger.js';
+import type { MessageRenderer } from '../../messages/renderer.js';
 import { type ExtendedServiceRegistry } from '../service-registry.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
+import { BuildSession, type BuildSessionContext } from './build-session.js';
 /** Document states a phase-reached line is emitted for by default — every built phase. */
 export declare const DEFAULT_LOGGED_PHASES: DocumentState[];
 /** Constructor options for {@link HydraniumDocumentBuilder}. */
@@ -46,6 +48,18 @@ export interface DocumentBuilderOptions extends LogNameOptions {
      * logged. Default: `25`. Read per phase; accepts a {@link MaybeObservableValue}.
      */
     readonly slowBuildMs?: MaybeObservableValue<number>;
+    /**
+     * Build duration at or above which a build's phase-reached and slow-listener
+     * lines are emitted; they are held for the duration of the build and dropped
+     * when it finishes faster. Default `0` — no buffering, every line emitted as
+     * it is produced, which is the only setting that keeps lines interleaved with
+     * the rest of the log in real time.
+     *
+     * Set it to make a fast rebuild log nothing but its one build line. The
+     * decision needs the build's TOTAL duration, so it cannot be made by any
+     * per-line hook. Read once per build; accepts a {@link MaybeObservableValue}.
+     */
+    readonly phaseDetailMs?: MaybeObservableValue<number>;
     /**
      * Refresh cross-document `ComputedScopes` derivations when a referencing
      * document is cascade-rebuilt (see
@@ -72,15 +86,24 @@ export interface DocumentBuilderOptions extends LogNameOptions {
  * - **In-place rebuild helpers** — {@link reparse} and
  *   {@link reparseAndRelink} — for a build-phase listener that mutated a
  *   document's AST and must reconcile it within the same build.
- * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}).
+ * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}), followed
+ *   by the **one server-side message render** every head inherits
+ *   ({@link renderDiagnostics}).
+ * - **Build sessions** ({@link BuildSession}): each `update` / `build` call is
+ *   one correlated unit carrying an id, a trigger label, a start time and
+ *   cancellation lineage, so every line of a rebuild reads as belonging to it
+ *   and a preempted build is distinguishable from the winner.
  * - **Logging instrumentation** (default on, opt-out via `logLevel: 'off'`):
- *   phase-reached lines, slow-listener breakdowns on `notifyDocumentPhase`,
- *   and slow-build-phase totals on `notifyBuildPhase`.
+ *   a per-build line, phase-reached lines, slow-listener breakdowns on
+ *   `notifyDocumentPhase`, and slow-build-phase totals on `notifyBuildPhase`.
  *
  * Adopters extend this class — the configuration knobs cover what most
  * adopters need; the `format*Line` methods, `formatUri`, and
  * `collectDeletedURIs` are protected so subclasses can customise wording or
- * domain-aware cascades without re-implementing surrounding logic.
+ * domain-aware cascades without re-implementing surrounding logic. An adopter
+ * with build-scoped state of its own subclasses {@link BuildSession} and
+ * overrides {@link createBuildSession}, which puts that state under the same
+ * preemption-correct teardown rather than a reimplementation of it.
  */
 export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     protected readonly tracer: Tracer;
@@ -94,8 +117,11 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     protected readonly slowListenerMs: ObservableValue<number>;
     /** Live slow-build-phase-total threshold; read `.value` per phase. */
     protected readonly slowBuildMs: ObservableValue<number>;
+    /** Live phase-detail buffering threshold; read `.value` once per build, onto the session. */
+    protected readonly phaseDetailMs: ObservableValue<number>;
     protected readonly uriPolicy: DocumentUriPolicy;
     protected readonly clock: Clock;
+    protected readonly messageRenderer: MessageRenderer;
     /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
     protected readonly languageRegistry: ExtendedServiceRegistry;
     protected languageFileExtensions: string[];
@@ -106,6 +132,22 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     protected readonly refreshCrossDocumentComputedScopes: boolean;
     /** LSP event name (e.g. `'didChangeWatchedFiles'`) staged for the next `update()` call. */
     protected pendingUpdateReason?: string;
+    /**
+     * The build currently in progress, or `undefined` between builds.
+     *
+     * A subclass carrying its own build-scoped state returns a {@link BuildSession}
+     * subclass from {@link createBuildSession} and narrows this with a typeguard
+     * where it reads that state — rather than redeclaring the field, whose
+     * initialiser would run after `super()` and clear a session opened during
+     * construction.
+     */
+    protected activeSession?: BuildSession;
+    /**
+     * `traceId` of the last build that ended in cancellation, for the successor's
+     * "cancels #N" tag. Held here rather than on a session because the session
+     * that carries it is already gone by the time its successor is opened.
+     */
+    protected lastCancelledTraceId?: number;
     constructor(services: ServerSharedServicesMinimal, options?: DocumentBuilderOptions);
     /**
      * Stage an LSP event name for the next `update()` call. Adopters call before
@@ -130,6 +172,8 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * duplicate what this already knows.
      */
     formatBuildStatus(uri: URI): string;
+    /** Render a session for a status line. `undefined` — no build in progress — reads as `none`. */
+    protected formatSession(session: BuildSession | undefined): string;
     /**
      * Two edge cases the default Langium implementation rejects on:
      * - Document below target state with no build active (newly-created file):
@@ -228,6 +272,12 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      */
     protected shouldRelink(document: LangiumDocument, changedUris: Set<string>): boolean;
     update(changed: URI[], deleted: URI[], cancelToken?: CancellationToken): Promise<void>;
+    /**
+     * The workspace-initialization entry point, bracketed by a session like
+     * {@link update}. Langium's `update` reaches `buildDocuments` directly rather
+     * than through here, so the two never nest.
+     */
+    build<T extends AstNode>(documents: Array<LangiumDocument<T>>, options?: BuildOptions, cancelToken?: CancellationToken): Promise<void>;
     /**
      * Refresh cross-document `ComputedScopes` derivations on cascade, when
      * {@link refreshCrossDocumentComputedScopes} is set (default off).
@@ -340,10 +390,65 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * project descriptor should cascade to all its members).
      */
     protected collectDeletedURIs(uri: URI): URI[];
+    /**
+     * Open a session, run `body` inside it, and close it — the bracket every
+     * line of a rebuild is emitted within.
+     *
+     * The session is installed **synchronously**, before the timed body runs, so
+     * that state a subclass computed in {@link createBuildSession} is already
+     * readable by the time Langium's `update` consults `shouldRelink`.
+     *
+     * Teardown is preemption-correct, which is the reason this is framework code
+     * rather than a recipe. Langium's write mutex cancels an in-flight build when
+     * a later one arrives, so two sessions overlap: the successor installs itself
+     * as {@link activeSession} while the predecessor is still unwinding, and the
+     * predecessor's `finally` runs LAST. Clearing unconditionally there would
+     * discard the winner's state mid-build. Only the session that is still
+     * current clears — and the check is reference equality on the session object,
+     * not on {@link BuildSession.traceId}, which is `undefined` for every build
+     * whenever the timing level is suppressed and would compare equal to itself
+     * across two different builds.
+     *
+     * Re-entrancy is not hypothetical even without an adopter: {@link
+     * requeueOrphaned} calls `update` from inside a wait, while a build may be
+     * running.
+     */
+    protected runInSession(context: BuildSessionContext, label: string, body: () => Promise<void>): Promise<void>;
+    /**
+     * Construct the session for one build. Override to return a
+     * {@link BuildSession} subclass carrying adopter build-scoped state — it is
+     * called before the build body, so anything derived here is readable
+     * throughout it.
+     */
+    protected createBuildSession(context: BuildSessionContext): BuildSession;
+    /**
+     * Close `session`: flush what it buffered, then release it if it is still the
+     * current one (see {@link runInSession} on why that check is conditional).
+     * The flush is unconditional — a preempted build's lines still describe work
+     * that happened.
+     */
+    protected endSession(session: BuildSession): void;
+    /**
+     * Emit the lines `session` held back, if it ran long enough to be worth the
+     * detail; drop them otherwise. Emits through {@link emit} rather than
+     * {@link log}, which would route them straight back into the buffer.
+     */
+    protected flushSession(session: BuildSession): void;
+    /** Label for the build's own log line. Override to customise wording. */
+    protected rebuildLabel(changed: URI[], deleted: URI[]): string;
+    /** Short description of what triggered the build, repeated on every phase line. Override to customise wording. */
+    protected buildTriggerLabel(changed: URI[], deleted: URI[]): string;
     protected registerPhaseListeners(): void;
     /** Called once per phase-reached event. Override to add custom side-effects beyond logging. */
     protected onPhaseReached(state: DocumentState, documents: LangiumDocument[]): void;
-    /** Format the phase-reached log line. Override to customise wording. */
+    /**
+     * Format the phase-reached log line. Override to customise wording.
+     *
+     * Within a session the line names what triggered the build, so a phase read
+     * in isolation still says which rebuild it belongs to. `elapsedMs` is ignored
+     * for the FIRST phase of a session: it measures from the previous build's
+     * last phase, an idle gap that says nothing about this build.
+     */
     protected phaseReachedLine(state: DocumentState, documents: LangiumDocument[], elapsedMs: number): string;
     notifyDocumentPhase(document: LangiumDocument, state: DocumentState, cancelToken: CancellationToken): Promise<void>;
     /**
@@ -399,7 +504,45 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * serialising anything.
      */
     protected dedupeDiagnostics(document: LangiumDocument): void;
-    /** Dispatch a log line at the configured log level; a no-op when `logLevel === 'off'`. */
+    /**
+     * Render every diagnostic on `document` through the bound message renderer,
+     * in ONE pass over the finished list.
+     *
+     * All three heads read `document.diagnostics` — the LSP publish,
+     * `TransferEncoder.toTransferDiagnostic` and the GLSP validation path — so
+     * one pass here is what keeps the render from happening per head. It is also
+     * the only placement that covers lexer and parser errors, which Langium
+     * pushes onto the document without routing them through `toDiagnostic`.
+     *
+     * Running here rather than from a `Validated` phase listener needs no
+     * ordering assumption: Langium publishes from `addDiagnosticsHandler`, a free
+     * function it registers as such a listener, which can only be outrun.
+     *
+     * **It inherits {@link dedupeDiagnostics}'s window, and therefore the same
+     * precondition.** A build settling inside the listener window appends
+     * diagnostics this pass never saw, and the publisher of the build that
+     * rendered sends them — unrendered. `ModelServiceOptions.serializeBuilds`
+     * closes it and defaults to `true`, so "every diagnostic is rendered" holds
+     * by default and is an opt-out rather than a guarantee. Opting out accepts
+     * unrendered diagnostics on exactly the terms it already accepts duplicates.
+     *
+     * Entries are REPLACED rather than mutated: `sendDiagnostics` passes the
+     * array by reference and serialises later, so an in-place message mutation
+     * reaches the wire even when it runs after the publisher — which would make
+     * a test for the ordering pass in either state.
+     */
+    protected renderDiagnostics(document: LangiumDocument): void;
+    /**
+     * Dispatch a log line at the configured log level; a no-op when `logLevel ===
+     * 'off'`.
+     *
+     * Held on the active session when it buffers, so the "was this build worth a
+     * per-phase breakdown" decision — which needs the build's total duration, and
+     * so cannot be taken by anything that runs while the lines are produced — is
+     * deferred to {@link flushSession}.
+     */
     protected log(message: string): void;
+    /** Write a line out, bypassing session buffering. The single sink every framework log line reaches. */
+    protected emit(message: string): void;
 }
 //# sourceMappingURL=document-builder.d.ts.map

package/lib/langium/document-builder/document-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-builder.d.ts","sourceRoot":"","sources":["../../../src/langium/document-builder/document-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"document-builder.d.ts","sourceRoot":"","sources":["../../../src/langium/document-builder/document-builder.ts"],"names":[],"mappings":"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"}

package/lib/langium/document-builder/document-builder.js

@@ -8,8 +8,12 @@
  ********************************************************************************/
 import { ObservableValue } from '@hydranium/protocol';
 import { DefaultDocumentBuilder, DocumentState, OperationCancelled, UriUtils, interruptAndCheck, isOperationCancelled } from '@hydranium/langium';
-import { CancellationToken } from 'vscode-languageserver-protocol';
+// `Diagnostic` as a VALUE: `renderDiagnostics` needs its `getMessageString`
+// namespace helper to read the `string | MarkupContent` union without
+// restating it.
+import { CancellationToken, Diagnostic } from 'vscode-languageserver-protocol';
 import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residency-service.js';
+import { BuildSession } from './build-session.js';
 import { labelPhaseListener } from './labeled-phase-listener.js';
 /** Document states a phase-reached line is emitted for by default — every built phase. */
 export const DEFAULT_LOGGED_PHASES = [
@@ -42,15 +46,24 @@ const MAX_STALLED_REQUEUES = 3;
  * - **In-place rebuild helpers** — {@link reparse} and
  *   {@link reparseAndRelink} — for a build-phase listener that mutated a
  *   document's AST and must reconcile it within the same build.
- * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}).
+ * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}), followed
+ *   by the **one server-side message render** every head inherits
+ *   ({@link renderDiagnostics}).
+ * - **Build sessions** ({@link BuildSession}): each `update` / `build` call is
+ *   one correlated unit carrying an id, a trigger label, a start time and
+ *   cancellation lineage, so every line of a rebuild reads as belonging to it
+ *   and a preempted build is distinguishable from the winner.
  * - **Logging instrumentation** (default on, opt-out via `logLevel: 'off'`):
- *   phase-reached lines, slow-listener breakdowns on `notifyDocumentPhase`,
- *   and slow-build-phase totals on `notifyBuildPhase`.
+ *   a per-build line, phase-reached lines, slow-listener breakdowns on
+ *   `notifyDocumentPhase`, and slow-build-phase totals on `notifyBuildPhase`.
  *
  * Adopters extend this class — the configuration knobs cover what most
  * adopters need; the `format*Line` methods, `formatUri`, and
  * `collectDeletedURIs` are protected so subclasses can customise wording or
- * domain-aware cascades without re-implementing surrounding logic.
+ * domain-aware cascades without re-implementing surrounding logic. An adopter
+ * with build-scoped state of its own subclasses {@link BuildSession} and
+ * overrides {@link createBuildSession}, which puts that state under the same
+ * preemption-correct teardown rather than a reimplementation of it.
  */
 export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     tracer;
@@ -64,8 +77,11 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     slowListenerMs;
     /** Live slow-build-phase-total threshold; read `.value` per phase. */
     slowBuildMs;
+    /** Live phase-detail buffering threshold; read `.value` once per build, onto the session. */
+    phaseDetailMs;
     uriPolicy;
     clock;
+    messageRenderer;
     /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
     languageRegistry;
     languageFileExtensions = [];
@@ -76,17 +92,35 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     refreshCrossDocumentComputedScopes;
     /** LSP event name (e.g. `'didChangeWatchedFiles'`) staged for the next `update()` call. */
     pendingUpdateReason;
+    /**
+     * The build currently in progress, or `undefined` between builds.
+     *
+     * A subclass carrying its own build-scoped state returns a {@link BuildSession}
+     * subclass from {@link createBuildSession} and narrows this with a typeguard
+     * where it reads that state — rather than redeclaring the field, whose
+     * initialiser would run after `super()` and clear a session opened during
+     * construction.
+     */
+    activeSession;
+    /**
+     * `traceId` of the last build that ended in cancellation, for the successor's
+     * "cancels #N" tag. Held here rather than on a session because the session
+     * that carries it is already gone by the time its successor is opened.
+     */
+    lastCancelledTraceId;
     constructor(services, options = {}) {
         super(services);
         this.languageRegistry = services.ServiceRegistry;
         this.uriPolicy = services.workspace.DocumentUriPolicy;
         this.clock = services.Clock;
+        this.messageRenderer = services.MessageRenderer;
         this.tracer = services.Tracer.for(options.logName ?? 'DocumentBuilder').trace('instantiated');
         this.logLevel = options.logLevel ?? 'debug';
         this.loggedPhases = options.loggedPhases ?? DEFAULT_LOGGED_PHASES;
         this.slowPhaseMs = ObservableValue.from(options.slowPhaseMs ?? 25);
         this.slowListenerMs = ObservableValue.from(options.slowListenerMs ?? 5);
         this.slowBuildMs = ObservableValue.from(options.slowBuildMs ?? 25);
+        this.phaseDetailMs = ObservableValue.from(options.phaseDetailMs ?? 0);
         this.refreshCrossDocumentComputedScopes = options.refreshCrossDocumentComputedScopes ?? false;
         if (this.logLevel !== 'off') {
             this.registerPhaseListeners();
@@ -126,7 +160,15 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         const doc = this.langiumDocuments.getDocument(UriUtils.toUri(this.uriPolicy.canonicalUri(uri)));
         const docState = doc ? DocumentState[doc.state] : 'unknown (document not loaded)';
         const lastPhase = this.lastPhaseMs > 0 ? `${Math.round(performance.now() - this.lastPhaseMs)}ms ago` : 'no phase observed';
-        return `current state: '${docState}', last phase: ${lastPhase}`;
+        return `current state: '${docState}', last phase: ${lastPhase}, active build: ${this.formatSession(this.activeSession)}`;
+    }
+    /** Render a session for a status line. `undefined` — no build in progress — reads as `none`. */
+    formatSession(session) {
+        if (!session) {
+            return 'none';
+        }
+        const id = session.traceId !== undefined ? `#${session.traceId}` : 'untimed';
+        return `${id} (${session.trigger}, ${Math.round(performance.now() - session.startMs)}ms in)`;
     }
     // ============================================================
     // Bug-fixes (always on)
@@ -331,7 +373,22 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         this.ensureLanguageFileExtensions();
         const changedURIs = changed.flatMap(uri => this.flattenAndAdaptURI(uri));
         const deletedURIs = deleted.flatMap(uri => this.collectDeletedURIs(uri));
-        return super.update(changedURIs, deletedURIs, cancelToken);
+        return this.runInSession({
+            kind: 'update',
+            trigger: this.buildTriggerLabel(changedURIs, deletedURIs),
+            triggerCountsDocs: changedURIs.length + deletedURIs.length !== 1,
+            changed: changedURIs,
+            deleted: deletedURIs
+        }, this.rebuildLabel(changedURIs, deletedURIs), () => super.update(changedURIs, deletedURIs, cancelToken));
+    }
+    /**
+     * The workspace-initialization entry point, bracketed by a session like
+     * {@link update}. Langium's `update` reaches `buildDocuments` directly rather
+     * than through here, so the two never nest.
+     */
+    build(documents, options, cancelToken) {
+        const uris = documents.map(document => document.uri);
+        return this.runInSession({ kind: 'build', trigger: `${documents.length} docs`, triggerCountsDocs: true, changed: uris, deleted: [] }, `Build documents (${documents.length} docs)`, () => super.build(documents, options, cancelToken));
     }
     /**
      * Refresh cross-document `ComputedScopes` derivations on cascade, when
@@ -528,6 +585,138 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         ];
     }
     // ============================================================
+    // Build sessions — one rebuild as a correlated unit
+    // ============================================================
+    /**
+     * Open a session, run `body` inside it, and close it — the bracket every
+     * line of a rebuild is emitted within.
+     *
+     * The session is installed **synchronously**, before the timed body runs, so
+     * that state a subclass computed in {@link createBuildSession} is already
+     * readable by the time Langium's `update` consults `shouldRelink`.
+     *
+     * Teardown is preemption-correct, which is the reason this is framework code
+     * rather than a recipe. Langium's write mutex cancels an in-flight build when
+     * a later one arrives, so two sessions overlap: the successor installs itself
+     * as {@link activeSession} while the predecessor is still unwinding, and the
+     * predecessor's `finally` runs LAST. Clearing unconditionally there would
+     * discard the winner's state mid-build. Only the session that is still
+     * current clears — and the check is reference equality on the session object,
+     * not on {@link BuildSession.traceId}, which is `undefined` for every build
+     * whenever the timing level is suppressed and would compare equal to itself
+     * across two different builds.
+     *
+     * Re-entrancy is not hypothetical even without an adopter: {@link
+     * requeueOrphaned} calls `update` from inside a wait, while a build may be
+     * running.
+     */
+    runInSession(context, label, body) {
+        // Read before installing the new session: the id being superseded belongs
+        // to the OUTGOING build, or — when the previous one already finished
+        // cancelled — to the id it parked for its successor.
+        const supersededId = this.activeSession?.traceId ?? this.lastCancelledTraceId;
+        this.lastCancelledTraceId = undefined;
+        const reason = this.pendingUpdateReason;
+        this.pendingUpdateReason = undefined;
+        const tags = [];
+        if (reason) {
+            tags.push(`event: ${reason}`);
+        }
+        if (supersededId !== undefined) {
+            tags.push(`cancels #${supersededId}`);
+        }
+        const session = this.createBuildSession(context);
+        this.activeSession = session;
+        // A phase's "since previous phase" must measure from the build's start,
+        // not from whenever the last build's final phase happened to land.
+        this.lastPhaseMs = session.startMs;
+        return this.tracer.time(label, async () => {
+            try {
+                await body();
+            }
+            catch (err) {
+                if (isOperationCancelled(err)) {
+                    session.cancelled = true;
+                }
+                throw err;
+            }
+            finally {
+                this.endSession(session);
+            }
+        }, this.logLevel, {
+            logAfterMs: 0,
+            forceMemoryAboveMs: session.buffers ? session.detailThresholdMs : undefined,
+            captureId: id => {
+                session.traceId = id;
+            },
+            tags
+        });
+    }
+    /**
+     * Construct the session for one build. Override to return a
+     * {@link BuildSession} subclass carrying adopter build-scoped state — it is
+     * called before the build body, so anything derived here is readable
+     * throughout it.
+     */
+    createBuildSession(context) {
+        return new BuildSession(performance.now(), context.trigger, context.triggerCountsDocs, this.phaseDetailMs.value);
+    }
+    /**
+     * Close `session`: flush what it buffered, then release it if it is still the
+     * current one (see {@link runInSession} on why that check is conditional).
+     * The flush is unconditional — a preempted build's lines still describe work
+     * that happened.
+     */
+    endSession(session) {
+        this.flushSession(session);
+        if (this.activeSession === session) {
+            this.activeSession = undefined;
+            if (session.cancelled) {
+                this.lastCancelledTraceId = session.traceId;
+            }
+        }
+    }
+    /**
+     * Emit the lines `session` held back, if it ran long enough to be worth the
+     * detail; drop them otherwise. Emits through {@link emit} rather than
+     * {@link log}, which would route them straight back into the buffer.
+     */
+    flushSession(session) {
+        const elapsedMs = performance.now() - session.startMs;
+        if (elapsedMs >= session.detailThresholdMs) {
+            for (const line of session.bufferedLines) {
+                this.emit(line);
+            }
+        }
+        session.bufferedLines.length = 0;
+    }
+    /** Label for the build's own log line. Override to customise wording. */
+    rebuildLabel(changed, deleted) {
+        if (changed.length === 0 && deleted.length === 0) {
+            return 'Rebuild documents (nothing to do)';
+        }
+        if (changed.length === 1 && deleted.length === 0) {
+            return `Rebuild document: ${this.formatUri(changed[0])}`;
+        }
+        if (changed.length === 0 && deleted.length === 1) {
+            return `Rebuild after delete: ${this.formatUri(deleted[0])}`;
+        }
+        return `Rebuild documents (${changed.length} changed, ${deleted.length} deleted)`;
+    }
+    /** Short description of what triggered the build, repeated on every phase line. Override to customise wording. */
+    buildTriggerLabel(changed, deleted) {
+        if (changed.length === 0 && deleted.length === 0) {
+            return 'nothing';
+        }
+        if (changed.length === 1 && deleted.length === 0) {
+            return this.formatUri(changed[0]);
+        }
+        if (changed.length === 0 && deleted.length === 1) {
+            return `deleted ${this.formatUri(deleted[0])}`;
+        }
+        return `${changed.length} changed, ${deleted.length} deleted`;
+    }
+    // ============================================================
     // Logging — phase-reached listeners
     // ============================================================
     registerPhaseListeners() {
@@ -540,12 +729,34 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         const now = performance.now();
         const elapsedMs = Math.round(now - this.lastPhaseMs);
         this.lastPhaseMs = now;
+        // Counted before the line is formatted, so the formatter stays a pure
+        // function of state a caller can also set up in a test.
+        if (this.activeSession) {
+            this.activeSession.phasesLogged++;
+        }
         this.log(this.phaseReachedLine(state, documents, elapsedMs));
     }
-    /** Format the phase-reached log line. Override to customise wording. */
+    /**
+     * Format the phase-reached log line. Override to customise wording.
+     *
+     * Within a session the line names what triggered the build, so a phase read
+     * in isolation still says which rebuild it belongs to. `elapsedMs` is ignored
+     * for the FIRST phase of a session: it measures from the previous build's
+     * last phase, an idle gap that says nothing about this build.
+     */
     phaseReachedLine(state, documents, elapsedMs) {
-        const docInfo = documents.length === 1 ? this.formatUri(documents[0].uri) : `${documents.length} docs`;
-        return `Reached phase '${DocumentState[state]}' [${docInfo}, ${elapsedMs}ms since previous phase]`;
+        const session = this.activeSession;
+        let docInfo;
+        if (session) {
+            docInfo = session.triggerCountsDocs ? `building ${session.trigger}` : `building ${session.trigger}, ${documents.length} docs`;
+        }
+        else {
+            docInfo = documents.length === 1 ? this.formatUri(documents[0].uri) : `${documents.length} docs`;
+        }
+        const elapsedInfo = session && session.phasesLogged <= 1
+            ? `${Math.round(performance.now() - session.startMs)}ms since build start`
+            : `${elapsedMs}ms since previous phase`;
+        return `Reached phase '${DocumentState[state]}' [${docInfo}, ${elapsedInfo}]`;
     }
     // ============================================================
     // Logging — slow-listener breakdown on notifyDocumentPhase
@@ -558,8 +769,12 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         // build settling inside that window therefore appends after this call has
         // already deduped, and the appended duplicate is published by the listener
         // of the build that deduped. Only `serializeBuilds` closes the window.
+        //
+        // Dedupe before rendering: rendering is deterministic, so it cannot
+        // change which entries are structurally equal, and fewer survive to render.
         if (state === DocumentState.Validated) {
             this.dedupeDiagnostics(document);
+            this.renderDiagnostics(document);
         }
         if (this.logLevel === 'off') {
             return super.notifyDocumentPhase(document, state, cancelToken);
@@ -718,11 +933,83 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
             document.diagnostics = unique;
         }
     }
+    /**
+     * Render every diagnostic on `document` through the bound message renderer,
+     * in ONE pass over the finished list.
+     *
+     * All three heads read `document.diagnostics` — the LSP publish,
+     * `TransferEncoder.toTransferDiagnostic` and the GLSP validation path — so
+     * one pass here is what keeps the render from happening per head. It is also
+     * the only placement that covers lexer and parser errors, which Langium
+     * pushes onto the document without routing them through `toDiagnostic`.
+     *
+     * Running here rather than from a `Validated` phase listener needs no
+     * ordering assumption: Langium publishes from `addDiagnosticsHandler`, a free
+     * function it registers as such a listener, which can only be outrun.
+     *
+     * **It inherits {@link dedupeDiagnostics}'s window, and therefore the same
+     * precondition.** A build settling inside the listener window appends
+     * diagnostics this pass never saw, and the publisher of the build that
+     * rendered sends them — unrendered. `ModelServiceOptions.serializeBuilds`
+     * closes it and defaults to `true`, so "every diagnostic is rendered" holds
+     * by default and is an opt-out rather than a guarantee. Opting out accepts
+     * unrendered diagnostics on exactly the terms it already accepts duplicates.
+     *
+     * Entries are REPLACED rather than mutated: `sendDiagnostics` passes the
+     * array by reference and serialises later, so an in-place message mutation
+     * reaches the wire even when it runs after the publisher — which would make
+     * a test for the ordering pass in either state.
+     */
+    renderDiagnostics(document) {
+        const diagnostics = document.diagnostics;
+        if (!diagnostics || diagnostics.length === 0) {
+            return;
+        }
+        let changed = false;
+        // No try/catch: `renderDiagnostic` carries a no-throw contract, because an
+        // error escaping this phase strands the document at `Validated` with
+        // Langium's publisher never invoked.
+        const rendered = diagnostics.map(diagnostic => {
+            const text = this.messageRenderer.renderDiagnostic(diagnostic);
+            // Against the message's STRING FORM, not the field. `renderDiagnostic`
+            // answers a `string` by contract, while `Diagnostic.message` is
+            // `string | MarkupContent` since LSP 3.17 — so comparing the answer
+            // against the field never matches for a markup message, and a pass
+            // that replaced on mismatch flattened every un-identified markup
+            // diagnostic to its own plain text. That is silent data loss on the
+            // path whose whole job is to leave such entries alone.
+            if (text === Diagnostic.getMessageString(diagnostic)) {
+                return diagnostic;
+            }
+            changed = true;
+            return { ...diagnostic, message: text };
+        });
+        if (changed) {
+            document.diagnostics = rendered;
+        }
+    }
     // ============================================================
     // Internal helpers
     // ============================================================
-    /** Dispatch a log line at the configured log level; a no-op when `logLevel === 'off'`. */
+    /**
+     * Dispatch a log line at the configured log level; a no-op when `logLevel ===
+     * 'off'`.
+     *
+     * Held on the active session when it buffers, so the "was this build worth a
+     * per-phase breakdown" decision — which needs the build's total duration, and
+     * so cannot be taken by anything that runs while the lines are produced — is
+     * deferred to {@link flushSession}.
+     */
     log(message) {
+        const session = this.activeSession;
+        if (session?.buffers) {
+            session.bufferedLines.push(message);
+            return;
+        }
+        this.emit(message);
+    }
+    /** Write a line out, bypassing session buffering. The single sink every framework log line reaches. */
+    emit(message) {
         this.tracer.logAt(this.logLevel, message);
     }
 }