@hydranium/core 1.0.0-next.205 → 1.0.0-next.206

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

@@ -12,10 +12,14 @@ 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, 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 Stopwatch, type TextState, type TextVersion, 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 { type ClientSessionClosedEvent, ClientSessionRegistry, type SessionEndCause } from './client-session-registry.js';
-import { LanguageClientTextShadow } from './language-client-text-shadow.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;
 }
@@ -32,123 +36,29 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
     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
+     * 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, reverts at once whatever this is.
+     * ending its session, releases 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.
+     * Defaults to 10 s. `0` releases such a document at once as well, in the
+     * close itself rather than on a timer.
      */
-    readonly revertGraceMs?: number;
+    readonly releaseGraceMs?: number;
 }
 /** Delivered by {@link HydraniumTextDocuments.onDidSaveInLanguageClient}. */
 export interface LanguageClientSavedEvent {
     readonly uri: string;
 }
-/** Delivered by {@link HydraniumTextDocuments.onDidCloseLastOpen}. */
-export interface LastOpenClosedEvent {
+/** Delivered by {@link HydraniumTextDocuments.onDidReleaseDocument}. */
+export interface DocumentReleasedEvent {
     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,
- * 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.
- *
- * 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.
- */
-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), 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;
-    /**
-     * 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}.
-     */
-    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 —
  * one entry of {@link HydraniumTextDocuments.openDocuments}.
@@ -179,199 +89,72 @@ export type RepairCommit<T extends TextDocument> = {
     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.
- */
-export interface VersionSequence {
-    /** The shared version of the text last closed or built. */
-    readonly version: number;
-    /** {@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} —
- * a `protected` field, so a subclass reading the queue has to name what it holds.
- */
-export interface PendingLanguageClientPush {
-    /**
-     * 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` 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 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 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.
- */
-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 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`.
+ * 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) 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 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 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
- *     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 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
+     * 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 __sessions: ClientSessionRegistry;
-    /**
-     * Per-URI shared-version continuity across close/reopen cycles
-     * ({@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 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, 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 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.
-     *
-     * **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, 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`
-     * diffs instead of full-document replaces (5–20 s → <500 ms on 20-30 KB YAML diagrams).
-     *
-     * Auto-tracked from the multi-client text-document events: open / change / close of
-     * the language client (re)baseline or invalidate the shadow. Other client ids
-     * (form editor, GLSP, integrity) do NOT touch the shadow — only what Monaco believes
-     * it has matters for the diff.
-     *
-     * Apply-verify safety net is built in: if the diff doesn't reconstruct `newText`
-     * exactly, {@link LanguageClientTextShadow.computeEdits} falls back to a full-range
-     * replace and invokes the `onFallback` callback — a diff regression becomes log
-     * noise, not a 0-byte save.
-     *
-     * Assigned in the constructor body so the `onFallback` callback can capture
-     * `this.logger` after the parameter-property assignment has run (field
-     * initializers fire BEFORE parameter-property assignment in TS).
-     */
-    protected readonly __shadow: LanguageClientTextShadow;
     protected readonly tracer: Tracer;
     protected readonly configuration: TextDocumentsConfiguration<T>;
-    /** See {@link HydraniumTextDocumentsOptions.revertGraceMs}. */
-    protected readonly revertGraceMs: number;
-    protected readonly lastOpenClosedEmitter: Emitter<LastOpenClosedEvent>;
+    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>;
-    protected readonly dirtyChangedEmitter: Emitter<DocumentDirtyChangedEvent>;
     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>;
@@ -407,64 +190,38 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
     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}.
+     * 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 revert grace, then release it.
+     * 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 resolvePendingRevert} for any other
+     * 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;
     /**
-     * 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.
+     * 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;
     /**
-     * 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>;
+     * 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>;
     /**
@@ -493,24 +250,12 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * 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
+     * `clientId` already holds it, or the document was waiting out the release
      * grace for other clients and was released instead (see
-     * {@link resolvePendingRevert}); the caller then opens it anew.
+     * {@link resolveDeferredRelease}); 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;
     /**
@@ -520,7 +265,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 DocumentTrackingRecord.languageClientDocuments}). The
+     * for egress addressing, by the {@link LanguageClientShadow}. The
      * policy is always bound (the framework defaults it to
      * `DefaultDocumentUriPolicy`, where canonical ≡ syntactic normalize).
      */
@@ -534,8 +279,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): DocumentTrackingRecord;
     setAuthor(uri: DocumentUri, version: number, author: string): void;
     /**
      * Resolve the synced `TextDocument` for `uri`. The store keys documents by
@@ -572,14 +315,18 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      */
     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.
+     * 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 heldTextHash(document: T): string;
+    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 (`VersionSyncService.modelProduced`) —
@@ -633,8 +380,10 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * `onDidClose` event fires for the last client, so `isOpen` returns `true`
      * 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.
+     * 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;
@@ -657,11 +406,11 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
     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.
+     * 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 onDidCloseLastOpen(): Event<LastOpenClosedEvent>;
+    get onDidReleaseDocument(): Event<DocumentReleasedEvent>;
     /**
      * Fires for every save the language client reports of a document it has
      * open: the editor has written the file. {@link onDidSave} follows only
@@ -669,16 +418,16 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      */
     get onDidSaveInLanguageClient(): Event<LanguageClientSavedEvent>;
     /**
-     * Whether `uri` is waiting out the revert grace: its last open closed with a
+     * 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.
      */
-    isRevertPending(uri: DocumentUri): boolean;
+    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 revert grace is still
+     * the store does not hold; a document waiting out the release grace is still
      * held.
      *
      * The baseline is the text a first open brought, or what the server wrote,
@@ -688,10 +437,11 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      */
     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.
+     * 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>;
     /**
@@ -699,15 +449,13 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * `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;
+    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>;
-    /** 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.
@@ -722,7 +470,7 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
     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
+     * 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.
      *
@@ -740,13 +488,6 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * 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.
@@ -786,10 +527,9 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      * 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.
+     * never reads the stage, and the release discards it. 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;
     /**
@@ -809,20 +549,19 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
      *
      * 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 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,
+     * 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.
      */
@@ -830,71 +569,7 @@ export declare class HydraniumTextDocuments<T extends TextDocument = TextDocumen
         label?: string;
     }): Promise<ApplyWorkspaceEditResult | undefined>;
     /**
-     * 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` 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 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, targetUri?: LanguageClientUri): 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 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 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
-     * push, so the first echo to arrive belongs to the oldest entry — a FIFO
-     * correspondence the queue preserves by consuming from the front. Comparing
-     * the reconstruction against every pending hash, not only the oldest, is
-     * what recognises an echo that a newer write already superseded: a rapid
-     * write sequence can deliver the echo of push N after the store applied
-     * push N+1, and everything older is then accounted for too.
-     *
-     * A reconstruction matching NO pending push means the client's buffer went
-     * somewhere we did not send it — it coalesced a keystroke into the echo, or
-     * typed before the push landed. That text is authoritative, and the queue
-     * drops: the client has stopped being a pure mirror, so no outstanding echo
-     * can match again. (A push still in flight at that point will be refused by
-     * the client's own version gate, which invalidates the shadow and makes the
-     * next sync a position-independent full replace.)
-     *
-     * Content equality is a sound echo proof because entries live only between a
-     * push and its echo — a milliseconds window, never history — and the
-     * client's `didChange` stream is ordered, so every buffer state arrives in
-     * mutation order. An UNDO returning the buffer to previously-pushed text is
-     * therefore never swallowed: the edit that preceded it already emptied the
-     * queue, so undo revisits PAST states while the queue holds IN-FLIGHT ones.
-     */
-    protected classifyLanguageClientChange(clientFacing: LanguageClientUri, document: T, changes: TextDocumentContentChangeEvent[]): LanguageClientChangeOrigin | undefined;
-    /**
-     * Explicitly baseline the language-client text shadow for a URI. Useful in
+     * Explicitly baseline the language-client 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.