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

package/lib/documents/hydranium-text-documents.js

@@ -18,11 +18,15 @@
 // 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 { OptionalVersionedTextDocumentIdentifier, TextDocumentEdit, TextDocumentSyncKind } from 'vscode-languageserver';
+import { URI, UriUtils } from '@hydranium/langium';
+import { Emitter, OptionalVersionedTextDocumentIdentifier, TextDocumentContentChangeEvent as ContentChange, TextDocumentEdit, TextDocumentSyncKind } from 'vscode-languageserver';
 import { TextDocument } from 'vscode-languageserver-textdocument';
 import { asLanguageClientUri, DisposableCollection } from '@hydranium/protocol';
+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 { ClientSessionRegistry } from './client-session-registry.js';
 import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
 /**
  * The LSP spec's "version is intentionally unknown" for an
@@ -32,6 +36,12 @@ import { isFullReplace, LanguageClientTextShadow } from './language-client-text-
  * cast at each call site.
  */
 const UNKNOWN_CLIENT_VERSION = null;
+/**
+ * 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;
 /**
  * Upper bound on {@link HydraniumTextDocuments.__pendingPushes} entries
  * per URI. Echoes normally return within milliseconds and consume their
@@ -39,6 +49,17 @@ const UNKNOWN_CLIENT_VERSION = null;
  * of leaking.
  */
 const PENDING_ECHO_CAP = 32;
+/**
+ * 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, target) {
+    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
@@ -65,15 +86,19 @@ function contentHash(text) {
  * 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.
  *   - 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
@@ -84,22 +109,26 @@ function contentHash(text) {
 export class HydraniumTextDocuments extends NormalizedTextDocuments {
     services;
     /**
-     * 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}.
      */
     __documents = new Map();
+    /**
+     * 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.
+     */
+    __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.
@@ -111,7 +140,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     /**
      * 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.
@@ -156,6 +185,10 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     __shadow;
     tracer;
     configuration;
+    /** See {@link HydraniumTextDocumentsOptions.revertGraceMs}. */
+    revertGraceMs;
+    lastOpenClosedEmitter = new Emitter();
+    languageClientSavedEmitter = new Emitter();
     constructor(services, options = {}) {
         const configuration = options.configuration ?? TextDocument;
         super(configuration);
@@ -163,6 +196,8 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         this.configuration = configuration;
         this.tracer = services.Tracer.for(options.logName ?? 'TextDocuments').trace('instantiated');
         this.__shadow = new LanguageClientTextShadow((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
     // (LanguageClientTextShadow's apply-verify probe; IntegrityService.resyncDocument)
@@ -235,7 +270,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         }));
         disposables.push(connection.onWillSaveTextDocumentWaitUntil((event, token) => this.notifyWillSaveTextDocumentWaitUntil(event, token)));
         disposables.push(connection.onDidSaveTextDocument((event) => {
-            this.notifyDidSaveTextDocument(event);
+            void this.notifyLanguageClientSave(event);
         }));
         return disposables;
     }
@@ -267,18 +302,19 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
                 // Distinguish "already at this version" (common: an echo from the client that triggered
                 // 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 = clientId === LANGUAGE_CLIENT_ID
+            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
@@ -290,18 +326,22 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
                 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);
@@ -325,7 +365,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
                     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 }));
         }
     }
@@ -341,7 +381,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * 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.
@@ -358,51 +398,183 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
             this.__syncedDocuments.set(key, document);
             this.setAuthor(key, document.version, clientId);
         }
-        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;
     }
-    notifyDidCloseTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
+    /**
+     * 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}.
+     */
+    notifyDidCloseTextDocument(event, clientId = LANGUAGE_CLIENT_ID, cause = 'closed') {
         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.
+     */
+    deferRelease(uri) {
+        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.
+     */
+    resolvePendingRevert(uri, clientId) {
+        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. */
+    pruneLostClients(record) {
+        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.
+     */
+    releaseDocument(uri) {
+        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.
+     */
+    async revertToDisk(uri) {
+        if (URI.parse(uri).scheme !== 'file') {
+            return;
+        }
+        const workspace = this.services.workspace;
+        const target = UriUtils.toUri(uri);
+        const reopened = () => 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) {
+                    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) {
+            // 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}`);
         }
     }
     notifyWillSaveTextDocument(event) {
@@ -420,39 +592,91 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
             return [];
         }
     }
+    /**
+     * 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.
+     */
+    async notifyLanguageClientSave(event) {
+        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;
+        try {
+            onDisk = await this.services.workspace.FileSystemTaskQueue.enqueue(uri, () => this.services.workspace.FileSystemProvider.readFile(UriUtils.toUri(uri)));
+        }
+        catch (err) {
+            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);
+    }
     notifyDidSaveTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
         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 }));
