@hydranium/core 1.0.0-next.19 → 1.0.0-next.193

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

@@ -8,11 +8,13 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { NormalizedTextDocuments } from '@hydranium/langium/lsp';
+import { type URI } from '@hydranium/langium';
 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 ApplyWorkspaceEditResult, type CancellationToken, type Connection, type DidChangeTextDocumentParams, type DidCloseTextDocumentParams, type DidOpenTextDocumentParams, type DidSaveTextDocumentParams, type Disposable, 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 CanonicalUri, type LanguageClientUri, type Stopwatch, type TextState, type TextVersion, type Tracer } from '@hydranium/protocol';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { type ClientSessionClosedEvent, ClientSessionRegistry, type SessionEndCause } from './client-session-registry.js';
 import { LanguageClientTextShadow } from './language-client-text-shadow.js';
 export interface ClientTextDocumentChangeEvent<T> extends TextDocumentChangeEvent<T> {
     clientId: string;
@@ -28,6 +30,56 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
      * Adopters with a custom text-document type (rare) pass their factory.
      */
     readonly configuration?: TextDocumentsConfiguration<T>;
+    /**
+     * How long a document whose last open closed because its client's
+     * connection was lost keeps its text before it reverts to disk. An open by
+     * a client lost from the document, within this time of its own loss,
+     * cancels the revert, so a client that registers again under its id after
+     * a dropped connection finds its unsaved edits. Any other open releases the
+     * document first and then opens it as a first open does, from the text the
+     * opener supplies (an editor's own) or else from the file. Meanwhile the
+     * document counts as open for the integrity service, which therefore writes
+     * none of its unsaved text to disk. A close the client makes itself, or
+     * ending its session, reverts at once whatever this is.
+     *
+     * Defaults to 10 s. `0` reverts such a document at once as well, released
+     * in the close itself rather than on a timer.
+     */
+    readonly revertGraceMs?: number;
+}
+/** Delivered by {@link HydraniumTextDocuments.onDidSaveInLanguageClient}. */
+export interface LanguageClientSavedEvent {
+    readonly uri: string;
+}
+/** Delivered by {@link HydraniumTextDocuments.onDidCloseLastOpen}. */
+export interface LastOpenClosedEvent {
+    readonly uri: CanonicalUri;
+}
+/** Delivered by {@link HydraniumTextDocuments.onDidChangeDirty}. */
+export interface DocumentDirtyChangedEvent {
+    readonly uri: CanonicalUri;
+    /**
+     * The text the new answer of {@link HydraniumTextDocuments.isDirty} was
+     * decided on. The answer changes with the text, before any build, so it can
+     * name text whose model has not been sent yet. Absent when the document no
+     * longer exists, or when the build that follows its release failed.
+     */
+    readonly text?: TextState;
+}
+/**
+ * The language client's open of a document under one URI, from its didOpen to
+ * its didClose. Each URI is its own editor buffer with its own version counter,
+ * so a file reached through a symlink and its real path has one of these each.
+ */
+export interface LanguageClientDocumentState {
+    /** The version the client last declared for this URI. */
+    declaredVersion: number;
+    /**
+     * The version an applied versioned push moved this URI to, ahead of its
+     * echo. Apart from `declaredVersion`, whose staleness guard would drop that
+     * echo and strand its pending push.
+     */
+    pushedVersion?: number;
 }
 /**
  * All per-URI client-facing tracking the manager keys by normalized URI,
@@ -42,32 +94,60 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
  *    separately-tested diff/apply-verify abstraction that owns its own baseline
  *    text; folding its storage here would couple a clean utility to this record
  *    for no real gain.
+ *
+ * Returned by the `protected` {@link HydraniumTextDocuments.trackingFor}, so an
+ * override has to name it. Restating the shape structurally instead compiles
+ * until a field is added here, and then fails at the adopter rather than at the
+ * change that caused it.
  */
