@hydranium/core 1.0.0-next.205 → 1.0.0-next.208

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

@@ -19,15 +19,17 @@
 // eslint-disable-next-line @typescript-eslint/no-restricted-imports
 import { NormalizedTextDocuments } from '@hydranium/langium/lsp';
 import { UriUtils } from '@hydranium/langium';
-import { Emitter, OptionalVersionedTextDocumentIdentifier, TextDocumentContentChangeEvent as ContentChange, TextDocumentEdit, TextDocumentSyncKind } from 'vscode-languageserver';
+import { Emitter, OptionalVersionedTextDocumentIdentifier, TextDocumentEdit, TextDocumentSyncKind } from 'vscode-languageserver';
 import { TextDocument } from 'vscode-languageserver-textdocument';
-import { asLanguageClientUri, DisposableCollection, textHash, STALE_VERSION, UNRECORDED_VERSION } from '@hydranium/protocol';
-import { HYDRANIUM_BUILD_REASONS } from '../langium/document-builder/document-builder.js';
-import { isConnectionGoneError } from '../util/connection-liveness.js';
+import { asLanguageClientUri, DisposableCollection, STALE_VERSION, UNRECORDED_VERSION } from '@hydranium/protocol';
 import { LANGUAGE_CLIENT_ID } from './client-ids.js';
 import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
 import { ClientSessionRegistry } from './client-session-registry.js';
-import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
+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
@@ -37,168 +39,124 @@ import { isFullReplace, LanguageClientTextShadow } from './language-client-text-
  */
 const UNKNOWN_CLIENT_VERSION = null;
 /**
- * The default of {@link HydraniumTextDocumentsOptions.revertGraceMs}: long
+ * 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 DEFAULT_REVERT_GRACE_MS = 10_000;
+const DEFAULT_RELEASE_GRACE_MS = 10_000;
 /**
- * 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.
- */
-const PENDING_ECHO_CAP = 32;
-/**
- * Whether `err` reports that the file of `target` does not exist, as a Node
- * file system and the framework's providers do: code `ENOENT`, with `target`'s
- * path. A missing file of another document is a different failure.
- */
-function isFileNotFound(err, target) {
-    if (typeof err !== 'object' || err === null || !('code' in err) || err.code !== 'ENOENT') {
-        return false;
-    }
-    return !('path' in err) || err.path === target.fsPath;
-}
-/**
- * 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.
  *
- * 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) and the client-session table, both kept by {@link __sessions}.
- *   - A SERVER-OWNED shared version sequence: per-URI, monotonic across
- *     close/reopen cycles, advancing exactly when the synced content changes.
- *     Client-declared version ids (Monaco's buffer numbering) feed only a
- *     per-client staleness guard and never leak into a running 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 base-version gate holders. A URI with no sequence, and no
- *     root that records a version, starts at its opener's declared id: no version
- *     was handed out for it.
- *   - Version-author history so each edit is attributable to its originating client.
- *   - The revert to disk once no client has a document open, for every head
- *     ({@link revertToDisk}), deferred by
- *     {@link HydraniumTextDocumentsOptions.revertGraceMs} after a lost connection.
- *   - A disk baseline per open document, and whether its text differs from it
- *     ({@link isDirty}).
- *   - Pending-content staging used by the integrity service to thread corrections
- *     through `workspace/applyEdit` cycles for currently-closed documents.
- *   - `didOpen` notifications arriving over the LSP connection wait on the
- *     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.
+ * 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.
+ *
+ * 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 DocumentTrackingRecord}), keyed by
-     * canonical URI. One record per URI, so dropping it clears every axis at
-     * once. Which client has the document open is kept apart, in
-     * {@link __sessions}.
-     */
-    __documents = new Map();
-    /**
-     * Which client has which document open, and which client ids are registered
-     * sessions. Every open-state predicate on this class reads it, so an open
+     * 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.
      */
     __sessions = new ClientSessionRegistry();
-    /**
-     * Per-URI shared-version continuity across close/reopen cycles
-     * ({@link VersionSequence}), kept for every document a build or a client
-     * gave the store, and consulted by the next first-client open. A URI
-     * with none, and no root that records a version, starts at its opener's
-     * declared version.
-     * DELIBERATELY outside {@link DocumentTrackingRecord}: that record is deleted on last close, while the version sequence must
-     * survive it — the shared version is a server-owned, monotonic,
-     * advances-iff-content-changes counter that never resets while the server
-     * lives. That invariant is what makes an optimistic base-version 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, not even when the file is deleted: a recreated file
-     * restarting at `0` would let a write based on the deleted text pass. Two
-     * small values per URI ever built, however often it changes.
-     */
-    __versionSequences = new Map();
-    /**
-     * Released documents last announced dirty. Their clean flip waits for the
-     * revert, so it carries the reverted text's version; a first open before the
-     * revert takes the entry over, and its own dirty answer decides the flip.
-     * Each release enters a token of its own, so the revert of an earlier
-     * release cannot announce a later one clean before that one's revert.
-     */
-    __releasedDirty = new Map();
-    /** Per held document, the {@link textHash} of its text at the version it was taken. */
-    __textHashes = new WeakMap();
-    /**
-     * Texts pushed to the LSP textual language client via
-     * {@link applyEditToLanguageClient} whose echoes have not come back yet
-     * ({@link PendingLanguageClientPush}), keyed like the shadow by language-client URI.
-     * Outbound pushes and inbound echoes are uncorrelated on the wire; this
-     * FIFO is the explicit correlation, and it is what
-     * {@link classifyLanguageClientChange} reconstructs against.
-     *
-     * **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).
-     */
-    __shadow;
+    /** The version each open document was opened at; see {@link openedVersion}. */
+    __openedVersions = new Map();
     tracer;
     configuration;
