@hydranium/core 1.0.0-next.135 → 1.0.0-next.140

package/src/documents/ast-document-manager.ts

@@ -19,7 +19,6 @@ import {
 } from '@hydranium/protocol';
 import {
    type AstNode,
-   type DocumentBuilder,
    DocumentState,
    type FileSystemProvider,
    type LangiumDocument,
@@ -83,7 +82,7 @@ import { TextDocumentIdentifier, type TextDocumentItem } from 'vscode-languagese
 import { type TextDocument } from 'vscode-languageserver-textdocument';
 import { URI } from '@hydranium/langium';
 import { type ServerSharedServices } from '../langium/module.js';
-import { labelPhaseListener } from '../langium/document-builder/index.js';
+import { type HydraniumDocumentBuilder, labelPhaseListener } from '../langium/document-builder/index.js';
 import { UNKNOWN_CLIENT_ID } from './client-ids.js';
 import { type HydraniumTextDocuments } from './hydranium-text-documents.js';
 import { type SelfSaveRegistry } from './self-save-registry.js';
@@ -177,6 +176,17 @@ export type AstDocumentSavedEvent<TAst extends AstNode, TDiagnostic extends AstD
    AstDocument<TAst, TDiagnostic>
 >;
 
+/**
+ * Why an update event fired and whose write it echoes, as
+ * {@link AstDocumentManager.attributeUpdate} answers for a document. The
+ * fields mean what they mean on `TransferUpdatedEvent`.
+ */
+export interface UpdateAttribution {
+   reason: 'changed' | 'rebuilt';
+   sourceClientId: string;
+   causedBy: string;
+}
+
 /** Construction options for {@link AstDocumentManager}. */
 export interface AstDocumentManagerOptions extends LogNameOptions {
    /**
@@ -227,6 +237,17 @@ export interface AstDocumentManager<TAst extends AstNode, TDiagnostic extends As
 
    /** Client id that authored the document's current version, or `undefined` for a framework-internal build. */
    getAuthor(document: LangiumDocument): string | undefined;
+
+   /**
+    * The reason, source and cause of an update event for `document` emitted
+    * now, from a phase listener of the build that carries it. Every head takes
+    * its update events' attribution from here, so they name the same client
+    * for one build. For a document a client opened, while rebuilds validate,
+    * the answer changes once its `Validated` listeners have all run: a later
+    * event at that version is `'rebuilt'`. `TransferDocumentUpdateReason`
+    * names the cases that fall back to the last update.
+    */
+   attributeUpdate(document: LangiumDocument): UpdateAttribution;
 }
 
 /**
@@ -253,7 +274,40 @@ export class DefaultAstDocumentManager<
    TAst extends AstNode,
    TDiagnostic extends AstDiagnostic = AstDiagnostic
 > implements AstDocumentManager<TAst, TDiagnostic> {
+   /** The last `DocumentBuilder.update`'s URIs; the reason for a document the store does not track. */
    protected lastUpdate?: UpdateInfo;
+   /**
+    * Canonical URIs a client has opened since the file was last deleted,
+    * whose versions the store keeps. One no client has opened keeps Langium's
+    * version `0` through every change of its content, so its version says
+    * nothing. Kept past the last close, since the store continues the version
+    * sequence on the next open; a delivery can land after that close.
+    */
+   protected readonly trackedUris = new Set<CanonicalUri>();
+   /**
+    * Per tracked URI, the version whose `Validated` listeners last all ran,
+    * which is the version an update event was delivered for. Dropped on
+    * deletion, so a file created again with the same text is changed again.
+    */
+   protected readonly deliveredVersions = new Map<CanonicalUri, number>();
+   /**
+    * Whose writes the build under way carries, set when it starts: the author
+    * of every open document's undelivered version, and the unknown-client id
+    * for a change no write explains, such as a deletion, a document no client
+    * has open, or a write that changed nothing. An undelivered version is one
+    * whose build has not validated it yet, so a write whose build was
+    * cancelled stays a cause of the build that takes over.
+    *
+    * Errs toward more than one cause, and so toward the unknown client, which
+    * a reader treats as foreign: an answer it repeats, never one it misses.
+    * A change no write explains counts for its own build only, so a build
+    * that takes over from a cancelled one loses it. One field for every build:
+    * a build started outside the workspace lock, such as a re-queue of an
+    * orphaned document, reads the causes of whichever build started last.
+    * An open document no build delivers, one a `shouldValidate` override
+    * skips, stays undelivered, so it is a cause of every build while open.
+    */
+   protected readonly buildCauses = new Set<string>();
 
    /** Per canonical URI, the newest save queued for it, which {@link coalesceSaves} lets older queued saves defer to. */
    protected readonly newestSaves = new Map<CanonicalUri, Promise<void>>();
@@ -262,7 +316,7 @@ export class DefaultAstDocumentManager<
    protected readonly textDocuments: HydraniumTextDocuments<TextDocument>;
    protected readonly fileSystemProvider: WritableFileSystemProvider;
    protected readonly langiumDocs: LangiumDocuments;
-   protected readonly documentBuilder: DocumentBuilder;
+   protected readonly documentBuilder: HydraniumDocumentBuilder;
    protected readonly uriPolicy: DocumentUriPolicy;
    protected readonly tracer: Tracer;
 
@@ -277,19 +331,40 @@ export class DefaultAstDocumentManager<
       this.uriPolicy = services.workspace.DocumentUriPolicy;
       this.tracer = services.Tracer.for(options.logName ?? 'AstDocumentManager').trace('instantiated');
       this.coalesceSaves = options.coalesceSaves ?? false;
-      this.textDocuments.onDidOpen(event =>
-         this.open({ clientId: event.clientId, uri: event.document.uri, languageId: event.document.languageId })
-      );
+      this.textDocuments.onDidOpen(event => {
+         this.trackedUris.add(this.uriPolicy.canonicalUri(event.document.uri));
+         return this.open({ clientId: event.clientId, uri: event.document.uri, languageId: event.document.languageId });
+      });
       this.textDocuments.onDidClose(event => this.close({ clientId: event.clientId, uri: event.document.uri }));
       this.documentBuilder.onUpdate((changed, deleted) => {
          this.lastUpdate = { changed, deleted };
+         this.buildCauses.clear();
+         for (const textDocument of this.textDocuments.all()) {
+            if (!this.isDelivered(textDocument.uri, textDocument.version)) {
+               this.buildCauses.add(this.textDocuments.getAuthor(textDocument.uri, textDocument.version) ?? UNKNOWN_CLIENT_ID);
+            }
+         }
+         const unexplained = changed.some(uri => {
+            const textDocument = this.textDocuments.get(uri.toString());
+            return textDocument === undefined || this.isDelivered(textDocument.uri, textDocument.version);
+         });
+         if (unexplained || deleted.length > 0) {
+            this.buildCauses.add(UNKNOWN_CLIENT_ID);
+         }
          // The only place a deletion is observable: `DocumentBuilder.update`
          // removes a deleted document before it builds anything, so no phase
          // listener ever sees it.
          for (const uri of deleted) {
+            const key = this.uriPolicy.canonicalUri(uri.toString());
+            this.trackedUris.delete(key);
+            this.deliveredVersions.delete(key);
             this.textDocuments.notifyDocumentDeleted(uri.toString());
          }
       });
+      // Once every listener ran, not in a listener of its own: listeners after
+      // it could still be skipped by a cancel, and the next build would then
+      // report as rebuilt a version they never delivered.
+      this.documentBuilder.onDocumentPhaseDelivered(DocumentState.Validated, (document, version) => this.markDelivered(document, version));
       // Content transitions for CLOSED documents bypass the text store: the
       // last-close revert and watched-file changes rebuild from disk into a
       // factory-fresh text document carrying the factory's own version. At the
@@ -381,21 +456,16 @@ export class DefaultAstDocumentManager<
          if (this.uriPolicy.canonicalUri(document.uri) !== target) {
             return;
          }
-         // Presentation boundary: the event field is a concrete `string`, so an
-         // unauthored (framework-rebuilt) document surfaces the readable default
-         // rather than `undefined` to subscribers and logs.
-         const sourceClientId = this.getAuthor(document) ?? UNKNOWN_CLIENT_ID;
+         // No `'deleted'` reason: `DocumentBuilder.update` drops a deleted
+         // document from `LangiumDocuments` before deriving the rebuild set
+         // from it, so a deleted URI is never built and never reaches this
+         // phase listener. A subscriber needing deletions has to be told on
+         // a channel that does not require a built document.
          const event: TransferUpdatedEvent<AstDocument<TAst, TDiagnostic>> = {
             document: this.toAstDocument(document),
-            sourceClientId,
-            // No `'deleted'` arm: `DocumentBuilder.update` drops a deleted
-            // document from `LangiumDocuments` before deriving the rebuild set
-            // from it, so a deleted URI is never built and never reaches this
-            // phase listener. A subscriber needing deletions has to be told on
-            // a channel that does not require a built document.
-            reason: this.lastUpdate?.changed.some(changed => UriUtils.equals(changed, document.uri)) ? 'changed' : 'rebuilt'
+            ...this.attributeUpdate(document)
          };
-         this.tracer.with(uri).trace(`emitUpdate start: source=${sourceClientId}, reason=${event.reason}`);
+         this.tracer.with(uri).trace(`emitUpdate start: source=${event.sourceClientId}, reason=${event.reason}, cause=${event.causedBy}`);
          listener(event);
          this.tracer.with(uri).trace('emitUpdate listener returned');
       };
