@hydranium/core 1.0.0-next.24 → 1.0.0-next.241

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

@@ -8,12 +8,18 @@
  * 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 TextState, type TextVersion, type Tracer } from '@hydranium/protocol';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
-import { LanguageClientTextShadow } from './language-client-text-shadow.js';
+import { type ClientSessionClosedEvent, ClientSessionRegistry, type SessionEndCause } from './client-session-registry.js';
+import { type LanguageClientShadow } from './language-client-shadow.js';
+import { type TextLedger } from './text-ledger.js';
+import { type ReleasedDocument } from './document-release-handler.js';
+import { type DocumentReleaseScheduler } from './document-release-scheduler.js';
+import { type CleanAnnouncement, type DirtyStateTracker, type DocumentDirtyChangedEvent } from './dirty-state-tracker.js';
 export interface ClientTextDocumentChangeEvent<T> extends TextDocumentChangeEvent<T> {
     clientId: string;
 }
@@ -28,46 +34,30 @@ 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 the store releases it. An open
+     * by a client lost from the document, within this time of its own loss,
+     * cancels the release, 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, releases at once whatever this is.
+     *
+     * Defaults to 10 s. `0` releases such a document at once as well, in the
+     * close itself rather than on a timer.
+     */
+    readonly releaseGraceMs?: number;
 }
-/**
- * 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>;
+/** Delivered by {@link HydraniumTextDocuments.onDidSaveInLanguageClient}. */
+export interface LanguageClientSavedEvent {
+    readonly uri: string;
+}
+/** Delivered by {@link HydraniumTextDocuments.onDidReleaseDocument}. */
+export interface DocumentReleasedEvent {
+    readonly uri: CanonicalUri;
 }
 /**
  * A document held open by at least one client, with the client ids holding it —
@@ -80,153 +70,93 @@ 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}.
- */
-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.
+ * 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.
  */
