@hydranium/core 1.0.0-next.38 → 1.0.0-next.380

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

@@ -6,13 +6,15 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { ObservableValue } from '@hydranium/protocol';
-import { DefaultDocumentBuilder, DocumentState, OperationCancelled, UriUtils, interruptAndCheck, isOperationCancelled } from '@hydranium/langium';
+import { Deferred, ObservableValue, describeErrorWithStack } from '@hydranium/protocol';
+import { DefaultDocumentBuilder, DocumentState, MultiMap, OperationCancelled, URI, UriUtils, interruptAndCheck, isOperationCancelled } from '@hydranium/langium';
 // `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 { CancellationToken, Diagnostic, Disposable } from 'vscode-languageserver-protocol';
+import { IntegrityService } from '../integrity/integrity-service.js';
 import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residency-service.js';
+import { HydraniumWorkspaceLock } from '../workspace/hydranium-workspace-lock.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. */
@@ -24,6 +26,22 @@ export const DEFAULT_LOGGED_PHASES = [
     DocumentState.IndexedReferences,
     DocumentState.Validated
 ];
+/**
+ * The build reasons the framework stages through
+ * {@link HydraniumDocumentBuilder.markNextReason}: the LSP events the update
+ * handler dispatches on, `didRelease` for the builds the
+ * `DocumentReleaseHandler` runs once the text store has released a document,
+ * and `memberRelink` for the follow-up builds a project manager queues to
+ * relink a changed project's members. Exposed so a subclass layering reasons
+ * of its own keeps the names the framework emits.
+ */
+export const HYDRANIUM_BUILD_REASONS = Object.freeze({
+    didOpen: 'didOpen',
+    didChangeContent: 'didChangeContent',
+    didChangeWatchedFiles: 'didChangeWatchedFiles',
+    didRelease: 'didRelease',
+    memberRelink: 'memberRelink'
+});
 /**
  * Consecutive re-queued builds that leave a waited-on document at the same state
  * before {@link HydraniumDocumentBuilder.awaitDocumentState} stops re-queuing it.
@@ -32,14 +50,29 @@ export const DEFAULT_LOGGED_PHASES = [
  * case this exists for.
  */
 const MAX_STALLED_REQUEUES = 3;
+/**
+ * Whether `store` reports the clients holding a document. Checked by shape,
+ * because importing the store's class here closes an import cycle.
+ */
+function tracksClients(store) {
+    return store !== undefined && 'clientsOf' in store && typeof store.clientsOf === 'function';
+}
+function sameClients(taken, current) {
+    return taken !== undefined && taken.length === current.length && taken.every((client, i) => client === current[i]);
+}
 /**
  * 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), an {@link awaitBuilderState} that resolves once a
+ *   phase ends, whether armed during its notification or on a phase no
+ *   document reached, 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}.
@@ -82,12 +115,17 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     uriPolicy;
     clock;
     messageRenderer;
+    /** The lock {@link scheduleUpdate} builds under. */
+    workspaceLock;
+    /** The latest write {@link scheduleUpdate} queued, until it ends; see {@link ScheduledUpdate}. */
+    scheduledUpdate;
     /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
     languageRegistry;
     languageFileExtensions = [];
     /** {@link ExtendedServiceRegistry.registrations} {@link languageFileExtensions} was built at; `-1` until first built. */
     cachedRegistrations = -1;
-    lastPhaseMs = 0;
+    /** Running since the last phase was reached, or since the active build started. */
+    sinceLastPhase;
     /** Resolved from {@link DocumentBuilderOptions.refreshCrossDocumentComputedScopes}. */
     refreshCrossDocumentComputedScopes;
     /** LSP event name (e.g. `'didChangeWatchedFiles'`) staged for the next `update()` call. */
@@ -102,18 +140,39 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * construction.
      */
     activeSession;