@@ -404,18 +474,81 @@ export class DefaultAstDocumentManager<
 
    /**
     * The client that authored `document`'s current version, or `undefined` when
-    * no client wrote it — a framework-internal rebuild (workspace startup, a
-    * cascade relink, a `didClose`-reload) or a genuine author gap. Honest about
-    * absence so a routing consumer tests `undefined` directly rather than
-    * against a sentinel; the presentation
-    * default ({@link UNKNOWN_CLIENT_ID}) is applied at the boundary that needs a
-    * concrete value (the `onUpdate` event's `sourceClientId`, the data-server's
-    * `resolveSourceClientId`).
+    * no client wrote it: a document no client has open. A rebuild that keeps
+    * the version keeps its author, so this does not say who caused a build;
+    * {@link attributeUpdate} does.
+    * Honest about absence so a routing consumer tests `undefined` directly
+    * rather than against a sentinel; the presentation default
+    * ({@link UNKNOWN_CLIENT_ID}) is applied where an event needs a value.
     */
    getAuthor(document: LangiumDocument): string | undefined {
       return this.textDocuments.getAuthor(document.textDocument.uri, document.textDocument.version);
    }
 
+   /**
+    * `'changed'` for the first delivery of the document's version, crediting
+    * its author; `'rebuilt'` for a later one, crediting nobody, since it echoes
+    * no write, and naming the build's single cause if it has one.
+    *
+    * A document the rule does not apply to (see {@link isTracked}) falls back
+    * to the last update: it is `'changed'` when its URI was passed to
+    * `DocumentBuilder.update`. An open document that a validating build skips,
+    * through a `shouldValidate` override, is never delivered, so each of its
+    * events is its author's change.
+    */
+   attributeUpdate(document: LangiumDocument): UpdateAttribution {
+      const key = this.uriPolicy.canonicalUri(document.uri.toString());
+      const changed = this.isTracked(key)
+         ? this.deliveredVersions.get(key) !== document.textDocument.version
+         : this.lastUpdate?.changed.some(uri => UriUtils.equals(uri, document.uri)) === true;
+      if (changed) {
+         // Presentation boundary: the event field is a concrete `string`, so an
+         // unauthored document surfaces the readable default rather than
+         // `undefined` to subscribers and logs.
+         const author = this.getAuthor(document) ?? UNKNOWN_CLIENT_ID;
+         return { reason: 'changed', sourceClientId: author, causedBy: author };
+      }
+      const [cause] = this.buildCauses;
+      return { reason: 'rebuilt', sourceClientId: UNKNOWN_CLIENT_ID, causedBy: this.buildCauses.size === 1 ? cause : UNKNOWN_CLIENT_ID };
+   }
+
+   /**
+    * Whether the version rule applies to `uri`: the store keeps its version,
+    * and rebuilds validate. With `updateBuildOptions.validation` off no version
+    * is ever delivered, and the rule would report every event of an open
+    * document as its author's change.
+    */
+   protected isTracked(uri: CanonicalUri): boolean {
+      return this.keepsVersion(uri) && Boolean(this.documentBuilder.updateBuildOptions.validation);
+   }
+
+   /**
+    * Whether the store keeps `uri`'s version: a client opened it since its
+    * file was last deleted, or has it open still, as an editor keeps a
+    * deleted file's buffer.
+    */
+   protected keepsVersion(uri: CanonicalUri): boolean {
+      return this.trackedUris.has(uri) || this.textDocuments.isOpen(uri);
+   }
+
+   /**
+    * Record that `version` of `document` was delivered, when the store tracks
+    * it. The version the listeners saw, not the document's current one: a
+    * write during them has moved that on, and marking it would report the
+    * write's own build as rebuilt.
+    */
+   protected markDelivered(document: LangiumDocument, version: number): void {
+      const key = this.uriPolicy.canonicalUri(document.uri.toString());
+      if (this.keepsVersion(key)) {
+         this.deliveredVersions.set(key, version);
+      }
+   }
+
+   /** Whether `version` of `uri` was delivered. */
+   protected isDelivered(uri: string, version: number): boolean {
+      return this.deliveredVersions.get(this.uriPolicy.canonicalUri(uri)) === version;
+   }
+
    async open(args: OpenModelArgs): Promise<Disposable> {
       // `open()` is the RPC-level "ensure this document is loaded" call. It is issued
       // by a session opening the document, including by every additional client

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

@@ -15,16 +15,18 @@ import {
    type DocumentPhaseListener,
    DocumentState,
    type LangiumDocument,
+   MultiMap,
    OperationCancelled,
    type 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 LogNameOptions } from '../diagnostics/logger.js';
 import type { MessageRenderer } from '../../messages/renderer.js';
 import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residency-service.js';
@@ -127,7 +129,8 @@ export interface DocumentBuilderOptions extends LogNameOptions {
  * 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.
@@ -173,6 +176,8 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly uriPolicy: DocumentUriPolicy;
    protected readonly clock: Clock;
    protected readonly messageRenderer: MessageRenderer;
+   /** The lock a re-queued build takes; see {@link requeueOrphaned}. */
+   protected readonly workspaceLock: WorkspaceLock;
    /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
    protected readonly languageRegistry: ExtendedServiceRegistry;
    protected languageFileExtensions: string[] = [];
@@ -199,6 +204,8 @@ 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>();
 
    constructor(services: ServerSharedServicesMinimal, options: DocumentBuilderOptions = {}) {
       super(services);
@@ -206,6 +213,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       this.uriPolicy = services.workspace.DocumentUriPolicy;
       this.clock = services.Clock;
       this.messageRenderer = services.MessageRenderer;
+      this.workspaceLock = services.workspace.WorkspaceLock;
       this.tracer = services.Tracer.for(options.logName ?? 'DocumentBuilder').trace('instantiated');
       this.logLevel = options.logLevel ?? 'debug';
       this.loggedPhases = options.loggedPhases ?? DEFAULT_LOGGED_PHASES;
@@ -238,6 +246,24 @@ 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));
+   }
+
    /**
     * Diagnostic snapshot for use in timeout/error messages around document
     * state.
@@ -292,13 +318,24 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     * {@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.
+    *
+    * 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> {
       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) => {
@@ -338,8 +375,22 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                }
             }, 'awaitDocumentState')
          );
+         // 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 buildDisposable = this.onBuildPhase(DocumentState.Validated, () => {
-            if (document.state >= state) {
+            if (document.state >= state || (state === DocumentState.Validated && this.skipsValidation(document))) {
                cleanup();
                resolve(uri);
             } else {
@@ -353,6 +404,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
          });
          const cleanup = (): void => {
             phaseDisposable.dispose();
+            skipDisposable.dispose();
             buildDisposable.dispose();
             cancelDisposable.dispose();
          };
@@ -366,6 +418,23 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       });
    }
 
+   /**
+    * 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.
@@ -395,14 +464,33 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     * 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.
+    *
+    * The build is an ordinary {@link WorkspaceLock} write, entered from a read.
+    * The read waits until no write runs or is queued, so the build neither runs
+    * beside a locked one nor cancels the build a re-queue is fired from. Unlocked,
+    * it runs beside a locked build that cannot cancel it: both validate the same
+    * version and deliver it twice. Taking the write directly, without the read,
+    * cancels the running build and skips the rest of its build-phase listeners.
+    * The read must not await the write, which queues behind that read.
+    *
+    * A write that ran while the read waited may have carried the document to
+    * `state` already, and a second build would deliver that version again; the
+    * read skips the write then.
     */
    protected requeueOrphaned(document: LangiumDocument, state: DocumentState, reason: string): 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)}`);
+      void this.workspaceLock.read(() => {
+         if (document.state >= state) {
+            return;
          }
+         this.workspaceLock
+            .write(token => this.update([document.uri], [], token))
+            .catch((err: unknown) => {
+               if (!isOperationCancelled(err)) {
+                  tracer.error(`Re-queue build failed: ${err instanceof Error ? err.message : String(err)}`);
+               }
+            });
       });
    }
 
@@ -727,19 +815,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 with `serializeBuilds` off 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
@@ -904,7 +993,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    }
 
    // ============================================================
-   // 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> {
@@ -922,13 +1011,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 () => {
@@ -947,6 +1031,14 @@ 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())

package/src/langium/model-service/client-session.ts

@@ -18,12 +18,13 @@ import {
    type Tracer,
    type TransferElement
 } from '@hydranium/protocol';
-import { type AstNode, UriUtils } from '@hydranium/langium';
+import { type AstNode, type DocumentBuilder, DocumentState, UriUtils } from '@hydranium/langium';
 import { type CancellationToken, type Disposable } from 'vscode-languageserver';
 import { type AstDocument } from '../../documents/ast-document-manager.js';
 import { DocumentNotOpenError, SessionClosedError } from '../../documents/client-session-errors.js';
 import { type OpenOptions, type SessionEndCause } from '../../documents/client-session-registry.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
+import { IntegrityService } from '../integrity/integrity-service.js';
 import { type ServerSharedServices } from '../module.js';
 import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type ModelService } from './model-service.js';
@@ -90,11 +91,19 @@ export interface ClientSession<
     * URI at most one succeeds.
     */
    create(uri: string, text: string): Promise<void>;
+   /**
+    * Write `args.model` into a document this session has open. Resolves to the
+    * rebuilt document once it is validated, in whichever build carried the
+    * write, so the answer holds every diagnostic its update event does: that
+    * event names this session, and a client dropping its own echo would
+    * otherwise never see them.
+    */
    update(args: ClientSessionWriteArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
    /**
     * Write several documents this session has open, all or none: a
     * `ConflictError` or `DocumentNotOpenError` for any of them is thrown before
-    * any text applies. Resolves to the rebuilt documents, in the order given.
+    * any text applies. Resolves to the rebuilt documents, in the order given,
+    * each validated as {@link update}'s is.
     */
    updateAll(args: ClientSessionUpdateAllArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>[]>;
    /** Write `args.model` as {@link update} does, then persist the document. */
@@ -120,6 +129,21 @@ export interface ClientSession<
    dispose(cause?: SessionEndCause): void;
 }
 
+/**
+ * The phase a session write waits for before it answers: `Validated`, or
+ * {@link IntegrityService.SettledState} when rebuilds do not validate, since
+ * no build then reaches `Validated` and the wait would never end. Read from
+ * `updateBuildOptions`, which every rebuild takes; a document a
+ * `shouldValidate` override skips is the builder's to resolve.
+ *
+ * Waiting for the write's own build is not enough: a later write cancels it,
+ * and the build that takes over validates the document after the answer was
+ * taken.
+ */
+function answerState(builder: DocumentBuilder): DocumentState {
+   return builder.updateBuildOptions.validation ? DocumentState.Validated : IntegrityService.SettledState;
+}
+
 /**
  * The framework's {@link ClientSession}, built by
  * {@link DefaultClientSessionFactory}.
@@ -308,7 +332,7 @@ export class DefaultClientSession<
       // An override that awaits before calling the base can outlast the build
       // this write already has, and then builds it twice; see
       // `ModelService.rebuild`.
-      const doc = await run('rebuild', () => service.rebuild(uri, undefined, cancelToken));
+      const doc = await run('rebuild', () => service.rebuild(uri, answerState(this.services.workspace.DocumentBuilder), cancelToken));
       const finalVersion = textDocuments.version(uri);
       if (finalVersion > appliedVersion) {
          this.tracer.debug(`Update to v${appliedVersion} ready at v${finalVersion} (changed again before it settled)`);
@@ -363,7 +387,8 @@ export class DefaultClientSession<
       check();
       const applied = uris.map((uri, i) => this.services.workspace.AstDocumentManager.update(uri, texts[i], this.clientId));
       await Promise.all(applied);
-      return Promise.all(uris.map(uri => service.rebuild(uri, undefined, cancelToken)));
+      const state = answerState(this.services.workspace.DocumentBuilder);
+      return Promise.all(uris.map(uri => service.rebuild(uri, state, cancelToken)));
    }
 
    /**