- | {
-    readonly kind: 'divergent';
-    readonly text: string;
+export type RepairCommit<T extends TextDocument> = {
+    readonly status: 'committed';
+    readonly document: T;
+} | {
+    readonly status: 'stale';
+} | {
+    readonly status: 'not-open';
 };
 /**
- * Multi-client text-document tracking on top of Langium's `NormalizedTextDocuments`.
+ * The one text store every head writes to, on top of Langium's
+ * `NormalizedTextDocuments`, and the LSP text-sync endpoint: every
+ * `textDocument/*` notification and every `workspace/applyEdit` push goes
+ * through here.
+ *
+ * Each open, change, close and save is one synchronous transition over the
+ * held document and the collaborators its `create…` methods build. A
+ * collaborator that defers its part lets a listener of the transition's event
+ * read state from before it. A document no client holds any more is
+ * released to the `DocumentReleaseHandler` slot, after
+ * {@link HydraniumTextDocumentsOptions.releaseGraceMs} when its last client's
+ * connection was lost.
  *
- * 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.
+ * Client-declared version ids feed only the per-client staleness guard and
+ * never a running shared sequence: the two count different things, and
+ * splicing them lets versions drift past base-version gate holders. A URI
+ * with no ledger record and no built root starts at its opener's declared id:
+ * no version was handed out for it.
+ *
+ * `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;
+    protected readonly options: HydraniumTextDocumentsOptions<T>;
+    /** Content staged by integrity rules for a document no client holds, consumed by its first open. */
+    protected readonly __pendingContent: Map<CanonicalUri, string>;
     /**
-     * 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.
+     * Which client has which document open, which client ids are registered
+     * sessions, and each client's declared version, the staleness guard's
+     * baseline. Every open-state predicate on this class reads it, so an open
+     * recorded anywhere else is invisible to the last-close transition.
      */
-    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 __sessions: ClientSessionRegistry;
+    /** The version each open document was opened at; see {@link openedVersion}. */
+    protected readonly __openedVersions: Map<CanonicalUri, number>;
     protected readonly tracer: Tracer;
     protected readonly configuration: TextDocumentsConfiguration<T>;
+    protected __textLedger: TextLedger | undefined;
+    protected __languageClientShadow: LanguageClientShadow | undefined;
+    protected __dirtyStateTracker: DirtyStateTracker | undefined;
+    protected __documentReleaseScheduler: DocumentReleaseScheduler | undefined;
+    protected readonly documentReleasedEmitter: Emitter<DocumentReleasedEvent>;
+    protected readonly languageClientSavedEmitter: Emitter<LanguageClientSavedEvent>;
     constructor(services: ServerSharedServices, options?: HydraniumTextDocumentsOptions<T>);
+    protected get textLedger(): TextLedger;
+    protected get languageClientShadow(): LanguageClientShadow;
+    protected get dirtyStateTracker(): DirtyStateTracker;
+    protected get documentReleaseScheduler(): DocumentReleaseScheduler;
+    protected createTextLedger(): TextLedger;
+    protected createLanguageClientShadow(): LanguageClientShadow;
+    protected createDirtyStateTracker(): DirtyStateTracker;
+    protected createDocumentReleaseScheduler(): DocumentReleaseScheduler;
+    /** Hold `document` as the text of `key`, a new version authored by `author`. */
+    protected commitText(key: CanonicalUri, document: T, author: string): void;
+    /**
+     * Apply `changes` to `document`, the held text of `key`, and hold the
+     * result. The version steps only when the text changes, which is what a
+     * base-version gate relies on: unchanged text keeps its version and its
+     * author. The new text is known only once the changes are applied, so they
+     * go in at a tentative step that an identical result rolls back.
+     */
+    protected commitChange(key: CanonicalUri, document: T, changes: TextDocumentContentChangeEvent[], author: string): {
+        document: T;
+        changed: boolean;
+    };
     create(uri: string, languageId: string, version: number, content: string): T;
     update(document: T, changes: TextDocumentContentChangeEvent[], version: number): T;
     protected get __syncedDocuments(): Map<string, T>;
@@ -254,17 +184,81 @@ 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, at once or, for a `'lost'`
+     * close, after {@link HydraniumTextDocumentsOptions.releaseGraceMs}.
+     */
+    notifyDidCloseTextDocument(event: DidCloseTextDocumentParams, clientId?: string, cause?: SessionEndCause): void;
+    /**
+     * Keep the document, text and all, for the release 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 resolveDeferredRelease} for any other
+     * open.
+     */
+    protected deferRelease(uri: CanonicalUri): void;
+    /** Resolve a deferred release of `uri` for an open by `clientId`: a release the scheduler decides on runs now. */
+    protected resolveDeferredRelease(uri: CanonicalUri, clientId: string): void;
+    /**
+     * Drop the document no client has open any more, announce it on
+     * {@link onDidReleaseDocument}, then hand it to the
+     * `DocumentReleaseHandler` slot: its listeners, such as the update
+     * handler dropping a change it still holds back, act before any build the
+     * handler runs.
+     */
+    protected releaseDocument(uri: CanonicalUri): void;
+    /**
+     * Call the `DocumentReleaseHandler` slot, and announce a document released
+     * dirty clean once the promise it returns settles, which is after the
+     * release event. A failure is logged rather than thrown: the store has let
+     * go of the document by now, and a throw would abort the transition that
+     * released it, a session's close of its other documents included.
+     */
+    protected handOverRelease(released: ReleasedDocument, cleanAnnouncement: CleanAnnouncement | undefined): void;
+    /** `uri` as the `DocumentReleaseHandler` slot receives it. */
+    protected toReleasedDocument(uri: CanonicalUri): ReleasedDocument;
     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.
+     *
+     * Returns whether a hold was added — `false` when `uri` is not open,
+     * `clientId` already holds it, or the document was waiting out the release
+     * grace for other clients and was released instead (see
+     * {@link resolveDeferredRelease}); the caller then opens it anew.
+     */
+    attachClient(uri: DocumentUri, clientId: string): boolean;
+    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 +267,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, by the {@link LanguageClientShadow}. The
      * policy is always bound (the framework defaults it to
      * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
      */
@@ -287,8 +281,6 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * 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
@@ -309,50 +301,107 @@ 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 version the document at `uri` was opened at, which a client's write
+     * or an integrity repair steps past; `undefined` while it is not open.
+     */
+    openedVersion(uri: DocumentUri): TextVersion | undefined;
+    /**
+     * 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;
+    /**
+     * The built root's recorded version for a first open of `key` with `text`,
+     * one on when the text differs from the root's; `undefined` when the root
+     * records no store version. Seeded from the opener's declared version
+     * instead, a write based on the built root passes the gate over other text,
+     * and the same text looks newer than its model. A built root records none
+     * only under a `LangiumDocuments` that does not reconcile at registration.
+     */
+    protected builtRootOpeningVersion(key: CanonicalUri, text: string): TextVersion | undefined;
     /**
      * 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
+     * disk after its release, 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`
-     * subscriber that finds this `false` knows the last client just closed and a
-     * disk re-read / rebuild can proceed.
+     * 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.
+     * What the build keeps is the release's: a subscriber that re-read or
+     * rebuilt the document would race the `DocumentReleaseHandler`, and after a
+     * lost connection the release waits out its grace.
      */
     isOpenInAnyClient(uri: DocumentUri): boolean;
     isOpenInClient(uri: DocumentUri, client: string): boolean;
     isOpenInLanguageClient(uri: DocumentUri): boolean;
+    /** The clients that have `uri` open, in the order they opened it. */
+    clientsOf(uri: DocumentUri): string[];
     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 +409,133 @@ 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 release grace runs out,
+     * another client opens it, or it is deleted, before the
+     * `DocumentReleaseHandler` slot is handed the document.
+     */
+    get onDidReleaseDocument(): Event<DocumentReleasedEvent>;
     /**
-     * Stages integrity-updated content for a closed document.
+     * 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 release 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.
+     */
+    isReleaseDeferred(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 release grace is still
+     * held.
      *
-     * 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.
+     * 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. For a document
+     * released dirty it fires once the `DocumentReleaseHandler` slot reports the
+     * release settled: at the version of the text the build then holds, or
+     * without text when the document is gone or the handler failed, 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.
+     */
+    setDiskBaseline(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>;
+    /**
+     * 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 releases its document. 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.
      *
-     * 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.
+     * 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>;
+    /**
+     * 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 document no client holds.
+     *
+     * Nothing is pushed to a file no client holds. The next open of it reads
+     * disk, which lacks the update; {@link notifyDidOpenTextDocument} takes this
+     * staged content in place of that text, and the open's sync then delivers
+     * it to an editor as an unsaved change.
+     *
+     * 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 release discards it. An entry waits for
+     * that first open, at one serialised string per URI.
      */
     stagePendingContent(uri: DocumentUri, text: string): void;
     /**
@@ -384,98 +547,53 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      *   - 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).
+     *   - The language client has not opened the document. A client applies an
+     *     edit to a closed file by opening it, and that open races the edit;
+     *     the document's own open delivers its text instead.
      *
      * On `applyEdit` rejection (`result.applied === false`) or RPC failure the
-     * shadow is invalidated so the next call sends a full-replace baseline.
+     * shadow is invalidated so the next call sends a full replace, or nothing
+     * when the client was last heard to hold that text.
      * 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.
+     * full replace on mismatch, logged, 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
+     * client keystroke lands between computing the edits and the client
+     * applying them, 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,
+     * addressed at the language client's last known version for that URI 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.
+     * safe to apply to whatever the client now holds — or nothing when the
+     * client was last heard to hold that text.
      */
     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.
+     * Explicitly baseline the language-client shadow for a URI the client has
+     * open, for an adopter that knows what the client holds without a
+     * `didChange` saying so (e.g. after a sideband save). Normal didOpen /
+     * didChange paths from the LSP language client already auto-track the
+     * shadow. A seed for a URI the client has not opened is kept but changes no
+     * push, since nothing is pushed there; its open replaces it with the text it
+     * declares.
      */
-    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;
+    setLanguageClientText(uri: DocumentUri, text: string): void;
     /**
-     * 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.
+     * Drop the shadow baseline for a URI; the next applyEditToLanguageClient
+     * sends a full replace, or nothing when the client was last heard to hold
+     * that text.
      */
-    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;
@@ -486,5 +604,4 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
         dispose(): void;
     };
 }
-export {};
 //# sourceMappingURL=hydranium-text-documents.d.ts.map