@hydranium/core 1.0.0-next.11 → 1.0.0-next.112

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

@@ -37,6 +37,7 @@ import {
    OptionalVersionedTextDocumentIdentifier,
    type RequestHandler,
    type TextDocumentChangeEvent,
+   TextDocumentContentChangeEvent as ContentChange,
    TextDocumentEdit,
    TextDocumentSyncKind,
    type TextDocumentWillSaveEvent,
@@ -89,8 +90,13 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
  *    separately-tested diff/apply-verify abstraction that owns its own baseline
  *    text; folding its storage here would couple a clean utility to this record
  *    for no real gain.
+ *
+ * Returned by the `protected` {@link HydraniumTextDocuments.trackingFor}, so an
+ * override has to name it. Restating the shape structurally instead compiles
+ * until a field is added here, and then fails at the adopter rather than at the
+ * change that caused it.
  */
-interface DocumentTracking {
+export interface DocumentTrackingRecord {
    /** 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. */
@@ -128,13 +134,28 @@ export interface OpenDocument {
    readonly clients: readonly string[];
 }
 
+/**
+ * What {@link HydraniumTextDocuments.commitRepair} did with an integrity repair.
+ *
+ * Three outcomes rather than a document-or-nothing, because the two ways of
+ * getting nothing call for opposite responses: `not-open` means there is no
+ * store document to correct and the caller carries on with the one it holds,
+ * while `stale` means there IS one and it has moved past the text the repair
+ * was computed against — so carrying on would persist a correction over an edit
+ * that superseded it. Collapsing them lets the second read as permission to
+ * proceed, which is the failure this shape exists to make unrepresentable.
+ */
+export type RepairCommit<T extends TextDocument> =
+   { readonly status: 'committed'; readonly document: T } | { readonly status: 'stale' } | { readonly status: 'not-open' };
+
 /**
  * Where a URI's shared version sequence left off — written once at last-client
  * close, consulted at the next open so the sequence CONTINUES instead of
  * restarting at whatever version id the reopening client declares. One entry
- * of {@link HydraniumTextDocuments.__versionSequences}.
+ * of {@link HydraniumTextDocuments.__versionSequences} — a `protected` field, so
+ * a subclass reading the map has to name what it holds.
  */
-interface VersionSequence {
+export interface VersionSequence {
    /** The shared version at last-client close. */
    readonly version: number;
    /** {@link contentHash} of the synced text at last-client close. */
@@ -161,19 +182,20 @@ interface ConnectionWithTextDocumentSync {
 /**
  * One text pushed to the LSP textual language client by
  * {@link HydraniumTextDocuments.applyEditToLanguageClient} whose echo has not
- * come back yet. One entry of {@link HydraniumTextDocuments.__pendingPushes}.
+ * come back yet. One entry of {@link HydraniumTextDocuments.__pendingPushes} —
+ * a `protected` field, so a subclass reading the queue has to name what it holds.
  */
-interface PendingPush {
+export interface PendingLanguageClientPush {
    /**
-    * The text the client held BEFORE this push — the shadow baseline the
-    * push's edits were diffed against, and therefore the text the client's
-    * echo addresses with its ranges.
+    * The text the client held BEFORE this push, and therefore the text its
+    * echo addresses with its ranges. Wider than the baseline the push's edits
+    * were diffed against: a full replace is sent with no diff baseline and
+    * still lands on a buffer the echo is keyed to.
     *
-    * `undefined` when the push was a full replace sent with no baseline (a
-    * first sync, or the recovery push after a rejection). There is then no
-    * knowing what the client held, so the echo is reconstructed against the
-    * synced text instead — which is sound for a full replace, whose
-    * application is position-independent.
+    * `undefined` only when that buffer is unknown — the client never declared
+    * one, or a rejection invalidated what was tracked. The echo is then
+    * reconstructed against the synced text, which is sound only for a
+    * position-independent (full-text) change.
     */
    readonly before: string | undefined;
    /** {@link contentHash} of the text this push moves the client to. */
@@ -182,18 +204,26 @@ interface PendingPush {
 
 /**
  * What an incoming language-client change turns out to be once reconstructed
- * against the pushes still in flight — the return of
- * {@link HydraniumTextDocuments.classifyLanguageClientChange}.
+ * against the buffer its ranges address — the return of
+ * {@link HydraniumTextDocuments.classifyLanguageClientChange}. That method is
+ * `protected`, so an override has to name every arm it can return.
  */
-type LanguageClientChangeOrigin =
+export type LanguageClientChangeOrigin =
    /** The client is reporting a text we pushed it. The synced document is already there. */
    | { readonly kind: 'echo' }
    /**
-    * The client's buffer has moved somewhere we did not push it — it coalesced
-    * a genuine keystroke into the echo, or typed before the push arrived. The
-    * reconstructed text is what it now holds, and is authoritative.
+    * The client's buffer holds a text we did not push it — a keystroke that
+    * raced a push, or an edit to a buffer the store has already been written
+    * past. The reconstructed text is what it now holds, and is authoritative.
+    */
+   | { readonly kind: 'divergent'; readonly text: string }
+   /**
+    * The change carries ranges and no known text addresses them, so no
+    * reconstruction is offered. Adopting one anyway splices the document and
+    * stores an edit nobody made; dropping costs at most the one keystroke the
+    * client still holds and the next push contradicts.
     */
-   | { readonly kind: 'divergent'; readonly text: string };
+   | { readonly kind: 'unreconstructable' };
 
 /**
  * Cheap, stable, non-cryptographic content hash (cyrb53) for the version
@@ -229,7 +259,7 @@ function contentHash(text: string): string {
  *     per-client staleness guard and never leak into the shared sequence —
  *     the two are different things (an editor's edit-operation counter vs the
  *     document's content-revision number), and splicing them lets versions drift
- *     silently past `baseVersion` gate holders.
+ *     silently past based-on gate holders.
  *   - Version-author history so each edit is attributable to its originating client.
  *   - Pending-content staging used by the integrity service to thread corrections
  *     through `workspace/applyEdit` cycles for currently-closed documents.
@@ -240,23 +270,23 @@ function contentHash(text: string): string {
  */
 export class HydraniumTextDocuments<T extends TextDocument = TextDocument> extends NormalizedTextDocuments<T> {
    /**
-    * Per-URI client-facing tracking ({@link DocumentTracking}): client
+    * Per-URI client-facing tracking ({@link DocumentTrackingRecord}): 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>();
+   protected __documents = new Map<CanonicalUri, DocumentTrackingRecord>();
 
    /**
     * Per-URI shared-version continuity across close/reopen cycles
     * ({@link VersionSequence}), written at last-client close and consulted by
-    * the next first-client open. DELIBERATELY outside {@link DocumentTracking}:
+    * the next first-client open. DELIBERATELY outside {@link DocumentTrackingRecord}:
     * that record is deleted on last close, while the version sequence must
     * survive it — the shared version is a server-owned, monotonic,
     * advances-iff-content-changes counter that never resets while the server
-    * lives. That invariant is what makes an optimistic `baseVersion` gate
+    * lives. That invariant is what makes an optimistic based-on gate
     * sound: "version unchanged ⇔ content unchanged", with no false conflicts
     * from close/reopen version resets and no false passes from a reopened
     * sequence coincidentally landing on a stale writer's number.
@@ -269,7 +299,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    /**
     * Texts pushed to the LSP textual language client via
     * {@link applyEditToLanguageClient} whose echoes have not come back yet
-    * ({@link PendingPush}), keyed like the shadow by language-client URI.
+    * ({@link PendingLanguageClientPush}), keyed like the shadow by language-client URI.
     * Outbound pushes and inbound echoes are uncorrelated on the wire; this
     * FIFO is the explicit correlation, and it is what
     * {@link classifyLanguageClientChange} reconstructs against.
@@ -291,7 +321,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * a pathological echo that never arrives; the memory cost until then is
     * one pre-push text per in-flight push, for milliseconds.
     */
-   protected readonly __pendingPushes = new Map<LanguageClientUri, PendingPush[]>();
+   protected readonly __pendingPushes = new Map<LanguageClientUri, PendingLanguageClientPush[]>();
 
    /**
     * Tracked text content per URI for the LSP textual language client (Monaco / VS Code).
@@ -471,15 +501,16 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          }
          record.clientVersions.set(clientId, td.version);
 
-         // A language-client change arriving while one of our own pushes is in
-         // flight is keyed to the buffer the client held BEFORE that push, NOT
-         // to the synced text — the authored write already advanced the latter.
+         // A language-client change is keyed to the buffer that client holds,
+         // which is the synced text only while the two agree — an authored
+         // write advances the synced text without the client knowing, and a
+         // push in flight moves the client without the store knowing.
          // Resolve which it is, and against what, before touching anything.
-         const inFlight =
+         const origin =
             clientId === LANGUAGE_CLIENT_ID
                ? this.classifyLanguageClientChange(this.toLanguageClientUri(td.uri), document, changes)
                : undefined;
-         if (inFlight?.kind === 'echo') {
+         if (origin?.kind === 'echo') {
             // The client is reporting a text we pushed it, so the synced
             // document is ALREADY there and the changes must not be applied a
             // second time. Nothing is minted and no rebuild fires. The
@@ -491,19 +522,23 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             this.logUri(uri, `Skip rebuild: echo of a server-authored push (client version ${td.version})`, 'debug');
             return;
          }
+         if (origin?.kind === 'unreconstructable') {
+            this.tracer.with(uri).warn(`Drop change: no known client buffer for its ranges (client version ${td.version})`);
+            return;
+         }
 
          // The SHARED version advances iff the content actually changes — the
-         // invariant optimistic `baseVersion` gates rely on. The new text is
+         // invariant optimistic based-on gates rely on. The new text is
          // only known after applying the (possibly incremental) changes, so
          // apply at a tentative +1 and roll the version back on an identical
          // result (an empty-changes update only re-stamps the version).
          //
-         // A divergent in-flight change is applied as its RECONSTRUCTED text
-         // rather than as its own ranges: the ranges address the pre-push
-         // baseline, so applying them here would splice the wrong lines.
+         // A divergent change is applied as its RECONSTRUCTED text rather than
+         // as its own ranges: those ranges address the client's own buffer, so
+         // applying them here would splice the wrong lines.
          const previousText = document.getText();
          const sharedVersion = document.version;
-         document = this.configuration.update(document, inFlight === undefined ? changes : [{ text: inFlight.text }], sharedVersion + 1);
+         document = this.configuration.update(document, origin === undefined ? changes : [{ text: origin.text }], sharedVersion + 1);
          const changed = document.getText() !== previousText;
          if (!changed) {
             document = this.configuration.update(document, [], sharedVersion);
@@ -544,7 +579,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * A content-identical write still fires the change event (rebuild): the
     * authored write's server-side rebuild is correctness-bearing, it just
     * mints no new version — nothing observable changed, so watchers'
-    * `baseVersion` pointers stay valid.
+    * based-on versions stay valid.
     *
     * Returns the resulting shared version. Throws when the document is not
     * open — callers (`AstDocumentManager.update`) open first.
@@ -644,18 +679,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       if (this.isOpenInClient(uri, clientId)) {
          // Already open for this client under this canonical identity. If this is a
          // NEW client-facing URI for the same file (a second tab reached via a
-         // divergent path, e.g. a symlink and its real path), record it and baseline
-         // its shadow so outbound edits reach this tab too — but do NOT re-fire
-         // open/rebuild; the document is already live.
+         // divergent path, e.g. a symlink and its real path), record it so outbound
+         // edits reach this tab too — but do NOT re-fire open/rebuild; the document
+         // is already live.
          if (clientId === LANGUAGE_CLIENT_ID) {
             const clientFacing = this.toLanguageClientUri(td.uri);
             const record = this.__documents.get(uri);
             if (record && !record.languageClientUris?.has(clientFacing)) {
                (record.languageClientUris ??= new Set<LanguageClientUri>()).add(clientFacing);
-               const open = this.__syncedDocuments.get(uri);
-               if (open) {
-                  this.__shadow.set(clientFacing, open.getText());
-               }
+               // This tab's own buffer, NOT the synced text: a second tab is a second
+               // client model, read from disk, so a server-authored write already
+               // applied to the first tab leaves it BEHIND the synced document. Keying
+               // a diff to the synced text here addresses lines this tab does not have
+               // and drops content it does.
+               this.__shadow.setOpenedText(clientFacing, td.text);
             }
          }
          return;
@@ -679,7 +716,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          const source = pendingText ? ', source=pending' : '';
          // The SHARED version is server-assigned: continue the persisted
          // sequence — same version when the content is unchanged since the
-         // last close (so watchers' `baseVersion` pointers stay valid), one
+         // last close (so watchers' based-on versions stay valid), one
          // step when it changed (so no stale pointer can coincidentally pass
          // the optimistic gate). Only a first-ever open adopts the client's
          // declared id as the sequence seed.
@@ -694,22 +731,77 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // Baseline the shadow to what Monaco just opened so the next outbound
             // applyEditToLanguageClient diffs against the right starting point. Keyed by the
             // language-client URI (what Monaco holds), not the canonical document key.
-            this.__shadow.set(this.toLanguageClientUri(td.uri), document.getText());
+            //
+            // The CLIENT's declared text, never the synced document: staged content
+            // consumed above leaves the two different, and a baseline asserting the
+            // client already holds the staged text suppresses the one sync that would
+            // deliver it. Skipped entirely when a push is already outstanding for this
+            // URI — an `applyEdit` to a closed file has the client open from disk and
+            // apply afterwards, so that shadow records what it is about to hold and
+            // disk text would key the next diff to a buffer nobody has.
+            const clientFacing = this.toLanguageClientUri(td.uri);
+            if (!this.__shadow.isTracked(clientFacing)) {
+               this.__shadow.set(clientFacing, td.text);
+            }
          }
          const toFire = Object.freeze({ document, clientId });
          this.__onDidOpen.fire(toFire);
          this.__onDidChangeContent.fire(toFire);
       } else {
          // An additional client attaches to a document already open by another client.
-         this.log(
-            uri,
-            `Attach client: ${clientId} joined existing document (version ${document.version}, ` +
-               `now open in: ${[...existingClients, clientId].join(', ')})`
-         );
+         this.logClientJoined(uri, clientId, document.version, existingClients);
+         if (clientId === LANGUAGE_CLIENT_ID) {
+            // Monaco's own buffer, which on this path is NOT the synced text — another
+            // client opened the document and may already have changed it. Recorded as
+            // an equality-only baseline (never a diff one, see `setOpenedText`) so the
+            // refresh below does not push a full replace of content Monaco already
+            // holds, which would dirty the file on open.
+            this.__shadow.setOpenedText(this.toLanguageClientUri(td.uri), td.text);
+         }
          this.refreshContent(uri, clientId);
       }
    }
 
+   /**
+    * Record `clientId` as an additional holder of a document another client
+    * already has open.
+    *
+    * Unlike the attach branch of {@link notifyDidOpenTextDocument} this does
+    * not refresh. That branch re-renders an attaching TEXTUAL view; a client
+    * reaching a document through a non-textual route has nothing to re-render,
+    * and refreshing per attach turns each into a Langium rebuild and dependent
+    * relink cascade.
+    *
+    * The staleness guard baselines at the SYNCED version, not a declared buffer
+    * version, because a client arriving this way holds no buffer of its own.
+    * Unifying the two routes therefore rebaselines a textual client's guard to a
+    * version it never declared.
+    *
+    * Returns whether a hold was added — `false` when `uri` is not open, or
+    * `clientId` already holds it.
+    */
+   attachClient(uri: DocumentUri, clientId: string): boolean {
+      const key = this.documentKey(uri);
+      const document = this.__syncedDocuments.get(key);
+      if (!document || this.isOpenInClient(key, clientId)) {
+         return false;
+      }
+      const record = this.trackingFor(key);
+      const existingClients = [...record.clients];
+      record.clients.add(clientId);
+      record.clientVersions.set(clientId, document.version);
+      this.logClientJoined(key, clientId, document.version, existingClients);
+      return true;
+   }
+
+   protected logClientJoined(uri: DocumentUri, clientId: string, version: number, existingClients: readonly string[]): void {
+      this.log(
+         uri,
+         `Attach client: ${clientId} joined existing document (version ${version}, ` +
+            `now open in: ${[...existingClients, clientId].join(', ')})`
+      );
+   }
+
    refreshContent(uri: DocumentUri, clientId: string): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(uri));
       if (syncedDocument) {
@@ -730,7 +822,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * two URIs for one physical file (a symlink path and its real path) into a
     * single registration — dedup at the editor layer, not just in
     * `LangiumDocuments`. The URI the client opened under is preserved separately
-    * for egress addressing (see {@link DocumentTracking.languageClientUris}). The
+    * for egress addressing (see {@link DocumentTrackingRecord.languageClientUris}). The
     * policy is always bound (the framework defaults it to
     * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
     */
@@ -751,7 +843,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    }
 
    /** Get-or-create the per-URI tracking record. `uri` must already be a {@link documentKey}. */
-   protected trackingFor(uri: CanonicalUri): DocumentTracking {
+   protected trackingFor(uri: CanonicalUri): DocumentTrackingRecord {
       let record = this.__documents.get(uri);
       if (!record) {
          record = { clients: new Set(), versionAuthors: [], clientVersions: new Map() };
@@ -790,7 +882,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * `0` for a URI this store has never seen. The shared sequence is
     * server-owned and monotonic across close/reopen cycles, and advances
     * exactly when the synced content changes — which is what makes it a sound
-    * optimistic-concurrency token (`baseVersion` gates): version unchanged ⇔
+    * optimistic-concurrency token (based-on gates): version unchanged ⇔
     * content unchanged.
     */
    version(uri: DocumentUri): number {
@@ -832,6 +924,51 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       return stepped.version;
    }
 
+   /**
+    * Commit an integrity repair into the OPEN document for `uri`, returning the
+    * document that now holds it, or `undefined` when there was nothing here to
+    * commit into.
+    *
+    * The one thing this exists to do is address the store BY URI. A repair
+    * reaches the resync as a text-document object, and that object is the
+    * store's own only on the LSP path; a document built for an already-open URI
+    * through `LangiumDocumentFactory.fromString` carries its own, so writing the
+    * repair into it corrects a copy the store does not know about and the editor
+    * never sees.
+    *
+    * `parsedFrom` is the text the repaired AST was parsed from, and a mismatch
+    * against the current content REFUSES the commit: the store has moved on,
+    * which means an editor change landed after that parse, and committing would
+    * overwrite a newer edit with a repair computed against text the user has
+    * already replaced. The build that change provokes recomputes the repair.
+    *
+    * Deliberately NOT compared by version. A separately created document seeds
+    * its own numbering, so requiring the two to agree would refuse every commit
+    * on the path this exists for. Content is the thing both sides can be held to.
+    *
+    * The version is KEPT rather than stepped, and no change event is fired: the
+    * repair rides the build already under way, so minting a version would
+    * invalidate the based-on token every watcher just took, and an event would
+    * re-enter the build that is mid-flight.
+    */
+   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' };
+      }
+      // Reassigned rather than mutated in place: the default configuration
+      // updates and returns the SAME instance, but an adopter-supplied one may
+      // return a new object, and the store must end up holding whichever it is.
+      const updated = this.configuration.update(document, [{ text: repaired }], document.version);
+      this.__syncedDocuments.set(key, updated);
+      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.
@@ -898,18 +1035,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    }
 
    /**
-    * Stages integrity-updated content for a closed document.
+    * Stages integrity-updated content for a document no editor holds.
     *
     * When `workspace/applyEdit` targets a closed file, the client opens it from
     * disk (stale) and sends `didOpen` before applying the edit. This staged
     * content is consumed by {@link notifyDidOpenTextDocument} to replace the
     * stale disk text, preventing a brief revert of the integrity update.
     *
-    * Not cleared on close: pending content is only staged for already-closed
-    * documents (the integrity service checks `isOpenInLanguageClient` first), so
-    * a close → stage → open cycle cannot occur. The only scenario where an
-    * entry lingers is if `workspace/applyEdit` fails and the file is never
-    * opened — the memory cost is one serialised string per URI.
+    * Only a FIRST open consumes it. The integrity service stages whenever the
+    * URI is not open in the language client, which includes a URI held only
+    * through another head; an editor attaching to that URI joins the existing
+    * entry and never reads the stage, and the last close discards it with the
+    * tracking record. For a closed URI an entry lingers only if
+    * `workspace/applyEdit` fails and the file is never opened — the memory cost
+    * is one serialised string per URI.
     */
    stagePendingContent(uri: DocumentUri, text: string): void {
       this.trackingFor(this.documentKey(uri)).pendingContent = text;
@@ -967,10 +1106,11 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       const targets: Iterable<LanguageClientUri> = recorded && recorded.size > 0 ? recorded : [this.toLanguageClientUri(uri)];
       let lastResult: ApplyWorkspaceEditResult | undefined;
       for (const targetUri of targets) {
-         // Read BEFORE computeEdits, which overwrites it. This is the text the
-         // edits below are keyed to, and therefore the only text the client's
-         // echo of them can be reconstructed against.
-         const before = this.__shadow.get(targetUri);
+         // Read BEFORE computeEdits, which overwrites the baseline and drops
+         // the opened snapshot. This is the text the client holds, and
+         // therefore the only text its echo of this push can be reconstructed
+         // against — whether or not the push below is keyed to it.
+         const before = this.__shadow.clientText(targetUri);
          const edits = this.__shadow.computeEdits(targetUri, newText);
          if (edits.length === 0) {
             continue;
@@ -985,9 +1125,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // it is exactly what the caller retries with after a rejection, so
             // gating it there would refuse the recovery too.
             const version = isFullReplace(edits) ? UNKNOWN_CLIENT_VERSION : this.languageClientVersion(uri);
+            // A full `ApplyWorkspaceEditParams`, `edit` and all — NOT a bare
+            // `WorkspaceEdit` with a `label` beside it. `applyEdit` takes
+            // `ApplyWorkspaceEditParams | WorkspaceEdit` and discriminates on
+            // `!!value.edit`, so `{ label, documentChanges }` is wrapped as
+            // `{ edit: { label, documentChanges } }` — putting the label inside
+            // the edit, where LSP defines no such field and no client reads it.
+            // The union is also what hides it at compile time: excess-property
+            // checking admits a property present in EITHER member, so an object
+            // matching neither type-checks against the union.
             const result = await connection.workspace.applyEdit({
                label: options?.label,
-               documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               edit: {
+                  documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               }
             });
             if (result && result.applied === false) {
                this.__shadow.invalidate(targetUri);
@@ -1043,12 +1194,17 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
 
    /**
     * Decide what an incoming language-client change actually is, by
-    * reconstructing the client's resulting buffer against the OLDEST push still
-    * in flight for `clientFacing`.
+    * reconstructing the client's resulting buffer against the text its ranges
+    * address — the pre-push buffer of the OLDEST push still in flight for
+    * `clientFacing`, else whatever that client is believed to hold.
     *
-    * `undefined` when nothing of ours is in flight, which is the ordinary path:
-    * the client's ranges then address the synced text and the caller applies
-    * them to it directly.
+    * `undefined` when the client's ranges address the synced text itself —
+    * nothing in flight, and no evidence the client holds anything else. That
+    * is the ordinary path, and the caller then applies the ranges directly.
+    * The two texts part company without a push in flight whenever a client
+    * attaches to a document another client has already written: it opened
+    * from disk, so applying its ranges to the synced text splices lines they
+    * never addressed.
     *
     * **Why the oldest, and why reconstruct at all.** The client applies our
     * pushes in order and echoes each against the buffer it held before that
@@ -1079,22 +1235,41 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       document: T,
       changes: TextDocumentContentChangeEvent[]
    ): LanguageClientChangeOrigin | undefined {
-      const pending = this.__pendingPushes.get(clientFacing);
-      if (pending === undefined || pending.length === 0) {
+      const queued = this.__pendingPushes.get(clientFacing);
+      const pending = queued?.length ? queued : undefined;
+      // The text the client's ranges address: the buffer it held before the
+      // oldest push still in flight, else the buffer it is believed to hold.
+      const clientText = pending?.[0].before ?? this.__shadow.clientText(clientFacing);
+      if (pending === undefined && (clientText === undefined || clientText === document.getText())) {
          return undefined;
       }
+      if (pending !== undefined && pending[0].before === undefined && changes.some(change => ContentChange.isIncremental(change))) {
+         // A push sent to a client whose buffer was unknown — a first sync, or
+         // the recovery push after a rejection. The shadow now holds the text
+         // that push MOVES the client to, which is the one text the echo's
+         // ranges provably do not address, so the fallback above is a baseline
+         // known to be wrong rather than merely unverified. Drop the queue and
+         // the shadow: the next sync is then a full replace, which lands on
+         // whatever the client holds. A full-text change is exempt because it
+         // reconstructs identically against any baseline.
+         pending.length = 0;
+         this.__shadow.invalidate(clientFacing);
+         return { kind: 'unreconstructable' };
+      }
       // Through the configured factories, not `TextDocument` directly, so an
       // adopter's custom text-document type governs how the ranges are applied
       // here exactly as it does on the synced document.
-      const probe = this.create(clientFacing, document.languageId, 0, pending[0].before ?? document.getText());
-      const clientText = this.update(probe, changes, 0).getText();
-      const matchIndex = pending.findIndex(push => push.afterHash === contentHash(clientText));
-      if (matchIndex >= 0) {
-         pending.splice(0, matchIndex + 1);
-         return { kind: 'echo' };
+      const probe = this.create(clientFacing, document.languageId, 0, clientText ?? document.getText());
+      const reconstructed = this.update(probe, changes, 0).getText();
+      if (pending !== undefined) {
+         const matchIndex = pending.findIndex(push => push.afterHash === contentHash(reconstructed));
+         if (matchIndex >= 0) {
+            pending.splice(0, matchIndex + 1);
+            return { kind: 'echo' };
+         }
+         pending.length = 0;
       }
-      pending.length = 0;
-      return { kind: 'divergent', text: clientText };
+      return { kind: 'divergent', text: reconstructed };
    }
 
    /**