@hydranium/core 1.0.0-next.10

package/lib/documents/hydranium-text-documents.d.ts

@@ -0,0 +1,490 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+import { NormalizedTextDocuments } from '@hydranium/langium/lsp';
+import { type ServerSharedServices } from '../langium/module.js';
+import { type ApplyWorkspaceEditResult, type CancellationToken, type Connection, type DidChangeTextDocumentParams, type DidCloseTextDocumentParams, type DidOpenTextDocumentParams, type DidSaveTextDocumentParams, type Disposable, type Emitter, type Event, type HandlerResult, type RequestHandler, type TextDocumentChangeEvent, type TextDocumentWillSaveEvent, type TextDocumentsConfiguration, type TextEdit, type WillSaveTextDocumentParams } from 'vscode-languageserver';
+import { type DocumentUri, TextDocument, type TextDocumentContentChangeEvent } from 'vscode-languageserver-textdocument';
+import { type CanonicalUri, type LanguageClientUri, type Tracer } from '@hydranium/protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { LanguageClientTextShadow } from './language-client-text-shadow.js';
+export interface ClientTextDocumentChangeEvent<T> extends TextDocumentChangeEvent<T> {
+    clientId: string;
+}
+/**
+ * Construction options for {@link HydraniumTextDocuments}. All fields optional —
+ * defaults reproduce the framework's behaviour exactly.
+ */
+export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocument> extends LogNameOptions {
+    /**
+     * Factory for the text-document type `T` (provides `create` / `update`).
+     * Defaults to `TextDocument` from `vscode-languageserver-textdocument`.
+     * Adopters with a custom text-document type (rare) pass their factory.
+     */
+    readonly configuration?: TextDocumentsConfiguration<T>;
+}
+/**
+ * All per-URI client-facing tracking the manager keys by normalized URI,
+ * collapsed into one record so a URI's full state lives in one place and the
+ * last-client close clears every axis in a single delete. (Parallel per-axis
+ * maps are the substrate of a close-on-stale-state desync — one map can be
+ * cleared while another lingers.)
+ *
+ * Two neighbours deliberately stay separate:
+ *  - The inherited `__syncedDocuments` (Langium's parsed `TextDocument` store).
+ *  - {@link LanguageClientTextShadow} (`__shadow`), a self-contained,
+ *    separately-tested diff/apply-verify abstraction that owns its own baseline
+ *    text; folding its storage here would couple a clean utility to this record
+ *    for no real gain.
+ */
+interface DocumentTracking {
+    /** Client ids currently holding this document open (multi-client membership). */
+    readonly clients: Set<string>;
+    /** Author of each version, sparse-indexed by the SHARED (server-assigned) version number. */
+    readonly versionAuthors: string[];
+    /**
+     * Last version id each client declared for this document (didOpen baseline,
+     * advanced by every accepted didChange). Client version ids are CLIENT-owned
+     * per LSP (Monaco numbers its own buffer) and are used ONLY for this
+     * per-client staleness guard — they never leak into the shared version
+     * sequence, which the server assigns (see {@link HydraniumTextDocuments.__versionSequences}).
+     */
+    readonly clientVersions: Map<string, number>;
+    /** Content staged by integrity rules for a closed document. Consumed on next open. */
+    pendingContent?: string;
+    /**
+     * The URI(s) the LSP textual language client opened this (canonically-keyed)
+     * document under. Usually one; a set because the same physical file can be
+     * opened under more than one URI (a symlink path and its real path). This is
+     * the egress address: `applyEditToLanguageClient`
+     * targets these, since the document is *keyed* by its canonical identity but
+     * Monaco holds it under the URI it opened. Lifecycle-bound — cleared with the
+     * record on last close.
+     */
+    languageClientUris?: Set<LanguageClientUri>;
+}
+/**
+ * A document held open by at least one client, with the client ids holding it —
+ * one entry of {@link HydraniumTextDocuments.openDocuments}.
+ */
+export interface OpenDocument {
+    /** Canonical identity the store keys the document by. */
+    readonly uri: CanonicalUri;
+    /** Client ids currently holding the document open (never empty). */
+    readonly clients: readonly string[];
+}
+/**
+ * Where a URI's shared version sequence left off — written once at last-client
+ * close, consulted at the next open so the sequence CONTINUES instead of
+ * restarting at whatever version id the reopening client declares. One entry
+ * of {@link HydraniumTextDocuments.__versionSequences}.
+ */
+interface VersionSequence {
+    /** The shared version at last-client close. */
+    readonly version: number;
+    /** {@link contentHash} of the synced text at last-client close. */
+    readonly contentHash: string;
+}
+/**
+ * One text pushed to the LSP textual language client by
+ * {@link HydraniumTextDocuments.applyEditToLanguageClient} whose echo has not
+ * come back yet. One entry of {@link HydraniumTextDocuments.__pendingPushes}.
+ */
+interface PendingPush {
+    /**
+     * The text the client held BEFORE this push — the shadow baseline the
+     * push's edits were diffed against, and therefore the text the client's
+     * echo addresses with its ranges.
+     *
+     * `undefined` when the push was a full replace sent with no baseline (a
+     * first sync, or the recovery push after a rejection). There is then no
+     * knowing what the client held, so the echo is reconstructed against the
+     * synced text instead — which is sound for a full replace, whose
+     * application is position-independent.
+     */
+    readonly before: string | undefined;
+    /** {@link contentHash} of the text this push moves the client to. */
+    readonly afterHash: string;
+}
+/**
+ * What an incoming language-client change turns out to be once reconstructed
+ * against the pushes still in flight — the return of
+ * {@link HydraniumTextDocuments.classifyLanguageClientChange}.
+ */
+type LanguageClientChangeOrigin = 
+/** The client is reporting a text we pushed it. The synced document is already there. */
+{
+    readonly kind: 'echo';
+}
+/**
+ * The client's buffer has moved somewhere we did not push it — it coalesced
+ * a genuine keystroke into the echo, or typed before the push arrived. The
+ * reconstructed text is what it now holds, and is authoritative.
+ */
+ | {
+    readonly kind: 'divergent';
+    readonly text: string;
+};
+/**
+ * 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 declare class HydraniumTextDocuments<T extends TextDocument = TextDocument> extends NormalizedTextDocuments<T> {
+    protected services: ServerSharedServices;
+    /**
+     * Per-URI client-facing tracking ({@link DocumentTracking}): client
+     * membership, version-author history, and integrity-staged pending content,
+     * keyed by normalized URI. One record per URI so the last-client close clears
+     * every axis atomically. The language-client diff baseline stays in
+     * {@link __shadow} (its own abstraction); the parsed-document store stays in
+     * the inherited `__syncedDocuments`.
+     */
+    protected __documents: Map<CanonicalUri, DocumentTracking>;
+    /**
+     * 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.
+     */
+    protected readonly __versionSequences: Map<CanonicalUri, VersionSequence>;
+    /**
+     * Texts pushed to the LSP textual language client via
+     * {@link applyEditToLanguageClient} whose echoes have not come back yet
+     * ({@link PendingPush}), keyed like the shadow by language-client URI.
+     * Outbound pushes and inbound echoes are uncorrelated on the wire; this
+     * FIFO is the explicit correlation, and it is what
+     * {@link classifyLanguageClientChange} reconstructs against.
+     *
+     * **Each entry keeps the client's PRE-push text, not only a hash of the
+     * post-push one.** A hash alone can classify a full-text echo, whose
+     * application is a no-op either way — and that is all it ever classified,
+     * because a conforming client echoes INCREMENTAL ranges keyed to its
+     * previous buffer. Those ranges cannot be applied to the synced text (which
+     * the authored write already advanced) and cannot be reconstructed without
+     * the baseline: the line they insert lands twice, validates cleanly, and
+     * compounds on every later edit.
+     *
+     * Lifecycle: entries are consumed by the matching echo (together with any
+     * older entries it supersedes), and the whole queue drops when the client
+     * stops being a pure mirror — a divergent change, an `applyEdit`
+     * failure/rejection (shadow invalidation), a close, or an explicit
+     * shadow (re)baseline. {@link PENDING_ECHO_CAP} bounds the queue against
+     * a pathological echo that never arrives; the memory cost until then is
+     * one pre-push text per in-flight push, for milliseconds.
+     */
+    protected readonly __pendingPushes: Map<LanguageClientUri, PendingPush[]>;
+    /**
+     * Tracked text content per URI for the LSP textual language client (Monaco / VS Code).
+     * Owned here so {@link applyEditToLanguageClient} can compute minimal `workspace/applyEdit`
+     * diffs instead of full-document replaces (5–20 s → <500 ms on 20-30 KB YAML diagrams).
+     *
+     * Auto-tracked from the multi-client text-document events: open / change / close of
+     * the language client (re)baseline or invalidate the shadow. Other client ids
+     * (form editor, GLSP, integrity) do NOT touch the shadow — only what Monaco believes
+     * it has matters for the diff.
+     *
+     * Apply-verify safety net is built in: if the diff doesn't reconstruct `newText`
+     * exactly, {@link LanguageClientTextShadow.computeEdits} falls back to a full-range
+     * replace and invokes the `onFallback` callback — a diff regression becomes log
+     * noise, not a 0-byte save.
+     *
+     * Assigned in the constructor body so the `onFallback` callback can capture
+     * `this.logger` after the parameter-property assignment has run (field
+     * initializers fire BEFORE parameter-property assignment in TS).
+     */
+    protected readonly __shadow: LanguageClientTextShadow;
+    protected readonly tracer: Tracer;
+    protected readonly configuration: TextDocumentsConfiguration<T>;
+    constructor(services: ServerSharedServices, options?: HydraniumTextDocumentsOptions<T>);
+    create(uri: string, languageId: string, version: number, content: string): T;
+    update(document: T, changes: TextDocumentContentChangeEvent[], version: number): T;
+    protected get __syncedDocuments(): Map<string, T>;
+    protected get __onDidChangeContent(): Emitter<ClientTextDocumentChangeEvent<T>>;
+    get onDidChangeContent(): Event<ClientTextDocumentChangeEvent<T>>;
+    protected get __onDidOpen(): Emitter<ClientTextDocumentChangeEvent<T>>;
+    get onDidOpen(): Event<ClientTextDocumentChangeEvent<T>>;
+    protected get __onDidClose(): Emitter<ClientTextDocumentChangeEvent<T>>;
+    get onDidClose(): Event<ClientTextDocumentChangeEvent<T>>;
+    protected get __onDidSave(): Emitter<ClientTextDocumentChangeEvent<T>>;
+    get onDidSave(): Event<ClientTextDocumentChangeEvent<T>>;
+    protected get __onWillSave(): Emitter<TextDocumentWillSaveEvent<T>>;
+    protected get __willSaveWaitUntil(): RequestHandler<TextDocumentWillSaveEvent<T>, TextEdit[], void> | undefined;
+    listen(connection: Connection): Disposable;
+    notifyDidChangeTextDocument(event: DidChangeTextDocumentParams, clientId?: string): void;
+    /**
+     * 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: DocumentUri, text: string, clientId: string): number;
+    notifyDidCloseTextDocument(event: DidCloseTextDocumentParams, clientId?: string): void;
+    notifyWillSaveTextDocument(event: WillSaveTextDocumentParams): void;
+    notifyWillSaveTextDocumentWaitUntil(event: WillSaveTextDocumentParams, token: CancellationToken): HandlerResult<TextEdit[], void>;
+    notifyDidSaveTextDocument(event: DidSaveTextDocumentParams, clientId?: string): void;
+    notifyDidOpenTextDocument(event: DidOpenTextDocumentParams, clientId?: string): void;
+    refreshContent(uri: DocumentUri, clientId: string): void;
+    /**
+     * 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).
+     */
+    protected documentKey(uri: string): CanonicalUri;
+    /**
+     * 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).
+     */
+    protected toLanguageClientUri(uri: string): LanguageClientUri;
+    /** Get-or-create the per-URI tracking record. `uri` must already be a {@link documentKey}. */
+    protected trackingFor(uri: CanonicalUri): DocumentTracking;
+    setAuthor(uri: DocumentUri, version: number, author: string): void;
+    /**
+     * 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: DocumentUri): T | undefined;
+    /**
+     * 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: DocumentUri): number;
+    /**
+     * 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: DocumentUri, text: string): number | undefined;
+    getAuthor(uri: DocumentUri, version?: number): string | undefined;
+    isOpen(uri: DocumentUri): boolean;
+    /**
+     * 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: DocumentUri): boolean;
+    isOpenInClient(uri: DocumentUri, client: string): boolean;
+    isOpenInLanguageClient(uri: DocumentUri): boolean;
+    isOnlyOpenInClient(uri: DocumentUri, client: string): boolean;
+    /**
+     * 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(): OpenDocument[];
+    /**
+     * 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: DocumentUri, text: string): void;
+    /**
+     * 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.
+     */
+    applyEditToLanguageClient(uri: DocumentUri, newText: string, options?: {
+        label?: string;
+    }): Promise<ApplyWorkspaceEditResult | undefined>;
+    /**
+     * The version the LSP textual language client last declared for `uri`, for
+     * addressing an outgoing `workspace/applyEdit`.
+     *
+     * Client version ids are CLIENT-owned per LSP, so this is the id the client
+     * itself stamped on its last `didOpen` / `didChange` — never the shared
+     * server version, which advances on authored writes the client knows nothing
+     * about and would therefore reject every push.
+     *
+     * Falls back to {@link UNKNOWN_CLIENT_VERSION} when the client has never
+     * declared one, which is the honest answer for a document it has not opened.
+     * That is also the case in which there is no shadow, so the push is already a
+     * position-independent full replace and has nothing to gain from a gate.
+     */
+    protected languageClientVersion(uri: DocumentUri): number;
+    /**
+     * Append a push to the in-flight queue for `targetUri`
+     * (see {@link __pendingPushes}). Bounded: beyond
+     * {@link PENDING_ECHO_CAP} the oldest entry drops with a debug log — an
+     * echo that far outstanding means the client is not echoing at all, and
+     * an unbounded queue must not become the leak.
+     */
+    protected recordPendingPush(targetUri: LanguageClientUri, before: string | undefined, newText: string): void;
+    /**
+     * 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.
+     */
+    protected classifyLanguageClientChange(clientFacing: LanguageClientUri, document: T, changes: TextDocumentContentChangeEvent[]): LanguageClientChangeOrigin | undefined;
+    /**
+     * 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: DocumentUri, text: string): void;
+    /** Drop the shadow baseline for a URI; the next applyEditToLanguageClient sends a full replace. */
+    invalidateLanguageClientText(uri: DocumentUri): void;
+    protected consumePendingContent(uri: DocumentUri): string | undefined;
+    protected log(uri: DocumentUri, message: string): void;
+    /** Hook for subclasses that want to attach a workspace-relative path component. */
+    protected logUri(uri: DocumentUri, message: string, level?: 'info' | 'debug'): void;
+    /** Hook for subclasses that want a URI-tagged timer. */
+    protected startTimerForUri(uri: DocumentUri, message: string): {
+        dispose(): void;
+    };
+}
+export {};
+//# sourceMappingURL=hydranium-text-documents.d.ts.map

package/lib/documents/hydranium-text-documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-text-documents.d.ts","sourceRoot":"","sources":["../../src/documents/hydranium-text-documents.ts"],"names":[],"mappings":"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"}