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

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 { UriUtils } from '@hydranium/langium';
+import { type URI, UriUtils } from '@hydranium/langium';
 import { type ServerSharedServices } from '../langium/module.js';
 import {
    type ApplyWorkspaceEditResult,
@@ -31,12 +31,13 @@ import {
    type DidOpenTextDocumentParams,
    type DidSaveTextDocumentParams,
    type Disposable,
-   type Emitter,
+   Emitter,
    type Event,
    type HandlerResult,
    OptionalVersionedTextDocumentIdentifier,
    type RequestHandler,
    type TextDocumentChangeEvent,
+   TextDocumentContentChangeEvent as ContentChange,
    TextDocumentEdit,
    TextDocumentSyncKind,
    type TextDocumentWillSaveEvent,
@@ -45,9 +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 SessionEndCause } from './client-session-registry.js';
 import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
 
 /**
@@ -74,6 +86,46 @@ 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;
+}
+
+/** Delivered by {@link HydraniumTextDocuments.onDidChangeDirty}. */
+export interface DocumentDirtyChangedEvent {
+   readonly uri: CanonicalUri;
+   /** The new answer of {@link HydraniumTextDocuments.isDirty}. */
+   readonly dirty: boolean;
 }
 
 /**
@@ -89,10 +141,13 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
  *    separately-tested diff/apply-verify abstraction that owns its own baseline
  *    text; folding its storage here would couple a clean utility to this record
  *    for no real gain.
+ *
+ * Returned by the `protected` {@link HydraniumTextDocuments.trackingFor}, so an
+ * override has to name it. Restating the shape structurally instead compiles
+ * until a field is added here, and then fails at the adopter rather than at the
+ * change that caused it.
  */
-interface DocumentTracking {
-   /** Client ids currently holding this document open (multi-client membership). */
-   readonly clients: Set<string>;
+export interface DocumentTrackingRecord {
    /** Author of each version, sparse-indexed by the SHARED (server-assigned) version number. */
    readonly versionAuthors: string[];
    /**
@@ -115,6 +170,29 @@ interface DocumentTracking {
     * 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>;
+   /**
+    * The text the server last knew the file to hold, `undefined` for no file.
+    * Set by the first open and moved by {@link HydraniumTextDocuments.updateDiskBaseline}.
+    */
+   diskBaseline?: string;
+   /** The last answer {@link HydraniumTextDocuments.onDidChangeDirty} announced. */
+   dirty?: boolean;
 }
 
 /**
@@ -128,13 +206,28 @@ export interface OpenDocument {
    readonly clients: readonly string[];
 }
 
+/**
+ * What {@link HydraniumTextDocuments.commitRepair} did with an integrity repair.
+ *
+ * Three outcomes rather than a document-or-nothing, because the two ways of
+ * getting nothing call for opposite responses: `not-open` means there is no
+ * store document to correct and the caller carries on with the one it holds,
+ * while `stale` means there IS one and it has moved past the text the repair
+ * was computed against — so carrying on would persist a correction over an edit
+ * that superseded it. Collapsing them lets the second read as permission to
+ * proceed, which is the failure this shape exists to make unrepresentable.
+ */
+export type RepairCommit<T extends TextDocument> =
+   { readonly status: 'committed'; readonly document: T } | { readonly status: 'stale' } | { readonly status: 'not-open' };
+
 /**
  * Where a URI's shared version sequence left off — written once at last-client
  * close, consulted at the next open so the sequence CONTINUES instead of
  * restarting at whatever version id the reopening client declares. One entry
- * of {@link HydraniumTextDocuments.__versionSequences}.
+ * of {@link HydraniumTextDocuments.__versionSequences} — a `protected` field, so
+ * a subclass reading the map has to name what it holds.
  */
-interface VersionSequence {
+export interface VersionSequence {
    /** The shared version at last-client close. */
    readonly version: number;
    /** {@link contentHash} of the synced text at last-client close. */
@@ -161,19 +254,20 @@ interface ConnectionWithTextDocumentSync {
 /**
  * One text pushed to the LSP textual language client by
  * {@link HydraniumTextDocuments.applyEditToLanguageClient} whose echo has not
- * come back yet. One entry of {@link HydraniumTextDocuments.__pendingPushes}.
+ * come back yet. One entry of {@link HydraniumTextDocuments.__pendingPushes} —
+ * a `protected` field, so a subclass reading the queue has to name what it holds.
  */
-interface PendingPush {
+export interface PendingLanguageClientPush {
    /**
-    * The text the client held BEFORE this push — the shadow baseline the
-    * push's edits were diffed against, and therefore the text the client's
-    * echo addresses with its ranges.
+    * The text the client held BEFORE this push, and therefore the text its
+    * echo addresses with its ranges. Wider than the baseline the push's edits
+    * were diffed against: a full replace is sent with no diff baseline and
+    * still lands on a buffer the echo is keyed to.
     *
-    * `undefined` when the push was a full replace sent with no baseline (a
-    * first sync, or the recovery push after a rejection). There is then no
-    * knowing what the client held, so the echo is reconstructed against the
-    * synced text instead — which is sound for a full replace, whose
-    * application is position-independent.
+    * `undefined` only when that buffer is unknown — the client never declared
+    * one, or a rejection invalidated what was tracked. The echo is then
+    * reconstructed against the synced text, which is sound only for a
+    * position-independent (full-text) change.
     */
    readonly before: string | undefined;
    /** {@link contentHash} of the text this push moves the client to. */
@@ -182,18 +276,38 @@ interface PendingPush {
 
 /**
  * What an incoming language-client change turns out to be once reconstructed
- * against the pushes still in flight — the return of
- * {@link HydraniumTextDocuments.classifyLanguageClientChange}.
+ * against the buffer its ranges address — the return of
+ * {@link HydraniumTextDocuments.classifyLanguageClientChange}. That method is
+ * `protected`, so an override has to name every arm it can return.
  */
-type LanguageClientChangeOrigin =
+export type LanguageClientChangeOrigin =
    /** The client is reporting a text we pushed it. The synced document is already there. */
    | { readonly kind: 'echo' }
    /**
-    * The client's buffer has moved somewhere we did not push it — it coalesced
-    * a genuine keystroke into the echo, or typed before the push arrived. The
-    * reconstructed text is what it now holds, and is authoritative.
+    * The client's buffer holds a text we did not push it — a keystroke that
+    * raced a push, or an edit to a buffer the store has already been written
+    * past. The reconstructed text is what it now holds, and is authoritative.
     */
-   | { readonly kind: 'divergent'; readonly text: string };
+   | { readonly kind: 'divergent'; readonly text: string }
+   /**
+    * The change carries ranges and no known text addresses them, so no
+    * reconstruction is offered. Adopting one anyway splices the document and
+    * stores an edit nobody made; dropping costs at most the one keystroke the
+    * client still holds and the next push contradicts.
+    */
+   | { 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
@@ -222,15 +336,21 @@ function contentHash(text: string): string {
  * Multi-client text-document tracking on top of Langium's `NormalizedTextDocuments`.
  *
  * Adds the framework features used by the integrity, model-server, and GLSP layers:
- *   - Per-document client membership (multiple clients can attach to the same URI).
+ *   - Per-document client membership (multiple clients can attach to the same
+ *     URI) and the client-session table, both kept by {@link __sessions}.
  *   - A SERVER-OWNED shared version sequence: per-URI, monotonic across
  *     close/reopen cycles, advancing exactly when the synced content changes.
  *     Client-declared version ids (Monaco's buffer numbering) feed only a
  *     per-client staleness guard and never leak into the shared sequence —
  *     the two are different things (an editor's edit-operation counter vs the
  *     document's content-revision number), and splicing them lets versions drift
- *     silently past `baseVersion` gate holders.
+ *     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.
+ *   - A disk baseline per open document, and whether its text differs from it
+ *     ({@link isDirty}).
  *   - 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
@@ -240,23 +360,28 @@ function contentHash(text: string): string {
  */
 export class HydraniumTextDocuments<T extends TextDocument = TextDocument> extends NormalizedTextDocuments<T> {
    /**
-    * Per-URI client-facing tracking ({@link DocumentTracking}): client
-    * membership, version-author history, and integrity-staged pending content,
-    * keyed by normalized URI. One record per URI so the last-client close clears
-    * every axis atomically. The language-client diff baseline stays in
-    * {@link __shadow} (its own abstraction); the parsed-document store stays in
-    * the inherited `__syncedDocuments`.
+    * Per-URI client-facing tracking ({@link DocumentTrackingRecord}), keyed by
+    * canonical URI. One record per URI, so dropping it clears every axis at
+    * once. Which client has the document open is kept apart, in
+    * {@link __sessions}.
     */
-   protected __documents = new Map<CanonicalUri, DocumentTracking>();
+   protected __documents = new Map<CanonicalUri, DocumentTrackingRecord>();
+
+   /**
+    * Which client has which document open, and which client ids are registered
+    * sessions. Every open-state predicate on this class reads it, so an open
+    * recorded anywhere else is invisible to the last-close transition.
+    */
+   protected readonly __sessions = new ClientSessionRegistry();
 
    /**
     * Per-URI shared-version continuity across close/reopen cycles
     * ({@link VersionSequence}), written at last-client close and consulted by
-    * the next first-client open. DELIBERATELY outside {@link DocumentTracking}:
+    * the next first-client open. DELIBERATELY outside {@link DocumentTrackingRecord}:
     * that record is deleted on last close, while the version sequence must
     * survive it — the shared version is a server-owned, monotonic,
     * advances-iff-content-changes counter that never resets while the server
-    * lives. That invariant is what makes an optimistic `baseVersion` gate
+    * lives. That invariant is what makes an optimistic based-on gate
     * sound: "version unchanged ⇔ content unchanged", with no false conflicts
     * from close/reopen version resets and no false passes from a reopened
     * sequence coincidentally landing on a stale writer's number.
@@ -269,7 +394,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    /**
     * Texts pushed to the LSP textual language client via
     * {@link applyEditToLanguageClient} whose echoes have not come back yet
-    * ({@link PendingPush}), keyed like the shadow by language-client URI.
+    * ({@link PendingLanguageClientPush}), keyed like the shadow by language-client URI.
     * Outbound pushes and inbound echoes are uncorrelated on the wire; this
     * FIFO is the explicit correlation, and it is what
     * {@link classifyLanguageClientChange} reconstructs against.
@@ -291,7 +416,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * a pathological echo that never arrives; the memory cost until then is
     * one pre-push text per in-flight push, for milliseconds.
     */
-   protected readonly __pendingPushes = new Map<LanguageClientUri, PendingPush[]>();
+   protected readonly __pendingPushes = new Map<LanguageClientUri, PendingLanguageClientPush[]>();
 
    /**
     * Tracked text content per URI for the LSP textual language client (Monaco / VS Code).
@@ -316,6 +441,11 @@ 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>();
+   protected readonly dirtyChangedEmitter = new Emitter<DocumentDirtyChangedEvent>();
 
    constructor(
       protected services: ServerSharedServices,
@@ -329,6 +459,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
@@ -429,7 +561,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       );
       disposables.push(
          connection.onDidSaveTextDocument((event: DidSaveTextDocumentParams) => {
-            this.notifyDidSaveTextDocument(event);
+            void this.notifyLanguageClientSave(event);
          })
       );
       return disposables;
@@ -466,20 +598,21 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // the update) from "incoming version older than ours" (stale race).
             const reason =
                lastSeen === td.version ? `already at version ${lastSeen}` : `incoming version ${td.version} older than current ${lastSeen}`;
-            this.logUri(uri, `Ignore update by ${clientId}: ${reason}`, 'debug');
+            this.logUri(uri, `Ignore update by ${this.formatClientId(clientId)}: ${reason}`, 'debug');
             return;
          }
          record.clientVersions.set(clientId, td.version);
 
-         // A language-client change arriving while one of our own pushes is in
-         // flight is keyed to the buffer the client held BEFORE that push, NOT
-         // to the synced text — the authored write already advanced the latter.
+         // A language-client change is keyed to the buffer that client holds,
+         // which is the synced text only while the two agree — an authored
+         // write advances the synced text without the client knowing, and a
+         // push in flight moves the client without the store knowing.
          // Resolve which it is, and against what, before touching anything.
-         const inFlight =
+         const origin =
             clientId === LANGUAGE_CLIENT_ID
                ? this.classifyLanguageClientChange(this.toLanguageClientUri(td.uri), document, changes)
                : undefined;
-         if (inFlight?.kind === 'echo') {
+         if (origin?.kind === 'echo') {
             // The client is reporting a text we pushed it, so the synced
             // document is ALREADY there and the changes must not be applied a
             // second time. Nothing is minted and no rebuild fires. The
@@ -491,19 +624,23 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             this.logUri(uri, `Skip rebuild: echo of a server-authored push (client version ${td.version})`, 'debug');
             return;
          }
+         if (origin?.kind === 'unreconstructable') {
+            this.tracer.with(uri).warn(`Drop change: no known client buffer for its ranges (client version ${td.version})`);
+            return;
+         }
 
          // The SHARED version advances iff the content actually changes — the
-         // invariant optimistic `baseVersion` gates rely on. The new text is
+         // invariant optimistic based-on gates rely on. The new text is
          // only known after applying the (possibly incremental) changes, so
          // apply at a tentative +1 and roll the version back on an identical
          // result (an empty-changes update only re-stamps the version).
          //
-         // A divergent in-flight change is applied as its RECONSTRUCTED text
-         // rather than as its own ranges: the ranges address the pre-push
-         // baseline, so applying them here would splice the wrong lines.
+         // A divergent change is applied as its RECONSTRUCTED text rather than
+         // as its own ranges: those ranges address the client's own buffer, so
+         // applying them here would splice the wrong lines.
          const previousText = document.getText();
          const sharedVersion = document.version;
-         document = this.configuration.update(document, inFlight === undefined ? changes : [{ text: inFlight.text }], sharedVersion + 1);
+         document = this.configuration.update(document, origin === undefined ? changes : [{ text: origin.text }], sharedVersion + 1);
          const changed = document.getText() !== previousText;
          if (!changed) {
             document = this.configuration.update(document, [], sharedVersion);
@@ -511,6 +648,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          this.__syncedDocuments.set(uri, document);
          if (changed) {
             this.setAuthor(uri, document.version, clientId);
+            this.refreshDirty(uri);
          }
          if (clientId === LANGUAGE_CLIENT_ID) {
             // Monaco just told us about its new content; record it so the next outbound
@@ -527,7 +665,10 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
                return;
             }
          }
-         this.log(document.uri, `Update to version ${document.version} by ${clientId}${changed ? '' : ' (content unchanged)'}`);
+         this.log(
+            document.uri,
+            `Update to version ${document.version} by ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`
+         );
          this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
       }
    }
@@ -544,7 +685,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * A content-identical write still fires the change event (rebuild): the
     * authored write's server-side rebuild is correctness-bearing, it just
     * mints no new version — nothing observable changed, so watchers'
-    * `baseVersion` pointers stay valid.
+    * based-on versions stay valid.
     *
     * Returns the resulting shared version. Throws when the document is not
     * open — callers (`AstDocumentManager.update`) open first.
@@ -560,57 +701,200 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          document = this.configuration.update(document, [{ text }], document.version + 1);
          this.__syncedDocuments.set(key, document);
          this.setAuthor(key, document.version, clientId);
+         this.refreshDirty(key);
       }
-      this.log(document.uri, `Update to version ${document.version} by ${clientId}${changed ? '' : ' (content unchanged)'}`);
+      this.log(
+         document.uri,
+         `Update to version ${document.version} by ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`
+      );
       this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
       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.isOpenInClient(uri, clientId)) {
+      if (!this.__sessions.removeOpen(uri, clientId)) {
          return;
       }
-      const closingRecord = this.__documents.get(uri);
-      closingRecord?.clients.delete(clientId);
-      closingRecord?.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 ${clientId}`);
+         this.log(syncedDocument.uri, `Closed synced document: ${syncedDocument.version} by ${this.formatClientId(clientId)}`);
          this.__onDidClose.fire(Object.freeze({ document: syncedDocument, clientId }));
 
          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.__documents.get(uri)?.clients.size) {
-            // 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 (!this.__sessions.isOpen(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())
+      });
+      const wasDirty = this.__documents.get(uri)?.dirty === true;
+      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 (wasDirty) {
+         this.dirtyChangedEmitter.fire(Object.freeze({ uri, dirty: false }));
+      }
+      this.lastOpenClosedEmitter.fire(Object.freeze({ uri }));
+   }
+
+   /**
+    * Rebuild a released document from the file system provider, so the build
+    * stops carrying the unsaved text of its last client.
+    *
+    * The provider decides, for every scheme, by `exists`: a document it can
+    * serve is rebuilt from its text, and any other — an editor's `untitled:`
+    * buffer, a file never saved, or one deleted meanwhile — is removed
+    * from the workspace. A `virtual:` document survives, since the framework's
+    * providers serve it from the index; an edited one therefore keeps its last
+    * client's text, and keeping it read-only is the client's job.
+    *
+    * The answer is read in the document's disk queue, so the rebuild follows
+    * any save still queued rather than reverting past it; a file that 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 would have its text rebuilt over, or the document
+    * 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> {
+      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}`);
+      }
+   }
+
    public notifyWillSaveTextDocument(event: WillSaveTextDocumentParams): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
       if (syncedDocument !== undefined) {
@@ -630,40 +914,103 @@ 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.
+      // 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 the save goes unannounced.
+      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;
+      }
+      // What the file holds, not what the editor meant to write: an editor
+      // that saved older text leaves the document dirty.
+      this.updateDiskBaseline(uri, onDisk);
+      // 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);
+   }
+
+   /**
+    * Announce a save the server made. `event.text`, when given, is what the
+    * file now holds, written or found there, and becomes the disk baseline
+    * before the save is announced. It lags the store when an edit landed
+    * after the save took its text, and the document then stays dirty.
+    */
    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 ${clientId}`);
-         this.__onDidSave.fire(Object.freeze({ document: syncedDocument, clientId }));
+         if (event.text !== undefined) {
+            this.updateDiskBaseline(syncedDocument.uri, event.text);
+         }
+         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
-         // divergent path, e.g. a symlink and its real path), record it and baseline
-         // its shadow so outbound edits reach this tab too — but do NOT re-fire
-         // open/rebuild; the document is already live.
+         // divergent path, e.g. a symlink and its real path), record it so outbound
+         // edits reach this tab too — but do NOT re-fire open/rebuild; the document
+         // is already live.
          if (clientId === LANGUAGE_CLIENT_ID) {
             const clientFacing = this.toLanguageClientUri(td.uri);
             const record = this.__documents.get(uri);
             if (record && !record.languageClientUris?.has(clientFacing)) {
                (record.languageClientUris ??= new Set<LanguageClientUri>()).add(clientFacing);
-               const open = this.__syncedDocuments.get(uri);
-               if (open) {
-                  this.__shadow.set(clientFacing, open.getText());
-               }
+               // This tab's own buffer, NOT the synced text: a second tab is a second
+               // client model, read from disk, so a server-authored write already
+               // applied to the first tab leaves it BEHIND the synced document. Keying
+               // a diff to the synced text here addresses lines this tab does not have
+               // and drops content it does.
+               this.__shadow.setOpenedText(clientFacing, td.text);
             }
          }
          return;
       }
       let document = this.__syncedDocuments.get(uri);
+      const existingClients = this.__sessions.clientsOf(uri);
+      this.__sessions.addOpen(uri, clientId);
       const record = this.trackingFor(uri);
-      const existingClients = [...record.clients];
-      record.clients.add(clientId);
       // Baseline the per-client staleness guard at the version id the client
       // declared for its own buffer (client-owned per LSP).
       record.clientVersions.set(clientId, td.version);
@@ -679,44 +1026,110 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          const source = pendingText ? ', source=pending' : '';
          // The SHARED version is server-assigned: continue the persisted
          // sequence — same version when the content is unchanged since the
-         // last close (so watchers' `baseVersion` pointers stay valid), one
+         // last close (so watchers' based-on versions stay valid), one
          // step when it changed (so no stale pointer can coincidentally pass
          // the optimistic gate). Only a first-ever open adopts the client's
          // declared id as the sequence seed.
          const sequence = this.__versionSequences.get(uri);
          const version =
             sequence === undefined ? td.version : sequence.contentHash === contentHash(text) ? sequence.version : sequence.version + 1;
-         this.log(uri, `Open document: Version ${version} by ${clientId} [first client${source}]`);
+         this.log(uri, `Open document: Version ${version} by ${this.formatClientId(clientId)} [first client${source}]`);
          document = this.configuration.create(uri, td.languageId, version, text);
          this.__syncedDocuments.set(uri, document);
          this.setAuthor(uri, version, clientId);
+         // The opener's text, not the staged content: a session's open read
+         // it from the file, and an editor opened its buffer from there. An
+         // editor that opens a buffer it never saved is taken as clean.
+         record.diskBaseline = td.text;
+         this.refreshDirty(uri);
          if (clientId === LANGUAGE_CLIENT_ID) {
             // Baseline the shadow to what Monaco just opened so the next outbound
             // applyEditToLanguageClient diffs against the right starting point. Keyed by the
             // language-client URI (what Monaco holds), not the canonical document key.
-            this.__shadow.set(this.toLanguageClientUri(td.uri), document.getText());
+            //
+            // The CLIENT's declared text, never the synced document: staged content
+            // consumed above leaves the two different, and a baseline asserting the
+            // client already holds the staged text suppresses the one sync that would
+            // deliver it. Skipped entirely when a push is already outstanding for this
+            // URI — an `applyEdit` to a closed file has the client open from disk and
+            // apply afterwards, so that shadow records what it is about to hold and
+            // disk text would key the next diff to a buffer nobody has.
+            const clientFacing = this.toLanguageClientUri(td.uri);
+            if (!this.__shadow.isTracked(clientFacing)) {
+               this.__shadow.set(clientFacing, td.text);
+            }
          }
          const toFire = Object.freeze({ document, clientId });
          this.__onDidOpen.fire(toFire);
          this.__onDidChangeContent.fire(toFire);
       } else {
          // An additional client attaches to a document already open by another client.
-         this.log(
-            uri,
-            `Attach client: ${clientId} joined existing document (version ${document.version}, ` +
-               `now open in: ${[...existingClients, clientId].join(', ')})`
-         );
+         this.logClientJoined(uri, clientId, document.version, existingClients);
+         if (clientId === LANGUAGE_CLIENT_ID) {
+            // Monaco's own buffer, which on this path is NOT the synced text — another
+            // client opened the document and may already have changed it. Recorded as
+            // an equality-only baseline (never a diff one, see `setOpenedText`) so the
+            // refresh below does not push a full replace of content Monaco already
+            // holds, which would dirty the file on open.
+            this.__shadow.setOpenedText(this.toLanguageClientUri(td.uri), td.text);
+         }
          this.refreshContent(uri, clientId);
       }
    }
 
+   /**
+    * Record `clientId` as an additional holder of a document another client
+    * already has open.
+    *
+    * Unlike the attach branch of {@link notifyDidOpenTextDocument} this does
+    * not refresh. That branch re-renders an attaching TEXTUAL view; a client
+    * reaching a document through a non-textual route has nothing to re-render,
+    * and refreshing per attach turns each into a Langium rebuild and dependent
+    * relink cascade.
+    *
+    * The staleness guard baselines at the SYNCED version, not a declared buffer
+    * version, because a client arriving this way holds no buffer of its own.
+    * 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,
+    * `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) {
+         return false;
+      }
+      const existingClients = this.__sessions.clientsOf(key);
+      this.__sessions.addOpen(key, clientId);
+      const record = this.trackingFor(key);
+      record.clientVersions.set(clientId, document.version);
+      this.logClientJoined(key, clientId, document.version, existingClients);
+      return true;
+   }
+
+   protected logClientJoined(uri: DocumentUri, clientId: string, version: number, existingClients: readonly string[]): void {
+      this.log(
+         uri,
+         `Attach client: ${this.formatClientId(clientId)} joined existing document (version ${version}, ` +
+            `now open in: ${[...existingClients, clientId].map(id => this.formatClientId(id)).join(', ')})`
+      );
+   }
+
    refreshContent(uri: DocumentUri, clientId: string): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(uri));
       if (syncedDocument) {
          // Trigger a (re-)build by firing a change event.
          const timer = this.startTimerForUri(
             syncedDocument.uri,
-            `Refresh synced document: Version ${syncedDocument.version} by ${clientId}`
+            `Refresh synced document: Version ${syncedDocument.version} by ${this.formatClientId(clientId)}`
          );
          this.__onDidChangeContent.fire(Object.freeze({ document: syncedDocument, clientId }));
          timer.dispose();
@@ -730,7 +1143,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * two URIs for one physical file (a symlink path and its real path) into a
     * single registration — dedup at the editor layer, not just in
     * `LangiumDocuments`. The URI the client opened under is preserved separately
-    * for egress addressing (see {@link DocumentTracking.languageClientUris}). The
+    * for egress addressing (see {@link DocumentTrackingRecord.languageClientUris}). The
     * policy is always bound (the framework defaults it to
     * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
     */
@@ -751,10 +1164,10 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    }
 
    /** Get-or-create the per-URI tracking record. `uri` must already be a {@link documentKey}. */
-   protected trackingFor(uri: CanonicalUri): DocumentTracking {
+   protected trackingFor(uri: CanonicalUri): DocumentTrackingRecord {
       let record = this.__documents.get(uri);
       if (!record) {
-         record = { clients: new Set(), versionAuthors: [], clientVersions: new Map() };
+         record = { versionAuthors: [], clientVersions: new Map() };
          this.__documents.set(uri, record);
       }
       return record;
@@ -790,7 +1203,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * `0` for a URI this store has never seen. The shared sequence is
     * server-owned and monotonic across close/reopen cycles, and advances
     * exactly when the synced content changes — which is what makes it a sound
-    * optimistic-concurrency token (`baseVersion` gates): version unchanged ⇔
+    * optimistic-concurrency token (based-on gates): version unchanged ⇔
     * content unchanged.
     */
    version(uri: DocumentUri): number {
@@ -832,6 +1245,59 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       return stepped.version;
    }
 
+   /**
+    * Commit an integrity repair into the OPEN document for `uri`, returning the
+    * document that now holds it, or `undefined` when there was nothing here to
+    * commit into.
+    *
+    * The one thing this exists to do is address the store BY URI. A repair
+    * reaches the resync as a text-document object, and that object is the
+    * store's own only on the LSP path; a document built for an already-open URI
+    * through `LangiumDocumentFactory.fromString` carries its own, so writing the
+    * repair into it corrects a copy the store does not know about and the editor
+    * never sees.
+    *
+    * `parsedFrom` is the text the repaired AST was parsed from, and a mismatch
+    * against the current content REFUSES the commit: the store has moved on,
+    * which means an editor change landed after that parse, and committing would
+    * overwrite a newer edit with a repair computed against text the user has
+    * already replaced. The build that change provokes recomputes the repair.
+    *
+    * Deliberately NOT compared by version. A separately created document seeds
+    * its own numbering, so requiring the two to agree would refuse every commit
+    * on the path this exists for. Content is the thing both sides can be held to.
+    *
+    * A changed text is a new version authored by {@link INTEGRITY_CLIENT_ID}.
+    * Kept at the old version, the repair is invisible to every reader keyed on
+    * versions: a write based on the unrepaired version passes the based-on gate
+    * and replaces the repair, and an echo filter credits the repair to the
+    * client whose edit it corrected. No change event is fired: the repair
+    * rides the build already under way, and an event would re-enter it.
+    */
+   commitRepair(uri: DocumentUri, parsedFrom: string, repaired: string): RepairCommit<T> {
+      const key = this.documentKey(uri);
+      const document = this.__syncedDocuments.get(key);
+      if (document === undefined) {
+         return { status: 'not-open' };
+      }
+      if (document.getText() !== parsedFrom) {
+         this.logUri(key, 'Refuse repair commit: the open document moved on from the text the AST was parsed from', 'debug');
+         return { status: 'stale' };
+      }
+      if (repaired === parsedFrom) {
+         return { status: 'committed', document };
+      }
+      // Reassigned rather than mutated in place: the default configuration
+      // updates and returns the SAME instance, but an adopter-supplied one may
+      // return a new object, and the store must end up holding whichever it is.
+      const updated = this.configuration.update(document, [{ text: repaired }], document.version + 1);
+      this.__syncedDocuments.set(key, updated);
+      this.setAuthor(key, updated.version, INTEGRITY_CLIENT_ID);
+      this.refreshDirty(key);
+      this.log(updated.uri, `Update to version ${updated.version} by ${this.formatClientId(INTEGRITY_CLIENT_ID)} (repair)`);
+      return { status: 'committed', document: updated };
+   }
+
    getAuthor(uri: DocumentUri, version?: number): string | undefined {
       const history = this.__documents.get(this.documentKey(uri))?.versionAuthors;
       // Either the requested version, or the latest. `version !== undefined` so we treat 0 correctly.
@@ -852,17 +1318,17 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * True iff any client still holds `uri` open. Distinct from {@link isOpen},
     * which reads `__syncedDocuments` — that map is cleared only AFTER the
     * `onDidClose` event fires for the last client, so `isOpen` returns `true`
-    * during the close event itself. `isOpenInAnyClient` reads the tracking
-    * record's `clients` set, which is updated BEFORE the fire, so an `onDidClose`
+    * during the close event itself. `isOpenInAnyClient` reads the open table
+    * ({@link __sessions}), which is updated BEFORE the fire, so an `onDidClose`
     * subscriber that finds this `false` knows the last client just closed and a
     * disk re-read / rebuild can proceed.
     */
    isOpenInAnyClient(uri: DocumentUri): boolean {
-      return (this.__documents.get(this.documentKey(uri))?.clients.size ?? 0) > 0;
+      return this.__sessions.isOpen(this.documentKey(uri));
    }
 
    isOpenInClient(uri: DocumentUri, client: string): boolean {
-      return !!this.__documents.get(this.documentKey(uri))?.clients.has(client);
+      return this.__sessions.isOpenIn(this.documentKey(uri), client);
    }
 
    isOpenInLanguageClient(uri: DocumentUri): boolean {
@@ -873,14 +1339,14 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    }
 
    isOnlyOpenInClient(uri: DocumentUri, client: string): boolean {
-      const key = this.documentKey(uri);
-      return this.__documents.get(key)?.clients.size === 1 && this.isOpenInClient(key, client);
+      const clients = this.__sessions.clientsOf(this.documentKey(uri));
+      return clients.length === 1 && clients[0] === client;
    }
 
    /**
     * Every document currently held open by at least one client, with the client
-    * ids holding it. Reads the same per-URI tracking records as
-    * {@link isOpenInAnyClient}, so it reflects a last-client close immediately.
+    * ids holding it. Reads the same open table as {@link isOpenInAnyClient}, so
+    * it reflects a last-client close immediately.
     *
     * Diagnostics-oriented — the server-state snapshot lists these so an operator
     * can see WHY a document is pinned: a document that lingers here after its
@@ -888,28 +1354,237 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * under a shedding policy, explains why its CST is never shed).
     */
    openDocuments(): OpenDocument[] {
-      const result: OpenDocument[] = [];
-      for (const [uri, tracking] of this.__documents) {
-         if (tracking.clients.size > 0) {
-            result.push({ uri, clients: [...tracking.clients] });
+      return this.__sessions.openDocuments();
+   }
+
+   /** Fires once a client session has ended, after every document it had open was closed. */
+   get onDidCloseSession(): Event<ClientSessionClosedEvent> {
+      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));
+   }
+
+   /**
+    * Whether the store holds `uri` with text that differs from its disk
+    * baseline: what the server last knew the file to hold. `false` for a URI
+    * the store does not hold; a document waiting out the revert grace is still
+    * held.
+    *
+    * The baseline is the text a first open brought, or what the server wrote,
+    * or read back after an editor's save or a watched-file change, so it can
+    * trail a change to the file that none of these has seen yet. A check that
+    * must know the file reads it instead.
+    */
+   isDirty(uri: DocumentUri): boolean {
+      return this.__documents.get(this.documentKey(uri))?.dirty ?? false;
+   }
+
+   /** Fires each time the answer of {@link isDirty} changes, the release of a dirty document included. */
+   get onDidChangeDirty(): Event<DocumentDirtyChangedEvent> {
+      return this.dirtyChangedEmitter.event;
+   }
+
+   /**
+    * Record that the file behind `uri` holds `text`, or no file at all for
+    * `undefined`. A no-op for a URI the store does not hold: the next first
+    * open sets the baseline from its own text.
+    */
+   updateDiskBaseline(uri: DocumentUri, text: string | undefined): void {
+      const key = this.documentKey(uri);
+      const record = this.__documents.get(key);
+      if (!record || !this.__syncedDocuments.has(key)) {
+         return;
+      }
+      record.diskBaseline = text;
+      this.refreshDirty(key);
+   }
+
+   /**
+    * Read the file behind `uri` through its disk queue and take it as the
+    * baseline. A file that cannot be read counts as none, the side that
+    * leaves the document dirty.
+    */
+   async reloadDiskBaseline(uri: DocumentUri): Promise<void> {
+      const key = this.documentKey(uri);
+      if (!this.__syncedDocuments.has(key)) {
+         return;
+      }
+      let onDisk: string | undefined;
+      try {
+         onDisk = await this.services.workspace.FileSystemTaskQueue.enqueue(key, () =>
+            this.services.workspace.FileSystemProvider.readFile(UriUtils.toUri(key))
+         );
+      } catch (err: unknown) {
+         this.tracer.with(key).debug(`Disk baseline: the file cannot be read. ${err instanceof Error ? err.message : String(err)}`);
+      }
+      this.updateDiskBaseline(key, onDisk);
+   }
+
+   /** Compare the held text of `uri` with its baseline, and announce a changed answer. */
+   protected refreshDirty(uri: CanonicalUri): void {
+      const record = this.__documents.get(uri);
+      const document = this.__syncedDocuments.get(uri);
+      if (!record || !document) {
+         return;
+      }
+      const dirty = document.getText() !== record.diskBaseline;
+      if (dirty !== (record.dirty ?? false)) {
+         record.dirty = dirty;
+         this.dirtyChangedEmitter.fire(Object.freeze({ uri, dirty }));
+      }
+   }
+
+   /**
+    * Start a client session under `clientId`. Throws where
+    * {@link ClientSessionRegistry.register} refuses the id.
+    */
+   registerSession(clientId: string): void {
+      this.__sessions.register(clientId);
+      this.tracer.info(`Session started: ${this.formatClientId(clientId)}`);
+      this.tracer.trace(`Session started: ${clientId}`);
+   }
+
+   /**
+    * 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, with `cause` as its cause. A no-op for an id that is not a
+    * registered session.
+    */
+   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, cause);
+         }
+      } finally {
+         this.__sessions.unregister(clientId);
+         this.tracer.info(`Session closed: ${this.formatClientId(clientId)}`);
+         this.tracer.trace(`Session closed: ${clientId}`);
+      }
+   }
+
+   /**
+    * Close every document the language client has open, as a `didClose` for
+    * each would, so each last close reverts. For a host whose editor connection
+    * can end while the process lives on, such as a worker whose port's peer
+    * closed: the language client is no session, so nothing else closes them.
+    *
+    * It first waits for the workspace initialization the open handler waits
+    * for, so an open that arrived before the close is closed too; closing at
+    * once would leave that open to land afterwards, held by a client that is
+    * gone.
+    */
+   async closeLanguageClientDocuments(): Promise<void> {
+      await this.services.workspace.WorkspaceManager.workspaceInitialized;
+      for (const uri of this.__sessions.opensOf(LANGUAGE_CLIENT_ID)) {
+         // Every spelling the client opened the file under, since the close
+         // below drops only the canonical one's.
+         const clientUris = this.__documents.get(uri)?.languageClientUris;
+         for (const clientUri of clientUris ?? []) {
+            this.invalidateLanguageClientText(clientUri);
+         }
+         clientUris?.clear();
+         this.notifyDidCloseTextDocument({ textDocument: { uri } });
+      }
+   }
+
+   /**
+    * The file behind `uri` was deleted: close every open of it except the
+    * language client's.
+    *
+    * The editor's open is left alone because the editor owns it: it keeps the
+    * buffer of a deleted file and goes on sending changes for it, and a store
+    * that had closed the document would drop every one of them until the editor
+    * reopened.
+    */
+   notifyDocumentDeleted(uri: DocumentUri): void {
+      const key = this.documentKey(uri);
+      for (const clientId of this.__sessions.clientsOf(key)) {
+         if (clientId !== LANGUAGE_CLIENT_ID) {
+            this.notifyDidCloseTextDocument({ textDocument: { uri: key } }, clientId);
          }
       }
-      return result;
    }
 
    /**
-    * Stages integrity-updated content for a closed document.
+    * Remove the document for `uri`, closing every open of it first — the
+    * editor's included, since the document it would keep editing is gone.
+    *
+    * The base removes the synced document without consulting the open table,
+    * which leaves every open recorded against a document that no longer exists:
+    * the store then answers that the URI is open, and the next open attaches to
+    * nothing.
+    */
+   override delete(uri: string | URI | T): void {
+      const key = this.documentKey((typeof uri === 'object' && 'uri' in uri ? uri.uri : uri).toString());
+      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);
+   }
+
+   /**
+    * A client id as log lines print it. An id containing `#` is cut eight
+    * characters after its last `#`, which leaves a minted `label#uuid` as the
+    * label and enough of the UUID to tell sessions apart; an id without `#`
+    * prints whole. The full id goes out at trace level wherever a session
+    * starts or ends.
+    */
+   protected formatClientId(clientId: string): string {
+      const separator = clientId.lastIndexOf('#');
+      return separator < 0 ? clientId : clientId.slice(0, separator + 9);
+   }
+
+   /**
+    * Stages integrity-updated content for a document no client holds.
     *
     * When `workspace/applyEdit` targets a closed file, the client opens it from
     * disk (stale) and sends `didOpen` before applying the edit. This staged
     * content is consumed by {@link notifyDidOpenTextDocument} to replace the
     * stale disk text, preventing a brief revert of the integrity update.
     *
-    * Not cleared on close: pending content is only staged for already-closed
-    * documents (the integrity service checks `isOpenInLanguageClient` first), so
-    * a close → stage → open cycle cannot occur. The only scenario where an
-    * entry lingers is if `workspace/applyEdit` fails and the file is never
-    * opened — the memory cost is one serialised string per URI.
+    * Only a FIRST open consumes it, so stage only for a URI no client holds
+    * ({@link isOpenInAnyClient} is `false`). A URI held only through another
+    * head is not closed: an editor attaching to it joins the existing entry and
+    * never reads the stage, and the last close discards the stage with the
+    * tracking record. An entry lingers only if `workspace/applyEdit` fails and
+    * the file is never opened — the memory cost is one serialised string per
+    * URI.
     */
    stagePendingContent(uri: DocumentUri, text: string): void {
       this.trackingFor(this.documentKey(uri)).pendingContent = text;
@@ -967,10 +1642,11 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       const targets: Iterable<LanguageClientUri> = recorded && recorded.size > 0 ? recorded : [this.toLanguageClientUri(uri)];
       let lastResult: ApplyWorkspaceEditResult | undefined;
       for (const targetUri of targets) {
-         // Read BEFORE computeEdits, which overwrites it. This is the text the
-         // edits below are keyed to, and therefore the only text the client's
-         // echo of them can be reconstructed against.
-         const before = this.__shadow.get(targetUri);
+         // Read BEFORE computeEdits, which overwrites the baseline and drops
+         // the opened snapshot. This is the text the client holds, and
+         // therefore the only text its echo of this push can be reconstructed
+         // against — whether or not the push below is keyed to it.
+         const before = this.__shadow.clientText(targetUri);
          const edits = this.__shadow.computeEdits(targetUri, newText);
          if (edits.length === 0) {
             continue;
@@ -985,9 +1661,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // it is exactly what the caller retries with after a rejection, so
             // gating it there would refuse the recovery too.
             const version = isFullReplace(edits) ? UNKNOWN_CLIENT_VERSION : this.languageClientVersion(uri);
+            // A full `ApplyWorkspaceEditParams`, `edit` and all — NOT a bare
+            // `WorkspaceEdit` with a `label` beside it. `applyEdit` takes
+            // `ApplyWorkspaceEditParams | WorkspaceEdit` and discriminates on
+            // `!!value.edit`, so `{ label, documentChanges }` is wrapped as
+            // `{ edit: { label, documentChanges } }` — putting the label inside
+            // the edit, where LSP defines no such field and no client reads it.
+            // The union is also what hides it at compile time: excess-property
+            // checking admits a property present in EITHER member, so an object
+            // matching neither type-checks against the union.
             const result = await connection.workspace.applyEdit({
                label: options?.label,
-               documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               edit: {
+                  documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               }
             });
             if (result && result.applied === false) {
                this.__shadow.invalidate(targetUri);
@@ -1043,12 +1730,17 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
 
    /**
     * Decide what an incoming language-client change actually is, by
-    * reconstructing the client's resulting buffer against the OLDEST push still
-    * in flight for `clientFacing`.
+    * reconstructing the client's resulting buffer against the text its ranges
+    * address — the pre-push buffer of the OLDEST push still in flight for
+    * `clientFacing`, else whatever that client is believed to hold.
     *
-    * `undefined` when nothing of ours is in flight, which is the ordinary path:
-    * the client's ranges then address the synced text and the caller applies
-    * them to it directly.
+    * `undefined` when the client's ranges address the synced text itself —
+    * nothing in flight, and no evidence the client holds anything else. That
+    * is the ordinary path, and the caller then applies the ranges directly.
+    * The two texts part company without a push in flight whenever a client
+    * attaches to a document another client has already written: it opened
+    * from disk, so applying its ranges to the synced text splices lines they
+    * never addressed.
     *
     * **Why the oldest, and why reconstruct at all.** The client applies our
     * pushes in order and echoes each against the buffer it held before that
@@ -1079,22 +1771,41 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       document: T,
       changes: TextDocumentContentChangeEvent[]
    ): LanguageClientChangeOrigin | undefined {
-      const pending = this.__pendingPushes.get(clientFacing);
-      if (pending === undefined || pending.length === 0) {
+      const queued = this.__pendingPushes.get(clientFacing);
+      const pending = queued?.length ? queued : undefined;
+      // The text the client's ranges address: the buffer it held before the
+      // oldest push still in flight, else the buffer it is believed to hold.
+      const clientText = pending?.[0].before ?? this.__shadow.clientText(clientFacing);
+      if (pending === undefined && (clientText === undefined || clientText === document.getText())) {
          return undefined;
       }
+      if (pending !== undefined && pending[0].before === undefined && changes.some(change => ContentChange.isIncremental(change))) {
+         // A push sent to a client whose buffer was unknown — a first sync, or
+         // the recovery push after a rejection. The shadow now holds the text
+         // that push MOVES the client to, which is the one text the echo's
+         // ranges provably do not address, so the fallback above is a baseline
+         // known to be wrong rather than merely unverified. Drop the queue and
+         // the shadow: the next sync is then a full replace, which lands on
+         // whatever the client holds. A full-text change is exempt because it
+         // reconstructs identically against any baseline.
+         pending.length = 0;
+         this.__shadow.invalidate(clientFacing);
+         return { kind: 'unreconstructable' };
+      }
       // Through the configured factories, not `TextDocument` directly, so an
       // adopter's custom text-document type governs how the ranges are applied
       // here exactly as it does on the synced document.
-      const probe = this.create(clientFacing, document.languageId, 0, pending[0].before ?? document.getText());
-      const clientText = this.update(probe, changes, 0).getText();
-      const matchIndex = pending.findIndex(push => push.afterHash === contentHash(clientText));
-      if (matchIndex >= 0) {
-         pending.splice(0, matchIndex + 1);
-         return { kind: 'echo' };
+      const probe = this.create(clientFacing, document.languageId, 0, clientText ?? document.getText());
+      const reconstructed = this.update(probe, changes, 0).getText();
+      if (pending !== undefined) {
+         const matchIndex = pending.findIndex(push => push.afterHash === contentHash(reconstructed));
+         if (matchIndex >= 0) {
+            pending.splice(0, matchIndex + 1);
+            return { kind: 'echo' };
+         }
+         pending.length = 0;
       }
-      pending.length = 0;
-      return { kind: 'divergent', text: clientText };
+      return { kind: 'divergent', text: reconstructed };
    }
 
    /**