@hydranium/core 1.0.0-next.22 → 1.0.0-next.221

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

@@ -0,0 +1,72 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * 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 {
+    startMs;
+    trigger;
+    triggerCountsDocs;
+    detailThresholdMs;
+    /**
+     * `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;
+    /** 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. */
+    bufferedLines = [];
+    constructor(
+    /** Millisecond timestamp the build started at, on the same clock as `performance.now()`. */
+    startMs, 
+    /** What caused this build — a formatted URI, a count summary, or an adopter label. */
+    trigger, 
+    /** True when {@link trigger} already states the document count, so a phase line must not repeat it. */
+    triggerCountsDocs, 
+    /**
+     * 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.
+     */
+    detailThresholdMs) {
+        this.startMs = startMs;
+        this.trigger = trigger;
+        this.triggerCountsDocs = triggerCountsDocs;
+        this.detailThresholdMs = detailThresholdMs;
+    }
+    /** True while lines are being held rather than emitted as they are produced. */
+    get buffers() {
+        return this.detailThresholdMs > 0;
+    }
+}
+//# sourceMappingURL=build-session.js.map

package/lib/langium/document-builder/build-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-session.js","sourceRoot":"","sources":["../../../src/langium/document-builder/build-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAuBlF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,YAAY;IAgBV,OAAO;IAEP,OAAO;IAEP,iBAAiB;IAOjB,iBAAiB;IA1B7B;;;;OAIG;IACH,OAAO,CAAU;IACjB,sGAAsG;IACtG,SAAS,GAAG,KAAK,CAAC;IAClB,4HAA4H;IAC5H,YAAY,GAAG,CAAC,CAAC;IACjB,4FAA4F;IACnF,aAAa,GAAa,EAAE,CAAC;IAEtC;IACG,4FAA4F;IACnF,OAAe;IACxB,sFAAsF;IAC7E,OAAe;IACxB,uGAAuG;IAC9F,iBAA0B;IACnC;;;;;OAKG;IACM,iBAAyB;uBAXzB,OAAO;uBAEP,OAAO;iCAEP,iBAAiB;iCAOjB,iBAAiB;IAC1B,CAAC;IAEJ,gFAAgF;IAChF,IAAI,OAAO;QACR,OAAO,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;IACrC,CAAC;CACH"}

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

@@ -7,14 +7,31 @@
  * 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 { CancellationToken } from 'vscode-languageserver-protocol';
+import { type AstNode, type BuildOptions, DefaultDocumentBuilder, type DocumentPhaseListener, DocumentState, type LangiumDocument, MultiMap, URI, type WorkspaceLock } from '@hydranium/langium';
+import { CancellationToken, Disposable } from 'vscode-languageserver-protocol';
+import { type VersionSyncService } from '../../documents/version-sync-service.js';
 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[];
+/**
+ * The build reasons the framework stages through
+ * {@link HydraniumDocumentBuilder.markNextReason}: the LSP events the update
+ * handler dispatches on, and `didRelease` for the builds the
+ * `DocumentReleaseHandler` runs once the text store has released a document.
+ * Exposed so a subclass layering reasons of its own keeps the names the
+ * framework emits.
+ */
+export declare const HYDRANIUM_BUILD_REASONS: Readonly<{
+    readonly didOpen: 'didOpen';
+    readonly didChangeContent: 'didChangeContent';
+    readonly didChangeWatchedFiles: 'didChangeWatchedFiles';
+    readonly didRelease: 'didRelease';
+}>;
 /** Constructor options for {@link HydraniumDocumentBuilder}. */
 export interface DocumentBuilderOptions extends LogNameOptions {
     /**
@@ -46,6 +63,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
@@ -58,29 +87,72 @@ export interface DocumentBuilderOptions extends LogNameOptions {
      */
     readonly refreshCrossDocumentComputedScopes?: boolean;
 }