-interface DocumentTracking {
-    /** Client ids currently holding this document open (multi-client membership). */
-    readonly clients: Set<string>;
+export interface DocumentTrackingRecord {
     /** 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}).
+     * advanced by every accepted didChange), for the per-client staleness guard.
+     * Client version ids are CLIENT-owned per LSP (Monaco numbers its own
+     * buffer) — they never leak into the shared version sequence, which the
+     * server assigns (see {@link HydraniumTextDocuments.__versionSequences}).
+     * The language client's entry is the latest any of its URIs declared; the
+     * store checks and addresses it per URI, through
+     * {@link DocumentTrackingRecord.languageClientDocuments}.
      */
     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.
+     * Each URI the LSP textual language client opened this (canonically-keyed)
+     * document under, with that open's state. Usually one; more when the same
+     * file is opened under a symlink path and its real path. These are the
+     * egress addresses: the document is *keyed* by its canonical identity, but
+     * Monaco holds it under the URI it opened. The language client holds the
+     * document while any entry remains.
+     */
+    languageClientDocuments?: Map<LanguageClientUri, LanguageClientDocumentState>;
+    /**
+     * The clients whose close of this document was caused by a lost connection
+     * and that have not opened it again, each with a stopwatch started at its
+     * loss on the store's `Clock`. While the document waits out the revert grace, only an
+     * open by one of them within its own
+     * {@link HydraniumTextDocumentsOptions.revertGraceMs} of that loss cancels
+     * the revert. Every such client counts, not only the last to close: one
+     * connection's sessions all end lost together, and any of them may reopen
+     * first. Without the time limit, a client that returns late inherits the
+     * unsaved text of a holder lost after it. A stopwatch rather than a `now()`
+     * reading, because a wall-clock step would otherwise expire a claim early or
+     * revive one past its grace, against a grace timer that the step leaves
+     * alone. An entry past its grace counts as any other client's and is pruned
+     * at the next open of the document.
+     */
+    lostClients?: Map<string, Stopwatch>;
+    /**
+     * The text the server last knew the file to hold, `undefined` for no file.
+     * Set by the first open and moved by {@link HydraniumTextDocuments.updateDiskBaseline}.
      */
-    languageClientUris?: Set<LanguageClientUri>;
+    diskBaseline?: string;
+    /** The last answer {@link HydraniumTextDocuments.onDidChangeDirty} announced. */
+    dirty?: boolean;
 }
 /**
  * A document held open by at least one client, with the client ids holding it —
@@ -80,70 +160,110 @@ export interface OpenDocument {
     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}.
+ * What {@link HydraniumTextDocuments.commitRepair} did with an integrity repair.
+ *
+ * Three outcomes rather than a document-or-nothing, because the two ways of
+ * getting nothing call for opposite responses: `not-open` means there is no
+ * store document to correct and the caller carries on with the one it holds,
+ * while `stale` means there IS one and it has moved past the text the repair
+ * was computed against — so carrying on would persist a correction over an edit
+ * that superseded it. Collapsing them lets the second read as permission to
+ * proceed, which is the failure this shape exists to make unrepresentable.
+ */
+export type RepairCommit<T extends TextDocument> = {
+    readonly status: 'committed';
+    readonly document: T;
+} | {
+    readonly status: 'stale';
+} | {
+    readonly status: 'not-open';
+};
+/**
+ * Where a URI's shared version sequence left off while no client holds it —
+ * started by its first build, stepped by builds of changed text, written at
+ * last-client close, and consulted at the next open so the sequence CONTINUES
+ * instead of restarting at whatever version id the opening client declares. One entry
+ * of {@link HydraniumTextDocuments.__versionSequences} — a `protected` field, so
+ * a subclass reading the map has to name what it holds.
  */
-interface VersionSequence {
-    /** The shared version at last-client close. */
+export interface VersionSequence {
+    /** The shared version of the text last closed or built. */
     readonly version: number;
-    /** {@link contentHash} of the synced text at last-client close. */
+    /** {@link textHash} of that text. */
     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}.
+ * come back yet. One entry of {@link HydraniumTextDocuments.__pendingPushes} —
+ * a `protected` field, so a subclass reading the queue has to name what it holds.
  */
-interface PendingPush {
+export interface PendingLanguageClientPush {
     /**
-     * The text the client held BEFORE this push — the shadow baseline the
-     * push's edits were diffed against, and therefore the text the client's
-     * echo addresses with its ranges.
+     * The text the client held BEFORE this push, and therefore the text its
+     * echo addresses with its ranges. Wider than the baseline the push's edits
+     * were diffed against: a full replace is sent with no diff baseline and
+     * still lands on a buffer the echo is keyed to.
      *
-     * `undefined` when the push was a full replace sent with no baseline (a
-     * first sync, or the recovery push after a rejection). There is then no
-     * knowing what the client held, so the echo is reconstructed against the
-     * synced text instead — which is sound for a full replace, whose
-     * application is position-independent.
+     * `undefined` only when that buffer is unknown — the client never declared
+     * one, or a rejection invalidated what was tracked. The echo is then
+     * reconstructed against the synced text, which is sound only for a
+     * position-independent (full-text) change.
      */
     readonly before: string | undefined;
-    /** {@link contentHash} of the text this push moves the client to. */
+    /** {@link textHash} 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}.
+ * against the buffer its ranges address — the return of
+ * {@link HydraniumTextDocuments.classifyLanguageClientChange}. That method is
+ * `protected`, so an override has to name every arm it can return.
  */
-type LanguageClientChangeOrigin = 
+export type LanguageClientChangeOrigin = 
 /** The client is reporting a text we pushed it. The synced document is already there. */
 {
     readonly kind: 'echo';
 }
 /**
- * The client's buffer has moved somewhere we did not push it — it coalesced
- * a genuine keystroke into the echo, or typed before the push arrived. The
- * reconstructed text is what it now holds, and is authoritative.
+ * The client's buffer holds a text we did not push it — a keystroke that
+ * raced a push, or an edit to a buffer the store has already been written
+ * past. The reconstructed text is what it now holds, and is authoritative.
  */
  | {
     readonly kind: 'divergent';
     readonly text: string;
+}
+/**
+ * The change carries ranges and no known text addresses them, so no
+ * reconstruction is offered. Adopting one anyway splices the document and
+ * stores an edit nobody made; dropping costs at most the one keystroke the
+ * client still holds and the next push contradicts.
+ */
+ | {
+    readonly kind: 'unreconstructable';
 };
 /**
  * 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).
+ *   - Per-document client membership (multiple clients can attach to the same
+ *     URI) and the client-session table, both kept by {@link __sessions}.
  *   - 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 —
+ *     per-client staleness guard and never leak into a running sequence —
  *     the two are different things (an editor's edit-operation counter vs the
  *     document's content-revision number), and splicing them lets versions drift
- *     silently past `baseVersion` gate holders.
+ *     silently past base-version gate holders. A URI with no sequence, and no
+ *     root that records a version, starts at its opener's declared id: no version
+ *     was handed out for it.
  *   - Version-author history so each edit is attributable to its originating client.
+ *   - The revert to disk once no client has a document open, for every head
+ *     ({@link revertToDisk}), deferred by
+ *     {@link HydraniumTextDocumentsOptions.revertGraceMs} after a lost connection.
+ *   - A disk baseline per open document, and whether its text differs from it
+ *     ({@link isDirty}).
  *   - 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
@@ -154,34 +274,54 @@ type LanguageClientChangeOrigin =
 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`.
+     * Per-URI client-facing tracking ({@link DocumentTrackingRecord}), keyed by
+     * canonical URI. One record per URI, so dropping it clears every axis at
+     * once. Which client has the document open is kept apart, in
+     * {@link __sessions}.
+     */
+    protected __documents: Map<CanonicalUri, DocumentTrackingRecord>;
+    /**
+     * Which client has which document open, and which client ids are registered
+     * sessions. Every open-state predicate on this class reads it, so an open
+     * recorded anywhere else is invisible to the last-close transition.
      */
-    protected __documents: Map<CanonicalUri, DocumentTracking>;
+    protected readonly __sessions: ClientSessionRegistry;
     /**
      * 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
+     * ({@link VersionSequence}), kept for every document a build or a client
+     * gave the store, and consulted by the next first-client open. A URI
+     * with none, and no root that records a version, starts at its opener's
+     * declared version.
+     * DELIBERATELY outside {@link DocumentTrackingRecord}: that record is deleted on last close, while the version sequence must
      * survive it — the shared version is a server-owned, monotonic,
      * advances-iff-content-changes counter that never resets while the server
-     * lives. That invariant is what makes an optimistic `baseVersion` gate
+     * lives. That invariant is what makes an optimistic base-version 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.
+     * Never pruned, not even when the file is deleted: a recreated file
+     * restarting at `0` would let a write based on the deleted text pass. Two
+     * small values per URI ever built, however often it changes.
      */
     protected readonly __versionSequences: Map<CanonicalUri, VersionSequence>;
+    /**
+     * Released documents last announced dirty. Their clean flip waits for the
+     * revert, so it carries the reverted text's version; a first open before the
+     * revert takes the entry over, and its own dirty answer decides the flip.
+     * Each release enters a token of its own, so the revert of an earlier
+     * release cannot announce a later one clean before that one's revert.
+     */
+    protected readonly __releasedDirty: Map<CanonicalUri, object>;
+    /** Per held document, the {@link textHash} of its text at the version it was taken. */
+    protected readonly __textHashes: WeakMap<TextDocument, {
+        readonly version: number;
+        readonly hash: string;
+    }>;
     /**
      * Texts pushed to the LSP textual language client via
      * {@link applyEditToLanguageClient} whose echoes have not come back yet
-     * ({@link PendingPush}), keyed like the shadow by language-client URI.
+     * ({@link PendingLanguageClientPush}), keyed like the shadow by language-client URI.
      * Outbound pushes and inbound echoes are uncorrelated on the wire; this
      * FIFO is the explicit correlation, and it is what
      * {@link classifyLanguageClientChange} reconstructs against.
@@ -203,7 +343,7 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * 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[]>;
+    protected readonly __pendingPushes: Map<LanguageClientUri, PendingLanguageClientPush[]>;
     /**
      * Tracked text content per URI for the LSP textual language client (Monaco / VS Code).
      * Owned here so {@link applyEditToLanguageClient} can compute minimal `workspace/applyEdit`
@@ -226,6 +366,11 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
     protected readonly __shadow: LanguageClientTextShadow;
     protected readonly tracer: Tracer;
     protected readonly configuration: TextDocumentsConfiguration<T>;
+    /** See {@link HydraniumTextDocumentsOptions.revertGraceMs}. */
+    protected readonly revertGraceMs: number;
+    protected readonly lastOpenClosedEmitter: Emitter<LastOpenClosedEvent>;
+    protected readonly languageClientSavedEmitter: Emitter<LanguageClientSavedEvent>;
+    protected readonly dirtyChangedEmitter: Emitter<DocumentDirtyChangedEvent>;
     constructor(services: ServerSharedServices, options?: HydraniumTextDocumentsOptions<T>);
     create(uri: string, languageId: string, version: number, content: string): T;
     update(document: T, changes: TextDocumentContentChangeEvent[], version: number): T;
@@ -254,17 +399,119 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * A content-identical write still fires the change event (rebuild): the
      * authored write's server-side rebuild is correctness-bearing, it just
      * mints no new version — nothing observable changed, so watchers'
-     * `baseVersion` pointers stay valid.
+     * base versions stay valid.
      *
      * Returns the resulting shared version. Throws when the document is not
      * open — callers (`AstDocumentManager.update`) open first.
      */
-    applyContentChange(uri: DocumentUri, text: string, clientId: string): number;
-    notifyDidCloseTextDocument(event: DidCloseTextDocumentParams, clientId?: string): void;
+    applyContentChange(uri: DocumentUri, text: string, clientId: string): TextVersion;
+    /**
+     * Close `clientId`'s open of the document. When it was the last open, the
+     * document is released and reverts to disk, at once or, for a `'lost'`
+     * close, after {@link HydraniumTextDocumentsOptions.revertGraceMs}.
+     */
+    notifyDidCloseTextDocument(event: DidCloseTextDocumentParams, clientId?: string, cause?: SessionEndCause): void;
+    /**
+     * Keep the document, text and all, for the revert grace, then release it.
+     * The document stays in the store meanwhile, so a lost client that opens it
+     * again within its own grace attaches to it and finds its unsaved text
+     * rather than reading disk; see {@link resolvePendingRevert} for any other
+     * open.
+     */
+    protected deferRelease(uri: CanonicalUri): void;
+    /**
+     * Resolve the pending revert of `uri` for an open by `clientId`. An open by a
+     * client lost from the document within its grace cancels the revert, and
+     * the client finds its unsaved text. Any other open releases the document
+     * first, so it opens as a first open does: cancelling for every open hands
+     * a lost client's unsaved text to whoever opens next, a reloaded page or an
+     * editor, with nothing marking it unsaved.
+     */
+    protected resolvePendingRevert(uri: CanonicalUri, clientId: string): void;
+    /** Drop the entries of {@link DocumentTrackingRecord.lostClients} whose grace has run out. */
+    protected pruneLostClients(record: DocumentTrackingRecord): void;
+    /**
+     * Drop the document no client has open any more, then announce it on
+     * {@link onDidCloseLastOpen}, which is what reverts it to disk.
+     */
+    protected releaseDocument(uri: CanonicalUri): void;
+    /**
+     * Rebuild a released document from the file system provider, so the build
+     * stops carrying the unsaved text of its last client.
+     *
+     * The provider decides, for every scheme, by `exists`: a document it can
+     * serve is rebuilt from its text, and any other — an editor's `untitled:`
+     * buffer, a file never saved, or one deleted meanwhile — is removed
+     * from the workspace. A `virtual:` document survives, since the framework's
+     * provider for that scheme serves it from the index, whatever provider the
+     * host passes as `context.fileSystemProvider`; an edited one therefore keeps
+     * its last client's text, and keeping it read-only is the client's job.
+     *
+     * The answer is read in the document's disk queue, so the rebuild follows
+     * any save still queued rather than reverting past it; a file that goes
+     * after that read is removed when its rebuild finds none.
+     *
+     * Whether to revert at all is decided inside the write lock, as its holder:
+     * decided before waiting for the lock, a client that opens or re-creates the
+     * document meanwhile would have its text rebuilt over, or the document
+     * removed. A document some client has open again, or that waits out a new
+     * grace, is left to that client.
+     *
+     * A document released dirty is announced clean, so a watcher is never left
+     * holding it dirty: once the revert has parsed the file, even if it is then
+     * cancelled, or else once the build it requests in its place has parsed it,
+     * as the announcement names the store's text. One the revert or that build
+     * removed, or that build failed, is announced without text. A reopen before
+     * that takes the announcement over.
+     */
+    protected revertToDisk(uri: CanonicalUri): Promise<void>;
     notifyWillSaveTextDocument(event: WillSaveTextDocumentParams): void;
     notifyWillSaveTextDocumentWaitUntil(event: WillSaveTextDocumentParams, token: CancellationToken): HandlerResult<TextEdit[], void>;
+    /**
+     * Handle a save the language client reports: fire
+     * {@link onDidSaveInLanguageClient}, then announce it on {@link onDidSave}
+     * only once the file read back from disk holds the store's current text.
+     */
+    protected notifyLanguageClientSave(event: DidSaveTextDocumentParams): Promise<void>;
+    /**
+     * Announce a save the server made. `event.text`, when given, is what the
+     * file now holds, written or found there, and becomes the disk baseline
+     * before the save is announced. It lags the store when an edit landed
+     * after the save took its text, and the document then stays dirty.
+     */
     notifyDidSaveTextDocument(event: DidSaveTextDocumentParams, clientId?: string): void;
+    /** Fire {@link onDidSave} for `document`, which need not be synced any more. */
+    protected announceSave(document: T, clientId: string): void;
     notifyDidOpenTextDocument(event: DidOpenTextDocumentParams, clientId?: string): void;
+    /**
+     * 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,
+     * `clientId` already holds it, or the document was waiting out the revert
+     * grace for other clients and was released instead (see
+     * {@link resolvePendingRevert}); the caller then opens it anew.
+     */
+    attachClient(uri: DocumentUri, clientId: string): boolean;
+    /**
+     * The built root's recorded version, one on when `text` differs from the root's;
+     * `declared` when the root records no store version. Seeded from `declared`, a write based
+     * on the root passes the gate over other text, and the same text looks newer than its model.
+     * A built root has no sequence only under a `LangiumDocuments` that does not reconcile at registration.
+     */
+    protected firstOpenVersion(uri: CanonicalUri, text: string, declared: number): number;
+    protected logClientJoined(uri: DocumentUri, clientId: string, version: number, existingClients: readonly string[]): void;
     refreshContent(uri: DocumentUri, clientId: string): void;
     /**
      * The canonical key a document is stored under — the single point this store
@@ -273,7 +520,7 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * two URIs for one physical file (a symlink path and its real path) into a
      * single registration — dedup at the editor layer, not just in
      * `LangiumDocuments`. The URI the client opened under is preserved separately
-     * for egress addressing (see {@link DocumentTracking.languageClientUris}). The
+     * for egress addressing (see {@link DocumentTrackingRecord.languageClientDocuments}). The
      * policy is always bound (the framework defaults it to
      * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
      */
@@ -288,7 +535,7 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      */
     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;
+    protected trackingFor(uri: CanonicalUri): DocumentTrackingRecord;
     setAuthor(uri: DocumentUri, version: number, author: string): void;
     /**
      * Resolve the synced `TextDocument` for `uri`. The store keys documents by
@@ -309,39 +556,83 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
     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
+     * version, else where its persisted sequence left off, else `0` for a URI
+     * this store has never seen. The shared sequence is
      * server-owned and monotonic across close/reopen cycles, and advances
      * exactly when the synced content changes — which is what makes it a sound
-     * optimistic-concurrency token (`baseVersion` gates): version unchanged ⇔
+     * optimistic-concurrency token (base-version gates): version unchanged ⇔
      * content unchanged.
      */
-    version(uri: DocumentUri): number;
+    version(uri: DocumentUri): TextVersion;
+    /**
+     * The text the store holds for `uri`: an open document's, or for a closed
+     * one, the clean text its version sequence left off at, which for a deleted
+     * document is its last text. `undefined` for a URI no build and no client
+     * gave the store.
+     */
+    textState(uri: DocumentUri): TextState | undefined;
+    /**
+     * {@link textHash} of `document`'s text, taken once per version: the store
+     * moves a document's version with every change of its text.
+     */
+    protected heldTextHash(document: T): string;
     /**
      * 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) —
+     * rebuilt document (`VersionSyncService.modelProduced`) —
      * keeping the "version advances iff content changes" invariant for
      * documents no client currently holds.
      *
-     * Returns `undefined` — and does nothing — when the document is open (the
-     * store's own content is authoritative; external transitions never reach
-     * the Langium factory for open documents) or was never tracked (no gate
-     * holder can hold a version pointer for it, and the early exit keeps
-     * workspace-wide builds from hashing every untouched document).
+     * For an open document, its version when it holds `text`, since a build
+     * that read the file while the document was closed can finish after an
+     * open; else `undefined`, and the caller has to build the document again.
+     *
+     * A document without a sequence starts one at `0` with `text`: snapshots
+     * hand out versions for documents no client opened, so an uncounted change
+     * would let a write based on the old text pass the gate.
      */
     reconcileExternalContent(uri: DocumentUri, text: string): number | undefined;
+    /**
+     * Commit an integrity repair into the OPEN document for `uri`, returning the
+     * document that now holds it, or `undefined` when there was nothing here to
+     * commit into.
+     *
+     * The one thing this exists to do is address the store BY URI. A repair
+     * reaches the resync as a text-document object, and that object is the
+     * store's own only on the LSP path; a document built for an already-open URI
+     * through `LangiumDocumentFactory.fromString` carries its own, so writing the
+     * repair into it corrects a copy the store does not know about and the editor
+     * never sees.
+     *
+     * `parsedFrom` is the text the repaired AST was parsed from, and a mismatch
+     * against the current content REFUSES the commit: the store has moved on,
+     * which means an editor change landed after that parse, and committing would
+     * overwrite a newer edit with a repair computed against text the user has
+     * already replaced. The build that change provokes recomputes the repair.
+     *
+     * Deliberately NOT compared by version. A separately created document seeds
+     * its own numbering, so requiring the two to agree would refuse every commit
+     * on the path this exists for. Content is the thing both sides can be held to.
+     *
+     * A changed text is a new version authored by {@link INTEGRITY_CLIENT_ID}.
+     * Kept at the old version, the repair is invisible to every reader keyed on
+     * versions: a write based on the unrepaired version passes the base-version gate
+     * and replaces the repair, and an echo filter credits the repair to the
+     * client whose edit it corrected. No change event is fired: the repair
+     * rides the build already under way, and an event would re-enter it.
+     */
+    commitRepair(uri: DocumentUri, parsedFrom: string, repaired: string): RepairCommit<T>;
     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`
+     * during the close event itself. `isOpenInAnyClient` reads the open table
+     * ({@link __sessions}), which is updated BEFORE the fire, so an `onDidClose`
      * subscriber that finds this `false` knows the last client just closed and a
      * disk re-read / rebuild can proceed.
      */
@@ -351,8 +642,8 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
     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.
+     * ids holding it. Reads the same open table as {@link isOpenInAnyClient}, so
+     * it reflects a last-client close immediately.
      *
      * Diagnostics-oriented — the server-state snapshot lists these so an operator
      * can see WHY a document is pinned: a document that lingers here after its
@@ -360,19 +651,143 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * under a shedding policy, explains why its CST is never shed).
      */
     openDocuments(): OpenDocument[];
+    /** Fires once a client session has ended, after every document it had open was closed. */
+    get onDidCloseSession(): Event<ClientSessionClosedEvent>;
+    /**
+     * Fires once a document no client has open is released: at its last close,
+     * or, for a lost client's last close, when its revert grace runs out,
+     * another client opens it, or it is deleted. The document then reverts to
+     * disk.
+     */
+    get onDidCloseLastOpen(): Event<LastOpenClosedEvent>;
+    /**
+     * Fires for every save the language client reports of a document it has
+     * open: the editor has written the file. {@link onDidSave} follows only
+     * when the file holds the store's text.
+     */
+    get onDidSaveInLanguageClient(): Event<LanguageClientSavedEvent>;
+    /**
+     * Whether `uri` is waiting out the revert grace: its last open closed with a
+     * lost connection, and it still holds its unsaved text. Such a document is
+     * open for no client, yet not closed either, so a caller that would persist
+     * a closed document's text to disk treats it as open.
+     */
+    isRevertPending(uri: DocumentUri): boolean;
+    /**
+     * Whether the store holds `uri` with text that differs from its disk
+     * baseline: what the server last knew the file to hold. `false` for a URI
+     * the store does not hold; a document waiting out the revert grace is still
+     * held.
+     *
+     * The baseline is the text a first open brought, or what the server wrote,
+     * or read back after an editor's save or a watched-file change, so it can
+     * trail a change to the file that none of these has seen yet. A check that
+     * must know the file reads it instead.
+     */
+    isDirty(uri: DocumentUri): boolean;
+    /**
+     * Fires each time the answer of {@link isDirty} changes. A dirty document's
+     * release fires once a parse of the file reaches the store, at that text's
+     * version, or without text once its revert removed the document or could
+     * not rebuild it, though {@link isDirty} answers clean from the release on.
+     */
+    get onDidChangeDirty(): Event<DocumentDirtyChangedEvent>;
+    /**
+     * Record that the file behind `uri` holds `text`, or no file at all for
+     * `undefined`. A no-op for a URI the store does not hold: the next first
+     * open sets the baseline from its own text.
+     */
+    updateDiskBaseline(uri: DocumentUri, text: string | undefined): void;
+    /**
+     * Read the file behind `uri` through its disk queue and take it as the
+     * baseline. A file that cannot be read counts as none, the side that
+     * leaves the document dirty.
+     */
+    reloadDiskBaseline(uri: DocumentUri): Promise<void>;
+    /** Compare the held text of `uri` with its baseline, and announce a changed answer. */
+    protected refreshDirty(uri: CanonicalUri): void;
+    /**
+     * Start a client session under `clientId`. Throws where
+     * {@link ClientSessionRegistry.register} refuses the id.
+     */
+    registerSession(clientId: string): void;
+    /**
+     * End the client session `clientId`: close every document it has open, then
+     * free the id. Immediate — each close runs the ordinary close path before
+     * this returns, with `cause` as its cause. A no-op for an id that is not a
+     * registered session.
+     */
+    closeSession(clientId: string, cause?: SessionEndCause): void;
+    /**
+     * Close every document the language client has open, as a `didClose` for
+     * each would, so each last close reverts. For a host whose editor connection
+     * can end while the process lives on, such as a worker whose port's peer
+     * closed: the language client is no session, so nothing else closes them.
+     *
+     * It first waits for the workspace initialization the open handler waits
+     * for, so an open that arrived before the close is closed too; closing at
+     * once would leave that open to land afterwards, held by a client that is
+     * gone.
+     */
+    closeLanguageClientDocuments(): Promise<void>;
+    /**
+     * Settles once the initial workspace build has finished, whether it
+     * completed, was cancelled or failed. Awaiting `workspaceInitialized` itself
+     * throws after a cancelled build, which any write during startup causes, and
+     * every open and close gated on it is then dropped for the process lifetime.
+     * The workspace manager logs a failed build.
+     */
+    protected initialBuildFinished(): Promise<void>;
+    /**
+     * Stop tracking every URI the language client holds the document `key`
+     * under, with its shadow and pending pushes. Call before a close by
+     * canonical key that means all of them: a close for one URI while others
+     * remain drops only that URI's and keeps the client's hold.
+     */
+    protected untrackLanguageClientDocuments(key: CanonicalUri): void;
+    /**
+     * The file behind `uri` was deleted: close every open of it except the
+     * language client's.
+     *
+     * The editor's open is left alone because the editor owns it: it keeps the
+     * buffer of a deleted file and goes on sending changes for it, and a store
+     * that had closed the document would drop every one of them until the editor
+     * reopened.
+     */
+    notifyDocumentDeleted(uri: DocumentUri): void;
+    /**
+     * Remove the document for `uri`, closing every open of it first — the
+     * editor's included, since the document it would keep editing is gone.
+     *
+     * The base removes the synced document without consulting the open table,
+     * which leaves every open recorded against a document that no longer exists:
+     * the store then answers that the URI is open, and the next open attaches to
+     * nothing.
+     */
+    delete(uri: string | URI | T): void;
+    /**
+     * A client id as log lines print it. An id containing `#` is cut eight
+     * characters after its last `#`, which leaves a minted `label#uuid` as the
+     * label and enough of the UUID to tell sessions apart; an id without `#`
+     * prints whole. The full id goes out at trace level wherever a session
+     * starts or ends.
+     */
+    protected formatClientId(clientId: string): string;
     /**
-     * Stages integrity-updated content for a closed document.
+     * Stages integrity-updated content for a document no client holds.
      *
      * When `workspace/applyEdit` targets a closed file, the client opens it from
      * disk (stale) and sends `didOpen` before applying the edit. This staged
      * content is consumed by {@link notifyDidOpenTextDocument} to replace the
      * stale disk text, preventing a brief revert of the integrity update.
      *
-     * Not cleared on close: pending content is only staged for already-closed
-     * documents (the integrity service checks `isOpenInLanguageClient` first), so
-     * a close → stage → open cycle cannot occur. The only scenario where an
-     * entry lingers is if `workspace/applyEdit` fails and the file is never
-     * opened — the memory cost is one serialised string per URI.
+     * Only a FIRST open consumes it, so stage only for a URI no client holds
+     * ({@link isOpenInAnyClient} is `false`). A URI held only through another
+     * head is not closed: an editor attaching to it joins the existing entry and
+     * never reads the stage, and the last close discards the stage with the
+     * tracking record. An entry lingers only if `workspace/applyEdit` fails and
+     * the file is never opened — the memory cost is one serialised string per
+     * URI.
      */
     stagePendingContent(uri: DocumentUri, text: string): void;
     /**
@@ -402,8 +817,9 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * 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
+     * addressed at the language client's last known version for that URI (see
+     * {@link languageClientVersion}) 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.
@@ -412,20 +828,22 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
         label?: string;
     }): Promise<ApplyWorkspaceEditResult | undefined>;
     /**
-     * The version the LSP textual language client last declared for `uri`, for
-     * addressing an outgoing `workspace/applyEdit`.
+     * The version the LSP textual language client holds `uri` at under
+     * `targetUri`, 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.
+     * itself stamped on its last `didOpen` / `didChange` for `targetUri`, or the
+     * one an applied push moved it to ahead of the push's echo
+     * ({@link LanguageClientDocumentState}) — 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
+     * Falls back to {@link UNKNOWN_CLIENT_VERSION} when the client has not opened
+     * the document under `targetUri`, which is the honest answer. 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;
+    protected languageClientVersion(uri: DocumentUri, targetUri?: LanguageClientUri): number;
     /**
      * Append a push to the in-flight queue for `targetUri`
      * (see {@link __pendingPushes}). Bounded: beyond
@@ -436,12 +854,17 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
     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`.
+     * 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
@@ -486,5 +909,4 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
         dispose(): void;
     };
 }
-export {};
 //# sourceMappingURL=hydranium-text-documents.d.ts.map