@hydranium/core 1.0.0-next.117 → 1.0.0-next.123

package/src/documents/hydranium-text-documents.ts

@@ -20,7 +20,7 @@
 // on lsp-server, contradicting the peer architecture.
 // eslint-disable-next-line @typescript-eslint/no-restricted-imports
 import { NormalizedTextDocuments } from '@hydranium/langium/lsp';
-import { type URI, UriUtils } from '@hydranium/langium';
+import { URI, UriUtils } from '@hydranium/langium';
 import { type ServerSharedServices } from '../langium/module.js';
 import {
    type ApplyWorkspaceEditResult,
@@ -31,7 +31,7 @@ import {
    type DidOpenTextDocumentParams,
    type DidSaveTextDocumentParams,
    type Disposable,
-   type Emitter,
+   Emitter,
    type Event,
    type HandlerResult,
    OptionalVersionedTextDocumentIdentifier,
@@ -46,11 +46,20 @@ import {
    type WillSaveTextDocumentParams
 } from 'vscode-languageserver';
 import { type DocumentUri, TextDocument, type TextDocumentContentChangeEvent } from 'vscode-languageserver-textdocument';
-import { type CanonicalUri, type LanguageClientUri, asLanguageClientUri, DisposableCollection, type Tracer } from '@hydranium/protocol';
+import {
+   type CanonicalUri,
+   type LanguageClientUri,
+   asLanguageClientUri,
+   DisposableCollection,
+   type Stopwatch,
+   type Tracer
+} from '@hydranium/protocol';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { HYDRANIUM_BUILD_REASONS } from '../langium/document-builder/document-builder.js';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
 import { LANGUAGE_CLIENT_ID } from './client-ids.js';
 import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
-import { type ClientSessionClosedEvent, ClientSessionRegistry, type OpenOptions } from './client-session-registry.js';
+import { type ClientSessionClosedEvent, ClientSessionRegistry, type SessionEndCause } from './client-session-registry.js';
 import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
 
 /**
@@ -77,6 +86,39 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
     * Adopters with a custom text-document type (rare) pass their factory.
     */
    readonly configuration?: TextDocumentsConfiguration<T>;
+   /**
+    * How long a document whose last open closed because its client's
+    * connection was lost keeps its text before it reverts to disk. An open by
+    * a client lost from the document, within this time of its own loss,
+    * cancels the revert, so a client that registers again under its id after
+    * a dropped connection finds its unsaved edits. Any other open releases the
+    * document first and then opens it as a first open does, from the text the
+    * opener supplies (an editor's own) or else from the file. Meanwhile the
+    * document counts as open for the integrity service, which therefore writes
+    * none of its unsaved text to disk. A close the client makes itself, or
+    * ending its session, reverts at once whatever this is.
+    *
+    * Defaults to 10 s. `0` reverts such a document at once as well, released
+    * in the close itself rather than on a timer.
+    */
+   readonly revertGraceMs?: number;
+}
+
+/**
+ * The default of {@link HydraniumTextDocumentsOptions.revertGraceMs}: long
+ * enough for a client whose connection dropped to register again and reopen
+ * its documents, which a data client does as soon as it has a connection.
+ */
+const DEFAULT_REVERT_GRACE_MS = 10_000;
+
+/** Delivered by {@link HydraniumTextDocuments.onDidSaveInLanguageClient}. */
+export interface LanguageClientSavedEvent {
+   readonly uri: string;
+}
+
+/** Delivered by {@link HydraniumTextDocuments.onDidCloseLastOpen}. */
+export interface LastOpenClosedEvent {
+   readonly uri: CanonicalUri;
 }
 
 /**
@@ -121,6 +163,22 @@ export interface DocumentTrackingRecord {
     * record on last close.
     */
    languageClientUris?: Set<LanguageClientUri>;
+   /**
+    * The clients whose close of this document was caused by a lost connection
+    * and that have not opened it again, each with a stopwatch started at its
+    * loss on the store's `Clock`. While the document waits out the revert grace, only an
+    * open by one of them within its own
+    * {@link HydraniumTextDocumentsOptions.revertGraceMs} of that loss cancels
+    * the revert. Every such client counts, not only the last to close: one
+    * connection's sessions all end lost together, and any of them may reopen
+    * first. Without the time limit, a client that returns late inherits the
+    * unsaved text of a holder lost after it. A stopwatch rather than a `now()`
+    * reading, because a wall-clock step would otherwise expire a claim early or
+    * revive one past its grace, against a grace timer that the step leaves
+    * alone. An entry past its grace counts as any other client's and is pruned
+    * at the next open of the document.
+    */
+   lostClients?: Map<string, Stopwatch>;
 }
 
 /**
@@ -225,6 +283,18 @@ export type LanguageClientChangeOrigin =
     */
    | { readonly kind: 'unreconstructable' };
 