-    /** See {@link HydraniumTextDocumentsOptions.revertGraceMs}. */
-    revertGraceMs;
-    lastOpenClosedEmitter = new Emitter();
+    __textLedger;
+    __languageClientShadow;
+    __dirtyStateTracker;
+    __documentReleaseScheduler;
+    documentReleasedEmitter = new Emitter();
     languageClientSavedEmitter = new Emitter();
-    dirtyChangedEmitter = 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);
-        this.revertGraceMs = options.revertGraceMs ?? DEFAULT_REVERT_GRACE_MS;
-        this.onDidCloseLastOpen(event => void this.revertToDisk(event.uri));
-    }
-    // Re-exposed configuration factories — for framework-internal callers
-    // (LanguageClientTextShadow's apply-verify probe; IntegrityService.resyncDocument)
-    // 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);
     }
@@ -283,19 +241,18 @@ 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. The language client is checked per URI: each is
-            // its own buffer, and one URI's higher id would drop the other's edits.
-            const record = this.trackingFor(uri);
-            const languageClientDocument = clientId === LANGUAGE_CLIENT_ID ? record.languageClientDocuments?.get(this.toLanguageClientUri(td.uri)) : undefined;
-            const lastSeen = languageClientDocument?.declaredVersion ?? 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).
@@ -303,71 +260,42 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
                 this.logUri(uri, `Ignore update by ${this.formatClientId(clientId)}: ${reason}`, 'debug');
                 return;
             }
-            record.clientVersions.set(clientId, td.version);
-            if (languageClientDocument) {
-                languageClientDocument.declaredVersion = td.version;
-            }
-            // A language-client change is keyed to the buffer that client holds,
-            // which is the synced text only while the two agree — an authored
-            // write advances the synced text without the client knowing, and a
-            // push in flight moves the client without the store knowing.
-            // Resolve which it is, and against what, before touching anything.
-            const origin = clientId === LANGUAGE_CLIENT_ID
-                ? this.classifyLanguageClientChange(this.toLanguageClientUri(td.uri), document, changes)
-                : undefined;
-            if (origin?.kind === 'echo') {
-                // The client is reporting a text we pushed it, so the synced
-                // document is ALREADY there and the changes must not be applied a
-                // second time. Nothing is minted and no rebuild fires. The
-                // 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;
             }
