@hydranium/core 1.0.0-next.32 → 1.0.0-next.320

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

@@ -7,7 +7,15 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock, type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
+import {
+   type Clock,
+   type Stopwatch,
+   type LogThreshold,
+   type MaybeObservableValue,
+   ObservableValue,
+   type Tracer,
+   describeErrorWithStack
+} from '@hydranium/protocol';
 import {
    type AstNode,
    type BuildOptions,
@@ -15,22 +23,28 @@ import {
    type DocumentPhaseListener,
    DocumentState,
    type LangiumDocument,
+   MultiMap,
    OperationCancelled,
-   type URI,
+   URI,
    UriUtils,
+   type WorkspaceLock,
    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 type { HydraniumTextDocuments } from '../../documents/hydranium-text-documents.js';
+import { type VersionSyncService } from '../../documents/version-sync-service.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
-import type { ServerMessageRenderer } from '../../messages/renderer.js';
+import { IntegrityService } from '../integrity/integrity-service.js';
+import type { MessageRenderer } from '../../messages/renderer.js';
 import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residency-service.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 { HydraniumWorkspaceLock } from '../workspace/hydranium-workspace-lock.js';
 import { BuildSession, type BuildSessionContext } from './build-session.js';
 import { type LabeledPhaseListener, labelPhaseListener } from './labeled-phase-listener.js';
 
@@ -44,6 +58,21 @@ export const DEFAULT_LOGGED_PHASES: DocumentState[] = [
    DocumentState.Validated
 ];
 
+/**
+ * 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 const HYDRANIUM_BUILD_REASONS = Object.freeze({
+   didOpen: 'didOpen',
+   didChangeContent: 'didChangeContent',
+   didChangeWatchedFiles: 'didChangeWatchedFiles',
+   didRelease: 'didRelease'
+} as const);
+
 /**
  * Consecutive re-queued builds that leave a waited-on document at the same state
  * before {@link HydraniumDocumentBuilder.awaitDocumentState} stops re-queuing it.
@@ -109,14 +138,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;
+}
+
+/** What {@link HydraniumDocumentBuilder.onBuildEnded} tells a listener. */
+export interface BuildEndedEvent {
+   /**
+    * `true` once a build ran every phase, validating or not; `false` once the
+    * lock has drained after builds that threw, cancelled or failed, which
+    * share one event.
+    */
+   readonly completed: 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>;
+}
+
+/**
+ * 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: object | undefined): store is Pick<HydraniumTextDocuments, 'clientsOf'> {
+   return store !== undefined && 'clientsOf' in store && typeof store.clientsOf === 'function';
+}
+
+function sameClients(taken: readonly string[] | undefined, current: readonly string[]): boolean {
+   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), 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}.
@@ -158,13 +245,18 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly phaseDetailMs: ObservableValue<number>;
    protected readonly uriPolicy: DocumentUriPolicy;
    protected readonly clock: Clock;
-   protected readonly messageRenderer: ServerMessageRenderer;
+   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[] = [];
    /** {@link ExtendedServiceRegistry.registrations} {@link languageFileExtensions} was built at; `-1` until first built. */
    protected cachedRegistrations = -1;
-   protected lastPhaseMs = 0;
+   /** Running since the last phase was reached, or since the active build started. */
+   protected sinceLastPhase?: Stopwatch;
    /** Resolved from {@link DocumentBuilderOptions.refreshCrossDocumentComputedScopes}. */
    protected readonly refreshCrossDocumentComputedScopes: boolean;
    /** LSP event name (e.g. `'didChangeWatchedFiles'`) staged for the next `update()` call. */
@@ -185,6 +277,14 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     * 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 = new MultiMap<DocumentState, (document: LangiumDocument, version: number) => void>();
+   /** Registered through {@link onBuildEnded}. */
+   protected readonly buildEndedListeners = new Set<(event: BuildEndedEvent) => void>();
+   /** Set while the lock read {@link checkWaitsOnceDrained} queued has not run. */
+   protected drainCheckQueued = false;
+   /** Resolved per call: the sync service reaches this builder. */
+   protected readonly versionSyncService: () => VersionSyncService;
 
    constructor(services: ServerSharedServicesMinimal, options: DocumentBuilderOptions = {}) {
       super(services);
@@ -192,6 +292,8 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       this.uriPolicy = services.workspace.DocumentUriPolicy;
       this.clock = services.Clock;
       this.messageRenderer = services.MessageRenderer;
+      this.workspaceLock = services.workspace.WorkspaceLock;
+      this.versionSyncService = () => services.workspace.VersionSyncService;
       this.tracer = services.Tracer.for(options.logName ?? 'DocumentBuilder').trace('instantiated');
       this.logLevel = options.logLevel ?? 'debug';
       this.loggedPhases = options.loggedPhases ?? DEFAULT_LOGGED_PHASES;
@@ -211,8 +313,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
@@ -224,6 +326,50 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       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: DocumentState, listener: (document: LangiumDocument, version: number) => void): Disposable {
+      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: (event: BuildEndedEvent) => void): Disposable {
+      this.buildEndedListeners.add(listener);
+      return Disposable.create(() => this.buildEndedListeners.delete(listener));
+   }
+
+   /** Tell every {@link buildEndedListeners} entry, each in isolation. */
+   protected notifyBuildEnded(event: BuildEndedEvent): void {
+      for (const listener of [...this.buildEndedListeners]) {
+         try {
+            listener(event);
+         } catch (error: unknown) {
+            this.tracer.error(`A build-ended listener failed: ${describeErrorWithStack(error)}`);
+         }
+      }
+   }
+
    /**
     * Diagnostic snapshot for use in timeout/error messages around document
     * state.
@@ -240,23 +386,54 @@ 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(): DocumentState {
+      return this.updateBuildOptions.validation ? DocumentState.Validated : IntegrityService.SettledState;
+   }
+
    /** Render a session for a status line. `undefined` — no build in progress — reads as `none`. */
    protected formatSession(session: BuildSession | undefined): string {
       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)`;
    }
 
    // ============================================================
    // Bug-fixes (always on)
    // ============================================================
 
+   /**
+    * 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.
+    */
+   override waitUntil(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+   override waitUntil(state: DocumentState, uri?: URI, cancelToken?: CancellationToken, options?: WaitUntilOptions): Promise<URI>;
+   override waitUntil(
+      state: DocumentState,
+      uriOrToken?: URI | CancellationToken,
+      cancelToken?: CancellationToken,
+      options: WaitUntilOptions = {}
+   ): Promise<URI | void> {
+      return URI.isUri(uriOrToken)
+         ? this.awaitDocumentState(state, uriOrToken, cancelToken ?? CancellationToken.None, options)
+         : super.waitUntil(state, uriOrToken);
+   }
+
    /**
     * Two edge cases the default Langium implementation rejects on:
     * - Document below target state with no build active (newly-created file):
@@ -271,20 +448,43 @@ 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.
     */
-   protected override awaitDocumentState(state: DocumentState, uri: URI, cancelToken: CancellationToken): Promise<URI> {
+   protected override awaitDocumentState(
+      state: DocumentState,
+      uri: URI,
+      cancelToken: CancellationToken,
+      { rejectWhenStuck = false }: WaitUntilOptions = {}
+   ): Promise<URI> {
       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<URI>((resolve, reject) => {
@@ -297,15 +497,31 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
          // land while a busy workspace keeps cancelling builds.
          let stalledRequeues = 0;
          let lastRequeueState: DocumentState | undefined;
+         let settled = false;
+         let cancelled = false;
+         const giveUp = (reason: string, cause?: unknown): void => {
+            cleanup();
+            reject(
+               new Error(
+                  `Gave up building ${this.formatUri(uri)} to '${DocumentState[state]}' ` +
+                     `(at '${DocumentState[document.state]}'): ${reason}`,
+                  { cause }
+               )
+            );
+         };
          const requeue = (reason: string): void => {
             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;
                }
@@ -313,7 +529,18 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                stalledRequeues = 0;
                lastRequeueState = document.state;
             }
-            this.requeueOrphaned(document, state, reason);
+            this.requeueOrphaned(document, state, reason).catch((error: unknown) => {
+               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,
@@ -324,34 +551,73 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                }
             }, '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: LangiumDocument): void => {
+                       if (UriUtils.equals(doc.uri, uri) && this.skipsValidation(doc)) {
+                          cleanup();
+                          resolve(doc.uri);
+                       }
+                    }, 'awaitDocumentState.skipsValidation')
+                 )
+               : Disposable.create(() => undefined);
+         const buildEnded = ({ completed }: BuildEndedEvent): void => {
+            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 = (): void => {
+            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.
+    */
+   protected skipsValidation(document: LangiumDocument): boolean {
+      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.
@@ -369,26 +635,219 @@ 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.
     */
    protected isOrphaned(document: LangiumDocument, state: DocumentState): boolean {
       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.
+    * 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.
     */
-   protected requeueOrphaned(document: LangiumDocument, state: DocumentState, reason: string): void {
+   protected requeueOrphaned(document: LangiumDocument, state: DocumentState, reason: string): Promise<void> {
       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: unknown) => {
-         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: URI[], deleted: URI[], reason?: string): Promise<void> {
+      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: ScheduledUpdate = {
+         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.
+    */
+   protected canJoinRunningUpdate(scheduled: ScheduledUpdate, changed: URI[], deleted: URI[]): boolean {
+      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. */
+   protected clientsHolding(uri: URI): readonly string[] {
+      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.
+    */
+   protected async runScheduledUpdate(request: ScheduledUpdate, token: CancellationToken): Promise<void> {
+      try {
+         const taken = new Map<string, number>();
+         const takenClients = new Map<string, readonly string[]>();
+         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.
+    */
+   protected override async buildDocuments(
+      documents: LangiumDocument[],
+      options: BuildOptions,
+      cancelToken: CancellationToken
+   ): Promise<void> {
+      await super.buildDocuments(documents, options, cancelToken);
+      this.notifyBuildEnded({ completed: true });
+   }
+
+   /**
+    * 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.
+    */
+   protected checkWaitsOnceDrained(): void {
+      if (this.drainCheckQueued) {
+         return;
+      }
+      this.drainCheckQueued = true;
+      void this.workspaceLock.read(() => {
+         this.drainCheckQueued = false;
+         this.notifyBuildEnded({ completed: false });
       });
    }
 
@@ -641,13 +1100,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.
     */
    protected flattenAndAdaptURI(uri: URI): 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
@@ -713,19 +1184,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.
     */
    protected runInSession(context: BuildSessionContext, label: string, body: () => Promise<void>): Promise<void> {
       // Read before installing the new session: the id being superseded belongs
@@ -747,7 +1219,7 @@ 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 () => {
@@ -757,6 +1229,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                if (isOperationCancelled(err)) {
                   session.cancelled = true;
                }
+               this.checkWaitsOnceDrained();
                throw err;
             } finally {
                this.endSession(session);
@@ -781,7 +1254,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     * throughout it.
     */
    protected createBuildSession(context: BuildSessionContext): BuildSession {
-      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);
    }
 
    /**
@@ -806,8 +1279,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     * {@link log}, which would route them straight back into the buffer.
     */
    protected flushSession(session: BuildSession): void {
-      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);
          }
@@ -855,9 +1327,8 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
 
    /** Called once per phase-reached event. Override to add custom side-effects beyond logging. */
    protected onPhaseReached(state: DocumentState, documents: LangiumDocument[]): void {
-      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) {
@@ -884,13 +1355,13 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       }
       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
    // ============================================================
 
    override async notifyDocumentPhase(document: LangiumDocument, state: DocumentState, cancelToken: CancellationToken): Promise<void> {
@@ -900,7 +1371,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.
@@ -908,13 +1379,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: number[] = [];
       let cancelledListeners = 0;
       const { elapsedMs: totalMs } = await this.clock.measure(async () => {
@@ -933,10 +1399,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));
@@ -1023,8 +1497,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
@@ -1099,10 +1573,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