+/**
+ * Whether `err` reports that the file of `target` does not exist, as a Node
+ * file system and the framework's providers do: code `ENOENT`, with `target`'s
+ * path. A missing file of another document is a different failure.
+ */
+function isFileNotFound(err: unknown, target: URI): boolean {
+   if (typeof err !== 'object' || err === null || !('code' in err) || err.code !== 'ENOENT') {
+      return false;
+   }
+   return !('path' in err) || err.path === target.fsPath;
+}
+
 /**
  * Cheap, stable, non-cryptographic content hash (cyrb53) for the version
  * sequence's "did the content change across close/reopen?" question. Only
@@ -262,6 +332,9 @@ function contentHash(text: string): string {
  *     document's content-revision number), and splicing them lets versions drift
  *     silently past based-on gate holders.
  *   - Version-author history so each edit is attributable to its originating client.
+ *   - The revert to disk once no client has a document open, for every head
+ *     ({@link revertToDisk}), deferred by
+ *     {@link HydraniumTextDocumentsOptions.revertGraceMs} after a lost connection.
  *   - Pending-content staging used by the integrity service to thread corrections
  *     through `workspace/applyEdit` cycles for currently-closed documents.
  *   - `didOpen` notifications arriving over the LSP connection wait on the
@@ -352,6 +425,10 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
 
    protected readonly tracer: Tracer;
    protected readonly configuration: TextDocumentsConfiguration<T>;
+   /** See {@link HydraniumTextDocumentsOptions.revertGraceMs}. */
+   protected readonly revertGraceMs: number;
+   protected readonly lastOpenClosedEmitter = new Emitter<LastOpenClosedEvent>();
+   protected readonly languageClientSavedEmitter = new Emitter<LanguageClientSavedEvent>();
 
    constructor(
       protected services: ServerSharedServices,
@@ -365,6 +442,8 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          (uri, reason) => this.tracer.with(uri).warn(`Diff apply-verify fallback (${reason}) — using full-document replace`),
          this
       );
+      this.revertGraceMs = options.revertGraceMs ?? DEFAULT_REVERT_GRACE_MS;
+      this.onDidCloseLastOpen(event => void this.revertToDisk(event.uri));
    }
 
    // Re-exposed configuration factories — for framework-internal callers
@@ -465,7 +544,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       );
       disposables.push(
          connection.onDidSaveTextDocument((event: DidSaveTextDocumentParams) => {
-            this.notifyDidSaveTextDocument(event);
+            void this.notifyLanguageClientSave(event);
          })
       );
       return disposables;
@@ -613,12 +692,25 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       return document.version;
    }
 