-            if (origin?.kind === 'unreconstructable') {
+            if (verdict.kind === 'unreconstructable') {
                 this.tracer.with(uri).warn(`Drop change: no known client buffer for its ranges (client version ${td.version})`);
                 return;
             }
-            // The SHARED version advances iff the content actually changes — the
-            // invariant optimistic base-version 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 change is applied as its RECONSTRUCTED text rather than
-            // as its own ranges: those ranges address the client's own buffer, so
+            // 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 previousText = document.getText();
-            const sharedVersion = document.version;
-            document = this.configuration.update(document, origin === undefined ? changes : [{ text: origin.text }], sharedVersion + 1);
-            const changed = document.getText() !== previousText;
-            if (!changed) {
-                document = this.configuration.update(document, [], sharedVersion);
-            }
-            this.__syncedDocuments.set(uri, document);
-            if (changed) {
-                this.setAuthor(uri, document.version, clientId);
-                this.refreshDirty(uri);
-            }
-            if (clientId === LANGUAGE_CLIENT_ID) {
-                // Monaco just told us about its new content; record it so the next outbound
-                // 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) {
+            const committed = this.commitChange(uri, document, verdict.kind === 'direct' ? changes : [{ text: verdict.text }], clientId);
+            document = committed.document;
+            if (editor) {
+                this.languageClientShadow.setClientText(clientUri, document.getText());
+                // 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 ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`);
+            this.log(document.uri, `Update to version ${document.version} by ${this.formatClientId(clientId)}${committed.changed ? '' : ' (content unchanged)'}`);
             this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
         }
     }
@@ -390,60 +318,49 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      */
     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.refreshDirty(key);
-        }
+        // 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.log(document.uri, `Update to version ${document.version} by ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`);
         this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
         return document.version;
     }
     /**
      * Close `clientId`'s open of the document. When it was the last open, the
-     * document is released and reverts to disk, at once or, for a `'lost'`
-     * close, after {@link HydraniumTextDocumentsOptions.revertGraceMs}.
+     * 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 (clientId === LANGUAGE_CLIENT_ID) {
-            const clientFacing = this.toLanguageClientUri(event.textDocument.uri);
-            const languageClientDocuments = this.__documents.get(uri)?.languageClientDocuments;
-            if (languageClientDocuments?.delete(clientFacing) && languageClientDocuments.size > 0) {
-                // Another URI still holds the document, so only this one's buffer goes.
-                this.__shadow.invalidate(clientFacing);
-                this.__pendingPushes.delete(clientFacing);
+            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 record = this.__documents.get(uri);
-        record?.clientVersions.delete(clientId);
-        if (record && cause === 'lost') {
-            (record.lostClients ??= new Map()).set(clientId, this.services.Clock.stopwatch());
+        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 ${this.formatClientId(clientId)}`);
             this.__onDidClose.fire(Object.freeze({ document: syncedDocument, clientId }));
-            if (clientId === LANGUAGE_CLIENT_ID) {
-                // Monaco closed the document; drop the shadow baselined under the URI
-                // it held. (If this was the last client the whole record is deleted on
-                // release.)
-                const droppedUri = this.toLanguageClientUri(event.textDocument.uri);
-                this.__shadow.invalidate(droppedUri);
-                this.__pendingPushes.delete(droppedUri);
-            }
-            if (!this.__sessions.isOpen(uri)) {
-                if (cause === 'lost' && this.revertGraceMs > 0) {
+            if (!this.isOpenInAnyClient(uri)) {
+                if (cause === 'lost') {
                     this.deferRelease(uri);
                 }
                 else {
@@ -453,55 +370,34 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         }
     }
     /**
-     * Keep the document, text and all, for the revert grace, then release it.
+     * 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 resolvePendingRevert} for any other
+     * rather than reading disk; see {@link resolveDeferredRelease} for any other
      * open.
      */
     deferRelease(uri) {
-        this.log(uri, `No client left; revert deferred for ${this.revertGraceMs} ms (connection lost)`);
-        const timer = this.services.Clock.setTimer(() => {
-            this.__sessions.cancelRevert(uri);
-            if (!this.__sessions.isOpen(uri)) {
+        this.documentReleaseScheduler.defer(uri, () => {
+            if (!this.isOpenInAnyClient(uri)) {
                 this.releaseDocument(uri);
             }
-        }, this.revertGraceMs);
-        this.__sessions.deferRevert(uri, timer);
-    }
-    /**
-     * Resolve the pending revert of `uri` for an open by `clientId`. An open by a
-     * client lost from the document within its grace cancels the revert, and
-     * the client finds its unsaved text. Any other open releases the document
-     * first, so it opens as a first open does: cancelling for every open hands
-     * a lost client's unsaved text to whoever opens next, a reloaded page or an
-     * editor, with nothing marking it unsaved.
-     */
-    resolvePendingRevert(uri, clientId) {
-        const record = this.__documents.get(uri);
-        if (record) {
-            this.pruneLostClients(record);
-        }
-        const returning = record?.lostClients?.delete(clientId) ?? false;
-        if (!this.__sessions.isRevertPending(uri)) {
-            return;
-        }
-        this.__sessions.cancelRevert(uri);
-        if (!returning) {
-            this.releaseDocument(uri);
+        });
+        if (this.documentReleaseScheduler.isDeferred(uri)) {
+            this.log(uri, `No client left; release deferred for ${this.documentReleaseScheduler.graceMs} ms (connection lost)`);
         }
     }
-    /** Drop the entries of {@link DocumentTrackingRecord.lostClients} whose grace has run out. */
-    pruneLostClients(record) {
-        for (const [clientId, sinceLoss] of record.lostClients ?? []) {
-            if (sinceLoss.elapsedMs >= this.revertGraceMs) {
-                record.lostClients?.delete(clientId);
-            }
+    /** 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);
         }
     }
     /**
-     * Drop the document no client has open any more, then announce it on
-     * {@link onDidCloseLastOpen}, which is what reverts it to disk.
+     * 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);
@@ -509,175 +405,72 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
             return;
         }
         this.log(syncedDocument.uri, `Remove synced document: ${syncedDocument.version} (no client left)`);
-        // Persist where the shared version sequence left off (version +
-        // content hash) so the next open CONTINUES the sequence instead of
-        // restarting at the reopening client's declared id. Hashed once
-        // here at release, not on every change.
-        this.__versionSequences.set(uri, {
-            version: syncedDocument.version,
-            contentHash: this.heldTextHash(syncedDocument)
-        });
-        if (this.__documents.get(uri)?.dirty === true) {
-            this.__releasedDirty.set(uri, {});
-        }
+        // 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);
+        const cleanAnnouncement = this.dirtyStateTracker.release(uri);
         this.__syncedDocuments.delete(uri);
-        // One delete clears every per-URI axis (version history + any staged
-        // pending content) so a future open with the same URI starts fresh.
-        this.__documents.delete(uri);
-        this.lastOpenClosedEmitter.fire(Object.freeze({ uri }));
+        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(this.toReleasedDocument(uri), cleanAnnouncement);
     }
     /**
-     * Rebuild a released document from the file system provider, so the build
-     * stops carrying the unsaved text of its last client.
-     *
-     * The provider decides, for every scheme, by `exists`: a document it can
-     * serve is rebuilt from its text, and any other — an editor's `untitled:`
-     * buffer, a file never saved, or one deleted meanwhile — is removed
-     * from the workspace. A `virtual:` document survives, since the framework's
-     * provider for that scheme serves it from the index, whatever provider the
-     * host passes as `context.fileSystemProvider`; an edited one therefore keeps
-     * its last client's text, and keeping it read-only is the client's job.
-     *
-     * The answer is read in the document's disk queue, so the rebuild follows
-     * any save still queued rather than reverting past it; a file that goes
-     * after that read is removed when its rebuild finds none.
-     *
-     * Whether to revert at all is decided inside the write lock, as its holder:
-     * decided before waiting for the lock, a client that opens or re-creates the
-     * document meanwhile would have its text rebuilt over, or the document
-     * removed. A document some client has open again, or that waits out a new
-     * grace, is left to that client.
-     *
-     * A document released dirty is announced clean, so a watcher is never left
-     * holding it dirty: once the revert has parsed the file, even if it is then
-     * cancelled, or else once the build it requests in its place has parsed it,
-     * as the announcement names the store's text. One the revert or that build
-     * removed, or that build failed, is announced without text. A reopen before
-     * that takes the announcement over.
+     * 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.
      */
-    async revertToDisk(uri) {
-        const workspace = this.services.workspace;
-        const target = UriUtils.toUri(uri);
-        const reopened = () => this.isOpenInAnyClient(uri) || this.__syncedDocuments.has(uri);
-        const releasedDirty = this.__releasedDirty.get(uri);
-        const owesFlip = () => releasedDirty !== undefined && this.__releasedDirty.get(uri) === releasedDirty;
-        const announceClean = (withText = true) => {
-            if (owesFlip()) {
-                this.__releasedDirty.delete(uri);
-                // The sequence of a removed document still names the discarded text.
-                const text = !withText || workspace.LangiumDocuments.getDocument(target) === undefined ? undefined : this.textState(uri);
-                this.dirtyChangedEmitter.fire(Object.freeze(text ? { uri, text } : { uri }));
-            }
-        };
-        let parsedFromFile = false;
-        let parses;
-        let onDisk;
-        let cancelled = false;
-        let stopWaiting;
-        // Without it, a revert stopped short leaves the root on the released text.
-        const buildInstead = () => {
-            void workspace.VersionSyncService.requestRecoveryBuild(target, {
-                deleted: onDisk === false,
-                reason: HYDRANIUM_BUILD_REASONS.didClose,
-                // The update handler dropped the change it held back at the release.
-                ignoreDeferred: true,
-                stillNeeded: () => !reopened()
-            }).then(built => {
-                if (!built) {
-                    this.tracer.with(uri).error('Build after a revert that stopped short failed; the store keeps the released text');
-                    // No parse or removal is coming.
-                    stopWaiting?.();
-                    announceClean(false);
-                }
-            });
-        };
+    handOverRelease(released, cleanAnnouncement) {
+        let settled;
         try {
-            // Read before the lock: every build and read waits while the lock is
-            // held, and this read waits on the file's save I/O.
-            onDisk = await workspace.FileSystemTaskQueue.enqueue(uri, () => workspace.FileSystemProvider.exists(target));
-            await workspace.WorkspaceManager?.ready;
-            // Queuing the write cancels the running build, even when it then reverts nothing.
-            if (reopened()) {
-                return;
-            }
-            await workspace.WorkspaceLock.write(async (token) => {
-                if (reopened()) {
-                    return;
-                }
-                // Observed rather than awaited: a build cancelled after its parse
-                // returns early, and the build it yields to does not parse again.
-                parses = workspace.VersionSyncService.onDidRecordModel(document => {
-                    parsedFromFile ||= this.documentKey(document.uri.toString()) === uri;
-                });
-                workspace.DocumentBuilder.markNextReason(HYDRANIUM_BUILD_REASONS.didClose);
-                // Cleared once the build ends: a cancelled one throws, and the lock resolves.
-                cancelled = true;
-                try {
-                    await (onDisk
-                        ? workspace.DocumentBuilder.update([target], [], token)
-                        : workspace.DocumentBuilder.update([], [target], token));
-                }
-                catch (err) {
-                    if (!onDisk || !isFileNotFound(err, target)) {
-                        throw err;
-                    }
-                    // The file went after its existence was read.
-                    this.tracer.with(uri).debug('Revert found no file; removing the document instead');
-                    workspace.DocumentBuilder.markNextReason(HYDRANIUM_BUILD_REASONS.didClose);
-                    await workspace.DocumentBuilder.update([], [target], token);
-                }
-                cancelled = false;
-            });
-            // Cancelled before its parse: the write that cancelled it may build nothing.
-            if (cancelled && !parsedFromFile && !reopened() && workspace.LangiumDocuments.getDocument(target) !== undefined) {
-                buildInstead();
-            }
+            // 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) {
-            // A revert that finishes after the LSP peer went away fails its
-            // diagnostics publish, and one that runs after its workspace was torn
-            // down finds no file: teardown races, not failed reverts.
-            if (isConnectionGoneError(err) || isFileNotFound(err, target)) {
-                this.tracer.with(uri).debug(`Revert on last close skipped: ${err instanceof Error ? err.message : String(err)}`);
-                return;
+            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);
             }
-            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
-            this.tracer.with(uri).error(`Revert on last close dropped. ${detail}`);
-            // The update handler drops a change still debounced at release, so
-            // without this build the root stays behind the store's version. A
-            // document known to have no file is removed, as the revert would have.
-            if (!reopened()) {
-                buildInstead();
-            }
-        }
-        finally {
-            parses?.dispose();
-            if (parsedFromFile || workspace.LangiumDocuments.getDocument(target) === undefined) {
-                announceClean();
+        };
+        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 if (owesFlip()) {
-                // Cancelled before its parse or failed, the revert left the released
-                // text in the store: announced now, the clean flip would name it.
-                stopWaiting = () => {
-                    parsed.dispose();
-                    deleted.dispose();
-                };
-                const done = () => {
-                    stopWaiting?.();
-                    announceClean();
-                };
-                const parsed = workspace.VersionSyncService.onDidRecordModel(document => {
-                    if (this.documentKey(document.uri.toString()) === uri) {
-                        done();
-                    }
-                });
-                const deleted = workspace.DocumentBuilder.onUpdate((_changed, deletedUris) => {
-                    if (deletedUris.some(deletedUri => this.documentKey(deletedUri.toString()) === uri)) {
-                        done();
-                    }
-                });
+            else {
+                this.tracer
+                    .with(released.uri)
+                    .error(`Release handler failed. ${err instanceof Error ? (err.stack ?? err.message) : String(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,
+            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));
@@ -728,7 +521,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         }
         // What the file holds, not what the editor meant to write: an editor
         // that saved older text leaves the document dirty.
-        this.updateDiskBaseline(uri, onDisk);
+        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;
@@ -748,7 +541,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
         if (syncedDocument !== undefined) {
             if (event.text !== undefined) {
-                this.updateDiskBaseline(syncedDocument.uri, event.text);
+                this.setDiskBaseline(syncedDocument.uri, event.text);
             }
             this.announceSave(syncedDocument, clientId);
         }
@@ -761,86 +554,46 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     notifyDidOpenTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
         const td = event.textDocument;
         const uri = this.documentKey(td.uri);
-        this.resolvePendingRevert(uri, clientId);
+        // 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);
+        // 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.
+        if (clientId === LANGUAGE_CLIENT_ID) {
+            this.languageClientShadow.addOpen(uri, this.toLanguageClientUri(td.uri), td.version, td.text, document === undefined);
+        }
         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.languageClientDocuments?.has(clientFacing)) {
-                    (record.languageClientDocuments ??= new Map()).set(clientFacing, { declaredVersion: td.version });
-                    // 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);
-                }
-            }
+            // 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;
         }
-        let document = this.__syncedDocuments.get(uri);
         const existingClients = this.__sessions.clientsOf(uri);
         this.__sessions.addOpen(uri, clientId);
-        const record = this.trackingFor(uri);
-        // 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.
-            // A fresh state, since a reopened buffer numbers its versions afresh.
-            (record.languageClientDocuments ??= new Map()).set(this.toLanguageClientUri(td.uri), { declaredVersion: td.version });
-        }
+        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' base versions stay valid), one
-            // step when it changed (so no stale pointer can coincidentally pass
-            // the optimistic gate). An open with no sequence yet seeds it from the built root.
-            const sequence = this.__versionSequences.get(uri);
-            const version = sequence === undefined
-                ? this.firstOpenVersion(uri, text, td.version)
-                : sequence.contentHash === textHash(text)
-                    ? sequence.version
-                    : sequence.version + 1;
+            const version = this.textLedger.openingVersion(uri, text) ?? this.builtRootOpeningVersion(uri, text) ?? td.version;
             this.log(uri, `Open document: Version ${version} by ${this.formatClientId(clientId)} [first client${source}]`);
-            document = this.configuration.create(uri, td.languageId, version, text);
-            this.__syncedDocuments.set(uri, document);
-            this.setAuthor(uri, version, clientId);
+            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.
-            record.diskBaseline = td.text;
-            if (this.__releasedDirty.delete(uri)) {
-                record.dirty = true;
-            }
-            this.refreshDirty(uri);
-            if (clientId === LANGUAGE_CLIENT_ID) {
-                // Baseline the shadow to what Monaco just opened so the next outbound
-                // applyEditToLanguageClient diffs against the right starting point. Keyed by the
-                // language-client URI (what Monaco holds), not the canonical document key.
-                //
-                // The CLIENT's declared text, never the synced document: staged content
-                // consumed above leaves the two different, and a baseline asserting the
-                // client already holds the staged text suppresses the one sync that would
-                // deliver it. Skipped entirely when a push is already outstanding for this
-                // URI — an `applyEdit` to a closed file has the client open from disk and
-                // apply afterwards, so that shadow records what it is about to hold and
-                // disk text would key the next diff to a buffer nobody has.
-                const clientFacing = this.toLanguageClientUri(td.uri);
-                if (!this.__shadow.isTracked(clientFacing)) {
-                    this.__shadow.set(clientFacing, td.text);
-                }
-            }
+            this.dirtyStateTracker.track(uri, document, td.text);
             const toFire = Object.freeze({ document, clientId });
             this.__onDidOpen.fire(toFire);
             this.__onDidChangeContent.fire(toFire);
@@ -848,14 +601,6 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         else {
             // An additional client attaches to a document already open by another client.
             this.logClientJoined(uri, clientId, document.version, existingClients);
-            if (clientId === LANGUAGE_CLIENT_ID) {
-                // Monaco's own buffer, which on this path is NOT the synced text — another
-                // client opened the document and may already have changed it. Recorded as
-                // an equality-only baseline (never a diff one, see `setOpenedText`) so the
-                // refresh below does not push a full replace of content Monaco already
-                // holds, which would dirty the file on open.
-                this.__shadow.setOpenedText(this.toLanguageClientUri(td.uri), td.text);
-            }
             this.refreshContent(uri, clientId);
         }
     }
@@ -869,52 +614,31 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * and refreshing per attach turns each into a Langium rebuild and dependent
      * relink cascade.
      *
-     * The staleness guard baselines at the SYNCED version, not a declared buffer
-     * version, because a client arriving this way holds no buffer of its own.
-     * Unifying the two routes therefore rebaselines a textual client's guard to a
-     * version it never declared.
-     *
      * Returns whether a hold was added — `false` when `uri` is not open,
-     * `clientId` already holds it, or the document was waiting out the revert
+     * `clientId` already holds it, or the document was waiting out the release
      * grace for other clients and was released instead (see
-     * {@link resolvePendingRevert}); the caller then opens it anew.
+     * {@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;
         }
-        this.resolvePendingRevert(key, clientId);
+        // 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);
-        const record = this.trackingFor(key);
-        record.clientVersions.set(clientId, document.version);
+        // 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;
     }
-    /**
-     * The built root's recorded version, one on when `text` differs from the root's;
-     * `declared` when the root records no store version. Seeded from `declared`, a write based
-     * on the root passes the gate over other text, and the same text looks newer than its model.
-     * A built root has no sequence only under a `LangiumDocuments` that does not reconcile at registration.
-     */
-    firstOpenVersion(uri, text, declared) {
-        const built = this.services.workspace.LangiumDocuments.getDocument(UriUtils.toUri(uri));
-        if (built === undefined) {
-            return declared;
-        }
-        const ledger = this.services.workspace.ModelLedger;
-        const root = built.parseResult.value;
-        const recorded = ledger.versionOf(root);
-        if (recorded === UNRECORDED_VERSION || recorded === STALE_VERSION) {
-            return declared;
-        }
-        return (ledger.textOf(root) ?? built.textDocument.getText()) === text ? recorded : recorded + 1;
-    }
     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(', ')})`);
@@ -935,7 +659,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 DocumentTrackingRecord.languageClientDocuments}). The
+     * for egress addressing, by the {@link LanguageClientShadow}. The
      * policy is always bound (the framework defaults it to
      * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
      */
@@ -953,17 +677,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 = { 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
@@ -994,7 +709,14 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * 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));
     }
     /**
      * The text the store holds for `uri`: an open document's, or for a closed
@@ -1005,28 +727,36 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     textState(uri) {
         const document = this.get(uri);
         if (document) {
-            return { version: document.version, hash: this.heldTextHash(document), dirty: this.isDirty(uri) };
+            return { version: document.version, hash: this.textLedger.hashOf(document), dirty: this.isDirty(uri) };
         }
-        const sequence = this.__versionSequences.get(this.documentKey(uri));
-        return sequence && { version: sequence.version, hash: sequence.contentHash, dirty: false };
+        const recorded = this.textLedger.recordOf(this.documentKey(uri));
+        return recorded && { version: recorded.version, hash: recorded.hash, dirty: false };
     }
     /**
-     * {@link textHash} of `document`'s text, taken once per version: the store
-     * moves a document's version with every change of its text.
+     * 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.
      */
-    heldTextHash(document) {
-        const taken = this.__textHashes.get(document);
-        if (taken?.version === document.version) {
-            return taken.hash;
+    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;
         }
-        const hash = textHash(document.getText());
-        this.__textHashes.set(document, { version: document.version, hash });
-        return hash;
+        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 (`VersionSyncService.modelProduced`) —
@@ -1047,19 +777,12 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         if (open !== undefined) {
             return open.getText() === text ? open.version : undefined;
         }
-        const hash = textHash(text);
-        const sequence = this.__versionSequences.get(key);
-        if (sequence === undefined) {
-            this.__versionSequences.set(key, { version: 0, contentHash: hash });
-            return 0;
+        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');
         }
-        if (hash === sequence.contentHash) {
-            return sequence.version;
-        }
-        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;
+        return version;
     }
     /**
      * Commit an integrity repair into the OPEN document for `uri`, returning the
@@ -1106,18 +829,14 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         // Reassigned rather than mutated in place: the default configuration
         // updates and returns the SAME instance, but an adopter-supplied one may
         // return a new object, and the store must end up holding whichever it is.
-        const updated = this.configuration.update(document, [{ text: repaired }], document.version + 1);
-        this.__syncedDocuments.set(key, updated);
-        this.setAuthor(key, updated.version, INTEGRITY_CLIENT_ID);
-        this.refreshDirty(key);
+        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}.`);
@@ -1133,8 +852,10 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * `onDidClose` event fires for the last client, so `isOpen` returns `true`
      * during the close event itself. `isOpenInAnyClient` reads the open table
      * ({@link __sessions}), which is updated BEFORE the fire, so an `onDidClose`
-     * subscriber that finds this `false` knows the last client just closed and a
-     * disk re-read / rebuild can proceed.
+     * 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.__sessions.isOpen(this.documentKey(uri));
@@ -1175,12 +896,12 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     }
     /**
      * Fires once a document no client has open is released: at its last close,
-     * or, for a lost client's last close, when its revert grace runs out,
-     * another client opens it, or it is deleted. The document then reverts to
-     * disk.
+     * 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 onDidCloseLastOpen() {
-        return this.lastOpenClosedEmitter.event;
+    get onDidReleaseDocument() {
+        return this.documentReleasedEmitter.event;
     }
     /**
      * Fires for every save the language client reports of a document it has
@@ -1191,18 +912,18 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         return this.languageClientSavedEmitter.event;
     }
     /**
-     * Whether `uri` is waiting out the revert grace: its last open closed with a
+     * 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.
      */
-    isRevertPending(uri) {
-        return this.__sessions.isRevertPending(this.documentKey(uri));
+    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 revert grace is still
+     * 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,
@@ -1211,30 +932,29 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * must know the file reads it instead.
      */
     isDirty(uri) {
-        return this.__documents.get(this.documentKey(uri))?.dirty ?? false;
+        return this.dirtyStateTracker.isDirty(this.documentKey(uri));
     }
     /**
-     * Fires each time the answer of {@link isDirty} changes. A dirty document's
-     * release fires once a parse of the file reaches the store, at that text's
-     * version, or without text once its revert removed the document or could
-     * not rebuild it, though {@link isDirty} answers clean from the release on.
+     * 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.dirtyChangedEmitter.event;
+        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.
      */
-    updateDiskBaseline(uri, text) {
+    setDiskBaseline(uri, text) {
         const key = this.documentKey(uri);
-        const record = this.__documents.get(key);
-        if (!record || !this.__syncedDocuments.has(key)) {
-            return;
+        const document = this.__syncedDocuments.get(key);
+        if (document !== undefined) {
+            this.dirtyStateTracker.setDiskBaseline(key, document, text);
         }
-        record.diskBaseline = text;
-        this.refreshDirty(key);
     }
     /**
      * Read the file behind `uri` through its disk queue and take it as the
@@ -1253,20 +973,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         catch (err) {
             this.tracer.with(key).debug(`Disk baseline: the file cannot be read. ${err instanceof Error ? err.message : String(err)}`);
         }
-        this.updateDiskBaseline(key, onDisk);
-    }
-    /** Compare the held text of `uri` with its baseline, and announce a changed answer. */
-    refreshDirty(uri) {
-        const record = this.__documents.get(uri);
-        const document = this.__syncedDocuments.get(uri);
-        if (!record || !document) {
-            return;
-        }
-        const dirty = document.getText() !== record.diskBaseline;
-        if (dirty !== (record.dirty ?? false)) {
-            record.dirty = dirty;
-            this.dirtyChangedEmitter.fire(Object.freeze({ uri, text: { version: document.version, hash: this.heldTextHash(document), dirty } }));
-        }
+        this.setDiskBaseline(key, onDisk);
     }
     /**
      * Start a client session under `clientId`. Throws where
@@ -1300,7 +1007,7 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     }
     /**
      * Close every document the language client has open, as a `didClose` for
-     * each would, so each last close reverts. For a host whose editor connection
+     * 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.
      *
@@ -1312,7 +1019,8 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     async closeLanguageClientDocuments() {
         await this.initialBuildFinished();
         for (const uri of this.__sessions.opensOf(LANGUAGE_CLIENT_ID)) {
-            this.untrackLanguageClientDocuments(uri);
+            // A close for one URI while others remain keeps the client's hold.
+            this.languageClientShadow.removeAllOpens(uri);
             this.notifyDidCloseTextDocument({ textDocument: { uri } });
         }
     }
@@ -1326,20 +1034,6 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
     async initialBuildFinished() {
         await this.services.workspace.WorkspaceManager.workspaceInitialized.catch(() => undefined);
     }
-    /**
-     * Stop tracking every URI the language client holds the document `key`
-     * under, with its shadow and pending pushes. Call before a close by
-     * canonical key that means all of them: a close for one URI while others
-     * remain drops only that URI's and keeps the client's hold.
-     */
-    untrackLanguageClientDocuments(key) {
-        const languageClientDocuments = this.__documents.get(key)?.languageClientDocuments;
-        for (const clientUri of languageClientDocuments?.keys() ?? []) {
-            this.__shadow.invalidate(clientUri);
-            this.__pendingPushes.delete(clientUri);
-        }
-        languageClientDocuments?.clear();
-    }
     /**
      * The file behind `uri` was deleted: close every open of it except the
      * language client's.
@@ -1368,14 +1062,14 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      */
     delete(uri) {
         const key = this.documentKey((typeof uri === 'object' && 'uri' in uri ? uri.uri : uri).toString());
-        this.untrackLanguageClientDocuments(key);
+        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.
-        if (this.__sessions.isRevertPending(key)) {
-            this.__sessions.cancelRevert(key);
+        if (this.documentReleaseScheduler.isDeferred(key)) {
+            this.documentReleaseScheduler.cancel(key);
             this.releaseDocument(key);
         }
         super.delete(key);
@@ -1402,13 +1096,12 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      * Only a FIRST open consumes it, so stage only for a URI no client holds
      * ({@link isOpenInAnyClient} is `false`). A URI held only through another
      * head is not closed: an editor attaching to it joins the existing entry and
-     * never reads the stage, and the last close discards the stage with the
-     * tracking record. An entry lingers only if `workspace/applyEdit` fails and
-     * the file is never opened — the memory cost is one serialised string per
-     * URI.
+     * never reads the stage, and the release discards it. An entry lingers
+     * only if `workspace/applyEdit` fails and the file is never opened — the
+     * memory cost is one serialised string per URI.
      */
     stagePendingContent(uri, text) {
-        this.trackingFor(this.documentKey(uri)).pendingContent = text;
+        this.__pendingContent.set(this.documentKey(uri), text);
     }
     /**
      * Send `newText` to the LSP textual language client (Monaco / VS Code) via
@@ -1427,20 +1120,19 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
      *
      * 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 known version for that URI (see
-     * {@link languageClientVersion}) 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.
      */
@@ -1449,38 +1141,19 @@ export class HydraniumTextDocuments extends NormalizedTextDocuments {
         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))?.languageClientDocuments;
-        const targets = recorded && recorded.size > 0 ? [...recorded.keys()] : [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 the baseline and drops
-            // the opened snapshot. This is the text the client holds, and
-            // therefore the only text its echo of this push can be reconstructed
-            // against — whether or not the push below is keyed to it.
-            const before = this.__shadow.clientText(targetUri);
-            const edits = this.__shadow.computeEdits(targetUri, newText);
-            if (edits.length === 0) {
+        for (const clientUri of this.languageClientShadow.pushTargets(key, this.toLanguageClientUri(uri))) {
+            // 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, targetUri);
-                // Captured before the await: a reopen replaces the state, so a late
-                // reply then writes to the old one instead of the new buffer's.
-                const languageClientDocument = recorded?.get(targetUri);
                 // A full `ApplyWorkspaceEditParams`, `edit` and all — NOT a bare
                 // `WorkspaceEdit` with a `label` beside it. `applyEdit` takes
                 // `ApplyWorkspaceEditParams | WorkspaceEdit` and discriminates on
@@ -1490,180 +1163,45 @@ 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);
-                    if (version !== UNKNOWN_CLIENT_VERSION) {
-                        this.tracer
-                            .with(uri)
-                            .warn(`Language client refused applyEdit addressed at version ${version} (it last declared version ${languageClientDocument?.declaredVersion})`);
-                    }
+                    push.notifyOutcome('refused');
                 }
-                else if (result?.applied && version !== UNKNOWN_CLIENT_VERSION && languageClientDocument) {
-                    // A client steps once per applied edit that changes its buffer. A
-                    // line edit does while the shadow is right; a full replace may be a
-                    // no-op the client drops. Left to the echo, a push sent first is
-                    // refused; advanced after a no-op, one could pass at a version a
-                    // keystroke reached.
-                    languageClientDocument.pushedVersion = version + 1;
+                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 holds `uri` at under
-     * `targetUri`, 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` for `targetUri`, or the
-     * one an applied push moved it to ahead of the push's echo
-     * ({@link LanguageClientDocumentState}) — 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 not opened
-     * the document under `targetUri`, which is the honest answer. 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.
-     */
-    languageClientVersion(uri, targetUri = this.toLanguageClientUri(uri)) {
-        const state = this.__documents.get(this.documentKey(uri))?.languageClientDocuments?.get(targetUri);
-        if (state === undefined) {
-            return UNKNOWN_CLIENT_VERSION;
-        }
-        return Math.max(state.declaredVersion, state.pushedVersion ?? state.declaredVersion);
-    }
-    /**
-     * 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: textHash(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 text its ranges
-     * address — the pre-push buffer of the OLDEST push still in flight for
-     * `clientFacing`, else whatever that client is believed to hold.
-     *
-     * `undefined` when the client's ranges address the synced text itself —
-     * nothing in flight, and no evidence the client holds anything else. That
-     * is the ordinary path, and the caller then applies the ranges directly.
-     * The two texts part company without a push in flight whenever a client
-     * attaches to a document another client has already written: it opened
-     * from disk, so applying its ranges to the synced text splices lines they
-     * never addressed.
-     *
-     * **Why the oldest, and why reconstruct at all.** The client applies our
-     * pushes in order and echoes each against the buffer it held before that
-     * 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 queued = this.__pendingPushes.get(clientFacing);
-        const pending = queued?.length ? queued : undefined;
-        // The text the client's ranges address: the buffer it held before the
-        // oldest push still in flight, else the buffer it is believed to hold.
-        const clientText = pending?.[0].before ?? this.__shadow.clientText(clientFacing);
-        if (pending === undefined && (clientText === undefined || clientText === document.getText())) {
-            return undefined;
-        }
-        if (pending !== undefined && pending[0].before === undefined && changes.some(change => ContentChange.isIncremental(change))) {
-            // A push sent to a client whose buffer was unknown — a first sync, or
-            // the recovery push after a rejection. The shadow now holds the text
-            // that push MOVES the client to, which is the one text the echo's
-            // ranges provably do not address, so the fallback above is a baseline
-            // known to be wrong rather than merely unverified. Drop the queue and
-            // the shadow: the next sync is then a full replace, which lands on
-            // whatever the client holds. A full-text change is exempt because it
-            // reconstructs identically against any baseline.
-            pending.length = 0;
-            this.__shadow.invalidate(clientFacing);
-            return { kind: 'unreconstructable' };
-        }
-        // Through the configured factories, not `TextDocument` directly, so an
-        // adopter's custom text-document type governs how the ranges are applied
-        // here exactly as it does on the synced document.
-        const probe = this.create(clientFacing, document.languageId, 0, clientText ?? document.getText());
-        const reconstructed = this.update(probe, changes, 0).getText();
-        if (pending !== undefined) {
-            const matchIndex = pending.findIndex(push => push.afterHash === textHash(reconstructed));
-            if (matchIndex >= 0) {
-                pending.splice(0, matchIndex + 1);
-                return { kind: 'echo' };
-            }
-            pending.length = 0;
-        }
-        return { kind: 'divergent', text: reconstructed };
-    }
-    /**
-     * Explicitly baseline the language-client text shadow for a URI. Useful in
+     * Explicitly baseline the language-client 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.
      */
     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);
+        this.languageClientShadow.setClientText(this.toLanguageClientUri(uri), text);
     }
     /** 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.invalidateClientText(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) {