@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,893 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ * Copyright (c) Microsoft Corporation and EclipseSource. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+// Adapted from Langium's `NormalizedTextDocuments`, itself an adaptation of
+// Microsoft's `TextDocuments` — hence the Microsoft copyright above. The
+// `listen()` override below follows that handler-registration sequence:
+// https://github.com/microsoft/vscode-languageserver-node/blob/8f5fa710d3a9f60ff5e7583a9e61b19f86e39da3/server/src/common/textDocuments.ts
+// Deliberate exception to `@hydranium/core`'s no-runtime-langium/lsp rule:
+// this class IS the shared LSP-style document-sync primitive that every
+// protocol head (lsp-server, data-server, glsp-server) coordinates through.
+// Moving it into lsp-server would force data-server / glsp-server to depend
+// 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 { OptionalVersionedTextDocumentIdentifier, TextDocumentEdit, TextDocumentSyncKind } from 'vscode-languageserver';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import { asLanguageClientUri, DisposableCollection } from '@hydranium/protocol';
+import { LANGUAGE_CLIENT_ID } from './client-ids.js';
+import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
+/**
+ * The LSP spec's "version is intentionally unknown" for an
+ * {@link OptionalVersionedTextDocumentIdentifier} is `null`, but
+ * `OptionalVersionedTextDocumentIdentifier.create` requires `number` in its TS
+ * signature — so the null routes through this one typed bridge rather than a
+ * cast at each call site.
+ */
+const UNKNOWN_CLIENT_VERSION = null;
+/**
+ * Upper bound on {@link HydraniumTextDocuments.__pendingPushes} entries
+ * per URI. Echoes normally return within milliseconds and consume their
+ * entry; a queue this deep means the client stopped echoing — cap instead
+ * of leaking.
+ */
+const PENDING_ECHO_CAP = 32;
+/**
+ * Cheap, stable, non-cryptographic content hash (cyrb53) for the version
+ * sequence's "did the content change across close/reopen?" question. Only
+ * needs to be collision-resistant enough that an accidental match across two
+ * DIFFERENT revisions of the same file is practically impossible; 53 bits of
+ * a well-mixed hash over full text + length gives that without pulling in
+ * `node:crypto` (this module must stay runnable in browser hosts).
+ */
+function contentHash(text) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let index = 0; index < text.length; index++) {
+        const code = text.charCodeAt(index);
+        h1 = Math.imul(h1 ^ code, 2654435761);
+        h2 = Math.imul(h2 ^ code, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return `${(4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36)}:${text.length}`;
+}
+/**
+ * Multi-client text-document tracking on top of Langium's `NormalizedTextDocuments`.
+ *
+ * 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.
+ */
+export class HydraniumTextDocuments extends NormalizedTextDocuments {
+    services;
+    /**
+     * Per-URI client-facing tracking ({@link DocumentTracking}): client
+     * membership, version-author history, and integrity-staged pending content,
+     * keyed by normalized URI. One record per URI so the last-client close clears
+     * every axis atomically. The language-client diff baseline stays in
+     * {@link __shadow} (its own abstraction); the parsed-document store stays in
+     * the inherited `__syncedDocuments`.
+     */
+    __documents = new Map();
+    /**
+     * Per-URI shared-version continuity across close/reopen cycles
+     * ({@link VersionSequence}), written at last-client close and consulted by
+     * the next first-client open. DELIBERATELY outside {@link DocumentTracking}:
+     * that record is deleted on last close, while the version sequence must
+     * survive it — the shared version is a server-owned, monotonic,
+     * advances-iff-content-changes counter that never resets while the server
+     * lives. That invariant is what makes an optimistic `baseVersion` gate
+     * sound: "version unchanged ⇔ content unchanged", with no false conflicts
+     * from close/reopen version resets and no false passes from a reopened
+     * sequence coincidentally landing on a stale writer's number.
+     *
+     * Never pruned: two small values per URI ever touched — bounded by
+     * workspace size, not by activity.
+     */
+    __versionSequences = new Map();
+    /**
+     * Texts pushed to the LSP textual language client via
+     * {@link applyEditToLanguageClient} whose echoes have not come back yet
+     * ({@link PendingPush}), keyed like the shadow by language-client URI.
+     * Outbound pushes and inbound echoes are uncorrelated on the wire; this
+     * FIFO is the explicit correlation, and it is what
+     * {@link classifyLanguageClientChange} reconstructs against.
+     *
+     * **Each entry keeps the client's PRE-push text, not only a hash of the
+     * post-push one.** A hash alone can classify a full-text echo, whose
+     * application is a no-op either way — and that is all it ever classified,
+     * because a conforming client echoes INCREMENTAL ranges keyed to its
+     * previous buffer. Those ranges cannot be applied to the synced text (which
+     * the authored write already advanced) and cannot be reconstructed without
+     * the baseline: the line they insert lands twice, validates cleanly, and
+     * compounds on every later edit.
+     *
+     * Lifecycle: entries are consumed by the matching echo (together with any
+     * older entries it supersedes), and the whole queue drops when the client
+     * stops being a pure mirror — a divergent change, an `applyEdit`
+     * failure/rejection (shadow invalidation), a close, or an explicit
+     * shadow (re)baseline. {@link PENDING_ECHO_CAP} bounds the queue against
+     * a pathological echo that never arrives; the memory cost until then is
+     * one pre-push text per in-flight push, for milliseconds.
+     */
+    __pendingPushes = new Map();
+    /**
+     * Tracked text content per URI for the LSP textual language client (Monaco / VS Code).
+     * Owned here so {@link applyEditToLanguageClient} can compute minimal `workspace/applyEdit`
+     * diffs instead of full-document replaces (5–20 s → <500 ms on 20-30 KB YAML diagrams).
+     *
+     * Auto-tracked from the multi-client text-document events: open / change / close of
+     * the language client (re)baseline or invalidate the shadow. Other client ids
+     * (form editor, GLSP, integrity) do NOT touch the shadow — only what Monaco believes
+     * it has matters for the diff.
+     *
+     * Apply-verify safety net is built in: if the diff doesn't reconstruct `newText`
+     * exactly, {@link LanguageClientTextShadow.computeEdits} falls back to a full-range
+     * replace and invokes the `onFallback` callback — a diff regression becomes log
+     * noise, not a 0-byte save.
+     *
+     * Assigned in the constructor body so the `onFallback` callback can capture
+     * `this.logger` after the parameter-property assignment has run (field
+     * initializers fire BEFORE parameter-property assignment in TS).
+     */
+    __shadow;
+    tracer;
+    configuration;
+    constructor(services, options = {}) {
+        const configuration = options.configuration ?? TextDocument;
+        super(configuration);
+        this.services = services;
+        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.
+    create(uri, languageId, version, content) {
+        return this.configuration.create(uri, languageId, version, content);
+    }
+    update(document, changes, version) {
+        return this.configuration.update(document, changes, version);
+    }
+    get __syncedDocuments() {
+        return this['_syncedDocuments'];
+    }
+    get __onDidChangeContent() {
+        return this['_onDidChangeContent'];
+    }
+    get onDidChangeContent() {
+        return this.__onDidChangeContent.event;
+    }
+    get __onDidOpen() {
+        return this['_onDidOpen'];
+    }
+    get onDidOpen() {
+        return this.__onDidOpen.event;
+    }
+    get __onDidClose() {
+        return this['_onDidClose'];
+    }
+    get onDidClose() {
+        return this.__onDidClose.event;
+    }
+    get __onDidSave() {
+        return this['_onDidSave'];
+    }
+    get onDidSave() {
+        return this['__onDidSave'].event;
+    }
+    get __onWillSave() {
+        return this['_onWillSave'];
+    }
+    get __willSaveWaitUntil() {
+        return this['_willSaveWaitUntil'];
+    }
+    listen(connection) {
+        // The advertised `textDocumentSync` capability is read off this field
+        // while `initialize` is answered, and it falls back to
+        // `TextDocumentSyncKind.None` when the field holds anything but a number
+        // — at which point the client stops sending change notifications at all
+        // and every document goes stale after its first open. Upstream's own
+        // `TextDocuments.listen` performs this write; replacing that class means
+        // taking it over. The field is private to `vscode-languageserver`, so on
+        // a bump of the pinned wire chain re-check that it still exists: a rename
+        // makes this line a silent no-op, whose symptom is no `didChange` traffic
+        // rather than an error.
+        connection.__textDocumentSync = TextDocumentSyncKind.Incremental;
+        const disposables = new DisposableCollection();
+        disposables.push(connection.onDidOpenTextDocument(async (event) => {
+            await this.services.workspace.WorkspaceManager.workspaceInitialized;
+            this.notifyDidOpenTextDocument(event);
+        }));
+        disposables.push(connection.onDidChangeTextDocument((event) => {
+            this.notifyDidChangeTextDocument(event);
+        }));
+        disposables.push(connection.onDidCloseTextDocument((event) => {
+            this.notifyDidCloseTextDocument(event);
+        }));
+        disposables.push(connection.onWillSaveTextDocument((event) => {
+            this.notifyWillSaveTextDocument(event);
+        }));
+        disposables.push(connection.onWillSaveTextDocumentWaitUntil((event, token) => this.notifyWillSaveTextDocumentWaitUntil(event, token)));
+        disposables.push(connection.onDidSaveTextDocument((event) => {
+            this.notifyDidSaveTextDocument(event);
+        }));
+        return disposables;
+    }
+    notifyDidChangeTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
+        const td = event.textDocument;
+        const changes = event.contentChanges;
+        if (changes.length === 0) {
+            return;
+        }
+        const { version } = td;
+        if (version === null || version === undefined) {
+            throw new Error(`Received document change event for ${td.uri} without valid version identifier`);
+        }
+        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;
+            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');
+                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.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) {
+                    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)'}`);
+            this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
+        }
+    }
+    /**
+     * Apply a full-text content change authored server-side (ModelService /
+     * GLSP / integrity — any writer that is not an LSP wire client). The store
+     * assigns the shared version itself: step iff `text` differs from the
+     * current synced content, keep otherwise. Contrast
+     * {@link notifyDidChangeTextDocument}, the LSP wire path, where the client
+     * declares ITS version id and that id feeds only the per-client staleness
+     * guard.
+     *
+     * 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.
+     *
+     * Returns the resulting shared version. Throws when the document is not
+     * open — callers (`AstDocumentManager.update`) open first.
+     */
+    applyContentChange(uri, text, clientId) {
+        const key = this.documentKey(uri);
+        let document = this.__syncedDocuments.get(key);
+        if (document === undefined) {
+            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)'}`);
+        this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
+        return document.version;
+    }
+    notifyDidCloseTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
+        const uri = this.documentKey(event.textDocument.uri);
+        if (!this.isOpenInClient(uri, clientId)) {
+            return;
+        }
+        const closingRecord = this.__documents.get(uri);
+        closingRecord?.clients.delete(clientId);
+        closingRecord?.clientVersions.delete(clientId);
+        const syncedDocument = this.__syncedDocuments.get(uri);
+        if (syncedDocument !== undefined) {
+            this.log(syncedDocument.uri, `Closed synced document: ${syncedDocument.version} by ${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.__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);
+            }
+        }
+    }
+    notifyWillSaveTextDocument(event) {
+        const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
+        if (syncedDocument !== undefined) {
+            this.__onWillSave.fire(Object.freeze({ document: syncedDocument, reason: event.reason }));
+        }
+    }
+    notifyWillSaveTextDocumentWaitUntil(event, token) {
+        const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
+        if (syncedDocument !== undefined && this.__willSaveWaitUntil) {
+            return this.__willSaveWaitUntil(Object.freeze({ document: syncedDocument, reason: event.reason }), token);
+        }
+        else {
+            return [];
+        }
+    }
+    notifyDidSaveTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
+        const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
+        if (syncedDocument !== undefined) {
+            this.log(syncedDocument.uri, `Saved synced document: ${syncedDocument.version} by ${clientId}`);
+            this.__onDidSave.fire(Object.freeze({ document: syncedDocument, clientId }));
+        }
+    }
+    notifyDidOpenTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
+        const td = event.textDocument;
+        const uri = this.documentKey(td.uri);
+        if (this.isOpenInClient(uri, clientId)) {
+            // Already open for this client under this canonical identity. If this is a
+            // NEW client-facing URI for the same file (a second tab reached via a
+            // divergent path, e.g. a symlink and its real path), record it 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()).add(clientFacing);
+                    const open = this.__syncedDocuments.get(uri);
+                    if (open) {
+                        this.__shadow.set(clientFacing, open.getText());
+                    }
+                }
+            }
+            return;
+        }
+        let document = this.__syncedDocuments.get(uri);
+        const record = this.trackingFor(uri);
+        const existingClients = [...record.clients];
+        record.clients.add(clientId);
+        // Baseline the per-client staleness guard at the version id the client
+        // declared for its own buffer (client-owned per LSP).
+        record.clientVersions.set(clientId, td.version);
+        if (clientId === LANGUAGE_CLIENT_ID) {
+            // Remember the URI Monaco opened under (may differ from the canonical key)
+            // so outbound applyEditToLanguageClient can address the URI it actually holds.
+            (record.languageClientUris ??= new Set()).add(this.toLanguageClientUri(td.uri));
+        }
+        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 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.refreshContent(uri, clientId);
+        }
+    }
+    refreshContent(uri, clientId) {
+        const syncedDocument = this.__syncedDocuments.get(this.documentKey(uri));
+        if (syncedDocument) {
+            // Trigger a (re-)build by firing a change event.
+            const timer = this.startTimerForUri(syncedDocument.uri, `Refresh synced document: Version ${syncedDocument.version} by ${clientId}`);
+            this.__onDidChangeContent.fire(Object.freeze({ document: syncedDocument, clientId }));
+            timer.dispose();
+        }
+    }
+    /**
+     * The canonical key a document is stored under — the single point this store
+     * turns an incoming URI into its identity, the store-side analogue of
+     * `DocumentUriPolicy.canonicalUri`. Keying by the CANONICAL identity collapses
+     * 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
+     * policy is always bound (the framework defaults it to
+     * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
+     */
+    documentKey(uri) {
+        return this.services.workspace.DocumentUriPolicy.canonicalUri(uri);
+    }
+    /**
+     * The language-client URI for `uri` — syntactic `normalize` only, NOT
+     * canonicalized. This is the URI the LSP textual client (Monaco / VS Code)
+     * actually holds the document under (what `applyEditToLanguageClient` must address and
+     * what the shadow is keyed by), distinct from {@link documentKey} (the canonical
+     * identity the document is stored under). They coincide unless the path diverges
+     * from its real path (symlink / `..` / case).
+     */
+    toLanguageClientUri(uri) {
+        return asLanguageClientUri(UriUtils.normalize(uri));
+    }
+    /** Get-or-create the per-URI tracking record. `uri` must already be a {@link documentKey}. */
+    trackingFor(uri) {
+        let record = this.__documents.get(uri);
+        if (!record) {
+            record = { clients: new Set(), versionAuthors: [], clientVersions: new Map() };
+            this.__documents.set(uri, record);
+        }
+        return record;
+    }
+    setAuthor(uri, version, author) {
+        this.trackingFor(this.documentKey(uri)).versionAuthors[version] = author;
+    }
+    /**
+     * Resolve the synced `TextDocument` for `uri`. The store keys documents by
+     * their canonical identity ({@link documentKey}), so a direct normalized hit
+     * wins the common case (the caller passes the canonical URI, or the opened URI
+     * coincides with it) with no canonicalization, and a miss falls back to the
+     * single canonical-key lookup — which is what bridges a client-space caller
+     * that addresses a symlinked path `S` to the document the build keys by its
+     * real path `R` (`documentKey(S) === R`).
+     *
+     * O(1): no scan. Because the interior is already canonically keyed, looking the
+     * canonical key up directly is equivalent to reverse-matching every entry, and
+     * the `super.get` fast path keeps the common case syscall-free (the
+     * canonical lookup, and its one `canonicalUri` realpath, runs only on a miss).
+     * Under the default policy `documentKey ≡ normalize`, so the fallback can never
+     * find a key the direct lookup didn't — `get` is then identical to the base.
+     */
+    get(uri) {
+        return super.get(uri) ?? this.__syncedDocuments.get(this.documentKey(uri));
+    }
+    /**
+     * 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
+     * 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 ⇔
+     * content unchanged.
+     */
+    version(uri) {
+        return this.get(uri)?.version ?? this.__versionSequences.get(this.documentKey(uri))?.version ?? 0;
+    }
+    /**
+     * 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
+     * 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) —
+     * 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).
+     */
+    reconcileExternalContent(uri, text) {
+        const key = this.documentKey(uri);
+        if (this.__syncedDocuments.has(key)) {
+            return undefined;
+        }
+        const sequence = this.__versionSequences.get(key);
+        if (sequence === undefined) {
+            return undefined;
+        }
+        const hash = contentHash(text);
+        if (hash === sequence.contentHash) {
+            return sequence.version;
+        }
+        const stepped = { version: sequence.version + 1, contentHash: hash };
+        this.__versionSequences.set(key, stepped);
+        this.logUri(key, `External content change while closed: sequence stepped to version ${stepped.version}`, 'debug');
+        return stepped.version;
+    }
+    getAuthor(uri, version) {
+        const history = this.__documents.get(this.documentKey(uri))?.versionAuthors;
+        // Either the requested version, or the latest. `version !== undefined` so we treat 0 correctly.
+        const clientId = version !== undefined ? history?.[version] : history?.at(-1);
+        if (!clientId && history) {
+            // 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}.`);
+        }
+        return clientId;
+    }
+    isOpen(uri) {
+        return this.__syncedDocuments.has(this.documentKey(uri));
+    }
+    /**
+     * 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.
+     */
+    isOpenInAnyClient(uri) {
+        return (this.__documents.get(this.documentKey(uri))?.clients.size ?? 0) > 0;
+    }
+    isOpenInClient(uri, client) {
+        return !!this.__documents.get(this.documentKey(uri))?.clients.has(client);
+    }
+    isOpenInLanguageClient(uri) {
+        // Takes any URI form (canonicalizes internally via `documentKey`, like
+        // `isOpen`); the document is keyed canonically, so a canonical or a
+        // client-facing URI both resolve to the same registration.
+        return this.isOpenInClient(uri, LANGUAGE_CLIENT_ID);
+    }
+    isOnlyOpenInClient(uri, client) {
+        const key = this.documentKey(uri);
+        return this.__documents.get(key)?.clients.size === 1 && this.isOpenInClient(key, 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.
+     *
+     * 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
+     * editor closed points directly at the client that failed to close it (and,
+     * under a shedding policy, explains why its CST is never shed).
+     */
+    openDocuments() {
+        const result = [];
+        for (const [uri, tracking] of this.__documents) {
+            if (tracking.clients.size > 0) {
+                result.push({ uri, clients: [...tracking.clients] });
+            }
+        }
+        return result;
+    }
+    /**
+     * Stages integrity-updated content for a closed document.
+     *
+     * 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.
+     */
+    stagePendingContent(uri, text) {
+        this.trackingFor(this.documentKey(uri)).pendingContent = text;
+    }
+    /**
+     * Send `newText` to the LSP textual language client (Monaco / VS Code) via
+     * `workspace/applyEdit`, using the tracked shadow to produce minimal
+     * `TextEdit`s instead of a full-document replace.
+     *
+     * Returns `undefined` when:
+     *   - 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).
+     *
+     * On `applyEdit` rejection (`result.applied === false`) or RPC failure the
+     * shadow is invalidated so the next call sends a full-replace baseline.
+     * 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.
+     *
+     * 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
+     * "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,
+     * so the caller's retry is a full-range replace — position-independent, and
+     * safe to apply to whatever the client now holds.
+     */
+    async applyEditToLanguageClient(uri, newText, options) {
+        const connection = this.services.lsp?.Connection;
+        if (!connection) {
+            return undefined;
+        }
+        // The document is keyed by its canonical identity, but Monaco holds it under
+        // the URI(s) it opened. Address each of those language-client URIs — the one
+        // R→S translation, kept here at the egress. Usually one; more than one only
+        // when the same file was opened under a symlink and its real path. Falls back
+        // to the normalized URI when nothing is tracked. The shadow is keyed by each
+        // URI, so every diff is against the right baseline.
+        const recorded = this.__documents.get(this.documentKey(uri))?.languageClientUris;
+        const targets = recorded && recorded.size > 0 ? recorded : [this.toLanguageClientUri(uri)];
+        let lastResult;
+        for (const targetUri of targets) {
+            // Read BEFORE computeEdits, which overwrites it. This is the text the
+            // edits below are keyed to, and therefore the only text the client's
+            // echo of them can be reconstructed against.
+            const before = this.__shadow.get(targetUri);
+            const edits = this.__shadow.computeEdits(targetUri, newText);
+            if (edits.length === 0) {
+                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);
+                const result = await connection.workspace.applyEdit({
+                    label: options?.label,
+                    documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+                });
+                if (result && result.applied === false) {
+                    this.__shadow.invalidate(targetUri);
+                    this.__pendingPushes.delete(targetUri);
+                }
+                lastResult = result;
+            }
+            catch (err) {
+                this.__shadow.invalidate(targetUri);
+                this.__pendingPushes.delete(targetUri);
+                throw err;
+            }
+        }
+        return lastResult;
+    }
+    /**
+     * The version the LSP textual language client last declared for `uri`, for
+     * addressing an outgoing `workspace/applyEdit`.
+     *
+     * Client version ids are CLIENT-owned per LSP, so this is the id the client
+     * itself stamped on its last `didOpen` / `didChange` — never the shared
+     * server version, which advances on authored writes the client knows nothing
+     * about and would therefore reject every push.
+     *
+     * Falls back to {@link UNKNOWN_CLIENT_VERSION} when the client has never
+     * declared one, which is the honest answer for a document it has not opened.
+     * That is also the case in which there is no shadow, so the push is already a
+     * position-independent full replace and has nothing to gain from a gate.
+     */
+    languageClientVersion(uri) {
+        return this.__documents.get(this.documentKey(uri))?.clientVersions.get(LANGUAGE_CLIENT_ID) ?? UNKNOWN_CLIENT_VERSION;
+    }
+    /**
+     * Append a push to the in-flight queue for `targetUri`
+     * (see {@link __pendingPushes}). Bounded: beyond
+     * {@link PENDING_ECHO_CAP} the oldest entry drops with a debug log — an
+     * echo that far outstanding means the client is not echoing at all, and
+     * an unbounded queue must not become the leak.
+     */
+    recordPendingPush(targetUri, before, newText) {
+        let pending = this.__pendingPushes.get(targetUri);
+        if (!pending) {
+            pending = [];
+            this.__pendingPushes.set(targetUri, pending);
+        }
+        pending.push({ before, afterHash: contentHash(newText) });
+        if (pending.length > PENDING_ECHO_CAP) {
+            pending.shift();
+            this.logUri(targetUri, `Pending-echo queue exceeded ${PENDING_ECHO_CAP} entries; dropped the oldest`, 'debug');
+        }
+    }
+    /**
+     * Decide what an incoming language-client change actually is, by
+     * reconstructing the client's resulting buffer against the OLDEST push still
+     * in flight for `clientFacing`.
+     *
+     * `undefined` when nothing of ours is in flight, which is the ordinary path:
+     * the client's ranges then address the synced text and the caller applies
+     * them to it directly.
+     *
+     * **Why the oldest, and why reconstruct at all.** The client applies our
+     * pushes in order and echoes each against the buffer it held before that
+     * push, so the first echo to arrive belongs to the oldest entry — a FIFO
+     * correspondence the queue preserves by consuming from the front. Comparing
+     * the reconstruction against every pending hash, not only the oldest, is
+     * what recognises an echo that a newer write already superseded: a rapid
+     * write sequence can deliver the echo of push N after the store applied
+     * push N+1, and everything older is then accounted for too.
+     *
+     * A reconstruction matching NO pending push means the client's buffer went
+     * somewhere we did not send it — it coalesced a keystroke into the echo, or
+     * typed before the push landed. That text is authoritative, and the queue
+     * drops: the client has stopped being a pure mirror, so no outstanding echo
+     * can match again. (A push still in flight at that point will be refused by
+     * the client's own version gate, which invalidates the shadow and makes the
+     * next sync a position-independent full replace.)
+     *
+     * Content equality is a sound echo proof because entries live only between a
+     * push and its echo — a milliseconds window, never history — and the
+     * client's `didChange` stream is ordered, so every buffer state arrives in
+     * mutation order. An UNDO returning the buffer to previously-pushed text is
+     * therefore never swallowed: the edit that preceded it already emptied the
+     * queue, so undo revisits PAST states while the queue holds IN-FLIGHT ones.
+     */
+    classifyLanguageClientChange(clientFacing, document, changes) {
+        const pending = this.__pendingPushes.get(clientFacing);
+        if (pending === undefined || pending.length === 0) {
+            return undefined;
+        }
+        // Through the configured factories, not `TextDocument` directly, so an
+        // adopter's custom text-document type governs how the ranges are applied
+        // here exactly as it does on the synced document.
+        const probe = this.create(clientFacing, document.languageId, 0, pending[0].before ?? document.getText());
+        const clientText = this.update(probe, changes, 0).getText();
+        const matchIndex = pending.findIndex(push => push.afterHash === contentHash(clientText));
+        if (matchIndex >= 0) {
+            pending.splice(0, matchIndex + 1);
+            return { kind: 'echo' };
+        }
+        pending.length = 0;
+        return { kind: 'divergent', text: clientText };
+    }
+    /**
+     * 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.
+     */
+    setLanguageClientText(uri, text) {
+        const clientFacing = this.toLanguageClientUri(uri);
+        this.__shadow.set(clientFacing, text);
+        // An explicit rebaseline supersedes whatever was in flight.
+        this.__pendingPushes.delete(clientFacing);
+    }
+    /** Drop the shadow baseline for a URI; the next applyEditToLanguageClient sends a full replace. */
+    invalidateLanguageClientText(uri) {
+        const clientFacing = this.toLanguageClientUri(uri);
+        this.__shadow.invalidate(clientFacing);
+        this.__pendingPushes.delete(clientFacing);
+    }
+    consumePendingContent(uri) {
+        const record = this.__documents.get(this.documentKey(uri));
+        const content = record?.pendingContent;
+        if (record) {
+            record.pendingContent = undefined;
+        }
+        return content;
+    }
+    log(uri, message) {
+        this.logUri(uri, message, 'info');
+    }
+    /** Hook for subclasses that want to attach a workspace-relative path component. */
+    logUri(uri, message, level = 'info') {
+        this.tracer.with(uri)[level](message);
+    }
+    /** Hook for subclasses that want a URI-tagged timer. */
+    startTimerForUri(uri, message) {
+        return this.tracer.with(uri).startTimer(message);
+    }
+}
+//# sourceMappingURL=hydranium-text-documents.js.map