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

package/lib/lsp/hydranium-document-update-handler.d.ts

@@ -9,25 +9,14 @@
 import { Debouncer, type Logger, ObservableValue, type MaybeObservableValue } from '@hydranium/protocol';
 import { URI } from '@hydranium/langium';
 import { DefaultDocumentUpdateHandler } from '@hydranium/langium/lsp';
-import { type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
+import { HYDRANIUM_BUILD_REASONS, type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
 import { type ServerSharedServices } from '../langium/module.js';
-import { type SelfSaveRegistry } from '../documents/self-save-registry.js';
-import { type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import { type SelfSaveRegistry } from '../langium/workspace/self-save-registry.js';
+import { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
 import { type HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
-import { type DidChangeWatchedFilesParams, type TextDocumentChangeEvent } from 'vscode-languageserver';
+import { type DidChangeWatchedFilesParams, type TextDocumentChangeEvent, type TextDocumentWillSaveEvent, type TextEdit } from 'vscode-languageserver';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
-/**
- * Default LSP-event reasons stamped by {@link HydraniumDocumentUpdateHandler}
- * onto the next `documentBuilder.update` call via `markNextReason`. Exposed
- * so adopters subclassing the handler can layer additional reasons or rename
- * existing ones without losing the canonical names the framework emits.
- */
-export declare const HYDRANIUM_BUILD_REASONS: Readonly<{
-    readonly didOpen: "didOpen";
-    readonly didChangeContent: "didChangeContent";
-    readonly didChangeWatchedFiles: "didChangeWatchedFiles";
-    readonly didClose: "didClose";
-}>;
+export { HYDRANIUM_BUILD_REASONS };
 /**
  * Construction options for {@link HydraniumDocumentUpdateHandler}.
  */
@@ -52,6 +41,17 @@ export interface HydraniumDocumentUpdateHandlerOptions {
      * load tests).
      */
     readonly bypassNonLanguageClientChanges?: boolean;
+    /**
+     * Longest an editor's save waits on the server, in milliseconds, at each of
+     * its two steps: the `willSaveWaitUntil` answer waits for the server's disk
+     * writes of the document already queued, and server writes queued after the
+     * answer wait for the editor's `didSave`. Either wait that runs out is
+     * logged, and the editor's write and the server's can then land in either
+     * order. Default `1000`: VS Code gives up on an answer after about 1.5 s,
+     * and switches the listener off for the session once four answers, over
+     * all documents, timed out or failed.
+     */
+    readonly willSaveGateMs?: number;
 }
 /**
  * Framework `DocumentUpdateHandler` adding these behaviours over Langium's
@@ -66,30 +66,37 @@ export interface HydraniumDocumentUpdateHandlerOptions {
  *     changes and watched-file changes bypass the debounce (their
  *     producers are already coalesced).
  *  3. **Build-reason stamping** — the LSP event overrides
- *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`,
- *     `didCloseDocument`) populate {@link nextReason} with a canonical
- *     reason string. {@link fireDocumentUpdate} captures the reason;
- *     {@link dispatch} stages it on the builder via
- *     {@link HydraniumDocumentBuilder.markNextReason}, so a subclass that
- *     formats build logs can tag its line with the event that caused the
- *     build without per-adopter wiring to capture it.
- *  4. **Last-client-close rebuild trigger** ({@link didCloseDocument}) —
- *     when the final client closes a document, dispatch a build so the
- *     LangiumDocument's `textDocument` is refreshed (from disk for `file:`
- *     URIs, or removed from the index for ephemeral URIs). Langium's
- *     default handler does not implement `didCloseDocument`, so the
- *     in-memory text of the last writer would otherwise persist.
+ *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`)
+ *     populate {@link nextReason} with a canonical reason string.
+ *     {@link fireDocumentUpdate} captures the reason; {@link dispatch} hands
+ *     it to {@link HydraniumDocumentBuilder.scheduleUpdate}, which stages it
+ *     through {@link HydraniumDocumentBuilder.markNextReason} when the build
+ *     runs, so a subclass that formats build logs can tag its line with the
+ *     event that caused the build without per-adopter wiring to capture it.
+ *  4. **Editor save gate** ({@link willSaveDocumentWaitUntil}) — the editor
+ *     writes the file itself, so the server's disk writes of that document
+ *     are ordered around it: the editor's save waits for the ones already
+ *     queued, and the ones queued during its save wait for its `didSave`.
+ *     Both waits are capped by
+ *     {@link HydraniumDocumentUpdateHandlerOptions.willSaveGateMs}.
+ *
+ * What the build keeps after a document's last close is not dispatched here:
+ * the store hands the released document to the `DocumentReleaseHandler` for
+ * every head, the LSP head included, so a `didCloseDocument` added in a
+ * subclass would build the document twice. A change still debounced for the
+ * document is dropped when the store releases it: the release handler rebuilds
+ * the document from the file system provider or removes it.
  *
  * Adopters with their own handler subclass should extend this class
  * (not Langium's `DefaultDocumentUpdateHandler`) so all of them are
  * preserved. The {@link dispatch} hook is the canonical override
- * point for adopters that need to stamp additional per-build metadata
- * inside the workspace-lock callback.
+ * point for adopters that need to stamp additional per-build metadata.
  */
 export declare class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler {
+    protected readonly services: ServerSharedServices;
     /**
      * Narrow Langium's `DefaultDocumentUpdateHandler.documentBuilder` typing to
-     * the framework subclass: `markNextReason` is the only method this handler
+     * the framework subclass: `scheduleUpdate` is the only method this handler
      * reaches for beyond the Langium interface.
      */
     protected readonly documentBuilder: HydraniumDocumentBuilder;
@@ -117,52 +124,53 @@ export declare class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdat
     protected nextReason?: string;
     /**
      * Build-reason captured at `fireDocumentUpdate` time, drained by
-     * {@link dispatch} into `markNextReason`. Survives across debounced
-     * batches (`?? pendingReason` in `fireDocumentUpdate` retains the
-     * first reason in a coalesced burst).
+     * {@link dispatch} into the scheduled build. Survives across debounced
+     * batches: `fireDocumentUpdate` replaces it with each event's reason, so a
+     * coalesced burst carries its latest.
      */
     protected pendingReason?: string;
+    protected readonly willSaveGateMs: number;
+    /**
+     * Per document URI, the release of the hold an editor's save in progress
+     * keeps on the document's disk queue. A second save of the document
+     * releases the first: its hold would otherwise keep the second's answer
+     * waiting until the cap. The key is the document, not the save, so for a
+     * client that sends its next `willSaveWaitUntil` before the previous
+     * `didSave`, that late `didSave` releases the next save's hold.
+     */
+    protected readonly editorSaves: Map<string, () => void>;
     constructor(services: ServerSharedServices, options?: HydraniumDocumentUpdateHandlerOptions);
     didOpenDocument(_change: TextDocumentChangeEvent<TextDocument>): void;
     didChangeContent(change: TextDocumentChangeEvent<TextDocument>): void;
+    didChangeWatchedFiles(params: DidChangeWatchedFilesParams): void;
     /**
-     * Last-client close is the missing rebuild trigger in Langium's
-     * `DefaultDocumentUpdateHandler`: `documents.onDidClose` fires on every
-     * per-client close, but the default handler ignores the event entirely.
-     * For multi-client servers this leaves the LangiumDocument carrying the
-     * unsaved in-memory `textDocument` of the last writer until something
-     * else triggers a rebuild — integrity rules walking `langiumDocuments.all`
-     * then see stale text long after the user discarded their edits.
-     *
-     * We funnel the last-client transition through the same dispatch path
-     * the other LSP events use, so the rebuild gets debouncing, workspace
-     * locking, build-reason stamping, and `markNextReason` for free. The
-     * scheme split governs the `DocumentBuilder.update` shape:
+     * Answer an editor's `willSaveWaitUntil` with no edits once the server's
+     * disk writes of the document already queued have landed, or after
+     * {@link willSaveGateMs}, whichever is first. From the moment the queue
+     * reaches this save, disk tasks of the document queued behind it wait for
+     * the editor's `didSave`, reported through
+     * `HydraniumTextDocuments.onDidSaveInLanguageClient`, or for
+     * {@link willSaveGateMs} more.
      *
-     *  - **`file:` URI** → `update([uri], [])`. Routes through
-     *    `LangiumDocuments.invalidateDocument` (doc stays in the trie) and
-     *    `LangiumDocumentFactory.update`, which consults the LSP-tracked
-     *    open-documents map first. That map is cleared LATER in the same
-     *    synchronous `notifyDidCloseTextDocument` call that fires this event,
-     *    and {@link dispatch} defers the build behind `workspaceManager.ready`
-     *    — so by the time the factory looks, the URI is gone: it falls back to
-     *    `FileSystemProvider.readFile` and the doc rebuilds from disk,
-     *    Langium's canonical close-without-save semantic. A dispatch made
-     *    synchronously here would still see the open document and re-read the
-     *    in-memory text instead.
-     *  - **non-`file:` URI** (`builtin:`, `untitled:`) → no dispatch.
-     *    Adopter-loaded schemes — documents pulled in via
-     *    `loadAdditionalDocuments` — need to stay in the workspace index;
-     *    dropping them on close would break every cross-reference that
-     *    targets them. The framework cannot enumerate adopter schemes, so the
-     *    safe default is "leave alone unless it's a file." Adopters that need
-     *    ephemeral-URI cleanup handle it explicitly.
-     *
-     * Per-client closes (where other clients still hold the URI) are
-     * suppressed via {@link HydraniumTextDocuments.isOpenInAnyClient}.
+     * The hold is a disk task that waits only for that signal or its timer:
+     * waiting on a build, a save or anything else queued for the document would
+     * wedge its queue. Resolves in every case, since a failed request counts
+     * against the listener in VS Code; Langium drops the request's cancellation,
+     * so an abandoned request still runs to the cap. A hold that runs out is
+     * logged at debug only: an editor skips `didSave` for a save it cancels or
+     * that changed nothing.
      */
-    didCloseDocument(change: TextDocumentChangeEvent<TextDocument>): void;
-    didChangeWatchedFiles(params: DidChangeWatchedFilesParams): void;
+    willSaveDocumentWaitUntil(event: TextDocumentWillSaveEvent<TextDocument>): Promise<TextEdit[]>;
+    /**
+     * Present so that Langium advertises `save` and editors send `didSave`;
+     * without it every hold of {@link willSaveDocumentWaitUntil} waits out its
+     * cap. The hold is released on
+     * `HydraniumTextDocuments.onDidSaveInLanguageClient` instead: it fires as
+     * soon as the editor reports the save, while `onDidSave`, and so this
+     * method, follows only once the file has been read back, and not at all
+     * when the file does not hold the store's text.
+     */
+    didSaveDocument(_event: TextDocumentChangeEvent<TextDocument>): void;
     /**
      * Drop watched-file changes whose path + mtime match a recent self-save
      * record. Deletions always pass (no mtime); stat failures pass (the
@@ -177,8 +185,7 @@ export declare class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdat
      * flush immediately (`immediateFlush` or `debounceMs <= 0`) or restart
      * the trailing-edge timer. Subclasses that need to stamp per-build
      * metadata can override and inspect the merged sets — but the canonical
-     * override point for the workspace-lock callback is {@link dispatch},
-     * not this method.
+     * override point for the build is {@link dispatch}, not this method.
      */
     protected fireDocumentUpdate(changed: URI[], deleted: URI[]): void;
     /**
@@ -189,15 +196,19 @@ export declare class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdat
      */
     flushPending(): void;
     /**
-     * Workspace-lock + `documentBuilder.update` call for the merged sets.
-     * Mirrors Langium's `super.fireDocumentUpdate` body plus
-     * `markNextReason(pendingReason)` inside the write-lock callback, so the
-     * build the lock is about to run carries the LSP event that triggered it.
-     * Adopters override to stamp additional per-build metadata — the canonical
-     * pattern is to read the reason via `this.pendingReason`, call
-     * `super.dispatch(...)` or replicate the
-     * `workspaceManager.ready -> workspaceLock.write` block, and add
-     * adopter-specific behaviour inside the write callback.
+     * Build the merged sets once the workspace is ready, through
+     * {@link HydraniumDocumentBuilder.scheduleUpdate} with the pending reason,
+     * so the build carries the LSP event that triggered it. A session's write
+     * fires the store's change event before the session rebuilds the document
+     * itself, and the scheduled build is what the two share.
+     *
+     * Adopters override to stamp additional per-build metadata: read the reason
+     * via `this.pendingReason` and call `super.dispatch(...)`; the build may
+     * be shared with other requests, so metadata stamped for it describes
+     * theirs too. An override that needs code inside the write action takes
+     * `workspaceLock.write` itself, as Langium's `fireDocumentUpdate` does, and
+     * stages the reason through `markNextReason` there; its build then cancels
+     * a scheduled one it coincides with rather than sharing it.
      */
     protected dispatch(changed: URI[], deleted: URI[]): void;
 }

package/lib/lsp/hydranium-document-update-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydranium-document-update-handler.d.ts","sourceRoot":"","sources":["../../src/lsp/hydranium-document-update-handler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hydranium-document-update-handler.d.ts","sourceRoot":"","sources":["../../src/lsp/hydranium-document-update-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,SAAS,EAAY,KAAK,MAAM,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAa,MAAM,qBAAqB,CAAC;AAC9H,OAAO,EAAE,GAAG,EAAY,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,KAAK,wBAAwB,EAAE,MAAM,iDAAiD,CAAC;AACzH,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AACnF,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,8CAA8C,CAAC;AAC/F,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAEvF,OAAO,EACJ,KAAK,2BAA2B,EAGhC,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,QAAQ,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,qCAAqC;IACnD;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACnD;;;;;;;;;OASG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,OAAO,CAAC;IAClD;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,8BAA+B,SAAQ,4BAA4B;IAqD1E,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB;IApDpD;;;;OAIG;IACH,mBAA2B,eAAe,EAAE,wBAAwB,CAAC;IAErE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IAClE,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC;IAEvE,0FAA0F;IAC1F,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACrD,SAAS,CAAC,QAAQ,CAAC,8BAA8B,EAAE,OAAO,CAAC;IAE3D,qHAAqH;IACrH,SAAS,CAAC,cAAc,mBAA0B;IAClD,SAAS,CAAC,cAAc,mBAA0B;IAClD,sGAAsG;IACtG,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IAC7C,iIAAiI;IACjI,SAAS,CAAC,cAAc,UAAS;IAEjC;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,SAAS,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEjC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAC1C;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,oBAAyB,IAAI,EAAI;IAE/D,YACsB,QAAQ,EAAE,oBAAoB,EACjD,OAAO,GAAE,qCAA0C,EAyBrD;IAED,eAAe,CAAC,OAAO,EAAE,uBAAuB,CAAC,YAAY,CAAC,GAAG,IAAI,CAQpE;IAEQ,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,CAAC,YAAY,CAAC,GAAG,IAAI,CAU7E;IAEQ,qBAAqB,CAAC,MAAM,EAAE,2BAA2B,GAAG,IAAI,CAkCxE;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,yBAAyB,CAAC,KAAK,EAAE,yBAAyB,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAuC7F;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,MAAM,EAAE,uBAAuB,CAAC,YAAY,CAAC,GAAG,IAAI,CAEnE;IAED;;;;;;;OAOG;IACH,UAAgB,eAAe,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAezG;IAED;;;;;;OAMG;IACH,UAAmB,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,CAqB1E;IAED;;;;;OAKG;IACI,YAAY,IAAI,IAAI,CAU1B;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,CAiBvD;CACH"}

package/lib/lsp/hydranium-document-update-handler.js

@@ -6,23 +6,14 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { Debouncer, ObservableValue } from '@hydranium/protocol';
+import { Debouncer, Deferred, ObservableValue, TIMED_OUT } from '@hydranium/protocol';
 import { URI, UriUtils } from '@hydranium/langium';
 import { DefaultDocumentUpdateHandler } from '@hydranium/langium/lsp';
+import { HYDRANIUM_BUILD_REASONS } from '../langium/document-builder/document-builder.js';
 import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
 import { FileChangeType } from 'vscode-languageserver';
-/**
- * Default LSP-event reasons stamped by {@link HydraniumDocumentUpdateHandler}
- * onto the next `documentBuilder.update` call via `markNextReason`. Exposed
- * so adopters subclassing the handler can layer additional reasons or rename
- * existing ones without losing the canonical names the framework emits.
- */
-export const HYDRANIUM_BUILD_REASONS = Object.freeze({
-    didOpen: 'didOpen',
-    didChangeContent: 'didChangeContent',
-    didChangeWatchedFiles: 'didChangeWatchedFiles',
-    didClose: 'didClose'
-});
+export { HYDRANIUM_BUILD_REASONS };
 /**
  * Framework `DocumentUpdateHandler` adding these behaviours over Langium's
  * default:
@@ -36,27 +27,34 @@ export const HYDRANIUM_BUILD_REASONS = Object.freeze({
  *     changes and watched-file changes bypass the debounce (their
  *     producers are already coalesced).
  *  3. **Build-reason stamping** — the LSP event overrides
- *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`,
- *     `didCloseDocument`) populate {@link nextReason} with a canonical
- *     reason string. {@link fireDocumentUpdate} captures the reason;
- *     {@link dispatch} stages it on the builder via
- *     {@link HydraniumDocumentBuilder.markNextReason}, so a subclass that
- *     formats build logs can tag its line with the event that caused the
- *     build without per-adopter wiring to capture it.
- *  4. **Last-client-close rebuild trigger** ({@link didCloseDocument}) —
- *     when the final client closes a document, dispatch a build so the
- *     LangiumDocument's `textDocument` is refreshed (from disk for `file:`
- *     URIs, or removed from the index for ephemeral URIs). Langium's
- *     default handler does not implement `didCloseDocument`, so the
- *     in-memory text of the last writer would otherwise persist.
+ *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`)
+ *     populate {@link nextReason} with a canonical reason string.
+ *     {@link fireDocumentUpdate} captures the reason; {@link dispatch} hands
+ *     it to {@link HydraniumDocumentBuilder.scheduleUpdate}, which stages it
+ *     through {@link HydraniumDocumentBuilder.markNextReason} when the build
+ *     runs, so a subclass that formats build logs can tag its line with the
+ *     event that caused the build without per-adopter wiring to capture it.
+ *  4. **Editor save gate** ({@link willSaveDocumentWaitUntil}) — the editor
+ *     writes the file itself, so the server's disk writes of that document
+ *     are ordered around it: the editor's save waits for the ones already
+ *     queued, and the ones queued during its save wait for its `didSave`.
+ *     Both waits are capped by
+ *     {@link HydraniumDocumentUpdateHandlerOptions.willSaveGateMs}.
+ *
+ * What the build keeps after a document's last close is not dispatched here:
+ * the store hands the released document to the `DocumentReleaseHandler` for
+ * every head, the LSP head included, so a `didCloseDocument` added in a
+ * subclass would build the document twice. A change still debounced for the
+ * document is dropped when the store releases it: the release handler rebuilds
+ * the document from the file system provider or removes it.
  *
  * Adopters with their own handler subclass should extend this class
  * (not Langium's `DefaultDocumentUpdateHandler`) so all of them are
  * preserved. The {@link dispatch} hook is the canonical override
- * point for adopters that need to stamp additional per-build metadata
- * inside the workspace-lock callback.
+ * point for adopters that need to stamp additional per-build metadata.
  */
 export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler {
+    services;
     logger;
     selfSaveRegistry;
     fileSystemProvider;
@@ -81,13 +79,24 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
     nextReason;
     /**
      * Build-reason captured at `fireDocumentUpdate` time, drained by
-     * {@link dispatch} into `markNextReason`. Survives across debounced
-     * batches (`?? pendingReason` in `fireDocumentUpdate` retains the
-     * first reason in a coalesced burst).
+     * {@link dispatch} into the scheduled build. Survives across debounced
+     * batches: `fireDocumentUpdate` replaces it with each event's reason, so a
+     * coalesced burst carries its latest.
      */
     pendingReason;
+    willSaveGateMs;
+    /**
+     * Per document URI, the release of the hold an editor's save in progress
+     * keeps on the document's disk queue. A second save of the document
+     * releases the first: its hold would otherwise keep the second's answer
+     * waiting until the cap. The key is the document, not the save, so for a
+     * client that sends its next `willSaveWaitUntil` before the previous
+     * `didSave`, that late `didSave` releases the next save's hold.
+     */
+    editorSaves = new Map();
     constructor(services, options = {}) {
         super(services);
+        this.services = services;
         this.logger = services.Logger;
         this.selfSaveRegistry = services.workspace.SelfSaveRegistry;
         this.fileSystemProvider = services.workspace.FileSystemProvider;
@@ -95,6 +104,19 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
         this.debounce = ObservableValue.from(options.debounceMs ?? 0);
         this.flushDebouncer = new Debouncer(services.Clock, () => this.flushPending(), { delayMs: this.debounce });
         this.bypassNonLanguageClientChanges = options.bypassNonLanguageClientChanges ?? true;
+        this.willSaveGateMs = options.willSaveGateMs ?? 1000;
+        this.textDocuments.onDidSaveInLanguageClient(event => this.editorSaves.get(event.uri)?.());
+        services.workspace.VersionSyncService.registerDeferredBuilds(uri => this.pendingChanged.has(uri.toString()) || this.pendingDeleted.has(uri.toString()));
+        // A change still debounced for a document the store has released would
+        // build it once more after the release handler's build: from the
+        // provider again, or, for a document the release removed, by reading a
+        // file that is not there.
+        this.textDocuments.onDidReleaseDocument(event => {
+            this.pendingChanged.delete(URI.parse(event.uri).toString());
+            if (this.pendingChanged.size === 0 && this.pendingDeleted.size === 0) {
+                this.pendingReason = undefined;
+            }
+        });
     }
     didOpenDocument(_change) {
         // Langium also fires `didChangeContent` on open, which is what triggers
@@ -116,60 +138,21 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
         }
         super.didChangeContent(change);
     }
-    /**
-     * Last-client close is the missing rebuild trigger in Langium's
-     * `DefaultDocumentUpdateHandler`: `documents.onDidClose` fires on every
-     * per-client close, but the default handler ignores the event entirely.
-     * For multi-client servers this leaves the LangiumDocument carrying the
-     * unsaved in-memory `textDocument` of the last writer until something
-     * else triggers a rebuild — integrity rules walking `langiumDocuments.all`
-     * then see stale text long after the user discarded their edits.
-     *
-     * We funnel the last-client transition through the same dispatch path
-     * the other LSP events use, so the rebuild gets debouncing, workspace
-     * locking, build-reason stamping, and `markNextReason` for free. The
-     * scheme split governs the `DocumentBuilder.update` shape:
-     *
-     *  - **`file:` URI** → `update([uri], [])`. Routes through
-     *    `LangiumDocuments.invalidateDocument` (doc stays in the trie) and
-     *    `LangiumDocumentFactory.update`, which consults the LSP-tracked
-     *    open-documents map first. That map is cleared LATER in the same
-     *    synchronous `notifyDidCloseTextDocument` call that fires this event,
-     *    and {@link dispatch} defers the build behind `workspaceManager.ready`
-     *    — so by the time the factory looks, the URI is gone: it falls back to
-     *    `FileSystemProvider.readFile` and the doc rebuilds from disk,
-     *    Langium's canonical close-without-save semantic. A dispatch made
-     *    synchronously here would still see the open document and re-read the
-     *    in-memory text instead.
-     *  - **non-`file:` URI** (`builtin:`, `untitled:`) → no dispatch.
-     *    Adopter-loaded schemes — documents pulled in via
-     *    `loadAdditionalDocuments` — need to stay in the workspace index;
-     *    dropping them on close would break every cross-reference that
-     *    targets them. The framework cannot enumerate adopter schemes, so the
-     *    safe default is "leave alone unless it's a file." Adopters that need
-     *    ephemeral-URI cleanup handle it explicitly.
-     *
-     * Per-client closes (where other clients still hold the URI) are
-     * suppressed via {@link HydraniumTextDocuments.isOpenInAnyClient}.
-     */
-    didCloseDocument(change) {
-        if (this.textDocuments.isOpenInAnyClient(change.document.uri)) {
-            return;
-        }
-        const uri = URI.parse(change.document.uri);
-        if (uri.scheme !== 'file') {
-            return;
-        }
-        this.nextReason = HYDRANIUM_BUILD_REASONS.didClose;
-        this.immediateFlush = true;
-        this.fireDocumentUpdate([uri], []);
-    }
     didChangeWatchedFiles(params) {
         void this.filterSelfSaves(params)
             .then(filtered => {
             if (filtered.changes.length === 0) {
                 return;
             }
+            // Only an open document keeps the file's text as its disk
+            // baseline; the store ignores the rest. The self-save filter has
+            // dropped the server's own writes, which set the baseline when
+            // they wrote.
+            for (const change of filtered.changes) {
+                this.textDocuments
+                    .reloadDiskBaseline(change.uri)
+                    .catch((err) => this.logger.error(`Disk baseline not reloaded for ${change.uri}. ${String(err)}`));
+            }
             // External file-system changes are authoritative — overwrite any
             // pending reason (typically empty here; could be `didChangeContent`
             // if a watcher event raced an in-flight Monaco edit, in which case
@@ -190,6 +173,70 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             this.logger.error(`Watched-file update dropped for ${uris}. ${detail}`);
         });
     }
+    /**
+     * Answer an editor's `willSaveWaitUntil` with no edits once the server's
+     * disk writes of the document already queued have landed, or after
+     * {@link willSaveGateMs}, whichever is first. From the moment the queue
+     * reaches this save, disk tasks of the document queued behind it wait for
+     * the editor's `didSave`, reported through
+     * `HydraniumTextDocuments.onDidSaveInLanguageClient`, or for
+     * {@link willSaveGateMs} more.
+     *
+     * The hold is a disk task that waits only for that signal or its timer:
+     * waiting on a build, a save or anything else queued for the document would
+     * wedge its queue. Resolves in every case, since a failed request counts
+     * against the listener in VS Code; Langium drops the request's cancellation,
+     * so an abandoned request still runs to the cap. A hold that runs out is
+     * logged at debug only: an editor skips `didSave` for a save it cancels or
+     * that changed nothing.
+     */
+    willSaveDocumentWaitUntil(event) {
+        const uri = event.document.uri;
+        this.editorSaves.get(uri)?.();
+        const hold = new Deferred();
+        const release = () => {
+            if (this.editorSaves.get(uri) === release) {
+                this.editorSaves.delete(uri);
+            }
+            hold.resolve();
+        };
+        this.editorSaves.set(uri, release);
+        return new Promise(resolve => {
+            const clock = this.services.Clock;
+            const cap = clock.setTimer(() => {
+                this.logger.warn(`willSaveWaitUntil for ${uri} answered after ${this.willSaveGateMs} ms with server writes of it still queued; the editor's save may race them.`);
+                resolve([]);
+            }, this.willSaveGateMs);
+            try {
+                void this.services.workspace.FileSystemTaskQueue.enqueue(uri, async () => {
+                    cap.dispose();
+                    resolve([]);
+                    if ((await clock.raceTimer(hold.promise, this.willSaveGateMs)) === TIMED_OUT) {
+                        this.logger.debug(`No didSave for ${uri} within ${this.willSaveGateMs} ms; server writes of it no longer wait for the editor's save.`);
+                        release();
+                    }
+                });
+            }
+            catch (err) {
+                cap.dispose();
+                this.logger.error(`willSaveWaitUntil for ${uri} answered without waiting. ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+                release();
+                resolve([]);
+            }
+        });
+    }
+    /**
+     * Present so that Langium advertises `save` and editors send `didSave`;
+     * without it every hold of {@link willSaveDocumentWaitUntil} waits out its
+     * cap. The hold is released on
+     * `HydraniumTextDocuments.onDidSaveInLanguageClient` instead: it fires as
+     * soon as the editor reports the save, while `onDidSave`, and so this
+     * method, follows only once the file has been read back, and not at all
+     * when the file does not hold the store's text.
+     */
+    didSaveDocument(_event) {
+        // Nothing to do; see the doc comment.
+    }
     /**
      * Drop watched-file changes whose path + mtime match a recent self-save
      * record. Deletions always pass (no mtime); stat failures pass (the
@@ -205,7 +252,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             }
             const uri = UriUtils.toUri(change.uri);
             const mtimeMs = await this.fileSystemProvider.mtimeMs?.(uri);
-            if (mtimeMs !== undefined && this.selfSaveRegistry.matches(uri.fsPath, mtimeMs)) {
+            if (mtimeMs !== undefined && this.selfSaveRegistry.isRegistered(uri.fsPath, mtimeMs)) {
                 return undefined;
             }
             return change;
@@ -217,15 +264,13 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
      * flush immediately (`immediateFlush` or `debounceMs <= 0`) or restart
      * the trailing-edge timer. Subclasses that need to stamp per-build
      * metadata can override and inspect the merged sets — but the canonical
-     * override point for the workspace-lock callback is {@link dispatch},
-     * not this method.
+     * override point for the build is {@link dispatch}, not this method.
      */
     fireDocumentUpdate(changed, deleted) {
         // Capture the reason set by the LSP event handler immediately before
-        // we merge into the pending sets. `?? pendingReason` keeps the
-        // first reason in a coalesced burst (LSP events arriving inside an
-        // active debounce window all stamp the same `pendingReason` once,
-        // because subsequent stamps see the field already non-undefined).
+        // we merge into the pending sets. Each event stamps its own reason, so
+        // a coalesced burst carries its latest; `?? pendingReason` keeps the
+        // earlier one only for a call no event stamped.
         this.pendingReason = this.nextReason ?? this.pendingReason;
         this.nextReason = undefined;
         for (const uri of changed) {
@@ -261,25 +306,34 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
         this.dispatch(changed, deleted);
     }
     /**
-     * Workspace-lock + `documentBuilder.update` call for the merged sets.
-     * Mirrors Langium's `super.fireDocumentUpdate` body plus
-     * `markNextReason(pendingReason)` inside the write-lock callback, so the
-     * build the lock is about to run carries the LSP event that triggered it.
-     * Adopters override to stamp additional per-build metadata — the canonical
-     * pattern is to read the reason via `this.pendingReason`, call
-     * `super.dispatch(...)` or replicate the
-     * `workspaceManager.ready -> workspaceLock.write` block, and add
-     * adopter-specific behaviour inside the write callback.
+     * Build the merged sets once the workspace is ready, through
+     * {@link HydraniumDocumentBuilder.scheduleUpdate} with the pending reason,
+     * so the build carries the LSP event that triggered it. A session's write
+     * fires the store's change event before the session rebuilds the document
+     * itself, and the scheduled build is what the two share.
+     *
+     * Adopters override to stamp additional per-build metadata: read the reason
+     * via `this.pendingReason` and call `super.dispatch(...)`; the build may
+     * be shared with other requests, so metadata stamped for it describes
+     * theirs too. An override that needs code inside the write action takes
+     * `workspaceLock.write` itself, as Langium's `fireDocumentUpdate` does, and
+     * stages the reason through `markNextReason` there; its build then cancels
+     * a scheduled one it coincides with rather than sharing it.
      */
     dispatch(changed, deleted) {
         const reason = this.pendingReason;
         this.pendingReason = undefined;
         this.workspaceManager.ready
-            .then(() => this.workspaceLock.write(token => {
-            this.documentBuilder.markNextReason(reason);
-            return this.documentBuilder.update(changed, deleted, token);
-        }))
+            .then(() => this.documentBuilder.scheduleUpdate(changed, deleted, reason))
             .catch(err => {
+            // A deferred rebuild can finish after the LSP peer has gone away.
+            // Unless the head was started through `startLanguageServer`, whose
+            // guard absorbs it, the diagnostics publish then fails this build:
+            // a routine teardown race, not a failed workspace update. Keep
+            // genuine update failures visible.
+            if (isConnectionGoneError(err)) {
+                return;
+            }
             const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
             this.logger.error(`Workspace initialization failed. Could not perform document update. ${detail}`);
         });