-   public notifyDidCloseTextDocument(event: DidCloseTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
+   /**
+    * Close `clientId`'s open of the document. When it was the last open, the
+    * document is released and reverts to disk, at once or, for a `'lost'`
+    * close, after {@link HydraniumTextDocumentsOptions.revertGraceMs}.
+    */
+   public notifyDidCloseTextDocument(
+      event: DidCloseTextDocumentParams,
+      clientId = LANGUAGE_CLIENT_ID,
+      cause: SessionEndCause = 'closed'
+   ): void {
       const uri = this.documentKey(event.textDocument.uri);
       if (!this.__sessions.removeOpen(uri, clientId)) {
          return;
       }
-      this.__documents.get(uri)?.clientVersions.delete(clientId);
+      const record = this.__documents.get(uri);
+      record?.clientVersions.delete(clientId);
+      if (record && cause === 'lost') {
+         (record.lostClients ??= new Map()).set(clientId, this.services.Clock.stopwatch());
+      }
       const syncedDocument = this.__syncedDocuments.get(uri);
       if (syncedDocument !== undefined) {
          this.log(syncedDocument.uri, `Closed synced document: ${syncedDocument.version} by ${this.formatClientId(clientId)}`);
@@ -627,32 +719,159 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          if (clientId === LANGUAGE_CLIENT_ID) {
             // Monaco closed the document; drop the URI it held and the shadow
             // baselined under it. (If this was the last URI/client the whole record
-            // is deleted below, clearing the set anyway.)
+            // is deleted on release, clearing the set anyway.)
             const droppedUri = this.toLanguageClientUri(event.textDocument.uri);
             this.__documents.get(uri)?.languageClientUris?.delete(droppedUri);
             this.__shadow.invalidate(droppedUri);
             this.__pendingPushes.delete(droppedUri);
          }
          if (!this.__sessions.isOpen(uri)) {
-            // Last client closed the document; delete sync state. The downstream
-            // "rebuild from disk for file URIs / drop from index for ephemeral
-            // URIs" decision lives in `HydraniumDocumentUpdateHandler.didCloseDocument`,
-            // which subscribes to `onDidClose` and consults `isOpenInAnyClient`
-            // to detect the last-close transition.
-            this.log(syncedDocument.uri, `Remove synced document: ${syncedDocument.version} (no client left)`);
-            // Persist where the shared version sequence left off (version +
-            // content hash) so the next open CONTINUES the sequence instead of
-            // restarting at the reopening client's declared id. Hashed once
-            // here at close, not on every change.
-            this.__versionSequences.set(uri, {
-               version: syncedDocument.version,
-               contentHash: contentHash(syncedDocument.getText())
-            });
-            this.__syncedDocuments.delete(uri);
-            // One delete clears every per-URI axis (version history + any staged
-            // pending content) so a future open with the same URI starts fresh.
-            this.__documents.delete(uri);
+            if (cause === 'lost' && this.revertGraceMs > 0) {
+               this.deferRelease(uri);
+            } else {
+               this.releaseDocument(uri);
+            }
+         }
+      }
+   }
+
+   /**
+    * Keep the document, text and all, for the revert grace, then release it.
+    * The document stays in the store meanwhile, so a lost client that opens it
+    * again within its own grace attaches to it and finds its unsaved text
+    * rather than reading disk; see {@link resolvePendingRevert} for any other
+    * open.
+    */
+   protected deferRelease(uri: CanonicalUri): void {
+      this.log(uri, `No client left; revert deferred for ${this.revertGraceMs} ms (connection lost)`);
+      const timer = this.services.Clock.setTimer(() => {
+         this.__sessions.cancelRevert(uri);
+         if (!this.__sessions.isOpen(uri)) {
+            this.releaseDocument(uri);
+         }
+      }, this.revertGraceMs);
+      this.__sessions.deferRevert(uri, timer);
+   }
+
+   /**
+    * Resolve the pending revert of `uri` for an open by `clientId`. An open by a
+    * client lost from the document within its grace cancels the revert, and
+    * the client finds its unsaved text. Any other open releases the document
+    * first, so it opens as a first open does: cancelling for every open hands
+    * a lost client's unsaved text to whoever opens next, a reloaded page or an
+    * editor, with nothing marking it unsaved.
+    */
+   protected resolvePendingRevert(uri: CanonicalUri, clientId: string): void {
+      const record = this.__documents.get(uri);
+      if (record) {
+         this.pruneLostClients(record);
+      }
+      const returning = record?.lostClients?.delete(clientId) ?? false;
+      if (!this.__sessions.isRevertPending(uri)) {
+         return;
+      }
+      this.__sessions.cancelRevert(uri);
+      if (!returning) {
+         this.releaseDocument(uri);
+      }
+   }
+
+   /** Drop the entries of {@link DocumentTrackingRecord.lostClients} whose grace has run out. */
+   protected pruneLostClients(record: DocumentTrackingRecord): void {
+      for (const [clientId, sinceLoss] of record.lostClients ?? []) {
+         if (sinceLoss.elapsedMs >= this.revertGraceMs) {
+            record.lostClients?.delete(clientId);
+         }
+      }
+   }
+
+   /**
+    * Drop the document no client has open any more, then announce it on
+    * {@link onDidCloseLastOpen}, which is what reverts it to disk.
+    */
+   protected releaseDocument(uri: CanonicalUri): void {
+      const syncedDocument = this.__syncedDocuments.get(uri);
+      if (syncedDocument === undefined) {
+         return;
+      }
+      this.log(syncedDocument.uri, `Remove synced document: ${syncedDocument.version} (no client left)`);
+      // Persist where the shared version sequence left off (version +
+      // content hash) so the next open CONTINUES the sequence instead of
+      // restarting at the reopening client's declared id. Hashed once
+      // here at release, not on every change.
+      this.__versionSequences.set(uri, {
+         version: syncedDocument.version,
+         contentHash: contentHash(syncedDocument.getText())
+      });
+      this.__syncedDocuments.delete(uri);
+      // One delete clears every per-URI axis (version history + any staged
+      // pending content) so a future open with the same URI starts fresh.
+      this.__documents.delete(uri);
+      this.lastOpenClosedEmitter.fire(Object.freeze({ uri }));
+   }
+
+   /**
+    * Rebuild a released document from disk, so the build stops carrying the
+    * unsaved text of its last client.
+    *
+    * Only a `file:` document reverts. A document of another scheme may have
+    * been loaded by the adopter into the workspace index, and a rebuild would
+    * drop it and break every reference to it.
+    *
+    * The file's existence is read in its disk queue, so the rebuild follows
+    * any save still queued rather than reverting past it. A document with no
+    * file behind it — created and never saved, or deleted meanwhile — is
+    * removed from the workspace instead: there is no disk text to revert to,
+    * and one whose file goes after that read is removed when its rebuild
+    * finds none.
+    *
+    * Whether to revert at all is decided inside the write lock, as its holder:
+    * decided before waiting for the lock, a client that opens or re-creates the
+    * document meanwhile has its text rebuilt over from disk, or removed. A
+    * document some client has open again, or that waits out a new grace, is
+    * left to that client.
+    */
+   protected async revertToDisk(uri: CanonicalUri): Promise<void> {
+      if (URI.parse(uri).scheme !== 'file') {
+         return;
+      }
+      const workspace = this.services.workspace;
+      const target = UriUtils.toUri(uri);
+      const reopened = (): boolean => this.isOpenInAnyClient(uri) || this.__syncedDocuments.has(uri);
+      try {
+         // Read before the lock: every build and read waits while the lock is
+         // held, and this read waits on the file's save I/O.
+         const onDisk = await workspace.FileSystemTaskQueue.enqueue(uri, () => workspace.FileSystemProvider.exists(target));
+         await workspace.WorkspaceManager?.ready;
+         await workspace.WorkspaceLock.write(async token => {
+            if (reopened()) {
+               return;
+            }
+            workspace.DocumentBuilder.markNextReason(HYDRANIUM_BUILD_REASONS.didClose);
+            try {
+               await (onDisk
+                  ? workspace.DocumentBuilder.update([target], [], token)
+                  : workspace.DocumentBuilder.update([], [target], token));
+            } catch (err: unknown) {
+               if (!onDisk || !isFileNotFound(err, target)) {
+                  throw err;
+               }
+               // The file went after its existence was read.
+               this.tracer.with(uri).debug('Revert found no file; removing the document instead');
+               workspace.DocumentBuilder.markNextReason(HYDRANIUM_BUILD_REASONS.didClose);
+               await workspace.DocumentBuilder.update([], [target], token);
+            }
+         });
+      } catch (err: unknown) {
+         // A revert that finishes after the LSP peer went away fails its
+         // diagnostics publish, and one that runs after its workspace was torn
+         // down finds no file: teardown races, not failed reverts.
+         if (isConnectionGoneError(err) || isFileNotFound(err, target)) {
+            this.tracer.with(uri).debug(`Revert on last close skipped: ${err instanceof Error ? err.message : String(err)}`);
+            return;
          }
+         const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+         this.tracer.with(uri).error(`Revert on last close dropped. ${detail}`);
       }
    }
 
@@ -675,17 +894,70 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       }
    }
 
