@hydranium/core 1.0.0-next.38 → 1.0.0-next.380

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

@@ -19,11 +19,17 @@
 // 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 { Emitter, OptionalVersionedTextDocumentIdentifier, TextDocumentEdit, TextDocumentSyncKind } from 'vscode-languageserver';
 import { TextDocument } from 'vscode-languageserver-textdocument';
-import { asLanguageClientUri, DisposableCollection } from '@hydranium/protocol';
+import { asLanguageClientUri, asModelVersion, ConflictError, DisposableCollection, DocumentNotOpenError, STALE_BASE_VERSION_SAVE, STALE_VERSION, UNRECORDED_VERSION, describeError, describeErrorWithStack } from '@hydranium/protocol';
 import { LANGUAGE_CLIENT_ID } from './client-ids.js';
-import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
+import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
+import { ClientSessionRegistry } from './client-session-registry.js';
+import { DefaultLanguageClientShadow } from './language-client-shadow.js';
+import { DefaultTextLedger } from './text-ledger.js';
+import { isDocumentReleaseSkippedError } from './document-release-handler.js';
+import { DefaultDocumentReleaseScheduler } from './document-release-scheduler.js';
+import { DefaultDirtyStateTracker } from './dirty-state-tracker.js';
 /**
  * The LSP spec's "version is intentionally unknown" for an
  * {@link OptionalVersionedTextDocumentIdentifier} is `null`, but
@@ -33,141 +39,124 @@ import { isFullReplace, LanguageClientTextShadow } from './language-client-text-
  */
 const UNKNOWN_CLIENT_VERSION = null;
 /**
- * Upper bound on {@link HydraniumTextDocuments.__pendingPushes} entries
- * per URI. Echoes normally return within milliseconds and consume their
- * entry; a queue this deep means the client stopped echoing — cap instead
- * of leaking.
+ * The default of {@link HydraniumTextDocumentsOptions.releaseGraceMs}: 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 PENDING_ECHO_CAP = 32;
+const DEFAULT_RELEASE_GRACE_MS = 10_000;
 /**
- * Cheap, stable, non-cryptographic content hash (cyrb53) for the version
- * sequence's "did the content change across close/reopen?" question. Only
- * needs to be collision-resistant enough that an accidental match across two
- * DIFFERENT revisions of the same file is practically impossible; 53 bits of
- * a well-mixed hash over full text + length gives that without pulling in
- * `node:crypto` (this module must stay runnable in browser hosts).
- */
-function contentHash(text) {
-    let h1 = 0xdeadbeef;
-    let h2 = 0x41c6ce57;
-    for (let index = 0; index < text.length; index++) {
-        const code = text.charCodeAt(index);
-        h1 = Math.imul(h1 ^ code, 2654435761);
-        h2 = Math.imul(h2 ^ code, 1597334677);
-    }
-    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
-    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
-    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
-    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
-    return `${(4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36)}:${text.length}`;
-}
-/**
- * Multi-client text-document tracking on top of Langium's `NormalizedTextDocuments`.
+ * The one text store every head writes to, on top of Langium's
+ * `NormalizedTextDocuments`, and the LSP text-sync endpoint: every
+ * `textDocument/*` notification and every `workspace/applyEdit` push goes
+ * through here.
+ *
+ * Each open, change, close and save is one synchronous transition over the
+ * held document and the collaborators its `create…` methods build. A
+ * collaborator that defers its part lets a listener of the transition's event
+ * read state from before it. A document no client holds any more is
+ * released to the `DocumentReleaseHandler` slot, after
+ * {@link HydraniumTextDocumentsOptions.releaseGraceMs} when its last client's
+ * connection was lost.
  *
- * 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).
- *   - 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.
- *   - Version-author history so each edit is attributable to its originating client.
- *   - 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
- *     workspace-ready promise, so a client's first open cannot race workspace
- *     discovery. Direct {@link notifyDidOpenTextDocument} calls (the non-LSP
- *     heads) do not pass that gate — their caller owns the ordering.
+ * Client-declared version ids feed only the per-client staleness guard and
+ * never a running shared sequence: the two count different things, and
+ * splicing them lets versions drift past base-version gate holders. A URI
+ * with no ledger record and no built root starts at its opener's declared id:
+ * no version was handed out for it.
+ *
+ * `didOpen` notifications arriving over the LSP connection wait on the
+ * workspace-ready promise, so a client's first open cannot race workspace
+ * discovery. Direct {@link notifyDidOpenTextDocument} calls (the non-LSP
+ * heads) do not pass that gate — their caller owns the ordering.
  */
 export class HydraniumTextDocuments extends NormalizedTextDocuments {
     services;
+    options;
+    /** Content staged by integrity rules for a document no client holds, consumed by its first open. */
+    __pendingContent = new Map();
     /**
-     * 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`.
-     */
-    __documents = new Map();
-    /**
-     * 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}:
-     * 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
-     * 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.
-     *
-     * Never pruned: two small values per URI ever touched — bounded by
-     * workspace size, not by activity.
-     */
-    __versionSequences = new Map();
-    /**
-     * 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.
-     * Outbound pushes and inbound echoes are uncorrelated on the wire; this
-     * FIFO is the explicit correlation, and it is what
-     * {@link classifyLanguageClientChange} reconstructs against.
-     *
-     * **Each entry keeps the client's PRE-push text, not only a hash of the
-     * post-push one.** A hash alone can classify a full-text echo, whose
-     * application is a no-op either way — and that is all it ever classified,
-     * because a conforming client echoes INCREMENTAL ranges keyed to its
-     * previous buffer. Those ranges cannot be applied to the synced text (which
-     * the authored write already advanced) and cannot be reconstructed without
-     * the baseline: the line they insert lands twice, validates cleanly, and
-     * compounds on every later edit.
-     *
-     * Lifecycle: entries are consumed by the matching echo (together with any
-     * older entries it supersedes), and the whole queue drops when the client
-     * stops being a pure mirror — a divergent change, an `applyEdit`
-     * failure/rejection (shadow invalidation), a close, or an explicit
-     * shadow (re)baseline. {@link PENDING_ECHO_CAP} bounds the queue against
-     * a pathological echo that never arrives; the memory cost until then is
-     * one pre-push text per in-flight push, for milliseconds.
-     */
-    __pendingPushes = new Map();
-    /**
-     * Tracked text content per URI for the LSP textual language client (Monaco / VS Code).
-     * Owned here so {@link applyEditToLanguageClient} can compute minimal `workspace/applyEdit`
-     * diffs instead of full-document replaces (5–20 s → <500 ms on 20-30 KB YAML diagrams).
-     *
-     * Auto-tracked from the multi-client text-document events: open / change / close of
-     * the language client (re)baseline or invalidate the shadow. Other client ids
-     * (form editor, GLSP, integrity) do NOT touch the shadow — only what Monaco believes
-     * it has matters for the diff.
-     *
-     * Apply-verify safety net is built in: if the diff doesn't reconstruct `newText`
-     * exactly, {@link LanguageClientTextShadow.computeEdits} falls back to a full-range
-     * replace and invokes the `onFallback` callback — a diff regression becomes log
-     * noise, not a 0-byte save.
-     *
-     * Assigned in the constructor body so the `onFallback` callback can capture
-     * `this.logger` after the parameter-property assignment has run (field
-     * initializers fire BEFORE parameter-property assignment in TS).
+     * Which client has which document open, which client ids are registered
+     * sessions, and each client's declared version, the staleness guard's
+     * baseline. Every open-state predicate on this class reads it, so an open
+     * recorded anywhere else is invisible to the last-close transition.
      */
-    __shadow;
+    __sessions = new ClientSessionRegistry();
+    /** The version each open document was opened at; see {@link openedVersion}. */
+    __openedVersions = new Map();
     tracer;
     configuration;
+    __textLedger;
+    __languageClientShadow;
+    __dirtyStateTracker;
+    __documentReleaseScheduler;
+    documentReleasedEmitter = new Emitter();
+    languageClientSavedEmitter = new Emitter();
     constructor(services, options = {}) {
         const configuration = options.configuration ?? TextDocument;
         super(configuration);
         this.services = services;
+        this.options = options;
         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);
     }
