@hydranium/core 1.0.0-next.7 → 1.0.0-next.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/core",
-  "version": "1.0.0-next.7",
+  "version": "1.0.0-next.71",
   "description": "Foundational runtime of the hydranium framework: AST coordination layer (services, integrity, AST extension, serialization, multi-client documents) plus the LSP textual head at the /lsp subpath. Consumed by protocol-head packages (@hydranium/data-server, @hydranium/glsp-server).",
   "keywords": [
     "hydranium",
@@ -72,6 +72,14 @@
     "./lib/testing/playwright": {
       "types": "./lib/testing/playwright/index.d.ts",
       "default": "./lib/testing/playwright/index.js"
+    },
+    "./messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
+    "./lib/messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
     }
   },
   "main": "lib/index.js",
@@ -96,8 +104,8 @@
     "diff": "^5.2.0"
   },
   "devDependencies": {
-    "@hydranium/langium": "1.0.0-next.7",
-    "@hydranium/protocol": "1.0.0-next.7",
+    "@hydranium/langium": "1.0.0-next.71",
+    "@hydranium/protocol": "1.0.0-next.71",
     "@playwright/test": "^1.40.0",
     "@types/diff": "^5.2.0",
     "rimraf": "^5.0.0",
@@ -109,12 +117,12 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "@hydranium/langium": "1.0.0-next.7",
-    "@hydranium/protocol": "1.0.0-next.7",
+    "@hydranium/langium": "1.0.0-next.71",
+    "@hydranium/protocol": "1.0.0-next.71",
     "@playwright/test": "^1.40.0",
-    "vscode-jsonrpc": "^8.0.0 || ^9.0.0",
-    "vscode-languageserver": "^9.0.0 || ^10.0.0",
-    "vscode-languageserver-protocol": "^3.17.5",
+    "vscode-jsonrpc": "9.0.1",
+    "vscode-languageserver": "~10.0.1",
+    "vscode-languageserver-protocol": "~3.18.1",
     "vscode-languageserver-textdocument": "^1.0.12",
     "vscode-languageserver-types": "^3.17.5"
   },
@@ -129,6 +137,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest, and docs/adopting/requirements.md carries the block to paste. This manifest declares the two links ABOVE the transport as well, and they carry `~` for the same reason: each admits exactly what `langium@4.3.1` itself admits, and a wider range reaches a `vscode-languageserver@9` / `vscode-languageserver-protocol@3.17.x` that depends on the 8.x transport, which is the same split one level up. `vscode-languageserver-types` and `vscode-languageserver-textdocument` are deliberately NOT narrowed: both declare zero dependencies and expose structural APIs, so a duplicate of either drags no transport in and no identity check reads it.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
   "//sideEffects": "NOT `false`: two barrels do work at module load that their re-exports do not account for, and a bundler skips an unflagged re-export barrel outright. `node/index.js` calls `installNodeLogFileSink()` and `installNodeWriteLockScope()`, which is how a Node host gets the log file-tee and write-lock reentrancy detection merely by importing `@hydranium/core/node`. `util/index.js` carries a bare `import '@hydranium/langium'` so the `UriUtils` namespace augmentation stays loaded for anything importing from here. Both failures are runtime-only and silent — a missing log file, a `UriUtils.toUri` that is `undefined`."
 }

package/src/documents/ast-document-manager.ts

@@ -166,6 +166,51 @@ export type AstDocumentSavedEvent<TAst extends AstNode, TDiagnostic> = TransferS
 /** Construction options for {@link AstDocumentManager}. */
 export type AstDocumentManagerOptions = LogNameOptions;
 