+   /**
+    * Handle a save the language client reports: fire
+    * {@link onDidSaveInLanguageClient}, then announce it on {@link onDidSave}
+    * only once the file read back from disk holds the store's current text.
+    */
+   protected async notifyLanguageClientSave(event: DidSaveTextDocumentParams): Promise<void> {
+      const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
+      if (syncedDocument === undefined) {
+         return;
+      }
+      const uri = syncedDocument.uri;
+      this.languageClientSavedEmitter.fire(Object.freeze({ uri }));
+      // `onDidSave` tells its listeners that the shared document is on disk: a
+      // diagram marks its save done, the data head broadcasts a save and its
+      // clients drop their dirty state. The editor wrote its own buffer,
+      // which lags the store while another client's edit is still on its way
+      // to it, so only the file says whether that holds. Read it rather than
+      // trust the editor: `didSave` carries text only for a client that
+      // honours `includeText`, and asking for it means rewriting Langium's
+      // initialize answer, which advertises `save` as a Boolean. The read goes
+      // through the disk queue and waits on nothing but the provider, so it
+      // follows a server save queued meanwhile. A file changed again between
+      // the editor's write and this read compares unequal and takes the safe
+      // side. A save not announced leaves every other client dirty, which is
+      // true of the store's text: a diagram keeps its save pending, and data
+      // clients keep their unsaved state until the next save of the document.
+      let onDisk: string | undefined;
+      try {
+         onDisk = await this.services.workspace.FileSystemTaskQueue.enqueue(uri, () =>
+            this.services.workspace.FileSystemProvider.readFile(UriUtils.toUri(uri))
+         );
+      } catch (err: unknown) {
+         this.tracer
+            .with(uri)
+            .debug(`Editor save not announced: reading the file back failed. ${err instanceof Error ? err.message : String(err)}`);
+         return;
+      }
+      // An editor that saves and then closes releases the document while the
+      // read is under way; its save is still a save of the text it held.
+      const document = this.__syncedDocuments.get(this.documentKey(uri)) ?? syncedDocument;
+      if (onDisk !== document.getText()) {
+         this.tracer.with(uri).debug(`Editor save not announced: the file does not hold the text of version ${document.version}`);
+         return;
+      }
+      this.announceSave(document, LANGUAGE_CLIENT_ID);
+   }
+
    public notifyDidSaveTextDocument(event: DidSaveTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
       if (syncedDocument !== undefined) {
-         this.log(syncedDocument.uri, `Saved synced document: ${syncedDocument.version} by ${this.formatClientId(clientId)}`);
-         this.__onDidSave.fire(Object.freeze({ document: syncedDocument, clientId }));
+         this.announceSave(syncedDocument, clientId);
       }
    }
 