-    // Re-exposed configuration factories — for framework-internal callers
-    // (LanguageClientTextShadow's apply-verify probe; IntegrityService.resyncDocument)
-    // that need to materialise documents outside the canonical didOpen/didChange flow
-    // and must respect the adopter's custom text-document type.
+    // Each collaborator is built on first use, after every constructor has run,
+    // so a create method may read its subclass's fields and the other collaborators.
+    get textLedger() {
+        return (this.__textLedger ??= this.createTextLedger());
+    }
+    get languageClientShadow() {
+        return (this.__languageClientShadow ??= this.createLanguageClientShadow());
+    }
+    get dirtyStateTracker() {
+        return (this.__dirtyStateTracker ??= this.createDirtyStateTracker());
+    }
+    get documentReleaseScheduler() {
+        return (this.__documentReleaseScheduler ??= this.createDocumentReleaseScheduler());
+    }
+    createTextLedger() {
+        return new DefaultTextLedger();
+    }
+    createLanguageClientShadow() {
+        return new DefaultLanguageClientShadow(this, this.tracer);
+    }
+    createDirtyStateTracker() {
+        return new DefaultDirtyStateTracker(this.textLedger);
+    }
+    createDocumentReleaseScheduler() {
+        return new DefaultDocumentReleaseScheduler(this.services.Clock, this.options.releaseGraceMs ?? DEFAULT_RELEASE_GRACE_MS);
+    }
+    /** Hold `document` as the text of `key`, a new version authored by `author`. */
+    commitText(key, document, author) {
+        this.__syncedDocuments.set(key, document);
+        this.setAuthor(key, document.version, author);
+        this.dirtyStateTracker.refreshDirty(key, document);
+    }
+    /**
+     * Apply `changes` to `document`, the held text of `key`, and hold the
+     * result. The version steps only when the text changes, which is what a
+     * base-version gate relies on: unchanged text keeps its version and its
+     * author. The new text is known only once the changes are applied, so they
+     * go in at a tentative step that an identical result rolls back.
+     */
+    commitChange(key, document, changes, author) {
+        const previousText = document.getText();
+        const version = document.version;
+        let next = this.update(document, changes, version + 1);
+        const changed = next.getText() !== previousText;
+        if (changed) {
+            this.commitText(key, next, author);
+        }
+        else {
+            // An empty-changes update only re-stamps the version.
+            next = this.update(next, [], version);
+            this.__syncedDocuments.set(key, next);
+        }
+        return { document: next, changed };
+    }
+    // The configuration's factories. Every document the store makes or changes
+    // goes through them, so an override sees each call: the store's own writes,
+    // callers outside the didOpen/didChange flow, and the shadow's throwaway
+    // probes, at version 0 under a client URI.
     create(uri, languageId, version, content) {
         return this.configuration.create(uri, languageId, version, content);
     }