+    /** Set while an explicit {@link build} calls the `onUpdate` listeners, see {@link isInsideBuildUpdate}. */
+    insideBuildUpdate = false;
+    /** How many builds have started and not ended. */
+    runningBuilds = 0;
+    /** Resolved once {@link runningBuilds} drops back to zero. Set while it is above. */
+    runningBuildsEnded;
     /**
      * `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;
+    /** Registered through {@link onDocumentPhaseDelivered}, by phase. */
+    documentPhaseDeliveredListeners = new MultiMap();
+    /** Registered through {@link onBuildEnded}. */
+    buildEndedListeners = new Set();
+    /** Held by {@link awaitBuilderState} until {@link runCancelable} sees their state reached. */
+    builderStateWaits = new Set();
+    /** Set while the lock read {@link checkWaitsOnceDrained} queued has not run. */
+    drainCheckQueued = false;
+    /** A thunk: a version-sync service whose constructor reads the builder would otherwise be a cycle. */
+    versionSyncService;
+    /** A thunk: a residency service whose constructor reads the builder would otherwise be a cycle. */
+    cstResidency;
     constructor(services, options = {}) {
         super(services);
         this.languageRegistry = services.ServiceRegistry;
         this.uriPolicy = services.workspace.DocumentUriPolicy;
         this.clock = services.Clock;
         this.messageRenderer = services.MessageRenderer;
+        this.workspaceLock = services.workspace.WorkspaceLock;
+        this.versionSyncService = () => services.workspace.VersionSyncService;
+        this.cstResidency = () => services.workspace.CstResidencyService;
         this.tracer = services.Tracer.for(options.logName ?? 'DocumentBuilder').trace('instantiated');
         this.logLevel = options.logLevel ?? 'debug';
         this.loggedPhases = options.loggedPhases ?? DEFAULT_LOGGED_PHASES;
@@ -131,8 +190,8 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     // ============================================================
     /**
      * 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
@@ -143,6 +202,68 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     markNextReason(reason) {
         this.pendingUpdateReason = reason;
     }
+    /**
+     * 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, listener) {
+        this.documentPhaseDeliveredListeners.add(state, listener);
+        return Disposable.create(() => this.documentPhaseDeliveredListeners.delete(state, listener));
+    }
+    /**
+     * Call `listener` when a build ends: once it has run every phase, which
+     * Langium's `onBuildPhase` cannot tell for a build that validates nothing,
+     * and once the lock has drained after builds that threw. Builds that throw
+     * before that drain share one call, so this does not count builds.
+     *
+     * A listener runs synchronously, inside the build or inside the lock read
+     * that waits for the drain, so it must not wait on a build. One that
+     * throws is logged and skipped; the build and the other listeners go on.
+     */
+    onBuildEnded(listener) {
+        this.buildEndedListeners.add(listener);
+        return Disposable.create(() => this.buildEndedListeners.delete(listener));
+    }
+    /** Tell every {@link buildEndedListeners} entry, each in isolation. */
+    notifyBuildEnded(event) {
+        for (const listener of [...this.buildEndedListeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                this.tracer.error(`A build-ended listener failed: ${describeErrorWithStack(error)}`);
+            }
+        }
+    }
+    /**
+     * Whether an explicit {@link build}, rather than {@link update}, is calling
+     * the `onUpdate` listeners. Langium calls them from both. A listener reads
+     * this before its first await, since it is set only while `build` runs
+     * synchronously, which reaches the listeners. That makes it exact while
+     * builds overlap, where no record of the running builds could tell which
+     * one is calling.
+     */
+    isInsideBuildUpdate() {
+        return this.insideBuildUpdate;
+    }
+    /**
+     * Resolves once no build is in progress, however each ended, and never
+     * rejects. It is `undefined` between builds. During a lock read no locked
+     * build runs, so a build seen there runs outside the lock. Builds that
+     * overlap count until the last of them ends.
+     */
+    get activeBuild() {
+        return this.runningBuildsEnded?.promise;
+    }
     /**
      * Diagnostic snapshot for use in timeout/error messages around document
      * state.
@@ -159,20 +280,44 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         // the document is keyed by its real path.
         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';
+        const lastPhase = this.sinceLastPhase ? `${Math.round(this.sinceLastPhase.elapsedMs)}ms ago` : 'no phase observed';
         return `current state: '${docState}', last phase: ${lastPhase}, active build: ${this.formatSession(this.activeSession)}`;
     }
+    /**
+     * 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() {
+        return this.updateBuildOptions.validation ? DocumentState.Validated : IntegrityService.SettledState;
+    }
+    /**
+     * Whether the build that carries `document` validates it, as Langium's
+     * protected `shouldValidate` decides. One it does not validate ends that
+     * build at `IndexedReferences`. Answers for the running build once its
+     * first phase has started, and before that for the build that last
+     * carried `document`.
+     */
+    shouldValidateDocument(document) {
+        return this.shouldValidate(document);
+    }
     /** 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)`;
+        return `${id} (${session.trigger}, ${Math.round(session.sinceStart.elapsedMs)}ms in)`;
+    }
+    waitUntil(state, uriOrToken, cancelToken, options = {}) {
+        return URI.isUri(uriOrToken)
+            ? this.awaitDocumentState(state, uriOrToken, cancelToken ?? CancellationToken.None, options)
+            : super.waitUntil(state, uriOrToken);
     }
-    // ============================================================
-    // Bug-fixes (always on)
-    // ============================================================
     /**
      * Two edge cases the default Langium implementation rejects on:
      * - Document below target state with no build active (newly-created file):
@@ -187,20 +332,38 @@ export 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.
      */
-    awaitDocumentState(state, uri, cancelToken) {
+    awaitDocumentState(state, uri, cancelToken, { rejectWhenStuck = false } = {}) {
         const document = this.langiumDocuments.getDocument(uri);
         if (!document) {
             return super.awaitDocumentState(state, uri, cancelToken);
         }
-        if (document.state >= state) {
+        if (document.state >= state || (state === DocumentState.Validated && this.skipsValidation(document))) {
             return Promise.resolve(uri);
         }
         return new Promise((resolve, reject) => {
@@ -213,14 +376,25 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
             // land while a busy workspace keeps cancelling builds.
             let stalledRequeues = 0;
             let lastRequeueState;
+            let settled = false;
+            let cancelled = false;
+            const giveUp = (reason, cause) => {
+                cleanup();
+                reject(new Error(`Gave up building ${this.formatUri(uri)} to '${DocumentState[state]}' ` +
+                    `(at '${DocumentState[document.state]}'): ${reason}`, { cause }));
+            };
             const requeue = (reason) => {
                 if (document.state === lastRequeueState) {
                     if (++stalledRequeues > MAX_STALLED_REQUEUES) {
+                        const stalled = `${stalledRequeues} builds did not advance it`;
+                        if (rejectWhenStuck) {
+                            giveUp(stalled);
+                            return;
+                        }
                         this.tracer
                             .withUri(uri.toString())
                             .warn(`Giving up re-queuing ${this.formatUri(uri)}: stuck at '${DocumentState[document.state]}', needs ` +
-                            `'${DocumentState[state]}' after ${stalledRequeues} builds that did not advance it. ` +
-                            'The wait now depends on its cancellation token.');
+                            `'${DocumentState[state]}' after ${stalled}. The wait now depends on its cancellation token.`);
                         return;
                     }
                 }
@@ -228,7 +402,20 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                     stalledRequeues = 0;
                     lastRequeueState = document.state;
                 }
-                this.requeueOrphaned(document, state, reason);
+                this.requeueOrphaned(document, state, reason).catch((error) => {
+                    const line = `A recovery build of ${this.formatUri(uri)} failed. ${describeErrorWithStack(error)}`;
+                    if (rejectWhenStuck && !settled) {
+                        giveUp('its recovery build failed', error);
+                    }
+                    else if (settled && !cancelled) {
+                        // The wait ended with an outcome its caller reports, and the retry warned.
+                        this.tracer.withUri(uri.toString()).debug(line);
+                    }
+                    else {
+                        // The waiter has gone, or waits on its cancellation token alone, so nothing else reports this.
+                        this.tracer.withUri(uri.toString()).error(line);
+                    }
+                });
             };
             const phaseDisposable = this.onDocumentPhase(state, labelPhaseListener((doc) => {
                 if (UriUtils.equals(doc.uri, uri)) {
@@ -236,34 +423,66 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                     resolve(doc.uri);
                 }
             }, 'awaitDocumentState'));
-            const buildDisposable = this.onBuildPhase(DocumentState.Validated, () => {
-                if (document.state >= state) {
+            // The phase after which a validating build either validates the
+            // document or has skipped it.
+            const skipDisposable = state === DocumentState.Validated
+                ? this.onDocumentPhase(DocumentState.IndexedReferences, labelPhaseListener((doc) => {
+                    if (UriUtils.equals(doc.uri, uri) && this.skipsValidation(doc)) {
+                        cleanup();
+                        resolve(doc.uri);
+                    }
+                }, 'awaitDocumentState.skipsValidation'))
+                : Disposable.create(() => undefined);
+            const buildEnded = ({ completed }) => {
+                if (document.state >= state || (state === DocumentState.Validated && this.skipsValidation(document))) {
                     cleanup();
                     resolve(uri);
                 }
-                else {
-                    // Orphaned by a cancelled build — re-queue so the next build catches it up.
-                    requeue('cancelled build');
+                else if (completed ? this.isOrphaned(document, state) : this.activeSession === undefined) {
+                    // No build is left to carry the document to `state`. Either
+                    // check fails only while an unlocked build still runs; that
+                    // build carries the document or ends here too.
+                    requeue(completed ? 'build ended short of the target' : 'build ended early');
                 }
-            });
+            };
+            const buildDisposable = this.onBuildEnded(buildEnded);
             const cancelDisposable = cancelToken.onCancellationRequested(() => {
+                cancelled = true;
                 cleanup();
                 reject(OperationCancelled);
             });
             const cleanup = () => {
+                settled = true;
                 phaseDisposable.dispose();
+                skipDisposable.dispose();
                 buildDisposable.dispose();
                 cancelDisposable.dispose();
             };
             // Orphaned BEFORE the wait was armed: the build that would have
-            // advanced this document has already finished, so neither listener
-            // above can ever fire. Re-queue now — the listeners are registered, so
-            // the resulting build resolves this wait.
-            if (this.isOrphaned(document, state)) {
+            // advanced this document has already finished, so none of these
+            // listeners fires until some other build runs. Re-queue now — the listeners are
+            // registered, so the resulting build resolves this wait.
+            // With `rejectWhenStuck`, also a document a failed build left behind:
+            // no build ends to re-queue it, so the wait would never give up.
+            if (this.isOrphaned(document, state) || (rejectWhenStuck && this.activeSession === undefined)) {
                 requeue('quiescent builder');
             }
         });
     }
+    /**
+     * 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.
+     */
+    skipsValidation(document) {
+        return (document.state >= DocumentState.IndexedReferences &&
+            Boolean(this.getBuildOptions(document).validation) &&
+            !this.shouldValidate(document));
+    }
     /**
      * Whether no build will advance `document` to `state`, so a wait on it can
      * only be resolved by starting one.
@@ -281,25 +500,267 @@ export 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.
      */
     isOrphaned(document, state) {
         return document.state < state && this.currentState >= state;
     }
     /**
-     * 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.
+     * Resolve once `currentState` reaches `state`, which {@link runCancelable}
+     * checks after every phase.
+     *
+     * Langium's waits for `onBuildPhase(state)`, which never fires for a wait
+     * armed while that phase notifies its listeners: the notification calls a
+     * copy of the listener list taken before it yields to the event loop, and
+     * `currentState` is raised only after it. Nor does it fire for a phase no
+     * document reached. Either way the wait never ends, and neither does the
+     * request Langium holds on it.
+     */
+    awaitBuilderState(state, cancelToken) {
+        if (this.currentState >= state) {
+            return Promise.resolve();
+        }
+        if (cancelToken.isCancellationRequested) {
+            return Promise.reject(OperationCancelled);
+        }
+        return new Promise((resolve, reject) => {
+            const settle = (outcome) => {
+                this.builderStateWaits.delete(wait);
+                cancelled.dispose();
+                outcome();
+            };
+            const wait = { state, resolve: () => settle(resolve) };
+            const cancelled = cancelToken.onCancellationRequested(() => settle(() => reject(OperationCancelled)));
+            this.builderStateWaits.add(wait);
+        });
+    }
+    async runCancelable(documents, targetState, cancelToken, callback) {
+        await super.runCancelable(documents, targetState, cancelToken, callback);
+        for (const wait of this.builderStateWaits) {
+            if (this.currentState >= wait.state) {
+                wait.resolve();
+            }
+        }
+    }
+    /**
+     * 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 promise only tells it whether the build was given up.
      */
     requeueOrphaned(document, state, reason) {
         const tracer = this.tracer.withUri(document.uri.toString());
-        tracer.info(`Re-queuing orphaned document (at '${DocumentState[document.state]}', needs '${DocumentState[state]}'): ${reason}`);
-        this.update([document.uri], []).catch((err) => {
-            if (!isOperationCancelled(err)) {
-                tracer.error(`Re-queue build failed: ${err instanceof Error ? err.message : String(err)}`);
+        tracer.debug(`Re-queuing orphaned document (at '${DocumentState[document.state]}', needs '${DocumentState[state]}'): ${reason}`);
+        return this.versionSyncService().requestRecoveryBuild(document.uri, {
+            // Skipped on purpose: a waiting caller is answered sooner, at the cost
+            // of a possible duplicate build once the debounce fires.
+            ignoreDeferred: true,
+            stillNeeded: () => document.state < state
+        });
+    }
+    // ============================================================
+    // Scheduled updates — one locked build for requests that coincide
+    // ============================================================
+    /**
+     * 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, deleted, reason) {
+        const lock = this.workspaceLock;
+        if (!(lock instanceof HydraniumWorkspaceLock)) {
+            return lock.write(token => {
+                if (reason !== undefined) {
+                    this.markNextReason(reason);
+                }
+                return this.update(changed, deleted, token);
+            });
+        }
+        const scheduled = this.scheduledUpdate;
+        if (scheduled && scheduled.cancellations === lock.writeCancellations) {
+            if (!scheduled.takenVersions) {
+                for (const uri of changed) {
+                    scheduled.changed.set(uri.toString(), uri);
+                    scheduled.deleted.delete(uri.toString());
+                }
+                for (const uri of deleted) {
+                    scheduled.deleted.set(uri.toString(), uri);
+                    scheduled.changed.delete(uri.toString());
+                }
+                scheduled.reason = reason ?? scheduled.reason;
+                return scheduled.promise;
+            }
+            if (this.canJoinRunningUpdate(scheduled, changed, deleted)) {
+                return scheduled.promise;
+            }
+        }
+        // The action runs on a later tick, by which time `request` is assigned.
+        const promise = lock.write(token => this.runScheduledUpdate(request, token));
+        const request = {
+            changed: new Map(changed.map(uri => [uri.toString(), uri])),
+            deleted: new Map(deleted.map(uri => [uri.toString(), uri])),
+            reason,
+            cancellations: lock.writeCancellations,
+            promise
+        };
+        this.scheduledUpdate = request;
+        return promise;
+    }
+    /**
+     * 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.
+     */
+    canJoinRunningUpdate(scheduled, changed, deleted) {
+        const taken = scheduled.takenVersions;
+        const takenClients = scheduled.takenClients;
+        if (!taken || deleted.length > 0) {
+            return false;
+        }
+        return changed.every(uri => taken.has(uri.toString()) &&
+            taken.get(uri.toString()) === this.textDocuments?.get(uri)?.version &&
+            sameClients(takenClients?.get(uri.toString()), this.clientsHolding(uri)));
+    }
+    /** The clients holding `uri` in the text store, or none when the store does not track them. */
+    clientsHolding(uri) {
+        const store = this.textDocuments;
+        return tracksClients(store) ? store.clientsOf(uri.toString()) : [];
+    }
+    /**
+     * 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.
+     */
+    async runScheduledUpdate(request, token) {
+        try {
+            const taken = new Map();
+            const takenClients = new Map();
+            for (const [key, uri] of request.changed) {
+                const version = this.textDocuments?.get(uri)?.version;
+                if (version !== undefined) {
+                    taken.set(key, version);
+                }
+                takenClients.set(key, this.clientsHolding(uri));
+            }
+            request.takenClients = takenClients;
+            request.takenVersions = taken;
+            if (request.reason !== undefined) {
+                this.markNextReason(request.reason);
+            }
+            await this.update([...request.changed.values()], [...request.deleted.values()], token);
+        }
+        finally {
+            if (this.scheduledUpdate === request) {
+                this.scheduledUpdate = undefined;
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async buildDocuments(documents, options, cancelToken) {
+        await this.rehydrateShedDocuments(documents, cancelToken);
+        await super.buildDocuments(documents, options, cancelToken);
+        this.notifyBuildEnded({ completed: true });
+    }
+    /**
+     * Graft the CST back onto every shed document the build advances, keeping
+     * its AST nodes so dependents outside the build stay linked to them.
+     * Indexing a document's references without its CST drops them from the
+     * reference index, so it would no longer be relinked when its targets
+     * change. Runs before Langium prepares the build, one document at a time
+     * with a cancellation check between, as the parse phase does. A refused or
+     * diverged graft resets the document to `Changed`, so this build re-parses
+     * it, and asks for a build after this one, whose relink selection reaches
+     * its dependents as those of a changed document.
+     */
+    async rehydrateShedDocuments(documents, cancelToken) {
+        for (const document of documents) {
+            if (document.state < DocumentState.Validated && isCstShed(document)) {
+                await interruptAndCheck(cancelToken);
+                this.tracer.debug(`rehydrating CST of ${this.formatUri(document.uri)} (re-entered build while shed)`);
+                this.cstResidency().rehydrate(document);
+                if (isCstShed(document)) {
+                    this.resetToState(document, CST_REHYDRATION_RESET_STATE);
+                    this.versionSyncService().rebuildWhileCurrent(document);
+                }
             }
+        }
+    }
+    /**
+     * After a build that threw, tell the {@link buildEndedListeners}, with
+     * `completed` false, 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.
+     */
+    checkWaitsOnceDrained() {
+        if (this.drainCheckQueued) {
+            return;
+        }
+        this.drainCheckQueued = true;
+        void this.workspaceLock.read(() => {
+            this.drainCheckQueued = false;
+            this.notifyBuildEnded({ completed: false });
         });
     }
     /**
@@ -388,7 +849,14 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      */
     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));
+        const outer = this.insideBuildUpdate;
+        this.insideBuildUpdate = true;
+        try {
+            return this.runInSession({ kind: 'build', trigger: `${documents.length} docs`, triggerCountsDocs: true, changed: uris, deleted: [] }, `Build documents (${documents.length} docs)`, () => super.build(documents, options, cancelToken));
+        }
+        finally {
+            this.insideBuildUpdate = outer;
+        }
     }
     /**
      * Refresh cross-document `ComputedScopes` derivations on cascade, when
@@ -416,27 +884,6 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * document per cascade.
      */
     resetToState(document, state) {
-        // Rehydrate-on-re-entry after CST shedding. A document whose CST was shed to
-        // reclaim memory (its `parseResult.value.$cstNode` nulled while the AST stays
-        // resident) cannot be relinked or re-indexed in place: Langium's
-        // `DefaultReferenceDescriptionProvider` derives the reference index — and thus
-        // `IndexManager.isAffected`, plus the `segment` used by rename / find-references —
-        // from each `reference.$refNode`. Re-running `IndexedReferences` with a shed CST
-        // drops the document's cross-references from the index (the provider skips any
-        // reference whose `$refNode` is missing), so its dependents silently stop being
-        // relinked when a referenced document changes, and they keep stale `.ref`s.
-        //
-        // So any re-entry into the build for a shed document must start from a full
-        // re-parse, which rebuilds the CST (and every `$refNode`). The residency
-        // feature owns both the "is shed" predicate and the recovery reset state
-        // (`CST_REHYDRATION_RESET_STATE`, necessarily `Changed`); this
-        // supersedes the `IndexedContent` cascade reset below — a re-parse re-runs
-        // every phase regardless.
-        if (isCstShed(document)) {
-            this.tracer.debug(`rehydrating CST of ${this.formatUri(document.uri)} (re-entered build while shed)`);
-            super.resetToState(document, CST_REHYDRATION_RESET_STATE);
-            return;
-        }
         const targetState = this.refreshCrossDocumentComputedScopes && state === DocumentState.ComputedScopes ? DocumentState.IndexedContent : state;
         super.resetToState(document, targetState);
     }
@@ -529,13 +976,25 @@ export 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.
      */
     flattenAndAdaptURI(uri) {
         const resolved = this.uriPolicy.loadUri(uri);
-        return resolved ? this.collectLanguageFiles(resolved) : [];
+        if (resolved) {
+            return this.collectLanguageFiles(resolved);
+        }
+        const canonical = UriUtils.toUri(this.uriPolicy.canonicalUri(uri));
+        const held = this.textDocuments?.get(canonical) !== undefined || this.langiumDocuments.hasDocument(canonical);
+        return held ? this.collectLanguageFiles(canonical) : [];
     }
     /** Recurse `uri` through the `FileSystemProvider`, gathering registered
      *  language files. A directory's entries carry their own `isDirectory`, so
@@ -596,19 +1055,20 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * 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,
+     * 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.
      *
-     * Re-entrancy is not hypothetical even without an adopter: {@link
-     * requeueOrphaned} calls `update` from inside a wait, while a build may be
-     * running.
+     * 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.
      */
     runInSession(context, label, body) {
         // Read before installing the new session: the id being superseded belongs
@@ -629,8 +1089,13 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         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;
+        this.sinceLastPhase = session.sinceStart;
         return this.tracer.time(label, async () => {
+            // Counted in the body, which the tracer calls synchronously, so a
+            // tracer that throws first leaves no build counted forever.
+            if (this.runningBuilds++ === 0) {
+                this.runningBuildsEnded = new Deferred();
+            }
             try {
                 await body();
             }
@@ -638,10 +1103,19 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                 if (isOperationCancelled(err)) {
                     session.cancelled = true;
                 }
+                this.checkWaitsOnceDrained();
                 throw err;
             }
             finally {
-                this.endSession(session);
+                try {
+                    this.endSession(session);
+                }
+                finally {
+                    if (--this.runningBuilds === 0) {
+                        this.runningBuildsEnded?.resolve();
+                        this.runningBuildsEnded = undefined;
+                    }
+                }
             }
         }, this.logLevel, {
             logAfterMs: 0,
@@ -659,7 +1133,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * throughout it.
      */
     createBuildSession(context) {
-        return new BuildSession(performance.now(), context.trigger, context.triggerCountsDocs, this.phaseDetailMs.value);
+        return new BuildSession(this.clock.stopwatch(), context.trigger, context.triggerCountsDocs, this.phaseDetailMs.value);
     }
     /**
      * Close `session`: flush what it buffered, then release it if it is still the
@@ -682,8 +1156,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * {@link log}, which would route them straight back into the buffer.
      */
     flushSession(session) {
-        const elapsedMs = performance.now() - session.startMs;
-        if (elapsedMs >= session.detailThresholdMs) {
+        if (session.sinceStart.elapsedMs >= session.detailThresholdMs) {
             for (const line of session.bufferedLines) {
                 this.emit(line);
             }
@@ -726,9 +1199,8 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     }
     /** Called once per phase-reached event. Override to add custom side-effects beyond logging. */
     onPhaseReached(state, documents) {
-        const now = performance.now();
-        const elapsedMs = Math.round(now - this.lastPhaseMs);
-        this.lastPhaseMs = now;
+        const elapsedMs = Math.round(this.sinceLastPhase?.elapsedMs ?? 0);
+        this.sinceLastPhase = this.clock.stopwatch();
         // 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) {
@@ -754,12 +1226,12 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
             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`
+            ? `${Math.round(session.sinceStart.elapsedMs)}ms since build start`
             : `${elapsedMs}ms since previous phase`;
         return `Reached phase '${DocumentState[state]}' [${docInfo}, ${elapsedInfo}]`;
     }
     // ============================================================
-    // Logging — slow-listener breakdown on notifyDocumentPhase
+    // notifyDocumentPhase — the delivery hook and the slow-listener breakdown
     // ============================================================
     async notifyDocumentPhase(document, state, cancelToken) {
         // Before the listeners, one of which is Langium's diagnostics publisher.
@@ -768,7 +1240,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
         // replacing it, and the publisher reads that array when it is invoked. A
         // 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.
+        // of the build that deduped. Only the write lock closes the window.
         //
         // Dedupe before rendering: rendering is deterministic, so it cannot
         // change which entries are structurally equal, and fewer survive to render.
@@ -776,13 +1248,8 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
             this.dedupeDiagnostics(document);
             this.renderDiagnostics(document);
         }
-        if (this.logLevel === 'off') {
-            return super.notifyDocumentPhase(document, state, cancelToken);
-        }
         const listeners = this.documentPhaseListeners.get(state).slice();
-        if (listeners.length === 0) {
-            return;
-        }
+        const version = document.textDocument.version;
         const perListenerMs = [];
         let cancelledListeners = 0;
         const { elapsedMs: totalMs } = await this.clock.measure(async () => {
@@ -802,10 +1269,18 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                 perListenerMs.push(elapsedMs);
             }
         });
+        if (cancelledListeners === 0) {
+            for (const delivered of this.documentPhaseDeliveredListeners.get(state).slice()) {
+                delivered(document, version);
+            }
+        }
+        if (this.logLevel === 'off' || listeners.length === 0) {
+            return;
+        }
         if (cancelledListeners > 0) {
             this.tracer
                 .withUri(document.uri.toString())
-                .info(this.cancelledDocumentPhaseLine(document, state, cancelledListeners, listeners.length));
+                .debug(this.cancelledDocumentPhaseLine(document, state, cancelledListeners, listeners.length));
         }
         if (totalMs >= this.slowPhaseMs.value) {
             this.log(this.slowDocumentPhaseLine(document, state, listeners, perListenerMs, totalMs));
@@ -875,8 +1350,8 @@ export 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
@@ -950,10 +1425,11 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
      * **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.
+     * 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
@@ -973,7 +1449,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
             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
+            // `string | MarkupContent` since LSP 3.18 — 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