+/** Options for a {@link HydraniumDocumentBuilder.waitUntil} wait on one document. */
+export interface WaitUntilOptions {
+    /**
+     * Reject once the builder gives up carrying the document to the target
+     * state. Without it, such a wait stays pending until its token is cancelled.
+     */
+    readonly rejectWhenStuck?: boolean;
+}
+/**
+ * One locked build {@link HydraniumDocumentBuilder.scheduleUpdate} queued,
+ * which later requests merge into while it waits and join while it runs.
+ */
+export interface ScheduledUpdate {
+    /** URIs to build, by URI string. Merged requests change it while the write is queued; fixed once it runs. */
+    readonly changed: Map<string, URI>;
+    /** URIs to delete, by URI string, under the same rule as {@link changed}. */
+    readonly deleted: Map<string, URI>;
+    /** The latest build reason any merged request gave; staged through {@link HydraniumDocumentBuilder.markNextReason} when the write runs. */
+    reason?: string;
+    /** The lock's {@link HydraniumWorkspaceLock.writeCancellations} right after this write was queued. */
+    readonly cancellations: number;
+    /**
+     * Set when the write starts to run, so its presence marks a running build:
+     * the text version of each changed URI the text store holds at that point.
+     */
+    takenVersions?: Map<string, number>;
+    /** Set with {@link takenVersions}: the clients holding each changed URI in the text store at that point. */
+    takenClients?: Map<string, readonly string[]>;
+    /** The lock's promise for this write: settles when the build completes or is cancelled. */
+    readonly promise: Promise<void>;
+}
 /**
  * Extends Langium's {@link DefaultDocumentBuilder} with:
  *
  * - **Bug-fixes** (always on): an {@link awaitDocumentState} that waits where
- *   the default rejects, a {@link prepareBuild} that keeps a cancelled
+ *   the default rejects (re-queuing, under the workspace lock, a document no
+ *   build will carry), a {@link prepareBuild} that keeps a cancelled
  *   non-validating build from suppressing validation, and a
  *   {@link shouldRelink} that never judges a document unaffected on an index
  *   that does not describe it.
+ * - **Shared locked builds** ({@link scheduleUpdate}): build requests that
+ *   coincide share one locked build instead of cancelling each other.
  * - **URI handling** (always on): directory-aware flattening and cascade
  *   deletes in {@link update}, plus the CST-rehydration and cross-document
  *   refresh resets in {@link resetToState}.
  * - **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 +166,15 @@ 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;
+    /** The lock {@link scheduleUpdate} builds under. */
+    protected readonly workspaceLock: WorkspaceLock;
+    /** The latest write {@link scheduleUpdate} queued, until it ends; see {@link ScheduledUpdate}. */
+    protected scheduledUpdate?: ScheduledUpdate;
     /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
     protected readonly languageRegistry: ExtendedServiceRegistry;
     protected languageFileExtensions: string[];
@@ -106,11 +185,35 @@ 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;
+    /** Registered through {@link onDocumentPhaseDelivered}, by phase. */
+    protected readonly documentPhaseDeliveredListeners: MultiMap<DocumentState, (document: LangiumDocument, version: number) => void>;
+    /** Registered through {@link onBuildEnded}. */
+    protected readonly buildEndedListeners: Set<(drained: boolean) => void>;
+    /** Set while the lock read {@link checkWaitsOnceDrained} queued has not run. */
+    protected drainCheckQueued: boolean;
+    /** Resolved per call: the sync service reaches this builder. */
+    protected readonly versionSyncService: () => VersionSyncService;
     constructor(services: ServerSharedServicesMinimal, options?: DocumentBuilderOptions);
     /**
      * Stage an LSP event name for the next `update()` call. Adopters call before
-     * the update fires; `HydraniumDocumentUpdateHandler` does it for the
-     * four LSP events.
+     * the update fires; `HydraniumDocumentUpdateHandler` does it for the LSP
+     * events, and the release handler for the builds that follow a release.
      *
      * The framework stages the value and never reads it back. The consumer is a
      * subclass overriding the build logging, which takes
@@ -119,6 +222,30 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * with no read — that is the seam working, not a dead field.
      */
     markNextReason(reason: string | undefined): void;
+    /**
+     * Call `listener` with a document once every {@link onDocumentPhase}
+     * listener of `state` ran for it and none was skipped by cancellation, and
+     * with the text version the phase listeners were called at. A write during
+     * them moves the document's own version on, past what they saw.
+     *
+     * Only here is it known what the phase listeners delivered. Langium sets the
+     * document's state before it notifies, and a cancel between two listeners
+     * skips the rest, leaving the document at the phase with those listeners
+     * never run and nothing to run them later. A build-phase listener comes too
+     * late: a cancel after this document but before the batch ends skips it,
+     * although every listener of this document ran.
+     */
+    onDocumentPhaseDelivered(state: DocumentState, listener: (document: LangiumDocument, version: number) => void): Disposable;
+    /**
+     * Call `listener` with `drained` false once a build has run every phase
+     * ({@link buildDocuments}), and true once the lock has drained after a
+     * build that threw ({@link checkWaitsOnceDrained}); builds that throw
+     * before that drain share one call, so this does not count builds. A
+     * listener runs synchronously, inside the build or inside that check's lock
+     * read. A throw fails the finished build; in the read it skips the
+     * listeners after it and surfaces only as an unhandled rejection.
+     */
+    protected onBuildEnded(listener: (drained: boolean) => void): Disposable;
     /**
      * Diagnostic snapshot for use in timeout/error messages around document
      * state.
@@ -130,6 +257,25 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * duplicate what this already knows.
      */
     formatBuildStatus(uri: URI): string;