@@ -221,7 +210,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         connection.__textDocumentSync = TextDocumentSyncKind.Incremental;
         const disposables = new DisposableCollection();
         disposables.push(connection.onDidOpenTextDocument(async (event) => {
-            await this.services.workspace.WorkspaceManager.workspaceInitialized;
+            await this.initialBuildFinished();
             this.notifyDidOpenTextDocument(event);
         }));
         disposables.push(connection.onDidChangeTextDocument((event) => {
@@ -235,7 +224,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;
     }
@@ -252,80 +241,58 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         const uri = this.documentKey(td.uri);
         let document = this.__syncedDocuments.get(uri);
         if (document !== undefined) {
-            // Per-client staleness guard: client version ids are CLIENT-owned per
-            // LSP (Monaco numbers its own buffer), so an incoming id is compared
-            // against THAT client's last declared id — never against the shared
-            // version, which the server assigns and which routinely runs ahead of
-            // a client's ids (authored ModelService writes advance it without the
-            // client knowing). Gating on the shared version drops real edits in
-            // exactly that lag window. A client with no baseline (never opened —
-            // a protocol anomaly) falls back to the shared-version compare, the
-            // conservative answer.
-            const record = this.trackingFor(uri);
-            const lastSeen = record.clientVersions.get(clientId) ?? document.version;
+            // Client version ids are the client's own, so compared against what
+            // that client declared, never against the shared version: an authored
+            // write advances that without the client knowing, and gating on it
+            // drops real edits. The editor is checked per URI, since each is its
+            // own buffer; its client-wide entry is only the fallback for a URI it
+            // never opened, and may name another URI's buffer. A client with no
+            // baseline falls back to the shared version.
+            const clientUri = this.toLanguageClientUri(td.uri);
+            const editor = clientId === LANGUAGE_CLIENT_ID;
+            const lastSeen = (editor ? this.languageClientShadow.declaredVersion(uri, clientUri) : undefined) ??
+                this.__sessions.clientVersionOf(uri, clientId) ??
+                document.version;
             if (lastSeen >= td.version) {
                 // 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.
-            // Resolve which it is, and against what, before touching anything.
-            const inFlight = clientId === LANGUAGE_CLIENT_ID
-                ? this.classifyLanguageClientChange(this.toLanguageClientUri(td.uri), document, changes)
-                : undefined;
-            if (inFlight?.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
-                // per-client baseline advanced above (the client's ids keep
-                // counting); the shadow is deliberately NOT touched — it
-                // optimistically tracks the NEWEST pushed text, and dragging it
-                // back would make the next outbound diff wrong against what the
-                // client actually holds.
+            this.__sessions.setClientVersion(uri, clientId, td.version);
+            // An editor change is keyed to the buffer the editor holds, which is
+            // the synced text only while the two agree — an authored write
+            // advances the synced text without the editor knowing, and a push in
+            // flight moves the editor without the store knowing.
+            const verdict = editor
+                ? this.languageClientShadow.acceptChange(uri, clientUri, td.version, document, changes)
+                : { kind: 'direct' };
+            if (verdict.kind === 'echo') {
+                // The synced document is already there, so the changes must not be
+                // applied a second time: nothing is minted and no rebuild fires. The
+                // shadow keeps the newest pushed text, which is what the next
+                // outbound diff has to be keyed to.
                 this.logUri(uri, `Skip rebuild: echo of a server-authored push (client version ${td.version})`, 'debug');
                 return;
             }
-            // The SHARED version advances iff the content actually changes — the
-            // invariant optimistic `baseVersion` 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.
-            const previousText = document.getText();
-            const sharedVersion = document.version;
-            document = this.configuration.update(document, inFlight === undefined ? changes : [{ text: inFlight.text }], sharedVersion + 1);
-            const changed = document.getText() !== previousText;
-            if (!changed) {
-                document = this.configuration.update(document, [], sharedVersion);
-            }
-            this.__syncedDocuments.set(uri, document);
-            if (changed) {
-                this.setAuthor(uri, document.version, clientId);
-            }
-            if (clientId === LANGUAGE_CLIENT_ID) {
-                // Monaco just told us about its new content; record it so the next outbound
-                // applyEditToLanguageClient diffs against the right baseline. Keyed by the
-                // language-client URI (what Monaco holds), not the canonical document key.
-                this.__shadow.set(this.toLanguageClientUri(td.uri), document.getText());
-                // Content-identical echo: the language client is echoing text we already had
-                // (e.g. Monaco re-emitting a server-pushed applyEditToLanguageClient). The model is
-                // unchanged, so skip the rebuild. The per-client baseline + shadow still advanced
-                // above so future staleness checks and diffs are correct. Restricted to the
-                // language client: a ModelService-authored change is never skipped.
-                if (!changed) {
+            // A divergent change is applied as its reconstructed text rather than
+            // as its own ranges: those ranges address the editor's own buffer, so
+            // applying them here would splice the wrong lines.
+            const committed = this.commitChange(uri, document, verdict.kind === 'direct' ? changes : [{ text: verdict.text }], clientId);
+            document = committed.document;
+            if (editor) {
+                this.languageClientShadow.setLanguageClientText(clientUri, document.getText(), document.version);
+                // Content-identical echo: the editor is echoing text we already had.
+                // The model is unchanged, so skip the rebuild. Restricted to the
+                // editor: a ModelService-authored change is never skipped.
+                if (!committed.changed) {
                     this.logUri(uri, `Skip rebuild: content unchanged (echo at client version ${td.version})`, 'debug');
                     return;
                 }
             }
-            this.log(document.uri, `Update to version ${document.version} by ${clientId}${changed ? '' : ' (content unchanged)'}`);
+            // Diagnosis: one comes with every keystroke.
+            this.logUri(document.uri, `Update to version ${document.version} by ${this.formatClientId(clientId)}${committed.changed ? '' : ' (content unchanged)'}`, 'debug');
             this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
         }
     }
@@ -341,69 +308,174 @@ 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.
+     * base versions stay valid.
      *
      * Returns the resulting shared version. Throws when the document is not
      * open — callers (`AstDocumentManager.update`) open first.
      */
     applyContentChange(uri, text, clientId) {
         const key = this.documentKey(uri);
-        let document = this.__syncedDocuments.get(key);
-        if (document === undefined) {
+        const synced = this.__syncedDocuments.get(key);
+        if (synced === undefined) {
             throw new Error(`Document ${uri} is not open for content changes`);
         }
-        const changed = document.getText() !== text;
-        if (changed) {
-            document = this.configuration.update(document, [{ text }], document.version + 1);
-            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)'}`);
+        // Unchanged text calls no update: a configuration may return a new document for one.
+        const { document, changed } = synced.getText() === text ? { document: synced, changed: false } : this.commitChange(key, synced, [{ text }], clientId);
+        this.logUri(document.uri, `Update to version ${document.version} by ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`, 'debug');
         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, at once or, for a `'lost'`
+     * close, after {@link HydraniumTextDocumentsOptions.releaseGraceMs}.
+     */
+    notifyDidCloseTextDocument(event, clientId = LANGUAGE_CLIENT_ID, cause = 'closed') {
         const uri = this.documentKey(event.textDocument.uri);
-        if (!this.isOpenInClient(uri, clientId)) {
+        if (clientId === LANGUAGE_CLIENT_ID) {
+            const clientUri = this.toLanguageClientUri(event.textDocument.uri);
+            // A close under a URI the editor never opened the document under ends its hold.
+            if (this.languageClientShadow.isOpen(uri, clientUri)) {
+                this.languageClientShadow.removeOpen(uri, clientUri);
+            }
+            else {
+                this.languageClientShadow.removeAllOpens(uri);
+            }
+            // Another URI still holds the document, so only this one's buffer goes.
+            if (this.languageClientShadow.isOpen(uri)) {
+                return;
+            }
+        }
+        if (!this.__sessions.removeOpen(uri, clientId)) {
             return;
         }
-        const closingRecord = this.__documents.get(uri);
-        closingRecord?.clients.delete(clientId);
-        closingRecord?.clientVersions.delete(clientId);
+        if (cause === 'lost') {
+            this.documentReleaseScheduler.recordLoss(uri, clientId);
+        }
         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.)
-                const droppedUri = this.toLanguageClientUri(event.textDocument.uri);
-                this.__documents.get(uri)?.languageClientUris?.delete(droppedUri);
-                this.__shadow.invalidate(droppedUri);
-                this.__pendingPushes.delete(droppedUri);
+            if (!this.isOpenInAnyClient(uri)) {
+                if (cause === 'lost') {
+                    this.deferRelease(uri);
+                }
+                else {
+                    this.releaseDocument(uri);
+                }
             }
-            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);
+        }
+    }
+    /**
+     * Keep the document, text and all, for the release 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 resolveDeferredRelease} for any other
+     * open.
+     */
+    deferRelease(uri) {
+        this.documentReleaseScheduler.defer(uri, () => {
+            if (!this.isOpenInAnyClient(uri)) {
+                this.releaseDocument(uri);
             }
+        });
+        if (this.documentReleaseScheduler.isDeferred(uri)) {
+            this.log(uri, `No client left; release deferred for ${this.documentReleaseScheduler.graceMs} ms (connection lost)`);
+        }
+    }
+    /** Resolve a deferred release of `uri` for an open by `clientId`: a release the scheduler decides on runs now. */
+    resolveDeferredRelease(uri, clientId) {
+        if (this.documentReleaseScheduler.resolveOpen(uri, clientId) === 'release') {
+            this.releaseDocument(uri);
+        }
+    }
+    /** Release now a document waiting out the grace, as its last close would have; one that is not waiting is left alone. */
+    releaseIfDeferred(uri) {
+        if (this.documentReleaseScheduler.isDeferred(uri)) {
+            this.documentReleaseScheduler.cancel(uri);
+            this.releaseDocument(uri);
+        }
+    }
+    /**
+     * Drop the document no client has open any more, announce it on
+     * {@link onDidReleaseDocument}, then hand it to the
+     * `DocumentReleaseHandler` slot: its listeners, such as the update
+     * handler dropping a change it still holds back, act before any build the
+     * handler runs.
+     */
+    releaseDocument(uri) {
+        const syncedDocument = this.__syncedDocuments.get(uri);
+        if (syncedDocument === undefined) {
+            return;
+        }
+        this.log(syncedDocument.uri, `Remove synced document: ${syncedDocument.version} (no client left)`);
+        // The next open continues the sequence instead of restarting at the
+        // reopening client's declared id.
+        this.textLedger.record(uri, syncedDocument);
+        this.textLedger.clearAuthors(uri);
+        // Before the tracker's release, which forgets whether a file was behind it.
+        const released = this.toReleasedDocument(uri);
+        const cleanAnnouncement = this.dirtyStateTracker.release(uri);
+        this.__syncedDocuments.delete(uri);
+        this.__openedVersions.delete(uri);
+        this.__sessions.forgetClientVersions(uri);
+        // A stage is for a first open; one released unconsumed is stale.
+        this.__pendingContent.delete(uri);
+        this.documentReleaseScheduler.clearLosses(uri);
+        this.documentReleasedEmitter.fire(Object.freeze({ uri }));
+        this.handOverRelease(released, cleanAnnouncement);
+    }
+    /**
+     * Call the `DocumentReleaseHandler` slot, and announce a document released
+     * dirty clean once the promise it returns settles, which is after the
+     * release event. A failure is logged rather than thrown: the store has let
+     * go of the document by now, and a throw would abort the transition that
+     * released it, a session's close of its other documents included.
+     */
+    handOverRelease(released, cleanAnnouncement) {
+        let settled;
+        try {
+            // Read here: a lazily built slot whose factory throws throws on this read.
+            const handler = this.services.workspace.DocumentReleaseHandler;
+            settled =
+                handler === undefined
+                    ? Promise.reject(new Error('no workspace.DocumentReleaseHandler bound'))
+                    : Promise.resolve(handler.didReleaseDocument(released));
         }
+        catch (err) {
+            settled = Promise.reject(err);
+        }
+        // Names the text the build holds at the settle, so it follows anything a
+        // release listener did meanwhile: none when its build failed or it no
+        // longer has the document, since a removal leaves the record on the
+        // discarded text.
+        const announceClean = (built) => {
+            if (cleanAnnouncement?.isOwed()) {
+                const inBuild = built && this.services.workspace.LangiumDocuments.getDocument(UriUtils.toUri(released.uri)) !== undefined;
+                cleanAnnouncement.announce(inBuild ? this.textState(released.uri) : undefined);
+            }
+        };
+        settled.then(() => announceClean(true), (err) => {
+            // A release skipped at teardown, its peer or its workspace gone, is
+            // routine, not a fault to investigate.
+            if (isDocumentReleaseSkippedError(err)) {
+                this.tracer.with(released.uri).debug(err.message);
+            }
+            else {
+                this.tracer.with(released.uri).error(`Release handler failed. ${describeErrorWithStack(err)}`);
+            }
+            // Left unsettled, a watcher keeps the document dirty though the store answers clean.
+            announceClean(false);
+        });
+    }
+    /** `uri` as the `DocumentReleaseHandler` slot receives it. */
+    toReleasedDocument(uri) {
+        return {
+            uri,
+            wasOnDisk: this.dirtyStateTracker.hasDiskBaseline(uri),
+            isFor: other => this.documentKey(other) === uri,
+            isReclaimed: () => this.isOpenInAnyClient(uri) || this.__syncedDocuments.has(uri)
+        };
     }
     notifyWillSaveTextDocument(event) {
         const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
@@ -420,107 +492,172 @@ 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.
+        // 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;
+        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. ${describeError(err)}`);
+            return;
+        }
+        // What the file holds, not what the editor meant to write: an editor
+        // that saved older text leaves the document dirty.
+        this.setDiskBaseline(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.
+     */
     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 }));
+            if (event.text !== undefined) {
+                this.setDiskBaseline(syncedDocument.uri, event.text);
+            }
+            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);
-        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 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);
-                    // 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;
+        // Before the deferred release is resolved: refused after it, the open
+        // would leave a document whose grace it ended with no holder and no timer.
+        // A repeat open stays a no-op.
+        if (!this.__sessions.isOpenIn(uri, clientId)) {
+            this.__sessions.assertCanOpen(clientId);
         }
+        this.resolveDeferredRelease(uri, clientId);
         let document = this.__syncedDocuments.get(uri);
-        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);
-        if (clientId === LANGUAGE_CLIENT_ID) {
-            // Remember the URI Monaco opened under (may differ from the canonical key)
-            // so outbound applyEditToLanguageClient can address the URI it actually holds.
-            (record.languageClientUris ??= new Set()).add(this.toLanguageClientUri(td.uri));
+        const editor = clientId === LANGUAGE_CLIENT_ID;
+        // The client's declared text, never the synced document: staged
+        // content this open consumes leaves the two different, and a baseline
+        // asserting the client already holds it suppresses the one sync that
+        // would deliver it. On an attach, another client may already have
+        // changed the synced text, so the baseline is equality-only; a refresh
+        // pushing the full text would dirty the file on open. A first open's
+        // version is known only once its document is made, below.
+        if (editor) {
+            const held = document?.getText() === td.text ? document.version : undefined;
+            this.languageClientShadow.addOpen(uri, this.toLanguageClientUri(td.uri), td.version, td.text, document === undefined, held);
         }
+        if (this.isOpenInClient(uri, clientId)) {
+            // A repeat open, or the editor's second URI for the file, e.g. a
+            // symlink and its real path: the shadow records it so pushes reach it,
+            // and nothing re-fires.
+            return;
+        }
+        const existingClients = this.__sessions.clientsOf(uri);
+        this.__sessions.addOpen(uri, clientId);
+        this.__sessions.setClientVersion(uri, clientId, td.version);
         if (!document) {
             // Use integrity-staged content if available, otherwise the client-provided (disk) text.
             const pendingText = this.consumePendingContent(uri);
             const text = pendingText ?? td.text;
             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
-            // 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}]`);
-            document = this.configuration.create(uri, td.languageId, version, text);
-            this.__syncedDocuments.set(uri, document);
-            this.setAuthor(uri, version, clientId);
-            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.
-                //
-                // 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.get(clientFacing) === undefined) {
-                    this.__shadow.set(clientFacing, td.text);
-                }
+            const version = this.textLedger.openingVersion(uri, text) ?? this.builtRootOpeningVersion(uri, text) ?? td.version;
+            if (editor && text === td.text) {
+                // What `addOpen` already recorded, now with the version it is held at.
+                this.languageClientShadow.setLanguageClientText(this.toLanguageClientUri(td.uri), text, version);
             }
+            this.log(uri, `Open document: Version ${version} by ${this.formatClientId(clientId)} [first client${source}]`);
+            document = this.create(uri, td.languageId, version, text);
+            this.commitText(uri, document, clientId);
+            this.__openedVersions.set(uri, version);
+            // 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.
+            this.dirtyStateTracker.track(uri, document, 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(', ')})`);
-            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.logClientJoined(uri, clientId, document.version, existingClients);
             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.
+     *
+     * Returns whether a hold was added — `false` when `uri` is not open,
+     * `clientId` already holds it, or the document was waiting out the release
+     * grace for other clients and was released instead (see
+     * {@link resolveDeferredRelease}); 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;
+        }
+        // Before the deferred release is resolved, as for an open.
+        this.__sessions.assertCanOpen(clientId);
+        this.resolveDeferredRelease(key, clientId);
+        const document = this.__syncedDocuments.get(key);
+        if (!document) {
+            return false;
+        }
+        const existingClients = this.__sessions.clientsOf(key);
+        this.__sessions.addOpen(key, clientId);
+        // A client arriving this way holds no buffer of its own, so its guard
+        // starts at the synced version.
+        this.__sessions.setClientVersion(key, 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();
         }
@@ -532,7 +669,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, by the {@link LanguageClientShadow}. The
      * policy is always bound (the framework defaults it to
      * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
      */
@@ -550,17 +687,8 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     toLanguageClientUri(uri) {
         return asLanguageClientUri(UriUtils.normalize(uri));
     }
-    /** Get-or-create the per-URI tracking record. `uri` must already be a {@link documentKey}. */
-    trackingFor(uri) {
-        let record = this.__documents.get(uri);
-        if (!record) {
-            record = { clients: new Set(), versionAuthors: [], clientVersions: new Map() };
-            this.__documents.set(uri, record);
-        }
-        return record;
-    }
     setAuthor(uri, version, author) {
-        this.trackingFor(this.documentKey(uri)).versionAuthors[version] = author;
+        this.textLedger.setAuthor(this.documentKey(uri), version, author);
     }
     /**
      * Resolve the synced `TextDocument` for `uri`. The store keys documents by
@@ -583,55 +711,190 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     }
     /**
      * Current SHARED version of the document at `uri`: the open document's
-     * version, else where the persisted sequence left off at last close, else
-     * `0` for a URI this store has never seen. The shared sequence is
+     * version, else where its persisted sequence left off, else `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 (base-version gates): version unchanged ⇔
      * content unchanged.
      */
     version(uri) {
-        return this.get(uri)?.version ?? this.__versionSequences.get(this.documentKey(uri))?.version ?? 0;
+        return this.get(uri)?.version ?? this.textLedger.recordOf(this.documentKey(uri))?.version ?? 0;
+    }
+    /**
+     * The version the document at `uri` was opened at, which a client's write
+     * or an integrity repair steps past; `undefined` while it is not open.
+     */
+    openedVersion(uri) {
+        return this.__openedVersions.get(this.documentKey(uri));
+    }
+    /**
+     * Refuse unless the editor's buffer under `uri`, at its own `version`, holds
+     * the synced text, so a save the editor asks for persists what it shows.
+     * The editor's version counts its own buffer and the store's counts the
+     * synced text, so neither stands in for the other: `version` has to be the
+     * one the editor last declared, and the shadow has to know the buffer to
+     * hold the store's current version, which a push in flight breaks.
+     *
+     * A refusal is a {@link ConflictError} based on the store version the buffer
+     * last held, or on {@link STALE_VERSION} when it never held one or `version`
+     * names a buffer the editor never declared. It is a
+     * {@link DocumentNotOpenError} when the editor does not have `uri` open, or
+     * a delete of it is under way, which a save landing before the deletion
+     * build would undo by writing the file back.
+     */
+    assertLanguageClientHolds(uri, version) {
+        const key = this.documentKey(uri);
+        const clientUri = this.toLanguageClientUri(uri);
+        const declared = this.languageClientShadow.declaredVersion(key, clientUri);
+        const document = this.__syncedDocuments.get(key);
+        if (declared === undefined || document === undefined || this.services.workspace.AstDocumentManager.isDeleting(key)) {
+            throw new DocumentNotOpenError(uri, LANGUAGE_CLIENT_ID);
+        }
+        const held = declared === version ? this.languageClientShadow.heldVersion(key, clientUri) : undefined;
+        if (held !== document.version) {
+            const base = held ?? STALE_VERSION;
+            this.logUri(key, `Refuse editor save: buffer v${version} holds text v${base}, store holds v${document.version}`, 'debug');
+            // A snapshot, as the brand means: recorded when the buffer held that text, not read live.
+            throw new ConflictError(uri, asModelVersion(base), document.version, STALE_BASE_VERSION_SAVE);
+        }
+    }
+    /**
+     * Whether the editor holds text older than the store's text at `version`,
+     * or text the store never held. The first is the case while the push of
+     * that text is in flight. An answer computed on the store's text at
+     * `version` then refers to text the editor does not have. `false` once the
+     * editor holds that text or a later one, and when it does not have `uri`
+     * open.
+     */
+    isLanguageClientBehind(uri, version) {
+        const key = this.documentKey(uri);
+        const clientUri = this.toLanguageClientUri(uri);
+        if (!this.languageClientShadow.isOpen(key, clientUri)) {
+            return false;
+        }
+        const held = this.languageClientShadow.heldVersion(key, clientUri);
+        return held === undefined || held < version;
+    }
+    /**
+     * The text the store holds for `uri`: an open document's, or for a closed
+     * one, the clean text its version sequence left off at, which for a deleted
+     * document is its last text. `undefined` for a URI no build and no client
+     * gave the store.
+     */
+    textState(uri) {
+        const document = this.get(uri);
+        if (document) {
+            return { version: document.version, hash: this.textLedger.hashOf(document), dirty: this.isDirty(uri) };
+        }
+        const recorded = this.textLedger.recordOf(this.documentKey(uri));
+        return recorded && { version: recorded.version, hash: recorded.hash, dirty: false };
+    }
+    /**
+     * The built root's recorded version for a first open of `key` with `text`,
+     * one on when the text differs from the root's; `undefined` when the root
+     * records no store version. Seeded from the opener's declared version
+     * instead, a write based on the built root passes the gate over other text,
+     * and the same text looks newer than its model. A built root records none
+     * only under a `LangiumDocuments` that does not reconcile at registration.
+     */
+    builtRootOpeningVersion(key, text) {
+        const built = this.services.workspace.LangiumDocuments.getDocument(UriUtils.toUri(key));
+        if (built === undefined) {
+            return undefined;
+        }
+        const ledger = this.services.workspace.ModelLedger;
+        const root = built.parseResult.value;
+        const recorded = ledger.versionOf(root);
+        if (recorded === UNRECORDED_VERSION || recorded === STALE_VERSION) {
+            return undefined;
+        }
+        return (ledger.textOf(root) ?? built.textDocument.getText()) === text ? recorded : recorded + 1;
     }
     /**
      * Reconcile the persisted version sequence with content that reached the
      * build OUTSIDE the store's write paths — a closed document rebuilt from
-     * disk (last-close revert) or replaced by a watched-file change. Steps the
+     * disk after its release, or replaced by a watched-file change. Steps the
      * sequence iff `text` differs from the sequence's last-known content and
      * returns the resulting sequence version so the caller can re-stamp the
-     * rebuilt document (see the `AstDocumentManager` Parsed-phase listener) —
+     * rebuilt document (`VersionSyncService.modelProduced`) —
      * keeping the "version advances iff content changes" invariant for
      * documents no client currently holds.
      *
-     * Returns `undefined` — and does nothing — when the document is open (the
-     * store's own content is authoritative; external transitions never reach
-     * the Langium factory for open documents) or was never tracked (no gate
-     * holder can hold a version pointer for it, and the early exit keeps
-     * workspace-wide builds from hashing every untouched document).
+     * For an open document, its version when it holds `text`, since a build
+     * that read the file while the document was closed can finish after an
+     * open; else `undefined`, and the caller has to build the document again.
+     *
+     * A document without a sequence starts one at `0` with `text`: snapshots
+     * hand out versions for documents no client opened, so an uncounted change
+     * would let a write based on the old text pass the gate.
      */
     reconcileExternalContent(uri, text) {
         const key = this.documentKey(uri);
-        if (this.__syncedDocuments.has(key)) {
-            return undefined;
+        const open = this.__syncedDocuments.get(key);
+        if (open !== undefined) {
+            return open.getText() === text ? open.version : undefined;
         }
-        const sequence = this.__versionSequences.get(key);
-        if (sequence === undefined) {
-            return undefined;
+        const before = this.textLedger.recordOf(key)?.version;
+        const version = this.textLedger.reconcile(key, text);
+        if (before !== undefined && version !== before) {
+            this.logUri(key, `External content change while closed: sequence stepped to version ${version}`, 'debug');
         }
-        const hash = contentHash(text);
-        if (hash === sequence.contentHash) {
-            return sequence.version;
+        return 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 base-version 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' };
         }
-        const stepped = { version: sequence.version + 1, contentHash: hash };
-        this.__versionSequences.set(key, stepped);
-        this.logUri(key, `External content change while closed: sequence stepped to version ${stepped.version}`, 'debug');
-        return stepped.version;
+        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.commitChange(key, document, [{ text: repaired }], INTEGRITY_CLIENT_ID).document;
+        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.
-        const clientId = version !== undefined ? history?.[version] : history?.at(-1);
-        if (!clientId && history) {
+        const key = this.documentKey(uri);
+        const clientId = this.textLedger.authorOf(key, version);
+        if (!clientId && this.textLedger.authorOf(key) !== undefined) {
             // Only warn when there IS a history but the specific version is missing; no history at all
             // means the document was rebuilt internally (e.g. by a project manager), not an error.
             this.log(uri, `Could not detect author of version ${version}.`);
@@ -645,16 +908,18 @@ 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`
-     * subscriber that finds this `false` knows the last client just closed and a
-     * disk re-read / rebuild can proceed.
+     * 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.
+     * What the build keeps is the release's: a subscriber that re-read or
+     * rebuilt the document would race the `DocumentReleaseHandler`, and after a
+     * lost connection the release waits out its grace.
      */
     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
@@ -662,14 +927,18 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         // client-facing URI both resolve to the same registration.
         return this.isOpenInClient(uri, LANGUAGE_CLIENT_ID);
     }
+    /** The clients that have `uri` open, in the order they opened it. */
+    clientsOf(uri) {
+        return this.__sessions.clientsOf(this.documentKey(uri));
+    }
     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
@@ -677,30 +946,252 @@ 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 release grace runs out,
+     * another client opens it, or it is deleted, before the
+     * `DocumentReleaseHandler` slot is handed the document.
+     */
+    get onDidReleaseDocument() {
+        return this.documentReleasedEmitter.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 release 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.
+     */
+    isReleaseDeferred(uri) {
+        return this.documentReleaseScheduler.isDeferred(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 release 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) {
+        return this.dirtyStateTracker.isDirty(this.documentKey(uri));
+    }
+    /**
+     * Fires each time the answer of {@link isDirty} changes. For a document
+     * released dirty it fires once the `DocumentReleaseHandler` slot reports the
+     * release settled: at the version of the text the build then holds, or
+     * without text when the document is gone or the handler failed, though
+     * {@link isDirty} answers clean from the release on.
+     */
+    get onDidChangeDirty() {
+        return this.dirtyStateTracker.onDidChangeDirty;
+    }
+    /**
+     * 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.
+     */
+    setDiskBaseline(uri, text) {
+        const key = this.documentKey(uri);
+        const document = this.__syncedDocuments.get(key);
+        if (document !== undefined) {
+            this.dirtyStateTracker.setDiskBaseline(key, document, text);
+        }
+    }
+    /**
+     * Record that `uri` was created from a session's text rather than read from
+     * its file: it has no disk baseline, so it is dirty until its first save,
+     * and {@link isUnsavedCreation} answers `true` until then. A no-op for a
+     * URI the store does not hold.
+     */
+    markCreated(uri) {
+        const key = this.documentKey(uri);
+        const document = this.__syncedDocuments.get(key);
+        if (document !== undefined) {
+            this.dirtyStateTracker.markCreated(key, document);
+        }
+    }
+    /**
+     * Whether `uri` was created from a session's text and the store has not
+     * seen its file since, by a save or a reload that found it. A baseline
+     * cleared because the file went missing does not count. `false` for a URI
+     * the store does not hold.
+     */
+    isUnsavedCreation(uri) {
+        return this.dirtyStateTracker.isUnsavedCreation(this.documentKey(uri));
+    }
+    /**
+     * 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, once `existsSettled` confirms it gone: a file
+     * it finds is read again. That wait runs outside the queue, so it holds up
+     * no write to the file.
+     */
+    async reloadDiskBaseline(uri) {
+        const key = this.documentKey(uri);
+        if (!this.__syncedDocuments.has(key)) {
+            return;
+        }
+        const workspace = this.services.workspace;
+        const fileSystem = workspace.FileSystemProvider;
+        const target = UriUtils.toUri(key);
+        const read = async () => {
+            try {
+                return await workspace.FileSystemTaskQueue.enqueue(key, () => fileSystem.readFile(target));
+            }
+            catch (err) {
+                this.tracer.with(key).debug(`Disk baseline: the file cannot be read. ${describeError(err)}`);
+                return undefined;
+            }
+        };
+        let onDisk = await read();
+        if (onDisk === undefined && (await (fileSystem.existsSettled?.(target) ?? fileSystem.exists(target)))) {
+            onDisk = await read();
+        }
+        this.setDiskBaseline(key, onDisk);
+    }
+    /**
+     * Start a client session under `clientId`. Throws 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, cause);
+            this.tracer.info(`Session closed: ${this.formatClientId(clientId)}`);
+            this.tracer.trace(`Session closed: ${clientId}`);
+        }
     }
     /**
-     * Stages integrity-updated content for a closed document.
+     * Close every document the language client has open, as a `didClose` for
+     * each would, so each last close releases its document. 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.
      *
-     * 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.
+     * 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() {
+        await this.initialBuildFinished();
+        for (const uri of this.__sessions.opensOf(LANGUAGE_CLIENT_ID)) {
+            // A close for one URI while others remain keeps the client's hold.
+            this.languageClientShadow.removeAllOpens(uri);
+            this.notifyDidCloseTextDocument({ textDocument: { uri } });
+        }
+    }
+    /**
+     * Settles once the initial workspace build has finished, whether it
+     * completed, was cancelled or failed. Awaiting `workspaceInitialized` itself
+     * throws after a cancelled build, which any write during startup causes, and
+     * every open and close gated on it is then dropped for the process lifetime.
+     * The workspace manager logs a failed build.
+     */
+    async initialBuildFinished() {
+        await this.services.workspace.WorkspaceManager.workspaceInitialized.catch(() => undefined);
+    }
+    /**
+     * The file behind `uri` was deleted: close every open of it except the
+     * language client's, and release now a document waiting out the grace,
+     * whose lost client's open would otherwise bring its text back with no
+     * file behind it.
      *
-     * 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.
+     * 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);
+            }
+        }
+        this.releaseIfDeferred(key);
+    }
+    /**
+     * 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());
+        this.languageClientShadow.removeAllOpens(key);
+        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.
+        this.releaseIfDeferred(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.
+     *
+     * Nothing is pushed to a file no client holds. The next open of it reads
+     * disk, which lacks the update; {@link notifyDidOpenTextDocument} takes this
+     * staged content in place of that text, and the open's sync then delivers
+     * it to an editor as an unsaved change.
+     *
+     * 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 release discards it. An entry waits for
+     * that first open, at one serialised string per URI.
      */
     stagePendingContent(uri, text) {
-        this.trackingFor(this.documentKey(uri)).pendingContent = text;
+        this.__pendingContent.set(this.documentKey(uri), text);
     }
     /**
      * Send `newText` to the LSP textual language client (Monaco / VS Code) via
@@ -711,63 +1202,53 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      *   - The shared services have no LSP {@link Connection} bound (non-LSP
      *     hosts like CLI / tests).
      *   - The shadow already matches `newText` (no edits needed; quiet skip).
+     *   - The language client has not opened the document. A client applies an
+     *     edit to a closed file by opening it, and that open races the edit;
+     *     the document's own open delivers its text instead.
      *
      * On `applyEdit` rejection (`result.applied === false`) or RPC failure the
-     * shadow is invalidated so the next call sends a full-replace baseline.
+     * shadow is invalidated so the next call sends a full replace, or nothing
+     * when the client was last heard to hold that text.
      * Errors are re-thrown — callers wrap with their own retry / coalescing
      * policy as needed.
      *
      * The diff path is apply-verify-safe: the shadow internally checks that
      * `TextDocument.applyEdits(old, edits) === newText` and falls back to a
-     * full replace on mismatch (logged via the warn-callback wired in the
-     * constructor), so a diff regression becomes log noise, not data loss.
+     * full replace on mismatch, logged, so a diff regression becomes log noise,
+     * not data loss.
      *
      * That safety net verifies the diff against the SHADOW, which is what the
      * client is *believed* to hold — so it cannot see the client's buffer moving
      * underneath a push. A line-keyed edit is position-dependent: if a genuine
-     * client keystroke lands between {@link LanguageClientTextShadow.computeEdits}
-     * and the client applying, the ranges address the wrong lines and splice the
-     * buffer (observed as a duplicated declaration, which the integrity tier then
+     * client keystroke lands between computing the edits and the client
+     * applying them, the ranges address the wrong lines and splice the buffer
+     * (observed as a duplicated declaration, which the integrity tier then
      * "repairs" into a suffixed name and persists). The edit is therefore
-     * addressed at the language client's LAST DECLARED VERSION rather than at
-     * `null` ("version intentionally unknown"), which is what lets the client
-     * reject a push its buffer has outrun. On rejection the shadow is invalidated,
+     * addressed at the language client's last known version for that URI rather
+     * than at `null` ("version intentionally unknown"), which is what lets the
+     * client reject a push its buffer has outrun. On rejection the shadow is invalidated,
      * so the caller's retry is a full-range replace — position-independent, and
-     * safe to apply to whatever the client now holds.
+     * safe to apply to whatever the client now holds — or nothing when the
+     * client was last heard to hold that text.
      */
     async applyEditToLanguageClient(uri, newText, options) {
         const connection = this.services.lsp?.Connection;
         if (!connection) {
             return undefined;
         }
-        // The document is keyed by its canonical identity, but Monaco holds it under
-        // the URI(s) it opened. Address each of those language-client URIs — the one
-        // R→S translation, kept here at the egress. Usually one; more than one only
-        // when the same file was opened under a symlink and its real path. Falls back
-        // to the normalized URI when nothing is tracked. The shadow is keyed by each
-        // URI, so every diff is against the right baseline.
-        const recorded = this.__documents.get(this.documentKey(uri))?.languageClientUris;
-        const targets = recorded && recorded.size > 0 ? recorded : [this.toLanguageClientUri(uri)];
+        // The document is keyed by its canonical identity, but the client holds it
+        // under each URI it opened, and each is diffed against its own baseline.
+        const key = this.documentKey(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);
-            const edits = this.__shadow.computeEdits(targetUri, newText);
-            if (edits.length === 0) {
+        for (const clientUri of this.languageClientShadow.pushTargets(key)) {
+            // Prepared per target, after the previous target's reply: prepared up
+            // front, a later target is diffed against what it held before a change
+            // that arrived meanwhile.
+            const push = this.languageClientShadow.preparePush(key, clientUri, newText);
+            if (push === undefined) {
                 continue;
             }
-            // Record the push for echo correlation BEFORE the RPC — the client's
-            // echo can race the applyEdit response. See `__pendingPushes`.
-            this.recordPendingPush(targetUri, before, newText);
             try {
-                // Version the push only when it is position-DEPENDENT. A full-range
-                // replace lands correctly on any buffer, so gating it would turn a
-                // stale-by-one version into a refused update for no safety gain — and
-                // 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
@@ -777,137 +1258,55 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
                 // 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 version = push.version ?? UNKNOWN_CLIENT_VERSION;
                 const result = await connection.workspace.applyEdit({
                     label: options?.label,
                     edit: {
-                        documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+                        documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(clientUri, version), push.edits)]
                     }
                 });
                 if (result && result.applied === false) {
-                    this.__shadow.invalidate(targetUri);
-                    this.__pendingPushes.delete(targetUri);
+                    push.notifyOutcome('refused');
+                }
+                else if (result?.applied) {
+                    push.notifyOutcome('applied');
                 }
                 lastResult = result;
             }
             catch (err) {
-                this.__shadow.invalidate(targetUri);
-                this.__pendingPushes.delete(targetUri);
+                push.notifyOutcome('failed');
                 throw err;
             }
         }
         return lastResult;
     }
     /**
-     * The version the LSP textual language client last declared for `uri`, for
-     * addressing an outgoing `workspace/applyEdit`.
-     *
-     * Client version ids are CLIENT-owned per LSP, so this is the id the client
-     * itself stamped on its last `didOpen` / `didChange` — never the shared
-     * server version, which advances on authored writes the client knows nothing
-     * about and would therefore reject every push.
-     *
-     * Falls back to {@link UNKNOWN_CLIENT_VERSION} when the client has never
-     * declared one, which is the honest answer for a document it has not opened.
-     * That is also the case in which there is no shadow, so the push is already a
-     * position-independent full replace and has nothing to gain from a gate.
+     * Explicitly baseline the language-client shadow for a URI the client has
+     * open, for an adopter that knows what the client holds without a
+     * `didChange` saying so (e.g. after a sideband save). Normal didOpen /
+     * didChange paths from the LSP language client already auto-track the
+     * shadow. A seed for a URI the client has not opened is kept but changes no
+     * push, since nothing is pushed there; its open replaces it with the text it
+     * declares. `text` other than the synced text refuses the editor's saves
+     * until the editor holds the synced text again.
      */
-    languageClientVersion(uri) {
-        return this.__documents.get(this.documentKey(uri))?.clientVersions.get(LANGUAGE_CLIENT_ID) ?? UNKNOWN_CLIENT_VERSION;
-    }
-    /**
-     * Append a push to the in-flight queue for `targetUri`
-     * (see {@link __pendingPushes}). Bounded: beyond
-     * {@link PENDING_ECHO_CAP} the oldest entry drops with a debug log — an
-     * echo that far outstanding means the client is not echoing at all, and
-     * an unbounded queue must not become the leak.
-     */
-    recordPendingPush(targetUri, before, newText) {
-        let pending = this.__pendingPushes.get(targetUri);
-        if (!pending) {
-            pending = [];
-            this.__pendingPushes.set(targetUri, pending);
-        }
-        pending.push({ before, afterHash: contentHash(newText) });
-        if (pending.length > PENDING_ECHO_CAP) {
-            pending.shift();
-            this.logUri(targetUri, `Pending-echo queue exceeded ${PENDING_ECHO_CAP} entries; dropped the oldest`, 'debug');
-        }
-    }
-    /**
-     * 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`.
-     *
-     * `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.
-     *
-     * **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
-     * push, so the first echo to arrive belongs to the oldest entry — a FIFO
-     * correspondence the queue preserves by consuming from the front. Comparing
-     * the reconstruction against every pending hash, not only the oldest, is
-     * what recognises an echo that a newer write already superseded: a rapid
-     * write sequence can deliver the echo of push N after the store applied
-     * push N+1, and everything older is then accounted for too.
-     *
-     * A reconstruction matching NO pending push means the client's buffer went
-     * somewhere we did not send it — it coalesced a keystroke into the echo, or
-     * typed before the push landed. That text is authoritative, and the queue
-     * drops: the client has stopped being a pure mirror, so no outstanding echo
-     * can match again. (A push still in flight at that point will be refused by
-     * the client's own version gate, which invalidates the shadow and makes the
-     * next sync a position-independent full replace.)
-     *
-     * Content equality is a sound echo proof because entries live only between a
-     * push and its echo — a milliseconds window, never history — and the
-     * client's `didChange` stream is ordered, so every buffer state arrives in
-     * mutation order. An UNDO returning the buffer to previously-pushed text is
-     * therefore never swallowed: the edit that preceded it already emptied the
-     * 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) {
-            return undefined;
-        }
-        // 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 };
+    setLanguageClientText(uri, text) {
+        const document = this.get(uri);
+        const held = document?.getText() === text ? document.version : undefined;
+        this.languageClientShadow.setLanguageClientText(this.toLanguageClientUri(uri), text, held);
     }
     /**
-     * Explicitly baseline the language-client text shadow for a URI. Useful in
-     * tests and for adopters that need to seed the shadow without going through
-     * a `didOpen` event (e.g. after a sideband save). Normal didOpen / didChange
-     * paths from the LSP language client already auto-track the shadow.
+     * Drop the shadow baseline for a URI; the next applyEditToLanguageClient
+     * sends a full replace, or nothing when the client was last heard to hold
+     * that text.
      */
-    setLanguageClientText(uri, text) {
-        const clientFacing = this.toLanguageClientUri(uri);
-        this.__shadow.set(clientFacing, text);
-        // An explicit rebaseline supersedes whatever was in flight.
-        this.__pendingPushes.delete(clientFacing);
-    }
-    /** Drop the shadow baseline for a URI; the next applyEditToLanguageClient sends a full replace. */
     invalidateLanguageClientText(uri) {
-        const clientFacing = this.toLanguageClientUri(uri);
-        this.__shadow.invalidate(clientFacing);
-        this.__pendingPushes.delete(clientFacing);
+        this.languageClientShadow.invalidateLanguageClientText(this.toLanguageClientUri(uri));
     }
     consumePendingContent(uri) {
-        const record = this.__documents.get(this.documentKey(uri));
-        const content = record?.pendingContent;
-        if (record) {
-            record.pendingContent = undefined;
-        }
+        const key = this.documentKey(uri);
+        const content = this.__pendingContent.get(key);
+        this.__pendingContent.delete(key);
         return content;
     }
     log(uri, message) {