+            this.announceSave(syncedDocument, clientId);
         }
     }
+    /** Fire {@link onDidSave} for `document`, which need not be synced any more. */
+    announceSave(document, clientId) {
+        this.log(document.uri, `Saved synced document: ${document.version} by ${this.formatClientId(clientId)}`);
+        this.__onDidSave.fire(Object.freeze({ document, clientId }));
+    }
     notifyDidOpenTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
         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()).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);
@@ -468,13 +692,13 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
             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);
@@ -482,7 +706,18 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
                 // 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);
@@ -490,16 +725,64 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         }
         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, clientId) {
+        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;
+    }
+    logClientJoined(uri, clientId, version, existingClients) {
+        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, clientId) {
         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}`);
+            const timer = this.startTimerForUri(syncedDocument.uri, `Refresh synced document: Version ${syncedDocument.version} by ${this.formatClientId(clientId)}`);
             this.__onDidChangeContent.fire(Object.freeze({ document: syncedDocument, clientId }));
             timer.dispose();
         }
@@ -511,7 +794,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * 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).
      */
@@ -533,7 +816,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     trackingFor(uri) {
         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;
@@ -566,7 +849,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * `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) {
@@ -606,6 +889,57 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         this.logUri(key, `External content change while closed: sequence stepped to version ${stepped.version}`, 'debug');
         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, parsedFrom, repaired) {
+        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.log(updated.uri, `Update to version ${updated.version} by ${this.formatClientId(INTEGRITY_CLIENT_ID)} (repair)`);
+        return { status: 'committed', document: updated };
+    }
     getAuthor(uri, version) {
         const history = this.__documents.get(this.documentKey(uri))?.versionAuthors;
         // Either the requested version, or the latest. `version !== undefined` so we treat 0 correctly.
@@ -624,16 +958,16 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * 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) {
-        return (this.__documents.get(this.documentKey(uri))?.clients.size ?? 0) > 0;
+        return this.__sessions.isOpen(this.documentKey(uri));
     }
     isOpenInClient(uri, client) {
-        return !!this.__documents.get(this.documentKey(uri))?.clients.has(client);
+        return this.__sessions.isOpenIn(this.documentKey(uri), client);
     }
     isOpenInLanguageClient(uri) {
         // Takes any URI form (canonicalizes internally via `documentKey`, like
@@ -642,13 +976,13 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         return this.isOpenInClient(uri, LANGUAGE_CLIENT_ID);
     }
     isOnlyOpenInClient(uri, client) {
-        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
@@ -656,27 +990,133 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * under a shedding policy, explains why its CST is never shed).
      */
     openDocuments() {
-        const result = [];
-        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() {
+        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() {
+        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() {
+        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) {
+        return this.__sessions.isRevertPending(this.documentKey(uri));
+    }
+    /**
+     * Start a client session under `clientId`. Throws `DuplicateClientIdError`
+     * where {@link ClientSessionRegistry.register} refuses the id.
+     */
+    registerSession(clientId) {
+        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, cause = 'closed') {
+        if (!this.__sessions.isRegistered(clientId)) {
+            return;
+        }
+        try {
+            for (const uri of this.__sessions.beginClose(clientId)) {
+                this.notifyDidCloseTextDocument({ textDocument: { uri } }, clientId, cause);
             }
         }
-        return result;
+        finally {
+            this.__sessions.unregister(clientId);
+            this.tracer.info(`Session closed: ${this.formatClientId(clientId)}`);
+            this.tracer.trace(`Session closed: ${clientId}`);
+        }
     }
     /**
-     * Stages integrity-updated content for a closed document.
+     * 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) {
+        const key = this.documentKey(uri);
+        for (const clientId of this.__sessions.clientsOf(key)) {
+            if (clientId !== LANGUAGE_CLIENT_ID) {
+                this.notifyDidCloseTextDocument({ textDocument: { uri: key } }, clientId);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    delete(uri) {
+        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.
+     */
+    formatClientId(clientId) {
+        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, text) {
         this.trackingFor(this.documentKey(uri)).pendingContent = text;
@@ -729,10 +1169,11 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         const targets = recorded && recorded.size > 0 ? recorded : [this.toLanguageClientUri(uri)];
         let lastResult;
         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;
@@ -747,9 +1188,20 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
                 // 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);
@@ -803,12 +1255,17 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     }
     /**
      * 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
@@ -835,22 +1292,41 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * queue, so undo revisits PAST states while the queue holds IN-FLIGHT ones.
      */
     classifyLanguageClientChange(clientFacing, document, changes) {
-        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' };
-        }
-        pending.length = 0;
-        return { kind: 'divergent', text: clientText };
+        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;
+        }
+        return { kind: 'divergent', text: reconstructed };
     }
     /**
      * Explicitly baseline the language-client text shadow for a URI. Useful in