+/**
+ * The document slot the model server and the integrity service talk to:
+ * open/close/update/save plus the AST-typed event streams, with the LSP
+ * plumbing hidden.
+ *
+ * Generic over `<TAst extends AstNode, TDiagnostic>` so each consumer projects
+ * its own AST root type and diagnostic shape into the emitted
+ * {@link AstDocument} envelopes.
+ *
+ * **URI contract.** Every URI-accepting member takes a URI in *any* spelling
+ * (canonical, symlinked, `..`/case-divergent) and canonicalizes internally
+ * through the {@link DocumentUriPolicy}, so a caller never has to canonicalize
+ * first and an implementation may not require it.
+ */
+export interface AstDocumentManager<TAst extends AstNode, TDiagnostic = unknown> {
+   open(args: OpenModelArgs): Promise<Disposable>;
+   close(args: CloseModelArgs): Promise<void>;
+   isOpen(uri: string): boolean;
+
+   /** Apply `text` as `clientId`'s edit. Resolves to the resulting text-document version. */
+   update(uri: string, text: string, clientId: string): Promise<number>;
+   save(uri: string, clientId: string): Promise<void>;
+
+   onUpdate(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onSave(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void | Promise<void>): Disposable;
+   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+
+   getDocument(uri: string): LangiumDocument | undefined;
+
+   /** Client id that authored the document's current version, or `undefined` for a framework-internal build. */
+   getAuthor(document: LangiumDocument): string | undefined;
+
+   /**
+    * Whether `uri` is one of the URIs the most recent build request named, as
+    * opposed to a document that build swept in as a dependent. Deletions are
+    * excluded: they never reach this layer, since a deleted document is
+    * removed before the build set is computed.
+    *
+    * The answer refers to the latest request, which may still be building, and
+    * it is retained between builds — so outside a build it describes whichever
+    * one ran last.
+    */
+   isTriggeringEdit(uri: string): boolean;
+}
+
 /**
  * Higher-level facade over {@link HydraniumTextDocuments} that speaks the
  * model-server protocol (open/close/update/save with the transfer-model event
@@ -186,7 +231,7 @@ export type AstDocumentManagerOptions = LogNameOptions;
  * resolution (the egress `applyEditToLanguageClient`) stay on
  * {@link HydraniumTextDocuments}, their owner.
  */
-export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = unknown> {
+export class DefaultAstDocumentManager<TAst extends AstNode, TDiagnostic = unknown> implements AstDocumentManager<TAst, TDiagnostic> {
    protected lastUpdate?: UpdateInfo;
 
    protected readonly textDocuments: HydraniumTextDocuments<TextDocument>;
@@ -311,11 +356,12 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
          const event: TransferUpdatedEvent<AstDocument<TAst, TDiagnostic>> = {
             document: this.toAstDocument(document),
             sourceClientId,
-            reason: this.lastUpdate?.changed.find(changed => UriUtils.equals(changed, document.uri))
-               ? 'changed'
-               : this.lastUpdate?.deleted.find(deleted => UriUtils.equals(deleted, document.uri))
-                 ? 'deleted'
-                 : 'rebuilt'
+            // No `'deleted'` arm: `DocumentBuilder.update` drops a deleted
+            // document from `LangiumDocuments` before deriving the rebuild set
+            // from it, so a deleted URI is never built and never reaches this
+            // phase listener. A subscriber needing deletions has to be told on
+            // a channel that does not require a built document.
+            reason: this.lastUpdate?.changed.some(changed => UriUtils.equals(changed, document.uri)) ? 'changed' : 'rebuilt'
          };
          this.tracer.with(uri).trace(`emitUpdate start: source=${sourceClientId}, reason=${event.reason}`);
          listener(event);
@@ -334,7 +380,7 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
     * concrete value (the `onUpdate` event's `sourceClientId`, the data-server's
     * `resolveSourceClientId`).
     */
-   getAuthor(document: LangiumDocument<AstNode>): string | undefined {
+   getAuthor(document: LangiumDocument): string | undefined {
       return this.textDocuments.getAuthor(document.textDocument.uri, document.textDocument.version);
    }
 
@@ -355,10 +401,17 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
       // transiently breaks cross-document linking mid-rebuild (a dependent briefly
       // seeing an `extends`/`type` reference unresolved). And because the constructor
       // wires `onDidOpen -> this.open`, it would fire a second, identical rebuild on
-      // every first open. So an already-open `open()` is a no-op.
+      // every first open.
+      //
+      // So an already-open `open()` records the attaching client's hold and nothing
+      // else. The hold is per `(uri, clientId)` and the last-close revert counts down
+      // to it, so skipping it lets the first holder's close tear down a document
+      // another client is still reading.
       if (!this.isOpen(args.uri)) {
          const textDocument = await this.createDocumentFromTextOrFileSystem(args.uri, args.languageId, args.version, args.text);
          this.textDocuments.notifyDidOpenTextDocument({ textDocument }, args.clientId);
+      } else {
+         this.textDocuments.attachClient(args.uri, args.clientId);
       }
       return Disposable.create(() => this.close(args));
    }
@@ -393,29 +446,56 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
     * callers don't need to pass it — the manager owns content and version
     * sequencing.
     *
+    * **The write is skipped when the file already holds that text; the
+    * notification is not.** A save announces that the content is on disk, which
+    * is true either way — so a subscriber clearing a dirty marker or reacting to
+    * a persist behaves the same, while an mtime is not moved for byte-identical
+    * content that a downstream mtime-keyed build would then read as new work.
+    *
     * Throws if no document is open for `uri`.
     */
    async save(uri: string, clientId: string): Promise<void> {
-      const document = this.textDocuments.get(uri);
+      // Canonical throughout: the write and the read that gates it must address
+      // the same file the store was keyed by, or a divergent spelling compares
+      // one file and writes another.
+      const canonical = this.uriPolicy.canonicalUri(uri);
+      const document = this.textDocuments.get(canonical);
       if (!document) {
          throw new Error(`Document ${uri} hasn't been opened for saving yet`);
       }
       const text = document.getText();
-      await this.tracer.with(uri).time(
-         `Write file (${text.length} bytes, from ${clientId})`,
-         // Async write so a slow disk does not block the event loop for the duration of the fs call.
-         () => this.fileSystemProvider.writeFile(UriUtils.toUri(uri), text),
-         'debug'
-      );
-      this.textDocuments.notifyDidSaveTextDocument({ textDocument: TextDocumentIdentifier.create(uri), text }, clientId);
+      if (!(await this.matchesDisk(canonical, text))) {
+         await this.tracer.with(canonical).time(
+            `Write file (${text.length} bytes, from ${clientId})`,
+            // Async write so a slow disk does not block the event loop for the duration of the fs call.
+            () => this.fileSystemProvider.writeFile(UriUtils.toUri(canonical), text),
+            'debug'
+         );
+      }
+      this.textDocuments.notifyDidSaveTextDocument({ textDocument: TextDocumentIdentifier.create(canonical), text }, clientId);
+   }
+
+   /**
+    * Whether the file at `uri` already holds `text`.
+    *
+    * Compared by CONTENT rather than against a remembered version, so a write
+    * from outside this server is still corrected: a version this manager already
+    * saved says nothing about what is on disk now. `false` when the file cannot
+    * be read at all, which is the answer that writes — a document whose file does
+    * not exist yet is exactly the one a first save has to create.
+    */
+   protected async matchesDisk(uri: string, text: string): Promise<boolean> {
+      return this.fileSystemProvider
+         .readFile(UriUtils.toUri(uri))
+         .then(onDisk => onDisk === text)
+         .catch(() => false);
    }
 
    isOpen(uri: string): boolean {
       return !!this.textDocuments.get(uri);
    }
 
-   /** True if the URI was in the directly-changed set of the most recent build (not just affected). */
-   isDirectChange(uri: string): boolean {
+   isTriggeringEdit(uri: string): boolean {
       const canonical = this.uriPolicy.canonicalUri(uri);
       return this.lastUpdate?.changed.some(changed => this.uriPolicy.canonicalUri(changed) === canonical) ?? false;
    }
@@ -437,11 +517,7 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
       version = 0,
       text?: string
    ): Promise<TextDocumentItem> {
-      return { uri, languageId, version, text: text ?? (await this.readFile(uri)) };
-   }
-
-   async readFile(uri: string): Promise<string> {
-      return this.fileSystemProvider.readFile(UriUtils.toUri(uri));
+      return { uri, languageId, version, text: text ?? (await this.fileSystemProvider.readFile(UriUtils.toUri(uri))) };
    }
 
    /**

package/src/documents/client-ids.ts

@@ -8,26 +8,9 @@
  ********************************************************************************/
 
 /**
- * Well-known client-kind identifiers used across the multi-client framework.
- *
- * The framework tracks each document as belonging to one or more "clients"
- * — typically an LSP-text-client (Monaco, VS Code, etc.), a GLSP diagram
- * client, and/or a structured-form client. Each kind carries a stable id so
- * the server can route outbound corrections, edits, and notifications to the
- * right transport.
- */
-
-/** Identifier for an LSP-text client (Monaco, VS Code, …). */
-export const LANGUAGE_CLIENT_ID = 'language-client';
-
-/** Fallback identifier when a document's author is unknown (e.g. cold workspace-init load). */
-export const UNKNOWN_CLIENT_ID = 'unknown';
-
-/**
- * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
- * emits after the LAST client closed a document and the framework rebuilt it
- * from its disk content (discarding unsaved in-session edits). Not a real
- * client: it lets consumers distinguish the revert broadcast from
- * client-authored updates.
+ * Re-export, because these are WIRE values and the side that has to recognise
+ * them is the client. They are defined in `@hydranium/protocol` so a frontend
+ * can name them without depending on the server tier; this path stays so
+ * server-side code keeps importing them from where it already does.
  */
-export const REVERT_ON_CLOSE_CLIENT_ID = 'revert-on-close';
+export { FRAMEWORK_CLIENT_IDS, LANGUAGE_CLIENT_ID, REVERT_ON_CLOSE_CLIENT_ID, UNKNOWN_CLIENT_ID } from '@hydranium/protocol';

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

@@ -37,6 +37,7 @@ import {
    OptionalVersionedTextDocumentIdentifier,
    type RequestHandler,
    type TextDocumentChangeEvent,
+   TextDocumentContentChangeEvent as ContentChange,
    TextDocumentEdit,
    TextDocumentSyncKind,
    type TextDocumentWillSaveEvent,
@@ -165,15 +166,15 @@ interface ConnectionWithTextDocumentSync {
  */
 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.
+    * 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 +183,25 @@ interface PendingPush {
 
 /**
  * What an incoming language-client change turns out to be once reconstructed
- * against the pushes still in flight — the return of
+ * against the buffer its ranges address — 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.
+    * 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 };
+   | { 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: 'unreconstructable' };
 
 /**
  * Cheap, stable, non-cryptographic content hash (cyrb53) for the version
@@ -471,15 +479,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,6 +500,10 @@ 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
@@ -498,12 +511,12 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          // 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);
@@ -644,18 +657,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;
@@ -694,22 +709,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) {
@@ -967,10 +1037,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 +1056,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 +1125,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 +1166,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 };
    }
 
    /**