+   /** Fire {@link onDidSave} for `document`, which need not be synced any more. */
+   protected announceSave(document: T, clientId: string): void {
+      this.log(document.uri, `Saved synced document: ${document.version} by ${this.formatClientId(clientId)}`);
+      this.__onDidSave.fire(Object.freeze({ document, clientId }));
+   }
+
    public notifyDidOpenTextDocument(event: DidOpenTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
       const td = event.textDocument;
       const uri = this.documentKey(td.uri);
+      this.resolvePendingRevert(uri, clientId);
       if (this.isOpenInClient(uri, clientId)) {
          // Already open for this client under this canonical identity. If this is a
          // NEW client-facing URI for the same file (a second tab reached via a
@@ -787,13 +1059,19 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * Unifying the two routes therefore rebaselines a textual client's guard to a
     * version it never declared.
     *
-    * Returns whether a hold was added — `false` when `uri` is not open, or
-    * `clientId` already holds it.
+    * Returns whether a hold was added — `false` when `uri` is not open,
+    * `clientId` already holds it, or the document was waiting out the revert
+    * grace for other clients and was released instead (see
+    * {@link resolvePendingRevert}); the caller then opens it anew.
     */
    attachClient(uri: DocumentUri, clientId: string): boolean {
       const key = this.documentKey(uri);
+      if (!this.__syncedDocuments.has(key) || this.isOpenInClient(key, clientId)) {
+         return false;
+      }
+      this.resolvePendingRevert(key, clientId);
       const document = this.__syncedDocuments.get(key);
-      if (!document || this.isOpenInClient(key, clientId)) {
+      if (!document) {
          return false;
       }
       const existingClients = this.__sessions.clientsOf(key);
@@ -1050,6 +1328,35 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       return this.__sessions.onDidCloseSession;
    }
 
+   /**
+    * Fires once a document no client has open is released: at its last close,
+    * or, for a lost client's last close, when its revert grace runs out,
+    * another client opens it, or it is deleted. The document then reverts to
+    * disk.
+    */
+   get onDidCloseLastOpen(): Event<LastOpenClosedEvent> {
+      return this.lastOpenClosedEmitter.event;
+   }
+
+   /**
+    * Fires for every save the language client reports of a document it has
+    * open: the editor has written the file. {@link onDidSave} follows only
+    * when the file holds the store's text.
+    */
+   get onDidSaveInLanguageClient(): Event<LanguageClientSavedEvent> {
+      return this.languageClientSavedEmitter.event;
+   }
+
+   /**
+    * Whether `uri` is waiting out the revert grace: its last open closed with a
+    * lost connection, and it still holds its unsaved text. Such a document is
+    * open for no client, yet not closed either, so a caller that would persist
+    * a closed document's text to disk treats it as open.
+    */
+   isRevertPending(uri: DocumentUri): boolean {
+      return this.__sessions.isRevertPending(this.documentKey(uri));
+   }
+
    /**
     * Start a client session under `clientId`. Throws `DuplicateClientIdError`
     * where {@link ClientSessionRegistry.register} refuses the id.
@@ -1063,15 +1370,16 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    /**
     * End the client session `clientId`: close every document it has open, then
     * free the id. Immediate — each close runs the ordinary close path before
-    * this returns. A no-op for an id that is not a registered session.
+    * this returns, with `cause` as its cause. A no-op for an id that is not a
+    * registered session.
     */
-   closeSession(clientId: string): void {
+   closeSession(clientId: string, cause: SessionEndCause = 'closed'): void {
       if (!this.__sessions.isRegistered(clientId)) {
          return;
       }
       try {
          for (const uri of this.__sessions.beginClose(clientId)) {
-            this.notifyDidCloseTextDocument({ textDocument: { uri } }, clientId);
+            this.notifyDidCloseTextDocument({ textDocument: { uri } }, clientId, cause);
          }
       } finally {
          this.__sessions.unregister(clientId);
@@ -1080,16 +1388,6 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       }
    }
 
-   /** The options `clientId` opened `uri` with, or `undefined` when it gave none or does not have it open. */
-   openOptions(uri: DocumentUri, clientId: string): OpenOptions | undefined {
-      return this.__sessions.openOptions(this.documentKey(uri), clientId);
-   }
-
-   /** Replace the options of an existing open. Does nothing when `clientId` does not have `uri` open. */
-   setOpenOptions(uri: DocumentUri, clientId: string, options: OpenOptions | undefined): void {
-      this.__sessions.setOpenOptions(this.documentKey(uri), clientId, options);
-   }
-
    /**
     * The file behind `uri` was deleted: close every open of it except the
     * language client's.
@@ -1122,6 +1420,12 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       for (const clientId of this.__sessions.clientsOf(key)) {
          this.notifyDidCloseTextDocument({ textDocument: { uri: key } }, clientId);
       }
+      // A document waiting out the grace has no client left to close, and is
+      // released now as its last close would have released it.
+      if (this.__sessions.isRevertPending(key)) {
+         this.__sessions.cancelRevert(key);
+         this.releaseDocument(key);
+      }
       super.delete(key);
    }
 

package/src/documents/index.ts

@@ -14,3 +14,4 @@ export * from './language-client-text-shadow.js';
 export * from './hydranium-text-documents.js';
 export * from './ast-document-manager.js';
 export * from './self-save-registry.js';
+export * from './file-system-task-queue.js';

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

@@ -44,6 +44,20 @@ 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 `didClose` for the revert the text store runs
+ * after a last close. 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',
+   didClose: 'didClose'
+} as const);
+
 /**
  * Consecutive re-queued builds that leave a waited-on document at the same state
  * before {@link HydraniumDocumentBuilder.awaitDocumentState} stops re-queuing it.
@@ -211,8 +225,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 text store for the revert that follows a last close.
     *
     * The framework stages the value and never reads it back. The consumer is a
     * subclass overriding the build logging, which takes

package/src/langium/integrity/integrity-service.ts

@@ -456,7 +456,8 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     *   mutation rode the current build, so `ModelService.syncToLanguageClient`
     *   (the persistent integrity-settled listener) mirrors it to the client by
     *   *content* (shadow diff), and the editor shows it as an unsaved change.
-    * - **Held only through the data or GLSP head** → the store is the
+    * - **Held only through the data or GLSP head**, or waiting out the revert
+    *   grace after its last client's connection was lost → the store is the
     *   authority, and those heads read the correction from the settled build.
     *   In silent mode it is also written to disk when the text it was computed
     *   from is what disk holds, since the repair is then the only difference;
@@ -497,7 +498,9 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          return;
       }
 
-      if (this.textDocuments.isOpenInAnyClient(document.uri)) {
+      // A document waiting out the revert grace still holds its lost client's
+      // unsaved text, so writing it as a closed file would persist that text.
+      if (this.textDocuments.isOpenInAnyClient(document.uri) || this.textDocuments.isRevertPending(document.uri)) {
          if (this.syncMode === 'silent' && parsedFrom !== undefined) {
             await this.persistIfDiskMatches(document, parsedFrom);
          }
@@ -508,9 +511,9 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
       if (this.syncMode === 'silent') {
          const repaired = document.getText();
          // Async write so the integrity pass does not block the event loop on a slow filesystem.
-         // In the URI's disk queue, behind any save already queued: written
+         // In the file's task queue, behind any save already queued: written
          // beside one, the older repair can land last and stay on disk.
-         await this.services.shared.workspace.AstDocumentManager.queueDiskTask(document.uri, () =>
+         await this.services.shared.workspace.FileSystemTaskQueue.enqueue(document.uri, () =>
             this.fileSystemProvider.writeFile(UriUtils.toUri(document.uri), repaired)
          );
          return;
@@ -525,7 +528,7 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     * the text the repair was computed from — so the write carries the repair
     * and nothing a holder could still discard.
     *
-    * The read, the compare and the write run as one task in the URI's disk
+    * The read, the compare and the write run as one task in the file's task
     * queue, so no save of the file lands between them. The store is compared
     * again once the read returns, and the write is skipped if it no longer
     * holds the repair: an edit does not wait for the queue, and writing the
@@ -537,7 +540,7 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
    protected async persistIfDiskMatches(document: TextDocument, parsedFrom: string): Promise<void> {
       const uri = UriUtils.toUri(document.uri);
       const repaired = document.getText();
-      await this.services.shared.workspace.AstDocumentManager.queueDiskTask(document.uri, async () => {
+      await this.services.shared.workspace.FileSystemTaskQueue.enqueue(document.uri, async () => {
          let onDisk: string;
          try {
             onDisk = await this.fileSystemProvider.readFile(uri);

package/src/langium/language-module.ts

@@ -158,7 +158,7 @@ export interface ServerAddedServices {
        * multi-grammar workspaces route to the right serializer per file. The
        * framework default throws a clear "no Serializer registered" error;
        * adopters bind their own per-language subclass to enable
-       * `ModelService.update` / `ModelService.save`.
+       * a client session's `update` / `save`.
        */
       Serializer: Serializer;
    };
@@ -211,7 +211,7 @@ export interface ServerAddedServices {
    updateRewrite: {
       /**
        * Per-language runner for transfer-model rewrites applied on the
-       * structured write path of `ModelService.update` / `save`, before
+       * structured write path of a client session's `update` / `save`, before
        * serialisation. The RPC-update-stage sibling of the
        * {@link IntegrityService} / {@link AstExtensionService} registries.
        * Framework default is a no-op (zero rewrites registered) — adopters
@@ -263,12 +263,12 @@ export interface ServerAddedServices {
 class UnboundSerializer implements Serializer {
    serializeAst(_model: AstNode): string {
       throw new Error(
-         'No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before calling ModelService.update / ModelService.save.'
+         "No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before writing through a client session's update or save."
       );
    }
    serializeTransfer(_model: TransferElement): string {
       throw new Error(
-         'No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before calling ModelService.update / ModelService.save.'
+         "No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before writing through a client session's update or save."
       );
    }
 }