+    /**
+     * The last phase a rebuild reaches under {@link updateBuildOptions}:
+     * `Validated`, or {@link IntegrityService.SettledState} when rebuilds do
+     * not validate, since no build then reaches `Validated` and a wait for it
+     * would never end. A document a `shouldValidate` override skips stops
+     * short of it; waiting on it is this builder's to resolve. An override that
+     * returns a phase rebuilds never reach makes every wait for it hang, the
+     * session writes that answer at it included.
+     */
+    finalBuildState(): DocumentState;
+    /** Render a session for a status line. `undefined` — no build in progress — reads as `none`. */
+    protected formatSession(session: BuildSession | undefined): string;
+    /**
+     * Resolve once the document at `uri` reaches `state`, or without `uri`, once
+     * the workspace does. A wait on `uri` re-queues a document no build is
+     * carrying, as {@link awaitDocumentState} describes.
+     */
+    waitUntil(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+    waitUntil(state: DocumentState, uri?: URI, cancelToken?: CancellationToken, options?: WaitUntilOptions): Promise<URI>;
     /**
      * Two edge cases the default Langium implementation rejects on:
      * - Document below target state with no build active (newly-created file):
@@ -144,15 +290,43 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      *
      * Replacing Langium's rejection with a wait makes the wait's liveness this
      * class's responsibility: a listener can only fire if some build is still
-     * going to reach `state`. Both re-queue sites below exist for that, and they
-     * differ only in when the orphaning is observed — {@link isOrphaned} at
-     * registration time, the `onBuildPhase` branch for a build cancelled after
-     * the wait was already armed. Re-queuing stops after
+     * going to reach `state`. So the wait re-queues the document whenever
+     * {@link isOrphaned} holds: once when it is armed, and again after every
+     * build that completes (see {@link buildDocuments}). The second check is
+     * the one a wait armed during a build needs, since only the build's end
+     * shows whether it left the document behind; Langium's `onBuildPhase` for
+     * `Validated` cannot serve, as it stays silent for a build that validates
+     * nothing, such as the workspace's initial one. A build that throws is
+     * checked once the lock drains instead (see {@link checkWaitsOnceDrained}):
+     * whatever cancelled it may build nothing. Re-queuing stops after
      * {@link MAX_STALLED_REQUEUES} builds that fail to advance the document, so a
      * document the builder will never carry to `state` degrades to a pending wait
-     * plus a warning rather than an endless build loop.
+     * plus a warning rather than an endless build loop. With `rejectWhenStuck`,
+     * the wait rejects instead, both then and once
+     * `VersionSyncService.requestRecoveryBuild` gives up a re-queued build.
+     *
+     * A wait for `Validated` on a document that a validating build skips
+     * resolves once that build has indexed its references, without diagnostics:
+     * see {@link skipsValidation}. Waiting on would never end, and re-queuing
+     * would skip it again.
+     *
+     * A re-queued build takes the {@link WorkspaceLock} (see
+     * {@link requeueOrphaned}), so a caller that awaits this wait while it holds
+     * the lock, inside a read or write action, deadlocks on a document that needs
+     * a re-queue: the build waits for that action to end. Await it outside the
+     * lock.
+     */
+    protected awaitDocumentState(state: DocumentState, uri: URI, cancelToken: CancellationToken, { rejectWhenStuck }?: WaitUntilOptions): Promise<URI>;
+    /**
+     * Whether the build that carries or last carried `document` has indexed its
+     * references, asks for validation, and still skips it, which is an override
+     * of `shouldValidate` excluding it. A build that does not ask for
+     * validation, such as the workspace's initial one, is not a skip: the next
+     * validating build validates the document. Nor is a document below
+     * `IndexedReferences`: the build writes its options before the first phase,
+     * so the document would pass for skipped before it is even parsed.
      */
-    protected awaitDocumentState(state: DocumentState, uri: URI, cancelToken: CancellationToken): Promise<URI>;
+    protected skipsValidation(document: LangiumDocument): boolean;
     /**
      * Whether no build will advance `document` to `state`, so a wait on it can
      * only be resolved by starting one.
@@ -170,17 +344,107 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * `currentState` still advances to `Validated` (the validation phase runs
      * over an empty document list). Any first read that wants diagnostics — a
      * one-shot data-head read, a CLI query, `ModelService.validated` — lands
-     * here.
+     * here. A read that arrives while that build still runs finds `currentState`
+     * below `state`, so this holds for it only once the build has ended, which
+     * is why {@link awaitDocumentState} asks again then.
      */
     protected isOrphaned(document: LangiumDocument, state: DocumentState): boolean;
     /**
-     * Schedule a build for a document no in-flight build will advance. Deliberately
-     * fire-and-forget: the caller is a waiter that resolves off the resulting phase
-     * notification, so awaiting here would invert the dependency. A rejection is
-     * logged rather than swallowed — it leaves the waiter pending until its own
-     * cancellation token fires, which is worth a line in the log.
+     * Schedule a build for a document no in-flight build will advance, through
+     * `VersionSyncService.requestRecoveryBuild`: from a {@link WorkspaceLock} read, so
+     * the build neither runs beside a locked one nor cancels the build a
+     * re-queue is fired from, and skipped if a write that ran meanwhile carried
+     * the document to `state`. The waiter resolves off the resulting phase
+     * notification; the answer only tells it whether the build was given up.
+     */
+    protected requeueOrphaned(document: LangiumDocument, state: DocumentState, reason: string): Promise<boolean>;
+    /**
+     * Build `changed` and `deleted` under the {@link WorkspaceLock}, as
+     * `workspaceLock.write(token => update(changed, deleted, token))` would,
+     * except where the build this method queued last already carries the
+     * request. The promise settles when the build that carries the request
+     * ends, completed or cancelled, as the lock's own promise does.
+     *
+     * Without it, requests that coincide cancel each other: each lock write
+     * cancels the one before it, after Langium's `update` has already reset the
+     * documents, scanned the workspace for relinking and called every
+     * `onUpdate` listener.
+     *
+     * - **Queued, not yet running:** the request merges into it, so nothing is
+     *   cancelled. The later of a change and a deletion of one URI wins, so
+     *   each URI reaches `update` in one list only: a file deleted and written
+     *   again before the build starts is a change.
+     * - **Running:** the request joins it only when {@link canJoinRunningUpdate}
+     *   holds, which keeps an edit made while it runs cancelling it.
+     * - **Otherwise,** or when anything else has cancelled that write since it
+     *   was queued, a new write, which cancels the running build as any lock
+     *   write does.
+     *
+     * `reason` is staged through {@link markNextReason} when the write runs. The
+     * latest reason of a merged request wins, as it does in the update
+     * handler's own debounced burst; a joining request's reason is dropped, since
+     * the build it joins has already started. A request without one leaves a
+     * reason staged by the caller in place.
+     *
+     * A caller that must run code of its own inside the write action takes the
+     * lock itself, and forgoes the sharing. A lock that is not a
+     * {@link HydraniumWorkspaceLock} cannot report a cancelled queued write, so
+     * every request then takes its own write.
+     */
+    scheduleUpdate(changed: URI[], deleted: URI[], reason?: string): Promise<void>;
+    /**
+     * Whether a request for `changed` and `deleted` is carried by the running
+     * `scheduled` build, whose write nothing has cancelled: the request deletes
+     * nothing, and each changed URI is one the build took, held by the text
+     * store at the version it had when the build started.
+     *
+     * Each condition keeps a request from joining a build that would miss its
+     * change. Text that moved since the start may be newer than what the build
+     * parsed; a URI the text store does not hold is read from its file, which
+     * may have changed after the build read it; and a deletion may concern a
+     * document the build has already built. A joined request is also absent
+     * from the running `update`'s `onUpdate` call, which reported the store as
+     * it was when the build started; at an unchanged version that is the store
+     * the request sees.
+     *
+     * The clients holding each URI must be unchanged too. Phase listeners that
+     * ask who holds a document, such as the push to an editor, may already have
+     * run for it, so a client that attached since would get no build that sees it.
+     */
+    protected canJoinRunningUpdate(scheduled: ScheduledUpdate, changed: URI[], deleted: URI[]): boolean;
+    /** The clients holding `uri` in the text store, or none when the store does not track them. */
+    protected clientsHolding(uri: URI): readonly string[];
+    /**
+     * The write action of a {@link scheduleUpdate}: freeze the request, record
+     * what it takes, stage its reason and run `update`. Releases
+     * {@link scheduledUpdate} inside the lock, whatever throws, so a request
+     * arriving after the build ends starts a write of its own rather than
+     * joining a build that is over.
      */
-    protected requeueOrphaned(document: LangiumDocument, state: DocumentState, reason: string): void;
+    protected runScheduledUpdate(request: ScheduledUpdate, token: CancellationToken): Promise<void>;
+    /**
+     * Tell the {@link buildEndedListeners} once every phase has run, which is
+     * the one point where a build that skipped a waited-on document can be seen
+     * to have ended. Langium's `onBuildPhase` for `Validated` is not: it stays
+     * silent when no document reached that phase, which is every build that
+     * validates nothing, the workspace's initial one among them.
+     *
+     * A build that throws, whether cancelled or failed, tells none of them
+     * here: `currentState` is then below `Validated`, so {@link isOrphaned}
+     * could hold for no wait. {@link checkWaitsOnceDrained} tells them instead.
+     */
+    protected buildDocuments(documents: LangiumDocument[], options: BuildOptions, cancelToken: CancellationToken): Promise<void>;
+    /**
+     * After a build that threw, tell the {@link buildEndedListeners}, with
+     * `drained` set, from a {@link WorkspaceLock} read: it runs once no write
+     * runs or is queued, so no locked build is left that could still carry a
+     * waited-on document. A cancelled build is usually followed by its
+     * canceller's, but a write that builds nothing, such as a release build
+     * that finds its document reopened, leaves a wait armed during the build
+     * with nothing to resolve it, and so does a build that fails. One read
+     * serves every build that throws before it runs.
+     */
+    protected checkWaitsOnceDrained(): void;
     /**
      * Don't let a cancelled non-validating build suppress validation forever.
      *
@@ -228,6 +492,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).
@@ -318,9 +588,16 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * documents*: the Node provider walks the real filesystem (a freshly added
      * directory or never-opened file still builds), while a browser / empty
      * provider yields nothing. `uriPolicy.loadUri` first maps the URI to its
-     * load identity — `undefined` (no on-disk content) short-circuits to `[]`
-     * rather than a doomed read, and a symlink resolves to its real path so the
-     * built documents key the same way every other layer does.
+     * load identity, and a symlink resolves to its real path so the built
+     * documents key the same way every other layer does.
+     *
+     * A URI with no on-disk content is dropped rather than read, unless the text
+     * store or the document registry holds it, under its canonical URI, the key
+     * both hold it by. A document created and not yet saved has text but no
+     * file, and a policy that checks the disk reports it absent. A registered
+     * document whose file has gone is kept too: its rebuild then fails on the
+     * read, which is how the release handler learns to remove it rather
+     * than leave it holding its last client's text.
      */
     protected flattenAndAdaptURI(uri: URI): URI[];
     /** Recurse `uri` through the `FileSystemProvider`, gathering registered
@@ -340,10 +617,66 @@ 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. A build outside the workspace lock overlaps another:
+     * the later one installs itself as {@link activeSession} while the earlier
+     * one is still running, and the earlier one's `finally` runs LAST. Clearing
+     * unconditionally there would discard the later build'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.
+     *
+     * Builds outside the lock are not hypothetical even without an adopter: the
+     * model service under `allowReentrantBuilds` starts one. Two locked builds
+     * never overlap, since the lock starts a write only once the write it
+     * cancelled has unwound.
+     */
+    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>;
     /**
@@ -374,8 +707,8 @@ export declare class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * twice: Langium's validate appends to `document.diagnostics` when they are
      * already set — deliberately, so a category-partitioned pass keeps the earlier
      * category's findings — and a repeated FULL pass therefore doubles the list.
-     * `ModelServiceOptions.serializeBuilds` prevents that at the source; this is
-     * the net for configurations that allow concurrent builds anyway.
+     * The write lock prevents that at the source; this is the net for builds
+     * that skip it, as `ModelServiceOptions.allowReentrantBuilds` lets one do.
      *
      * Clearing the list before a pass is NOT an alternative: the append happens at
      * pass completion, so two interleaved passes both clear, both finish, and the
@@ -399,7 +732,46 @@ 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. The write lock closes it, so "every
+     * diagnostic is rendered" holds while
+     * `ModelServiceOptions.allowReentrantBuilds` is `false`, its default.
+     * Turning it on 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