@hydranium/core 1.0.0-next.27 → 1.0.0-next.271

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

@@ -20,7 +20,7 @@
 // on lsp-server, contradicting the peer architecture.
 // eslint-disable-next-line @typescript-eslint/no-restricted-imports
 import { NormalizedTextDocuments } from '@hydranium/langium/lsp';
-import { UriUtils } from '@hydranium/langium';
+import { type URI, UriUtils } from '@hydranium/langium';
 import { type ServerSharedServices } from '../langium/module.js';
 import {
    type ApplyWorkspaceEditResult,
@@ -31,7 +31,7 @@ import {
    type DidOpenTextDocumentParams,
    type DidSaveTextDocumentParams,
    type Disposable,
-   type Emitter,
+   Emitter,
    type Event,
    type HandlerResult,
    OptionalVersionedTextDocumentIdentifier,
@@ -45,10 +45,33 @@ import {
    type WillSaveTextDocumentParams
 } from 'vscode-languageserver';
 import { type DocumentUri, TextDocument, type TextDocumentContentChangeEvent } from 'vscode-languageserver-textdocument';
-import { type CanonicalUri, type LanguageClientUri, asLanguageClientUri, DisposableCollection, type Tracer } from '@hydranium/protocol';
+import {
+   type CanonicalUri,
+   type LanguageClientUri,
+   asLanguageClientUri,
+   DisposableCollection,
+   type TextState,
+   type TextVersion,
+   STALE_VERSION,
+   type Tracer,
+   UNRECORDED_VERSION,
+   describeError,
+   describeErrorWithStack
+} from '@hydranium/protocol';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
 import { LANGUAGE_CLIENT_ID } from './client-ids.js';
-import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
+import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
+import { type ClientSessionClosedEvent, ClientSessionRegistry, type SessionEndCause } from './client-session-registry.js';
+import { DefaultLanguageClientShadow, type LanguageClientChangeVerdict, type LanguageClientShadow } from './language-client-shadow.js';
+import { DefaultTextLedger, type TextLedger } from './text-ledger.js';
+import { isDocumentReleaseSkippedError, type ReleasedDocument } from './document-release-handler.js';
+import { DefaultDocumentReleaseScheduler, type DocumentReleaseScheduler } from './document-release-scheduler.js';
+import {
+   type CleanAnnouncement,
+   DefaultDirtyStateTracker,
+   type DirtyStateTracker,
+   type DocumentDirtyChangedEvent
+} from './dirty-state-tracker.js';
 
 /**
  * The LSP spec's "version is intentionally unknown" for an
@@ -74,47 +97,39 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
     * Adopters with a custom text-document type (rare) pass their factory.
     */
    readonly configuration?: TextDocumentsConfiguration<T>;
+   /**
+    * How long a document whose last open closed because its client's
+    * connection was lost keeps its text before the store releases it. An open
+    * by a client lost from the document, within this time of its own loss,
+    * cancels the release, so a client that registers again under its id after
+    * a dropped connection finds its unsaved edits. Any other open releases the
+    * document first and then opens it as a first open does, from the text the
+    * opener supplies (an editor's own) or else from the file. Meanwhile the
+    * document counts as open for the integrity service, which therefore writes
+    * none of its unsaved text to disk. A close the client makes itself, or
+    * ending its session, releases at once whatever this is.
+    *
+    * Defaults to 10 s. `0` releases such a document at once as well, in the
+    * close itself rather than on a timer.
+    */
+   readonly releaseGraceMs?: number;
 }
 
 /**
- * All per-URI client-facing tracking the manager keys by normalized URI,
- * collapsed into one record so a URI's full state lives in one place and the
- * last-client close clears every axis in a single delete. (Parallel per-axis
- * maps are the substrate of a close-on-stale-state desync — one map can be
- * cleared while another lingers.)
- *
- * Two neighbours deliberately stay separate:
- *  - The inherited `__syncedDocuments` (Langium's parsed `TextDocument` store).
- *  - {@link LanguageClientTextShadow} (`__shadow`), a self-contained,
- *    separately-tested diff/apply-verify abstraction that owns its own baseline
- *    text; folding its storage here would couple a clean utility to this record
- *    for no real gain.
+ * 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.
  */
-interface DocumentTracking {
-   /** Client ids currently holding this document open (multi-client membership). */
-   readonly clients: Set<string>;
-   /** Author of each version, sparse-indexed by the SHARED (server-assigned) version number. */
-   readonly versionAuthors: string[];
-   /**
-    * Last version id each client declared for this document (didOpen baseline,
-    * advanced by every accepted didChange). Client version ids are CLIENT-owned
-    * per LSP (Monaco numbers its own buffer) and are used ONLY for this
-    * per-client staleness guard — they never leak into the shared version
-    * sequence, which the server assigns (see {@link HydraniumTextDocuments.__versionSequences}).
-    */
-   readonly clientVersions: Map<string, number>;
-   /** Content staged by integrity rules for a closed document. Consumed on next open. */
-   pendingContent?: string;
-   /**
-    * The URI(s) the LSP textual language client opened this (canonically-keyed)
-    * document under. Usually one; a set because the same physical file can be
-    * opened under more than one URI (a symlink path and its real path). This is
-    * the egress address: `applyEditToLanguageClient`
-    * targets these, since the document is *keyed* by its canonical identity but
-    * Monaco holds it under the URI it opened. Lifecycle-bound — cleared with the
-    * record on last close.
-    */
-   languageClientUris?: Set<LanguageClientUri>;
+const DEFAULT_RELEASE_GRACE_MS = 10_000;
+
+/** Delivered by {@link HydraniumTextDocuments.onDidSaveInLanguageClient}. */
+export interface LanguageClientSavedEvent {
+   readonly uri: string;
+}
+
+/** Delivered by {@link HydraniumTextDocuments.onDidReleaseDocument}. */
+export interface DocumentReleasedEvent {
+   readonly uri: CanonicalUri;
 }
 
 /**
@@ -129,25 +144,20 @@ export interface OpenDocument {
 }
 
 /**
- * Where a URI's shared version sequence left off — written once at last-client
- * close, consulted at the next open so the sequence CONTINUES instead of
- * restarting at whatever version id the reopening client declares. One entry
- * of {@link HydraniumTextDocuments.__versionSequences}.
- */
-interface VersionSequence {
-   /** The shared version at last-client close. */
-   readonly version: number;
-   /** {@link contentHash} of the synced text at last-client close. */
-   readonly contentHash: string;
-}
-
-/**
- * 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.
+ * What {@link HydraniumTextDocuments.commitRepair} did with an integrity repair.
+ *
+ * Three outcomes rather than a document-or-nothing, because the two ways of
+ * getting nothing call for opposite responses: `not-open` means there is no
+ * store document to correct and the caller carries on with the one it holds,
+ * while `stale` means there IS one and it has moved past the text the repair
+ * was computed against — so carrying on would persist a correction over an edit
+ * that superseded it. Collapsing them lets the second read as permission to
+ * proceed, which is the failure this shape exists to make unrepresentable.
  */
-const PENDING_ECHO_CAP = 32;
+export type RepairCommit<T extends TextDocument> =
+   | { readonly status: 'committed'; readonly document: T }
+   | { readonly status: 'stale' }
+   | { readonly status: 'not-open' };
 
 /**
  * The one field of `vscode-languageserver`'s `Connection` this class has to
@@ -159,182 +169,137 @@ interface ConnectionWithTextDocumentSync {
 }
 
 /**
- * One text pushed to the LSP textual language client by
- * {@link HydraniumTextDocuments.applyEditToLanguageClient} whose echo has not
- * come back yet. One entry of {@link HydraniumTextDocuments.__pendingPushes}.
- */
-interface PendingPush {
-   /**
-    * The text the client held BEFORE this push — the shadow baseline the
-    * push's edits were diffed against, and therefore the text the client's
-    * echo addresses with its ranges.
-    *
-    * `undefined` when the push was a full replace sent with no baseline (a
-    * first sync, or the recovery push after a rejection). There is then no
-    * knowing what the client held, so the echo is reconstructed against the
-    * synced text instead — which is sound for a full replace, whose
-    * application is position-independent.
-    */
-   readonly before: string | undefined;
-   /** {@link contentHash} of the text this push moves the client to. */
-   readonly afterHash: string;
-}
-
-/**
- * What an incoming language-client change turns out to be once reconstructed
- * against the pushes still in flight — the return of
- * {@link HydraniumTextDocuments.classifyLanguageClientChange}.
- */
-type LanguageClientChangeOrigin =
-   /** The client is reporting a text we pushed it. The synced document is already there. */
-   | { readonly kind: 'echo' }
-   /**
-    * The client's buffer has moved somewhere we did not push it — it coalesced
-    * a genuine keystroke into the echo, or typed before the push arrived. The
-    * reconstructed text is what it now holds, and is authoritative.
-    */
-   | { readonly kind: 'divergent'; readonly text: string };
-
-/**
- * Cheap, stable, non-cryptographic content hash (cyrb53) for the version
- * sequence's "did the content change across close/reopen?" question. Only
- * needs to be collision-resistant enough that an accidental match across two
- * DIFFERENT revisions of the same file is practically impossible; 53 bits of
- * a well-mixed hash over full text + length gives that without pulling in
- * `node:crypto` (this module must stay runnable in browser hosts).
- */
-function contentHash(text: string): string {
-   let h1 = 0xdeadbeef;
-   let h2 = 0x41c6ce57;
-   for (let index = 0; index < text.length; index++) {
-      const code = text.charCodeAt(index);
-      h1 = Math.imul(h1 ^ code, 2654435761);
-      h2 = Math.imul(h2 ^ code, 1597334677);
-   }
-   h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
-   h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
-   h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
-   h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
-   return `${(4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36)}:${text.length}`;
-}
-
-/**
- * Multi-client text-document tracking on top of Langium's `NormalizedTextDocuments`.
+ * The one text store every head writes to, on top of Langium's
+ * `NormalizedTextDocuments`, and the LSP text-sync endpoint: every
+ * `textDocument/*` notification and every `workspace/applyEdit` push goes
+ * through here.
  *
- * Adds the framework features used by the integrity, model-server, and GLSP layers:
- *   - Per-document client membership (multiple clients can attach to the same URI).
- *   - A SERVER-OWNED shared version sequence: per-URI, monotonic across
- *     close/reopen cycles, advancing exactly when the synced content changes.
- *     Client-declared version ids (Monaco's buffer numbering) feed only a
- *     per-client staleness guard and never leak into the shared sequence —
- *     the two are different things (an editor's edit-operation counter vs the
- *     document's content-revision number), and splicing them lets versions drift
- *     silently past `baseVersion` gate holders.
- *   - Version-author history so each edit is attributable to its originating client.
- *   - Pending-content staging used by the integrity service to thread corrections
- *     through `workspace/applyEdit` cycles for currently-closed documents.
- *   - `didOpen` notifications arriving over the LSP connection wait on the
- *     workspace-ready promise, so a client's first open cannot race workspace
- *     discovery. Direct {@link notifyDidOpenTextDocument} calls (the non-LSP
- *     heads) do not pass that gate — their caller owns the ordering.
+ * 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<T extends TextDocument = TextDocument> extends NormalizedTextDocuments<T> {
-   /**
-    * Per-URI client-facing tracking ({@link DocumentTracking}): client
-    * membership, version-author history, and integrity-staged pending content,
-    * keyed by normalized URI. One record per URI so the last-client close clears
-    * every axis atomically. The language-client diff baseline stays in
-    * {@link __shadow} (its own abstraction); the parsed-document store stays in
-    * the inherited `__syncedDocuments`.
-    */
-   protected __documents = new Map<CanonicalUri, DocumentTracking>();
+   /** Content staged by integrity rules for a document no client holds, consumed by its first open. */
+   protected readonly __pendingContent = new Map<CanonicalUri, string>();
 
    /**
-    * Per-URI shared-version continuity across close/reopen cycles
-    * ({@link VersionSequence}), written at last-client close and consulted by
-    * the next first-client open. DELIBERATELY outside {@link DocumentTracking}:
-    * that record is deleted on last close, while the version sequence must
-    * survive it — the shared version is a server-owned, monotonic,
-    * advances-iff-content-changes counter that never resets while the server
-    * lives. That invariant is what makes an optimistic `baseVersion` gate
-    * sound: "version unchanged ⇔ content unchanged", with no false conflicts
-    * from close/reopen version resets and no false passes from a reopened
-    * sequence coincidentally landing on a stale writer's number.
-    *
-    * Never pruned: two small values per URI ever touched — bounded by
-    * workspace size, not by activity.
+    * 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.
     */
-   protected readonly __versionSequences = new Map<CanonicalUri, VersionSequence>();
+   protected readonly __sessions = new ClientSessionRegistry();
 
-   /**
-    * Texts pushed to the LSP textual language client via
-    * {@link applyEditToLanguageClient} whose echoes have not come back yet
-    * ({@link PendingPush}), keyed like the shadow by language-client URI.
-    * Outbound pushes and inbound echoes are uncorrelated on the wire; this
-    * FIFO is the explicit correlation, and it is what
-    * {@link classifyLanguageClientChange} reconstructs against.
-    *
-    * **Each entry keeps the client's PRE-push text, not only a hash of the
-    * post-push one.** A hash alone can classify a full-text echo, whose
-    * application is a no-op either way — and that is all it ever classified,
-    * because a conforming client echoes INCREMENTAL ranges keyed to its
-    * previous buffer. Those ranges cannot be applied to the synced text (which
-    * the authored write already advanced) and cannot be reconstructed without
-    * the baseline: the line they insert lands twice, validates cleanly, and
-    * compounds on every later edit.
-    *
-    * Lifecycle: entries are consumed by the matching echo (together with any
-    * older entries it supersedes), and the whole queue drops when the client
-    * stops being a pure mirror — a divergent change, an `applyEdit`
-    * failure/rejection (shadow invalidation), a close, or an explicit
-    * shadow (re)baseline. {@link PENDING_ECHO_CAP} bounds the queue against
-    * a pathological echo that never arrives; the memory cost until then is
-    * one pre-push text per in-flight push, for milliseconds.
-    */
-   protected readonly __pendingPushes = new Map<LanguageClientUri, PendingPush[]>();
-
-   /**
-    * 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).
-    */
-   protected readonly __shadow: LanguageClientTextShadow;
+   /** The version each open document was opened at; see {@link openedVersion}. */
+   protected readonly __openedVersions = new Map<CanonicalUri, TextVersion>();
 
    protected readonly tracer: Tracer;
    protected readonly configuration: TextDocumentsConfiguration<T>;
+   protected __textLedger: TextLedger | undefined;
+   protected __languageClientShadow: LanguageClientShadow | undefined;
+   protected __dirtyStateTracker: DirtyStateTracker | undefined;
+   protected __documentReleaseScheduler: DocumentReleaseScheduler | undefined;
+   protected readonly documentReleasedEmitter = new Emitter<DocumentReleasedEvent>();
+   protected readonly languageClientSavedEmitter = new Emitter<LanguageClientSavedEvent>();
 
    constructor(
       protected services: ServerSharedServices,
-      options: HydraniumTextDocumentsOptions<T> = {}
+      protected readonly options: HydraniumTextDocumentsOptions<T> = {}
    ) {
       const configuration = options.configuration ?? (TextDocument as unknown as TextDocumentsConfiguration<T>);
       super(configuration);
       this.configuration = configuration;
       this.tracer = services.Tracer.for(options.logName ?? 'TextDocuments').trace('instantiated');
-      this.__shadow = new LanguageClientTextShadow(
-         (uri, reason) => this.tracer.with(uri).warn(`Diff apply-verify fallback (${reason}) — using full-document replace`),
-         this
-      );
    }
 
-   // Re-exposed configuration factories — for framework-internal callers
-   // (LanguageClientTextShadow's apply-verify probe; IntegrityService.resyncDocument)
-   // that need to materialise documents outside the canonical didOpen/didChange flow
-   // and must respect the adopter's custom text-document type.
+   // Each collaborator is built on first use, after every constructor has run,
+   // so a create method may read its subclass's fields and the other collaborators.
+
+   protected get textLedger(): TextLedger {
+      return (this.__textLedger ??= this.createTextLedger());
+   }
+
+   protected get languageClientShadow(): LanguageClientShadow {
+      return (this.__languageClientShadow ??= this.createLanguageClientShadow());
+   }
+
+   protected get dirtyStateTracker(): DirtyStateTracker {
+      return (this.__dirtyStateTracker ??= this.createDirtyStateTracker());
+   }
+
+   protected get documentReleaseScheduler(): DocumentReleaseScheduler {
+      return (this.__documentReleaseScheduler ??= this.createDocumentReleaseScheduler());
+   }
+
+   protected createTextLedger(): TextLedger {
+      return new DefaultTextLedger();
+   }
+
+   protected createLanguageClientShadow(): LanguageClientShadow {
+      return new DefaultLanguageClientShadow(this, this.tracer);
+   }
+
+   protected createDirtyStateTracker(): DirtyStateTracker {
+      return new DefaultDirtyStateTracker(this.textLedger);
+   }
+
+   protected createDocumentReleaseScheduler(): DocumentReleaseScheduler {
+      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`. */
+   protected commitText(key: CanonicalUri, document: T, author: string): void {
+      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.
+    */
+   protected commitChange(
+      key: CanonicalUri,
+      document: T,
+      changes: TextDocumentContentChangeEvent[],
+      author: string
+   ): { document: T; changed: boolean } {
+      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.
 
    public create(uri: string, languageId: string, version: number, content: string): T {
       return this.configuration.create(uri, languageId, version, content);
@@ -403,7 +368,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       const disposables = new DisposableCollection();
       disposables.push(
          connection.onDidOpenTextDocument(async (event: DidOpenTextDocumentParams) => {
-            await this.services.workspace.WorkspaceManager.workspaceInitialized;
+            await this.initialBuildFinished();
             this.notifyDidOpenTextDocument(event);
          })
       );
@@ -429,7 +394,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       );
       disposables.push(
          connection.onDidSaveTextDocument((event: DidSaveTextDocumentParams) => {
-            this.notifyDidSaveTextDocument(event);
+            void this.notifyLanguageClientSave(event);
          })
       );
       return disposables;
@@ -450,84 +415,66 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       const uri = this.documentKey(td.uri);
       let document = this.__syncedDocuments.get(uri);
       if (document !== undefined) {
-         // Per-client staleness guard: client version ids are CLIENT-owned per
-         // LSP (Monaco numbers its own buffer), so an incoming id is compared
-         // against THAT client's last declared id — never against the shared
-         // version, which the server assigns and which routinely runs ahead of
-         // a client's ids (authored ModelService writes advance it without the
-         // client knowing). Gating on the shared version drops real edits in
-         // exactly that lag window. A client with no baseline (never opened —
-         // a protocol anomaly) falls back to the shared-version compare, the
-         // conservative answer.
-         const record = this.trackingFor(uri);
-         const lastSeen = record.clientVersions.get(clientId) ?? document.version;
+         // Client version ids are the client's own, so compared against what
+         // that client declared, never against the shared version: an authored
+         // write advances that without the client knowing, and gating on it
+         // drops real edits. The editor is checked per URI, since each is its
+         // own buffer; its client-wide entry is only the fallback for a URI it
+         // never opened, and may name another URI's buffer. A client with no
+         // baseline falls back to the shared version.
+         const clientUri = this.toLanguageClientUri(td.uri);
+         const editor = clientId === LANGUAGE_CLIENT_ID;
+         const lastSeen =
+            (editor ? this.languageClientShadow.declaredVersion(uri, clientUri) : undefined) ??
+            this.__sessions.clientVersionOf(uri, clientId) ??
+            document.version;
          if (lastSeen >= td.version) {
             // Distinguish "already at this version" (common: an echo from the client that triggered
             // the update) from "incoming version older than ours" (stale race).
             const reason =
                lastSeen === td.version ? `already at version ${lastSeen}` : `incoming version ${td.version} older than current ${lastSeen}`;
-            this.logUri(uri, `Ignore update by ${clientId}: ${reason}`, 'debug');
+            this.logUri(uri, `Ignore update by ${this.formatClientId(clientId)}: ${reason}`, 'debug');
             return;
          }
-         record.clientVersions.set(clientId, td.version);
-
-         // A language-client change arriving while one of our own pushes is in
-         // flight is keyed to the buffer the client held BEFORE that push, NOT
-         // to the synced text — the authored write already advanced the latter.
-         // Resolve which it is, and against what, before touching anything.
-         const inFlight =
-            clientId === LANGUAGE_CLIENT_ID
-               ? this.classifyLanguageClientChange(this.toLanguageClientUri(td.uri), document, changes)
-               : undefined;
-         if (inFlight?.kind === 'echo') {
-            // The client is reporting a text we pushed it, so the synced
-            // document is ALREADY there and the changes must not be applied a
-            // second time. Nothing is minted and no rebuild fires. The
-            // per-client baseline advanced above (the client's ids keep
-            // counting); the shadow is deliberately NOT touched — it
-            // optimistically tracks the NEWEST pushed text, and dragging it
-            // back would make the next outbound diff wrong against what the
-            // client actually holds.
+         this.__sessions.setClientVersion(uri, clientId, td.version);
+
+         // An editor change is keyed to the buffer the editor holds, which is
+         // the synced text only while the two agree — an authored write
+         // advances the synced text without the editor knowing, and a push in
+         // flight moves the editor without the store knowing.
+         const verdict: LanguageClientChangeVerdict = editor
+            ? this.languageClientShadow.acceptChange(uri, clientUri, td.version, document, changes)
+            : { kind: 'direct' };
+         if (verdict.kind === 'echo') {
+            // The synced document is already there, so the changes must not be
+            // applied a second time: nothing is minted and no rebuild fires. The
+            // shadow keeps the newest pushed text, which is what the next
+            // outbound diff has to be keyed to.
             this.logUri(uri, `Skip rebuild: echo of a server-authored push (client version ${td.version})`, 'debug');
             return;
          }
 
-         // The SHARED version advances iff the content actually changes — the
-         // invariant optimistic `baseVersion` gates rely on. The new text is
-         // only known after applying the (possibly incremental) changes, so
-         // apply at a tentative +1 and roll the version back on an identical
-         // result (an empty-changes update only re-stamps the version).
-         //
-         // A divergent in-flight change is applied as its RECONSTRUCTED text
-         // rather than as its own ranges: the ranges address the pre-push
-         // baseline, so applying them here would splice the wrong lines.
-         const previousText = document.getText();
-         const sharedVersion = document.version;
-         document = this.configuration.update(document, inFlight === undefined ? changes : [{ text: inFlight.text }], sharedVersion + 1);
-         const changed = document.getText() !== previousText;
-         if (!changed) {
-            document = this.configuration.update(document, [], sharedVersion);
-         }
-         this.__syncedDocuments.set(uri, document);
-         if (changed) {
-            this.setAuthor(uri, document.version, clientId);
-         }
-         if (clientId === LANGUAGE_CLIENT_ID) {
-            // Monaco just told us about its new content; record it so the next outbound
-            // applyEditToLanguageClient diffs against the right baseline. Keyed by the
-            // language-client URI (what Monaco holds), not the canonical document key.
-            this.__shadow.set(this.toLanguageClientUri(td.uri), document.getText());
-            // Content-identical echo: the language client is echoing text we already had
-            // (e.g. Monaco re-emitting a server-pushed applyEditToLanguageClient). The model is
-            // unchanged, so skip the rebuild. The per-client baseline + shadow still advanced
-            // above so future staleness checks and diffs are correct. Restricted to the
-            // language client: a ModelService-authored change is never skipped.
-            if (!changed) {
+         // A divergent change is applied as its reconstructed text rather than
+         // as its own ranges: those ranges address the editor's own buffer, so
+         // applying them here would splice the wrong lines.
+         const committed = this.commitChange(uri, document, verdict.kind === 'direct' ? changes : [{ text: verdict.text }], clientId);
+         document = committed.document;
+         if (editor) {
+            this.languageClientShadow.setLanguageClientText(clientUri, document.getText());
+            // Content-identical echo: the editor is echoing text we already had.
+            // The model is unchanged, so skip the rebuild. Restricted to the
+            // editor: a ModelService-authored change is never skipped.
+            if (!committed.changed) {
                this.logUri(uri, `Skip rebuild: content unchanged (echo at client version ${td.version})`, 'debug');
                return;
             }
          }
-         this.log(document.uri, `Update to version ${document.version} by ${clientId}${changed ? '' : ' (content unchanged)'}`);
+         // Diagnosis: one comes with every keystroke.
+         this.logUri(
+            document.uri,
+            `Update to version ${document.version} by ${this.formatClientId(clientId)}${committed.changed ? '' : ' (content unchanged)'}`,
+            'debug'
+         );
          this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
       }
    }
@@ -544,73 +491,183 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * A content-identical write still fires the change event (rebuild): the
     * authored write's server-side rebuild is correctness-bearing, it just
     * mints no new version — nothing observable changed, so watchers'
-    * `baseVersion` pointers stay valid.
+    * base versions stay valid.
     *
     * Returns the resulting shared version. Throws when the document is not
     * open — callers (`AstDocumentManager.update`) open first.
     */
-   applyContentChange(uri: DocumentUri, text: string, clientId: string): number {
+   applyContentChange(uri: DocumentUri, text: string, clientId: string): TextVersion {
       const key = this.documentKey(uri);
-      let document = this.__syncedDocuments.get(key);
-      if (document === undefined) {
+      const synced = this.__syncedDocuments.get(key);
+      if (synced === undefined) {
          throw new Error(`Document ${uri} is not open for content changes`);
       }
-      const changed = document.getText() !== text;
-      if (changed) {
-         document = this.configuration.update(document, [{ text }], document.version + 1);
-         this.__syncedDocuments.set(key, document);
-         this.setAuthor(key, document.version, clientId);
-      }
-      this.log(document.uri, `Update to version ${document.version} by ${clientId}${changed ? '' : ' (content unchanged)'}`);
+      // Unchanged text calls no update: a configuration may return a new document for one.
+      const { document, changed } =
+         synced.getText() === text ? { document: synced, changed: false } : this.commitChange(key, synced, [{ text }], clientId);
+      this.logUri(
+         document.uri,
+         `Update to version ${document.version} by ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`,
+         'debug'
+      );
       this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
       return document.version;
    }
 
-   public notifyDidCloseTextDocument(event: DidCloseTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
+   /**
+    * Close `clientId`'s open of the document. When it was the last open, the
+    * document is released, at once or, for a `'lost'`
+    * close, after {@link HydraniumTextDocumentsOptions.releaseGraceMs}.
+    */
+   public notifyDidCloseTextDocument(
+      event: DidCloseTextDocumentParams,
+      clientId = LANGUAGE_CLIENT_ID,
+      cause: SessionEndCause = 'closed'
+   ): void {
       const uri = this.documentKey(event.textDocument.uri);
-      if (!this.isOpenInClient(uri, clientId)) {
+      if (clientId === LANGUAGE_CLIENT_ID) {
+         const clientUri = this.toLanguageClientUri(event.textDocument.uri);
+         // A close under a URI the editor never opened the document under ends its hold.
+         if (this.languageClientShadow.isOpen(uri, clientUri)) {
+            this.languageClientShadow.removeOpen(uri, clientUri);
+         } else {
+            this.languageClientShadow.removeAllOpens(uri);
+         }
+         // Another URI still holds the document, so only this one's buffer goes.
+         if (this.languageClientShadow.isOpen(uri)) {
+            return;
+         }
+      }
+      if (!this.__sessions.removeOpen(uri, clientId)) {
          return;
       }
-      const closingRecord = this.__documents.get(uri);
-      closingRecord?.clients.delete(clientId);
-      closingRecord?.clientVersions.delete(clientId);
+      if (cause === 'lost') {
+         this.documentReleaseScheduler.recordLoss(uri, clientId);
+      }
       const syncedDocument = this.__syncedDocuments.get(uri);
       if (syncedDocument !== undefined) {
-         this.log(syncedDocument.uri, `Closed synced document: ${syncedDocument.version} by ${clientId}`);
+         this.log(syncedDocument.uri, `Closed synced document: ${syncedDocument.version} by ${this.formatClientId(clientId)}`);
          this.__onDidClose.fire(Object.freeze({ document: syncedDocument, clientId }));
-
-         if (clientId === LANGUAGE_CLIENT_ID) {
-            // Monaco closed the document; drop the URI it held and the shadow
-            // baselined under it. (If this was the last URI/client the whole record
-            // is deleted below, clearing the set anyway.)
-            const droppedUri = this.toLanguageClientUri(event.textDocument.uri);
-            this.__documents.get(uri)?.languageClientUris?.delete(droppedUri);
-            this.__shadow.invalidate(droppedUri);
-            this.__pendingPushes.delete(droppedUri);
+         if (!this.isOpenInAnyClient(uri)) {
+            if (cause === 'lost') {
+               this.deferRelease(uri);
+            } else {
+               this.releaseDocument(uri);
+            }
          }
-         if (!this.__documents.get(uri)?.clients.size) {
-            // Last client closed the document; delete sync state. The downstream
-            // "rebuild from disk for file URIs / drop from index for ephemeral
-            // URIs" decision lives in `HydraniumDocumentUpdateHandler.didCloseDocument`,
-            // which subscribes to `onDidClose` and consults `isOpenInAnyClient`
-            // to detect the last-close transition.
-            this.log(syncedDocument.uri, `Remove synced document: ${syncedDocument.version} (no client left)`);
-            // Persist where the shared version sequence left off (version +
-            // content hash) so the next open CONTINUES the sequence instead of
-            // restarting at the reopening client's declared id. Hashed once
-            // here at close, not on every change.
-            this.__versionSequences.set(uri, {
-               version: syncedDocument.version,
-               contentHash: contentHash(syncedDocument.getText())
-            });
-            this.__syncedDocuments.delete(uri);
-            // One delete clears every per-URI axis (version history + any staged
-            // pending content) so a future open with the same URI starts fresh.
-            this.__documents.delete(uri);
+      }
+   }
+
+   /**
+    * Keep the document, text and all, for the release grace, then release it.
+    * The document stays in the store meanwhile, so a lost client that opens it
+    * again within its own grace attaches to it and finds its unsaved text
+    * rather than reading disk; see {@link resolveDeferredRelease} for any other
+    * open.
+    */
+   protected deferRelease(uri: CanonicalUri): void {
+      this.documentReleaseScheduler.defer(uri, () => {
+         if (!this.isOpenInAnyClient(uri)) {
+            this.releaseDocument(uri);
          }
+      });
+      if (this.documentReleaseScheduler.isDeferred(uri)) {
+         this.log(uri, `No client left; release deferred for ${this.documentReleaseScheduler.graceMs} ms (connection lost)`);
+      }
+   }
+
+   /** Resolve a deferred release of `uri` for an open by `clientId`: a release the scheduler decides on runs now. */
+   protected resolveDeferredRelease(uri: CanonicalUri, clientId: string): void {
+      if (this.documentReleaseScheduler.resolveOpen(uri, clientId) === 'release') {
+         this.releaseDocument(uri);
       }
    }
 
+   /**
+    * Drop the document no client has open any more, announce it on
+    * {@link onDidReleaseDocument}, then hand it to the
+    * `DocumentReleaseHandler` slot: its listeners, such as the update
+    * handler dropping a change it still holds back, act before any build the
+    * handler runs.
+    */
+   protected releaseDocument(uri: CanonicalUri): void {
+      const syncedDocument = this.__syncedDocuments.get(uri);
+      if (syncedDocument === undefined) {
+         return;
+      }
+      this.log(syncedDocument.uri, `Remove synced document: ${syncedDocument.version} (no client left)`);
+      // The next open continues the sequence instead of restarting at the
+      // reopening client's declared id.
+      this.textLedger.record(uri, syncedDocument);
+      this.textLedger.clearAuthors(uri);
+      // Before the tracker's release, which forgets whether a file was behind it.
+      const released = this.toReleasedDocument(uri);
+      const cleanAnnouncement = this.dirtyStateTracker.release(uri);
+      this.__syncedDocuments.delete(uri);
+      this.__openedVersions.delete(uri);
+      this.__sessions.forgetClientVersions(uri);
+      // A stage is for a first open; one released unconsumed is stale.
+      this.__pendingContent.delete(uri);
+      this.documentReleaseScheduler.clearLosses(uri);
+      this.documentReleasedEmitter.fire(Object.freeze({ uri }));
+      this.handOverRelease(released, cleanAnnouncement);
+   }
+
+   /**
+    * Call the `DocumentReleaseHandler` slot, and announce a document released
+    * dirty clean once the promise it returns settles, which is after the
+    * release event. A failure is logged rather than thrown: the store has let
+    * go of the document by now, and a throw would abort the transition that
+    * released it, a session's close of its other documents included.
+    */
+   protected handOverRelease(released: ReleasedDocument, cleanAnnouncement: CleanAnnouncement | undefined): void {
+      let settled: Promise<void>;
+      try {
+         // Read here: a lazily built slot whose factory throws throws on this read.
+         const handler = this.services.workspace.DocumentReleaseHandler;
+         settled =
+            handler === undefined
+               ? Promise.reject(new Error('no workspace.DocumentReleaseHandler bound'))
+               : Promise.resolve(handler.didReleaseDocument(released));
+      } catch (err: unknown) {
+         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: boolean): void => {
+         if (cleanAnnouncement?.isOwed()) {
+            const inBuild = built && this.services.workspace.LangiumDocuments.getDocument(UriUtils.toUri(released.uri)) !== undefined;
+            cleanAnnouncement.announce(inBuild ? this.textState(released.uri) : undefined);
+         }
+      };
+      settled.then(
+         () => announceClean(true),
+         (err: unknown) => {
+            // A release skipped at teardown, its peer or its workspace gone, is
+            // routine, not a fault to investigate.
+            if (isDocumentReleaseSkippedError(err)) {
+               this.tracer.with(released.uri).debug(err.message);
+            } else {
+               this.tracer.with(released.uri).error(`Release handler failed. ${describeErrorWithStack(err)}`);
+            }
+            // Left unsettled, a watcher keeps the document dirty though the store answers clean.
+            announceClean(false);
+         }
+      );
+   }
+
+   /** `uri` as the `DocumentReleaseHandler` slot receives it. */
+   protected toReleasedDocument(uri: CanonicalUri): ReleasedDocument {
+      return {
+         uri,
+         wasOnDisk: this.dirtyStateTracker.hasDiskBaseline(uri),
+         isFor: other => this.documentKey(other) === uri,
+         isReclaimed: () => this.isOpenInAnyClient(uri) || this.__syncedDocuments.has(uri)
+      };
+   }
+
    public notifyWillSaveTextDocument(event: WillSaveTextDocumentParams): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
       if (syncedDocument !== undefined) {
@@ -630,93 +687,176 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       }
    }
 
+   /**
+    * Handle a save the language client reports: fire
+    * {@link onDidSaveInLanguageClient}, then announce it on {@link onDidSave}
+    * only once the file read back from disk holds the store's current text.
+    */
+   protected async notifyLanguageClientSave(event: DidSaveTextDocumentParams): Promise<void> {
+      const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
+      if (syncedDocument === undefined) {
+         return;
+      }
+      const uri = syncedDocument.uri;
+      this.languageClientSavedEmitter.fire(Object.freeze({ uri }));
+      // `onDidSave` tells its listeners that the shared document is on disk.
+      // The editor wrote its own buffer, which lags the store while another
+      // client's edit is still on its way to it, so only the file says
+      // whether that holds. Read it rather than trust the editor: `didSave`
+      // carries text only for a client that honours `includeText`, and asking
+      // for it means rewriting Langium's initialize answer, which advertises
+      // `save` as a Boolean. The read goes through the disk queue and waits on
+      // nothing but the provider, so it follows a server save queued
+      // meanwhile. A file changed again between the editor's write and this
+      // read compares unequal, and the save goes unannounced.
+      let onDisk: string | undefined;
+      try {
+         onDisk = await this.services.workspace.FileSystemTaskQueue.enqueue(uri, () =>
+            this.services.workspace.FileSystemProvider.readFile(UriUtils.toUri(uri))
+         );
+      } catch (err: unknown) {
+         this.tracer.with(uri).debug(`Editor save not announced: reading the file back failed. ${describeError(err)}`);
+         return;
+      }
+      // What the file holds, not what the editor meant to write: an editor
+      // that saved older text leaves the document dirty.
+      this.setDiskBaseline(uri, onDisk);
+      // An editor that saves and then closes releases the document while the
+      // read is under way; its save is still a save of the text it held.
+      const document = this.__syncedDocuments.get(this.documentKey(uri)) ?? syncedDocument;
+      if (onDisk !== document.getText()) {
+         this.tracer.with(uri).debug(`Editor save not announced: the file does not hold the text of version ${document.version}`);
+         return;
+      }
+      this.announceSave(document, LANGUAGE_CLIENT_ID);
+   }
+
+   /**
+    * Announce a save the server made. `event.text`, when given, is what the
+    * file now holds, written or found there, and becomes the disk baseline
+    * before the save is announced. It lags the store when an edit landed
+    * after the save took its text, and the document then stays dirty.
+    */
    public notifyDidSaveTextDocument(event: DidSaveTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
       if (syncedDocument !== undefined) {
-         this.log(syncedDocument.uri, `Saved synced document: ${syncedDocument.version} by ${clientId}`);
-         this.__onDidSave.fire(Object.freeze({ document: syncedDocument, clientId }));
+         if (event.text !== undefined) {
+            this.setDiskBaseline(syncedDocument.uri, event.text);
+         }
+         this.announceSave(syncedDocument, clientId);
       }
    }
 
+   /** Fire {@link onDidSave} for `document`, which need not be synced any more. */
+   protected announceSave(document: T, clientId: string): void {
+      this.log(document.uri, `Saved synced document: ${document.version} by ${this.formatClientId(clientId)}`);
+      this.__onDidSave.fire(Object.freeze({ document, clientId }));
+   }
+
    public notifyDidOpenTextDocument(event: DidOpenTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
       const td = event.textDocument;
       const uri = this.documentKey(td.uri);
-      if (this.isOpenInClient(uri, clientId)) {
-         // Already open for this client under this canonical identity. If this is a
-         // NEW client-facing URI for the same file (a second tab reached via a
-         // divergent path, e.g. a symlink and its real path), record it and baseline
-         // its shadow so outbound edits reach this tab too — but do NOT re-fire
-         // open/rebuild; the document is already live.
-         if (clientId === LANGUAGE_CLIENT_ID) {
-            const clientFacing = this.toLanguageClientUri(td.uri);
-            const record = this.__documents.get(uri);
-            if (record && !record.languageClientUris?.has(clientFacing)) {
-               (record.languageClientUris ??= new Set<LanguageClientUri>()).add(clientFacing);
-               const open = this.__syncedDocuments.get(uri);
-               if (open) {
-                  this.__shadow.set(clientFacing, open.getText());
-               }
-            }
-         }
-         return;
+      // Before the deferred release is resolved: refused after it, the open
+      // would leave a document whose grace it ended with no holder and no timer.
+      // A repeat open stays a no-op.
+      if (!this.__sessions.isOpenIn(uri, clientId)) {
+         this.__sessions.assertCanOpen(clientId);
       }
+      this.resolveDeferredRelease(uri, clientId);
       let document = this.__syncedDocuments.get(uri);
-      const record = this.trackingFor(uri);
-      const existingClients = [...record.clients];
-      record.clients.add(clientId);
-      // Baseline the per-client staleness guard at the version id the client
-      // declared for its own buffer (client-owned per LSP).
-      record.clientVersions.set(clientId, td.version);
+      // 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) {
-         // Remember the URI Monaco opened under (may differ from the canonical key)
-         // so outbound applyEditToLanguageClient can address the URI it actually holds.
-         (record.languageClientUris ??= new Set<LanguageClientUri>()).add(this.toLanguageClientUri(td.uri));
+         this.languageClientShadow.addOpen(uri, this.toLanguageClientUri(td.uri), td.version, td.text, document === undefined);
       }
+      if (this.isOpenInClient(uri, clientId)) {
+         // A repeat open, or the editor's second URI for the file, e.g. a
+         // symlink and its real path: the shadow records it so pushes reach it,
+         // and nothing re-fires.
+         return;
+      }
+      const existingClients = this.__sessions.clientsOf(uri);
+      this.__sessions.addOpen(uri, clientId);
+      this.__sessions.setClientVersion(uri, clientId, td.version);
       if (!document) {
          // Use integrity-staged content if available, otherwise the client-provided (disk) text.
          const pendingText = this.consumePendingContent(uri);
          const text = pendingText ?? td.text;
          const source = pendingText ? ', source=pending' : '';
-         // The SHARED version is server-assigned: continue the persisted
-         // sequence — same version when the content is unchanged since the
-         // last close (so watchers' `baseVersion` pointers stay valid), one
-         // step when it changed (so no stale pointer can coincidentally pass
-         // the optimistic gate). Only a first-ever open adopts the client's
-         // declared id as the sequence seed.
-         const sequence = this.__versionSequences.get(uri);
-         const version =
-            sequence === undefined ? td.version : sequence.contentHash === contentHash(text) ? sequence.version : sequence.version + 1;
-         this.log(uri, `Open document: Version ${version} by ${clientId} [first client${source}]`);
-         document = this.configuration.create(uri, td.languageId, version, text);
-         this.__syncedDocuments.set(uri, document);
-         this.setAuthor(uri, version, clientId);
-         if (clientId === LANGUAGE_CLIENT_ID) {
-            // Baseline the shadow to what Monaco just opened so the next outbound
-            // applyEditToLanguageClient diffs against the right starting point. Keyed by the
-            // language-client URI (what Monaco holds), not the canonical document key.
-            this.__shadow.set(this.toLanguageClientUri(td.uri), document.getText());
-         }
+         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.create(uri, td.languageId, version, text);
+         this.commitText(uri, document, clientId);
+         this.__openedVersions.set(uri, version);
+         // The opener's text, not the staged content: a session's open read
+         // it from the file, and an editor opened its buffer from there. An
+         // editor that opens a buffer it never saved is taken as clean.
+         this.dirtyStateTracker.track(uri, document, td.text);
          const toFire = Object.freeze({ document, clientId });
          this.__onDidOpen.fire(toFire);
          this.__onDidChangeContent.fire(toFire);
       } else {
          // An additional client attaches to a document already open by another client.
-         this.log(
-            uri,
-            `Attach client: ${clientId} joined existing document (version ${document.version}, ` +
-               `now open in: ${[...existingClients, clientId].join(', ')})`
-         );
+         this.logClientJoined(uri, clientId, document.version, existingClients);
          this.refreshContent(uri, clientId);
       }
    }
 
+   /**
+    * Record `clientId` as an additional holder of a document another client
+    * already has open.
+    *
+    * Unlike the attach branch of {@link notifyDidOpenTextDocument} this does
+    * not refresh. That branch re-renders an attaching TEXTUAL view; a client
+    * reaching a document through a non-textual route has nothing to re-render,
+    * and refreshing per attach turns each into a Langium rebuild and dependent
+    * relink cascade.
+    *
+    * Returns whether a hold was added — `false` when `uri` is not open,
+    * `clientId` already holds it, or the document was waiting out the release
+    * grace for other clients and was released instead (see
+    * {@link resolveDeferredRelease}); the caller then opens it anew.
+    */
+   attachClient(uri: DocumentUri, clientId: string): boolean {
+      const key = this.documentKey(uri);
+      if (!this.__syncedDocuments.has(key) || this.isOpenInClient(key, clientId)) {
+         return false;
+      }
+      // Before the deferred release is resolved, as for an open.
+      this.__sessions.assertCanOpen(clientId);
+      this.resolveDeferredRelease(key, clientId);
+      const document = this.__syncedDocuments.get(key);
+      if (!document) {
+         return false;
+      }
+      const existingClients = this.__sessions.clientsOf(key);
+      this.__sessions.addOpen(key, clientId);
+      // A client arriving this way holds no buffer of its own, so its guard
+      // starts at the synced version.
+      this.__sessions.setClientVersion(key, clientId, document.version);
+      this.logClientJoined(key, clientId, document.version, existingClients);
+      return true;
+   }
+
+   protected logClientJoined(uri: DocumentUri, clientId: string, version: number, existingClients: readonly string[]): void {
+      this.log(
+         uri,
+         `Attach client: ${this.formatClientId(clientId)} joined existing document (version ${version}, ` +
+            `now open in: ${[...existingClients, clientId].map(id => this.formatClientId(id)).join(', ')})`
+      );
+   }
+
    refreshContent(uri: DocumentUri, clientId: string): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(uri));
       if (syncedDocument) {
          // Trigger a (re-)build by firing a change event.
          const timer = this.startTimerForUri(
             syncedDocument.uri,
-            `Refresh synced document: Version ${syncedDocument.version} by ${clientId}`
+            `Refresh synced document: Version ${syncedDocument.version} by ${this.formatClientId(clientId)}`
          );
          this.__onDidChangeContent.fire(Object.freeze({ document: syncedDocument, clientId }));
          timer.dispose();
@@ -730,7 +870,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * two URIs for one physical file (a symlink path and its real path) into a
     * single registration — dedup at the editor layer, not just in
     * `LangiumDocuments`. The URI the client opened under is preserved separately
-    * for egress addressing (see {@link DocumentTracking.languageClientUris}). The
+    * for egress addressing, by the {@link LanguageClientShadow}. The
     * policy is always bound (the framework defaults it to
     * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
     */
@@ -750,18 +890,8 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       return asLanguageClientUri(UriUtils.normalize(uri));
    }
 
-   /** Get-or-create the per-URI tracking record. `uri` must already be a {@link documentKey}. */
-   protected trackingFor(uri: CanonicalUri): DocumentTracking {
-      let record = this.__documents.get(uri);
-      if (!record) {
-         record = { clients: new Set(), versionAuthors: [], clientVersions: new Map() };
-         this.__documents.set(uri, record);
-      }
-      return record;
-   }
-
    setAuthor(uri: DocumentUri, version: number, author: string): void {
-      this.trackingFor(this.documentKey(uri)).versionAuthors[version] = author;
+      this.textLedger.setAuthor(this.documentKey(uri), version, author);
    }
 
    /**
@@ -786,57 +916,148 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
 
    /**
     * Current SHARED version of the document at `uri`: the open document's
-    * version, else where the persisted sequence left off at last close, else
-    * `0` for a URI this store has never seen. The shared sequence is
+    * version, else where its persisted sequence left off, else `0` for a URI
+    * this store has never seen. The shared sequence is
     * server-owned and monotonic across close/reopen cycles, and advances
     * exactly when the synced content changes — which is what makes it a sound
-    * optimistic-concurrency token (`baseVersion` gates): version unchanged ⇔
+    * optimistic-concurrency token (base-version gates): version unchanged ⇔
     * content unchanged.
     */
-   version(uri: DocumentUri): number {
-      return this.get(uri)?.version ?? this.__versionSequences.get(this.documentKey(uri))?.version ?? 0;
+   version(uri: DocumentUri): TextVersion {
+      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: DocumentUri): TextVersion | undefined {
+      return this.__openedVersions.get(this.documentKey(uri));
+   }
+
+   /**
+    * The text the store holds for `uri`: an open document's, or for a closed
+    * one, the clean text its version sequence left off at, which for a deleted
+    * document is its last text. `undefined` for a URI no build and no client
+    * gave the store.
+    */
+   textState(uri: DocumentUri): TextState | undefined {
+      const document = this.get(uri);
+      if (document) {
+         return { version: document.version, hash: this.textLedger.hashOf(document), dirty: this.isDirty(uri) };
+      }
+      const recorded = this.textLedger.recordOf(this.documentKey(uri));
+      return recorded && { version: recorded.version, hash: recorded.hash, dirty: false };
+   }
+
+   /**
+    * The built root's recorded version for a first open of `key` with `text`,
+    * one on when the text differs from the root's; `undefined` when the root
+    * records no store version. Seeded from the opener's declared version
+    * instead, a write based on the built root passes the gate over other text,
+    * and the same text looks newer than its model. A built root records none
+    * only under a `LangiumDocuments` that does not reconcile at registration.
+    */
+   protected builtRootOpeningVersion(key: CanonicalUri, text: string): TextVersion | undefined {
+      const built = this.services.workspace.LangiumDocuments.getDocument(UriUtils.toUri(key));
+      if (built === undefined) {
+         return undefined;
+      }
+      const ledger = this.services.workspace.ModelLedger;
+      const root = built.parseResult.value;
+      const recorded = ledger.versionOf(root);
+      if (recorded === UNRECORDED_VERSION || recorded === STALE_VERSION) {
+         return undefined;
+      }
+      return (ledger.textOf(root) ?? built.textDocument.getText()) === text ? recorded : recorded + 1;
    }
 
    /**
     * Reconcile the persisted version sequence with content that reached the
     * build OUTSIDE the store's write paths — a closed document rebuilt from
-    * disk (last-close revert) or replaced by a watched-file change. Steps the
+    * disk after its release, or replaced by a watched-file change. Steps the
     * sequence iff `text` differs from the sequence's last-known content and
     * returns the resulting sequence version so the caller can re-stamp the
-    * rebuilt document (see the `AstDocumentManager` Parsed-phase listener) —
+    * rebuilt document (`VersionSyncService.modelProduced`) —
     * keeping the "version advances iff content changes" invariant for
     * documents no client currently holds.
     *
-    * Returns `undefined` — and does nothing — when the document is open (the
-    * store's own content is authoritative; external transitions never reach
-    * the Langium factory for open documents) or was never tracked (no gate
-    * holder can hold a version pointer for it, and the early exit keeps
-    * workspace-wide builds from hashing every untouched document).
+    * For an open document, its version when it holds `text`, since a build
+    * that read the file while the document was closed can finish after an
+    * open; else `undefined`, and the caller has to build the document again.
+    *
+    * A document without a sequence starts one at `0` with `text`: snapshots
+    * hand out versions for documents no client opened, so an uncounted change
+    * would let a write based on the old text pass the gate.
     */
    reconcileExternalContent(uri: DocumentUri, text: string): number | undefined {
       const key = this.documentKey(uri);
-      if (this.__syncedDocuments.has(key)) {
-         return undefined;
+      const open = this.__syncedDocuments.get(key);
+      if (open !== undefined) {
+         return open.getText() === text ? open.version : undefined;
       }
-      const sequence = this.__versionSequences.get(key);
-      if (sequence === undefined) {
-         return undefined;
+      const before = this.textLedger.recordOf(key)?.version;
+      const version = this.textLedger.reconcile(key, text);
+      if (before !== undefined && version !== before) {
+         this.logUri(key, `External content change while closed: sequence stepped to version ${version}`, 'debug');
       }
-      const hash = contentHash(text);
-      if (hash === sequence.contentHash) {
-         return sequence.version;
+      return version;
+   }
+
+   /**
+    * Commit an integrity repair into the OPEN document for `uri`, returning the
+    * document that now holds it, or `undefined` when there was nothing here to
+    * commit into.
+    *
+    * The one thing this exists to do is address the store BY URI. A repair
+    * reaches the resync as a text-document object, and that object is the
+    * store's own only on the LSP path; a document built for an already-open URI
+    * through `LangiumDocumentFactory.fromString` carries its own, so writing the
+    * repair into it corrects a copy the store does not know about and the editor
+    * never sees.
+    *
+    * `parsedFrom` is the text the repaired AST was parsed from, and a mismatch
+    * against the current content REFUSES the commit: the store has moved on,
+    * which means an editor change landed after that parse, and committing would
+    * overwrite a newer edit with a repair computed against text the user has
+    * already replaced. The build that change provokes recomputes the repair.
+    *
+    * Deliberately NOT compared by version. A separately created document seeds
+    * its own numbering, so requiring the two to agree would refuse every commit
+    * on the path this exists for. Content is the thing both sides can be held to.
+    *
+    * A changed text is a new version authored by {@link INTEGRITY_CLIENT_ID}.
+    * Kept at the old version, the repair is invisible to every reader keyed on
+    * versions: a write based on the unrepaired version passes the base-version gate
+    * and replaces the repair, and an echo filter credits the repair to the
+    * client whose edit it corrected. No change event is fired: the repair
+    * rides the build already under way, and an event would re-enter it.
+    */
+   commitRepair(uri: DocumentUri, parsedFrom: string, repaired: string): RepairCommit<T> {
+      const key = this.documentKey(uri);
+      const document = this.__syncedDocuments.get(key);
+      if (document === undefined) {
+         return { status: 'not-open' };
+      }
+      if (document.getText() !== parsedFrom) {
+         this.logUri(key, 'Refuse repair commit: the open document moved on from the text the AST was parsed from', 'debug');
+         return { status: 'stale' };
       }
-      const stepped: VersionSequence = { version: sequence.version + 1, contentHash: hash };
-      this.__versionSequences.set(key, stepped);
-      this.logUri(key, `External content change while closed: sequence stepped to version ${stepped.version}`, 'debug');
-      return stepped.version;
+      if (repaired === parsedFrom) {
+         return { status: 'committed', document };
+      }
+      // Reassigned rather than mutated in place: the default configuration
+      // updates and returns the SAME instance, but an adopter-supplied one may
+      // return a new object, and the store must end up holding whichever it is.
+      const updated = this.commitChange(key, document, [{ text: repaired }], INTEGRITY_CLIENT_ID).document;
+      this.log(updated.uri, `Update to version ${updated.version} by ${this.formatClientId(INTEGRITY_CLIENT_ID)} (repair)`);
+      return { status: 'committed', document: updated };
    }
 
    getAuthor(uri: DocumentUri, version?: number): string | undefined {
-      const history = this.__documents.get(this.documentKey(uri))?.versionAuthors;
-      // Either the requested version, or the latest. `version !== undefined` so we treat 0 correctly.
-      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}.`);
@@ -852,17 +1073,19 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * True iff any client still holds `uri` open. Distinct from {@link isOpen},
     * which reads `__syncedDocuments` — that map is cleared only AFTER the
     * `onDidClose` event fires for the last client, so `isOpen` returns `true`
-    * during the close event itself. `isOpenInAnyClient` reads the tracking
-    * record's `clients` set, which is updated BEFORE the fire, so an `onDidClose`
-    * subscriber that finds this `false` knows the last client just closed and a
-    * disk re-read / rebuild can proceed.
+    * during the close event itself. `isOpenInAnyClient` reads the open table
+    * ({@link __sessions}), which is updated BEFORE the fire, so an `onDidClose`
+    * subscriber that finds this `false` knows the last client just closed.
+    * What the build keeps is the release's: a subscriber that re-read or
+    * rebuilt the document would race the `DocumentReleaseHandler`, and after a
+    * lost connection the release waits out its grace.
     */
    isOpenInAnyClient(uri: DocumentUri): boolean {
-      return (this.__documents.get(this.documentKey(uri))?.clients.size ?? 0) > 0;
+      return this.__sessions.isOpen(this.documentKey(uri));
    }
 
    isOpenInClient(uri: DocumentUri, client: string): boolean {
-      return !!this.__documents.get(this.documentKey(uri))?.clients.has(client);
+      return this.__sessions.isOpenIn(this.documentKey(uri), client);
    }
 
    isOpenInLanguageClient(uri: DocumentUri): boolean {
@@ -872,15 +1095,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       return this.isOpenInClient(uri, LANGUAGE_CLIENT_ID);
    }
 
+   /** The clients that have `uri` open, in the order they opened it. */
+   clientsOf(uri: DocumentUri): string[] {
+      return this.__sessions.clientsOf(this.documentKey(uri));
+   }
+
    isOnlyOpenInClient(uri: DocumentUri, client: string): boolean {
-      const key = this.documentKey(uri);
-      return this.__documents.get(key)?.clients.size === 1 && this.isOpenInClient(key, client);
+      const clients = this.__sessions.clientsOf(this.documentKey(uri));
+      return clients.length === 1 && clients[0] === client;
    }
 
    /**
     * Every document currently held open by at least one client, with the client
-    * ids holding it. Reads the same per-URI tracking records as
-    * {@link isOpenInAnyClient}, so it reflects a last-client close immediately.
+    * ids holding it. Reads the same open table as {@link isOpenInAnyClient}, so
+    * it reflects a last-client close immediately.
     *
     * Diagnostics-oriented — the server-state snapshot lists these so an operator
     * can see WHY a document is pinned: a document that lingers here after its
@@ -888,31 +1116,244 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * under a shedding policy, explains why its CST is never shed).
     */
    openDocuments(): OpenDocument[] {
-      const result: OpenDocument[] = [];
-      for (const [uri, tracking] of this.__documents) {
-         if (tracking.clients.size > 0) {
-            result.push({ uri, clients: [...tracking.clients] });
+      return this.__sessions.openDocuments();
+   }
+
+   /** Fires once a client session has ended, after every document it had open was closed. */
+   get onDidCloseSession(): Event<ClientSessionClosedEvent> {
+      return this.__sessions.onDidCloseSession;
+   }
+
+   /**
+    * Fires once a document no client has open is released: at its last close,
+    * or, for a lost client's last close, when its release grace runs out,
+    * another client opens it, or it is deleted, before the
+    * `DocumentReleaseHandler` slot is handed the document.
+    */
+   get onDidReleaseDocument(): Event<DocumentReleasedEvent> {
+      return this.documentReleasedEmitter.event;
+   }
+
+   /**
+    * Fires for every save the language client reports of a document it has
+    * open: the editor has written the file. {@link onDidSave} follows only
+    * when the file holds the store's text.
+    */
+   get onDidSaveInLanguageClient(): Event<LanguageClientSavedEvent> {
+      return this.languageClientSavedEmitter.event;
+   }
+
+   /**
+    * Whether `uri` is waiting out the release grace: its last open closed with a
+    * lost connection, and it still holds its unsaved text. Such a document is
+    * open for no client, yet not closed either, so a caller that would persist
+    * a closed document's text to disk treats it as open.
+    */
+   isReleaseDeferred(uri: DocumentUri): boolean {
+      return this.documentReleaseScheduler.isDeferred(this.documentKey(uri));
+   }
+
+   /**
+    * Whether the store holds `uri` with text that differs from its disk
+    * baseline: what the server last knew the file to hold. `false` for a URI
+    * the store does not hold; a document waiting out the release grace is still
+    * held.
+    *
+    * The baseline is the text a first open brought, or what the server wrote,
+    * or read back after an editor's save or a watched-file change, so it can
+    * trail a change to the file that none of these has seen yet. A check that
+    * must know the file reads it instead.
+    */
+   isDirty(uri: DocumentUri): boolean {
+      return this.dirtyStateTracker.isDirty(this.documentKey(uri));
+   }
+
+   /**
+    * Fires each time the answer of {@link isDirty} changes. For a document
+    * released dirty it fires once the `DocumentReleaseHandler` slot reports the
+    * release settled: at the version of the text the build then holds, or
+    * without text when the document is gone or the handler failed, though
+    * {@link isDirty} answers clean from the release on.
+    */
+   get onDidChangeDirty(): Event<DocumentDirtyChangedEvent> {
+      return this.dirtyStateTracker.onDidChangeDirty;
+   }
+
+   /**
+    * Record that the file behind `uri` holds `text`, or no file at all for
+    * `undefined`. A no-op for a URI the store does not hold: the next first
+    * open sets the baseline from its own text.
+    */
+   setDiskBaseline(uri: DocumentUri, text: string | undefined): void {
+      const key = this.documentKey(uri);
+      const document = this.__syncedDocuments.get(key);
+      if (document !== undefined) {
+         this.dirtyStateTracker.setDiskBaseline(key, document, text);
+      }
+   }
+
+   /**
+    * Read the file behind `uri` through its disk queue and take it as the
+    * baseline. A file that cannot be read counts as none, the side that
+    * leaves the document dirty, once `existsSettled` confirms it gone: a file
+    * it finds is read again. That wait runs outside the queue, so it holds up
+    * no write to the file.
+    */
+   async reloadDiskBaseline(uri: DocumentUri): Promise<void> {
+      const key = this.documentKey(uri);
+      if (!this.__syncedDocuments.has(key)) {
+         return;
+      }
+      const workspace = this.services.workspace;
+      const fileSystem = workspace.FileSystemProvider;
+      const target = UriUtils.toUri(key);
+      const read = async (): Promise<string | undefined> => {
+         try {
+            return await workspace.FileSystemTaskQueue.enqueue(key, () => fileSystem.readFile(target));
+         } catch (err: unknown) {
+            this.tracer.with(key).debug(`Disk baseline: the file cannot be read. ${describeError(err)}`);
+            return undefined;
+         }
+      };
+      let onDisk = await read();
+      if (onDisk === undefined && (await (fileSystem.existsSettled?.(target) ?? fileSystem.exists(target)))) {
+         onDisk = await read();
+      }
+      this.setDiskBaseline(key, onDisk);
+   }
+
+   /**
+    * Start a client session under `clientId`. Throws where
+    * {@link ClientSessionRegistry.register} refuses the id.
+    */
+   registerSession(clientId: string): void {
+      this.__sessions.register(clientId);
+      this.tracer.info(`Session started: ${this.formatClientId(clientId)}`);
+      this.tracer.trace(`Session started: ${clientId}`);
+   }
+
+   /**
+    * End the client session `clientId`: close every document it has open, then
+    * free the id. Immediate — each close runs the ordinary close path before
+    * this returns, with `cause` as its cause. A no-op for an id that is not a
+    * registered session.
+    */
+   closeSession(clientId: string, cause: SessionEndCause = 'closed'): void {
+      if (!this.__sessions.isRegistered(clientId)) {
+         return;
+      }
+      try {
+         for (const uri of this.__sessions.beginClose(clientId)) {
+            this.notifyDidCloseTextDocument({ textDocument: { uri } }, clientId, cause);
          }
+      } finally {
+         this.__sessions.unregister(clientId, cause);
+         this.tracer.info(`Session closed: ${this.formatClientId(clientId)}`);
+         this.tracer.trace(`Session closed: ${clientId}`);
       }
-      return result;
    }
 
    /**
-    * Stages integrity-updated content for a closed document.
+    * Close every document the language client has open, as a `didClose` for
+    * each would, so each last close releases its document. For a host whose editor connection
+    * can end while the process lives on, such as a worker whose port's peer
+    * closed: the language client is no session, so nothing else closes them.
     *
-    * When `workspace/applyEdit` targets a closed file, the client opens it from
-    * disk (stale) and sends `didOpen` before applying the edit. This staged
-    * content is consumed by {@link notifyDidOpenTextDocument} to replace the
-    * stale disk text, preventing a brief revert of the integrity update.
+    * It first waits for the workspace initialization the open handler waits
+    * for, so an open that arrived before the close is closed too; closing at
+    * once would leave that open to land afterwards, held by a client that is
+    * gone.
+    */
+   async closeLanguageClientDocuments(): Promise<void> {
+      await this.initialBuildFinished();
+      for (const uri of this.__sessions.opensOf(LANGUAGE_CLIENT_ID)) {
+         // A close for one URI while others remain keeps the client's hold.
+         this.languageClientShadow.removeAllOpens(uri);
+         this.notifyDidCloseTextDocument({ textDocument: { uri } });
+      }
+   }
+
+   /**
+    * Settles once the initial workspace build has finished, whether it
+    * completed, was cancelled or failed. Awaiting `workspaceInitialized` itself
+    * throws after a cancelled build, which any write during startup causes, and
+    * every open and close gated on it is then dropped for the process lifetime.
+    * The workspace manager logs a failed build.
+    */
+   protected async initialBuildFinished(): Promise<void> {
+      await this.services.workspace.WorkspaceManager.workspaceInitialized.catch(() => undefined);
+   }
+
+   /**
+    * The file behind `uri` was deleted: close every open of it except the
+    * language client's.
     *
-    * Not cleared on close: pending content is only staged for already-closed
-    * documents (the integrity service checks `isOpenInLanguageClient` first), so
-    * a close → stage → open cycle cannot occur. The only scenario where an
-    * entry lingers is if `workspace/applyEdit` fails and the file is never
-    * opened — the memory cost is one serialised string per URI.
+    * The editor's open is left alone because the editor owns it: it keeps the
+    * buffer of a deleted file and goes on sending changes for it, and a store
+    * that had closed the document would drop every one of them until the editor
+    * reopened.
+    */
+   notifyDocumentDeleted(uri: DocumentUri): void {
+      const key = this.documentKey(uri);
+      for (const clientId of this.__sessions.clientsOf(key)) {
+         if (clientId !== LANGUAGE_CLIENT_ID) {
+            this.notifyDidCloseTextDocument({ textDocument: { uri: key } }, clientId);
+         }
+      }
+   }
+
+   /**
+    * Remove the document for `uri`, closing every open of it first — the
+    * editor's included, since the document it would keep editing is gone.
+    *
+    * The base removes the synced document without consulting the open table,
+    * which leaves every open recorded against a document that no longer exists:
+    * the store then answers that the URI is open, and the next open attaches to
+    * nothing.
+    */
+   override delete(uri: string | URI | T): void {
+      const key = this.documentKey((typeof uri === 'object' && 'uri' in uri ? uri.uri : uri).toString());
+      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.documentReleaseScheduler.isDeferred(key)) {
+         this.documentReleaseScheduler.cancel(key);
+         this.releaseDocument(key);
+      }
+      super.delete(key);
+   }
+
+   /**
+    * A client id as log lines print it. An id containing `#` is cut eight
+    * characters after its last `#`, which leaves a minted `label#uuid` as the
+    * label and enough of the UUID to tell sessions apart; an id without `#`
+    * prints whole. The full id goes out at trace level wherever a session
+    * starts or ends.
+    */
+   protected formatClientId(clientId: string): string {
+      const separator = clientId.lastIndexOf('#');
+      return separator < 0 ? clientId : clientId.slice(0, separator + 9);
+   }
+
+   /**
+    * Stages integrity-updated content for a document no client holds.
+    *
+    * Nothing is pushed to a file no client holds. The next open of it reads
+    * disk, which lacks the update; {@link notifyDidOpenTextDocument} takes this
+    * staged content in place of that text, and the open's sync then delivers
+    * it to an editor as an unsaved change.
+    *
+    * Only a FIRST open consumes it, so stage only for a URI no client holds
+    * ({@link isOpenInAnyClient} is `false`). A URI held only through another
+    * head is not closed: an editor attaching to it joins the existing entry and
+    * never reads the stage, and the release discards it. An entry waits for
+    * that first open, at one serialised string per URI.
     */
    stagePendingContent(uri: DocumentUri, text: string): void {
-      this.trackingFor(this.documentKey(uri)).pendingContent = text;
+      this.__pendingContent.set(this.documentKey(uri), text);
    }
 
    /**
@@ -924,29 +1365,34 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     *   - The shared services have no LSP {@link Connection} bound (non-LSP
     *     hosts like CLI / tests).
     *   - The shadow already matches `newText` (no edits needed; quiet skip).
+    *   - The language client has not opened the document. A client applies an
+    *     edit to a closed file by opening it, and that open races the edit;
+    *     the document's own open delivers its text instead.
     *
     * On `applyEdit` rejection (`result.applied === false`) or RPC failure the
-    * shadow is invalidated so the next call sends a full-replace baseline.
+    * shadow is invalidated so the next call sends a full replace, or nothing
+    * when the client was last heard to hold that text.
     * Errors are re-thrown — callers wrap with their own retry / coalescing
     * policy as needed.
     *
     * The diff path is apply-verify-safe: the shadow internally checks that
     * `TextDocument.applyEdits(old, edits) === newText` and falls back to a
-    * full replace on mismatch (logged via the warn-callback wired in the
-    * constructor), so a diff regression becomes log noise, not data loss.
+    * full replace on mismatch, logged, so a diff regression becomes log noise,
+    * not data loss.
     *
     * That safety net verifies the diff against the SHADOW, which is what the
     * client is *believed* to hold — so it cannot see the client's buffer moving
     * underneath a push. A line-keyed edit is position-dependent: if a genuine
-    * client keystroke lands between {@link LanguageClientTextShadow.computeEdits}
-    * and the client applying, the ranges address the wrong lines and splice the
-    * buffer (observed as a duplicated declaration, which the integrity tier then
+    * client keystroke lands between computing the edits and the client
+    * applying them, the ranges address the wrong lines and splice the buffer
+    * (observed as a duplicated declaration, which the integrity tier then
     * "repairs" into a suffixed name and persists). The edit is therefore
-    * addressed at the language client's LAST DECLARED VERSION rather than at
-    * `null` ("version intentionally unknown"), which is what lets the client
-    * reject a push its buffer has outrun. On rejection the shadow is invalidated,
+    * addressed at the language client's last known version for that URI rather
+    * than at `null` ("version intentionally unknown"), which is what lets the
+    * client reject a push its buffer has outrun. On rejection the shadow is invalidated,
     * so the caller's retry is a full-range replace — position-independent, and
-    * safe to apply to whatever the client now holds.
+    * safe to apply to whatever the client now holds — or nothing when the
+    * client was last heard to hold that text.
     */
    async applyEditToLanguageClient(
       uri: DocumentUri,
@@ -957,46 +1403,43 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       if (!connection) {
          return undefined;
       }
-      // The document is keyed by its canonical identity, but Monaco holds it under
-      // the URI(s) it opened. Address each of those language-client URIs — the one
-      // R→S translation, kept here at the egress. Usually one; more than one only
-      // when the same file was opened under a symlink and its real path. Falls back
-      // to the normalized URI when nothing is tracked. The shadow is keyed by each
-      // URI, so every diff is against the right baseline.
-      const recorded = this.__documents.get(this.documentKey(uri))?.languageClientUris;
-      const targets: Iterable<LanguageClientUri> = recorded && recorded.size > 0 ? recorded : [this.toLanguageClientUri(uri)];
+      // The document is keyed by its canonical identity, but the client holds it
+      // under each URI it opened, and each is diffed against its own baseline.
+      const key = this.documentKey(uri);
       let lastResult: ApplyWorkspaceEditResult | undefined;
-      for (const targetUri of targets) {
-         // Read BEFORE computeEdits, which overwrites it. This is the text the
-         // edits below are keyed to, and therefore the only text the client's
-         // echo of them can be reconstructed against.
-         const before = this.__shadow.get(targetUri);
-         const edits = this.__shadow.computeEdits(targetUri, newText);
-         if (edits.length === 0) {
+      for (const clientUri of this.languageClientShadow.pushTargets(key)) {
+         // Prepared per target, after the previous target's reply: prepared up
+         // front, a later target is diffed against what it held before a change
+         // that arrived meanwhile.
+         const push = this.languageClientShadow.preparePush(key, clientUri, newText);
+         if (push === undefined) {
             continue;
          }
-         // Record the push for echo correlation BEFORE the RPC — the client's
-         // echo can race the applyEdit response. See `__pendingPushes`.
-         this.recordPendingPush(targetUri, before, newText);
          try {
-            // Version the push only when it is position-DEPENDENT. A full-range
-            // replace lands correctly on any buffer, so gating it would turn a
-            // stale-by-one version into a refused update for no safety gain — and
-            // it is exactly what the caller retries with after a rejection, so
-            // gating it there would refuse the recovery too.
-            const version = isFullReplace(edits) ? UNKNOWN_CLIENT_VERSION : this.languageClientVersion(uri);
+            // A full `ApplyWorkspaceEditParams`, `edit` and all — NOT a bare
+            // `WorkspaceEdit` with a `label` beside it. `applyEdit` takes
+            // `ApplyWorkspaceEditParams | WorkspaceEdit` and discriminates on
+            // `!!value.edit`, so `{ label, documentChanges }` is wrapped as
+            // `{ edit: { label, documentChanges } }` — putting the label inside
+            // the edit, where LSP defines no such field and no client reads it.
+            // The union is also what hides it at compile time: excess-property
+            // checking admits a property present in EITHER member, so an object
+            // matching neither type-checks against the union.
+            const version = push.version ?? UNKNOWN_CLIENT_VERSION;
             const result = await connection.workspace.applyEdit({
                label: options?.label,
-               documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               edit: {
+                  documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(clientUri, version), push.edits)]
+               }
             });
             if (result && result.applied === false) {
-               this.__shadow.invalidate(targetUri);
-               this.__pendingPushes.delete(targetUri);
+               push.notifyOutcome('refused');
+            } else if (result?.applied) {
+               push.notifyOutcome('applied');
             }
             lastResult = result;
-         } catch (err) {
-            this.__shadow.invalidate(targetUri);
-            this.__pendingPushes.delete(targetUri);
+         } catch (err: unknown) {
+            push.notifyOutcome('failed');
             throw err;
          }
       }
@@ -1004,125 +1447,31 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    }
 
    /**
-    * The version the LSP textual language client last declared for `uri`, for
-    * addressing an outgoing `workspace/applyEdit`.
-    *
-    * Client version ids are CLIENT-owned per LSP, so this is the id the client
-    * itself stamped on its last `didOpen` / `didChange` — never the shared
-    * server version, which advances on authored writes the client knows nothing
-    * about and would therefore reject every push.
-    *
-    * Falls back to {@link UNKNOWN_CLIENT_VERSION} when the client has never
-    * declared one, which is the honest answer for a document it has not opened.
-    * That is also the case in which there is no shadow, so the push is already a
-    * position-independent full replace and has nothing to gain from a gate.
-    */
-   protected languageClientVersion(uri: DocumentUri): number {
-      return this.__documents.get(this.documentKey(uri))?.clientVersions.get(LANGUAGE_CLIENT_ID) ?? UNKNOWN_CLIENT_VERSION;
-   }
-
-   /**
-    * Append a push to the in-flight queue for `targetUri`
-    * (see {@link __pendingPushes}). Bounded: beyond
-    * {@link PENDING_ECHO_CAP} the oldest entry drops with a debug log — an
-    * echo that far outstanding means the client is not echoing at all, and
-    * an unbounded queue must not become the leak.
-    */
-   protected recordPendingPush(targetUri: LanguageClientUri, before: string | undefined, newText: string): void {
-      let pending = this.__pendingPushes.get(targetUri);
-      if (!pending) {
-         pending = [];
-         this.__pendingPushes.set(targetUri, pending);
-      }
-      pending.push({ before, afterHash: contentHash(newText) });
-      if (pending.length > PENDING_ECHO_CAP) {
-         pending.shift();
-         this.logUri(targetUri, `Pending-echo queue exceeded ${PENDING_ECHO_CAP} entries; dropped the oldest`, 'debug');
-      }
-   }
-
-   /**
-    * Decide what an incoming language-client change actually is, by
-    * reconstructing the client's resulting buffer against the OLDEST push still
-    * in flight for `clientFacing`.
-    *
-    * `undefined` when nothing of ours is in flight, which is the ordinary path:
-    * the client's ranges then address the synced text and the caller applies
-    * them to it directly.
-    *
-    * **Why the oldest, and why reconstruct at all.** The client applies our
-    * pushes in order and echoes each against the buffer it held before that
-    * push, so the first echo to arrive belongs to the oldest entry — a FIFO
-    * correspondence the queue preserves by consuming from the front. Comparing
-    * the reconstruction against every pending hash, not only the oldest, is
-    * what recognises an echo that a newer write already superseded: a rapid
-    * write sequence can deliver the echo of push N after the store applied
-    * push N+1, and everything older is then accounted for too.
-    *
-    * A reconstruction matching NO pending push means the client's buffer went
-    * somewhere we did not send it — it coalesced a keystroke into the echo, or
-    * typed before the push landed. That text is authoritative, and the queue
-    * drops: the client has stopped being a pure mirror, so no outstanding echo
-    * can match again. (A push still in flight at that point will be refused by
-    * the client's own version gate, which invalidates the shadow and makes the
-    * next sync a position-independent full replace.)
-    *
-    * Content equality is a sound echo proof because entries live only between a
-    * push and its echo — a milliseconds window, never history — and the
-    * client's `didChange` stream is ordered, so every buffer state arrives in
-    * mutation order. An UNDO returning the buffer to previously-pushed text is
-    * therefore never swallowed: the edit that preceded it already emptied the
-    * queue, so undo revisits PAST states while the queue holds IN-FLIGHT ones.
+    * Explicitly baseline the language-client shadow for a URI the client has
+    * open, for an adopter that knows what the client holds without a
+    * `didChange` saying so (e.g. after a sideband save). Normal didOpen /
+    * didChange paths from the LSP language client already auto-track the
+    * shadow. A seed for a URI the client has not opened is kept but changes no
+    * push, since nothing is pushed there; its open replaces it with the text it
+    * declares.
     */
-   protected classifyLanguageClientChange(
-      clientFacing: LanguageClientUri,
-      document: T,
-      changes: TextDocumentContentChangeEvent[]
-   ): LanguageClientChangeOrigin | undefined {
-      const pending = this.__pendingPushes.get(clientFacing);
-      if (pending === undefined || pending.length === 0) {
-         return undefined;
-      }
-      // Through the configured factories, not `TextDocument` directly, so an
-      // adopter's custom text-document type governs how the ranges are applied
-      // here exactly as it does on the synced document.
-      const probe = this.create(clientFacing, document.languageId, 0, pending[0].before ?? document.getText());
-      const clientText = this.update(probe, changes, 0).getText();
-      const matchIndex = pending.findIndex(push => push.afterHash === contentHash(clientText));
-      if (matchIndex >= 0) {
-         pending.splice(0, matchIndex + 1);
-         return { kind: 'echo' };
-      }
-      pending.length = 0;
-      return { kind: 'divergent', text: clientText };
+   setLanguageClientText(uri: DocumentUri, text: string): void {
+      this.languageClientShadow.setLanguageClientText(this.toLanguageClientUri(uri), text);
    }
 
    /**
-    * Explicitly baseline the language-client text shadow for a URI. Useful in
-    * tests and for adopters that need to seed the shadow without going through
-    * a `didOpen` event (e.g. after a sideband save). Normal didOpen / didChange
-    * paths from the LSP language client already auto-track the shadow.
+    * Drop the shadow baseline for a URI; the next applyEditToLanguageClient
+    * sends a full replace, or nothing when the client was last heard to hold
+    * that text.
     */
-   setLanguageClientText(uri: DocumentUri, text: string): void {
-      const clientFacing = this.toLanguageClientUri(uri);
-      this.__shadow.set(clientFacing, text);
-      // An explicit rebaseline supersedes whatever was in flight.
-      this.__pendingPushes.delete(clientFacing);
-   }
-
-   /** Drop the shadow baseline for a URI; the next applyEditToLanguageClient sends a full replace. */
    invalidateLanguageClientText(uri: DocumentUri): void {
-      const clientFacing = this.toLanguageClientUri(uri);
-      this.__shadow.invalidate(clientFacing);
-      this.__pendingPushes.delete(clientFacing);
+      this.languageClientShadow.invalidateLanguageClientText(this.toLanguageClientUri(uri));
    }
 
    protected consumePendingContent(uri: DocumentUri): string | undefined {
-      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;
    }