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

package/src/langium/model-service/client-session.ts

@@ -80,7 +80,7 @@ export interface ClientSession<
 
    /**
     * Open `uri` for this session, reading it from disk unless some client has
-    * it open already or it holds this client's unsaved text within its revert
+    * it open already or it holds this client's unsaved text within its release
     * grace. `options` are kept for this open until it closes; a repeat open,
     * concurrent or not, keeps the options of the first.
     */
@@ -90,7 +90,7 @@ export interface ClientSession<
    /**
     * Create a document with `text` and open it for this session. It reaches
     * disk on the first `save`. Fails when the file exists, any client has the
-    * URI open, or the URI waits out the revert grace, and of two creates of one
+    * URI open, or the URI waits out the release grace, and of two creates of one
     * URI at most one succeeds.
     *
     * Resolves with the version the created document took, which a write based
@@ -137,8 +137,8 @@ export interface ClientSession<
     * End the session: close everything it has open and free its id.
     * Idempotent. `cause` is `'lost'` when the session ends because its
     * client's connection went away, which lets each document it was the last
-    * to have open wait out the store's revert grace; ending it for any other
-    * reason reverts such a document at once.
+    * to have open wait out the store's release grace; ending it for any other
+    * reason releases such a document at once.
     */
    dispose(cause?: SessionEndCause): void;
    /**
@@ -497,8 +497,8 @@ export class DefaultClientSession<
          throw new Error(`Cannot create ${uri}: the file exists`);
       }
       this.assertLive();
-      if (this.services.workspace.TextDocuments.isRevertPending(uri)) {
-         throw new Error(`Cannot create ${uri}: it holds the unsaved text of a lost client, waiting out the revert grace`);
+      if (this.services.workspace.TextDocuments.isReleaseDeferred(uri)) {
+         throw new Error(`Cannot create ${uri}: it holds the unsaved text of a lost client, waiting out the release grace`);
       }
       if (this.modelService.isOpen(uri)) {
          throw new Error(`Cannot create ${uri}: it is open in a client`);

package/src/langium/model-service/model-events.ts

@@ -9,8 +9,9 @@
 
 import { type CanonicalUri } from '@hydranium/protocol';
 import { type AstNode, type DocumentState } from '@hydranium/langium';
-import { type AstDocumentUpdatedEvent } from '../../documents/ast-document-manager.js';
-import { type DocumentDirtyChangedEvent } from '../../documents/hydranium-text-documents.js';
+import { type AstDocumentSavedEvent, type AstDocumentUpdatedEvent } from '../../documents/ast-document-manager.js';
+import { type DocumentDirtyChangedEvent } from '../../documents/dirty-state-tracker.js';
+import { type DocumentReleasedEvent } from '../../documents/hydranium-text-documents.js';
 import { type AstDiagnostic } from '../validation/document-validator.js';
 
 /** Which documents a `ModelService` subscription hears about. */
@@ -61,14 +62,14 @@ export interface ModelDeletedEvent {
    readonly uri: CanonicalUri;
 }
 
-/** A document's text started or stopped differing from its file. */
+/** A document was saved: the AST manager's event, as `ModelService` hands it out. */
+export type ModelSavedEvent<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> = AstDocumentSavedEvent<
+   TAst,
+   TDiagnostic
+>;
+
+/** A document's text started or stopped differing from its file: the store's event, as `ModelService` hands it out. */
 export type ModelDirtyChangedEvent = DocumentDirtyChangedEvent;
 
-/**
- * A document no client has open any more was released and reverts to disk.
- * The rebuild that reverts it follows as a {@link ModelUpdatedEvent}, unless a
- * client opens the document first or its file is deleted.
- */
-export interface ModelReleasedEvent {
-   readonly uri: CanonicalUri;
-}
+/** A document no client has open any more was released: the store's event, as `ModelService` hands it out. */
+export type ModelReleasedEvent = DocumentReleasedEvent;

package/src/langium/model-service/model-service.ts

@@ -25,7 +25,7 @@ import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
 import { ReentrantWriteLockError, isInsideWriteLock, isWriteLockScopeInstalled } from '../workspace/write-lock-scope.js';
 import { CancellationToken, Disposable } from 'vscode-languageserver';
-import { AstDocument, type AstDocumentSavedEvent } from '../../documents/ast-document-manager.js';
+import { AstDocument } from '../../documents/ast-document-manager.js';
 import { isConnectionGoneError } from '../../util/connection-liveness.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { IntegrityService } from '../integrity/integrity-service.js';
@@ -40,6 +40,7 @@ import {
    type ModelEventFilter,
    type ModelPhaseFilter,
    type ModelReleasedEvent,
+   type ModelSavedEvent,
    type ModelsBuiltEvent,
    type ModelUpdatedEvent
 } from './model-events.js';
@@ -261,6 +262,11 @@ export interface ModelService<
    validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
 
    isOpen(uri: string): boolean;
+   /**
+    * 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: string): TextVersion | undefined;
    snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined;
    /**
     * The text a session's write of `model` to `uri` applies: a textual model
@@ -285,9 +291,17 @@ export interface ModelService<
     * it. A document saved before its first build arrives as an empty envelope
     * at `UNRECORDED_VERSION`, whose `root` is `undefined` despite its type.
     */
-   onModelSaved(listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void, filter?: ModelEventFilter): Disposable;
+   onModelSaved(listener: (event: ModelSavedEvent<TAst, TDiagnostic>) => void, filter?: ModelEventFilter): Disposable;
    onModelDeleted(listener: (event: ModelDeletedEvent) => void, filter?: ModelEventFilter): Disposable;
+   /** Fires when a document's text starts or stops differing from its file. */
    onDirtyChanged(listener: (event: ModelDirtyChangedEvent) => void, filter?: ModelEventFilter): Disposable;
+   /**
+    * Fires when the store releases a document no client has open any more.
+    * What the build keeps for it is up to the
+    * `DocumentReleaseHandler` slot; the default reverts it to disk, and that
+    * rebuild follows as an {@link onModelUpdated} event, unless a client opens
+    * the document first or its file is deleted.
+    */
    onModelReleased(listener: (event: ModelReleasedEvent) => void, filter?: ModelEventFilter): Disposable;
    /** Fires when `filter.clientId` closes `filter.uri`, its session ending included. */
    onClientClosed(listener: () => void, filter: { readonly uri: string; readonly clientId: string }): Disposable;
@@ -830,6 +844,10 @@ export class DefaultModelService<
       return this.services.workspace.AstDocumentManager.isOpen(uri);
    }
 
+   openedVersion(uri: string): TextVersion | undefined {
+      return this.services.workspace.TextDocuments.openedVersion(uri);
+   }
+
    /**
     * Snapshot of `uri` as it stands RIGHT NOW — the synchronous sibling of the
     * phase reads, which all wait. `undefined` when no document is registered,
@@ -1145,7 +1163,7 @@ export class DefaultModelService<
       });
    }
 
-   onModelSaved(listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void, filter: ModelEventFilter = {}): Disposable {
+   onModelSaved(listener: (event: ModelSavedEvent<TAst, TDiagnostic>) => void, filter: ModelEventFilter = {}): Disposable {
       const target = this.filterUri(filter);
       return this.services.workspace.TextDocuments.onDidSave(event => {
          // LangiumDocuments keys by the canonical form, the saved event by the
@@ -1180,7 +1198,7 @@ export class DefaultModelService<
 
    onModelReleased(listener: (event: ModelReleasedEvent) => void, filter: ModelEventFilter = {}): Disposable {
       const target = this.filterUri(filter);
-      return this.services.workspace.TextDocuments.onDidCloseLastOpen(event => {
+      return this.services.workspace.TextDocuments.onDidReleaseDocument(event => {
          if (this.matches(target, event.uri)) {
             listener(event);
          }

package/src/langium/module.ts

@@ -38,6 +38,7 @@ import { DefaultAstDocumentManager, type AstDocumentManager } from '../documents
 import { DefaultSelfSaveRegistry, type SelfSaveRegistry } from './workspace/self-save-registry.js';
 import { DefaultFileSystemTaskQueue, type FileSystemTaskQueue } from '../documents/file-system-task-queue.js';
 import { DefaultModelLedger, type ModelLedger } from '../documents/model-ledger.js';
+import { DefaultDocumentReleaseHandler, type DocumentReleaseHandler } from '../documents/document-release-handler.js';
 import { DefaultVersionSyncService, type VersionSyncService } from '../documents/version-sync-service.js';
 import {
    DefaultEmptyFileSystemProvider,
@@ -286,6 +287,12 @@ export interface ServerAddedSharedServices<
       ModelLedger: ModelLedger;
       /** Reconciles each produced root with the store, and owns every build that syncs a root to its text or recovers one. */
       VersionSyncService: VersionSyncService;
+      /**
+       * What the build keeps for a document {@link HydraniumTextDocuments} has
+       * released, for every head. Bound to {@link DefaultDocumentReleaseHandler},
+       * which reverts it to disk.
+       */
+      DocumentReleaseHandler: DocumentReleaseHandler;
    };
    /**
     * In-process workspace facade ({@link ModelService}) + AST→transfer
@@ -562,7 +569,8 @@ export function createServerSharedModule(
          // first build.
          CstResidencyService: services => new DefaultCstResidencyService(services),
          ModelLedger: () => new DefaultModelLedger(),
-         VersionSyncService: services => new DefaultVersionSyncService(services)
+         VersionSyncService: services => new DefaultVersionSyncService(services),
+         DocumentReleaseHandler: services => new DefaultDocumentReleaseHandler(services)
       },
       model: {
          // Generic walker — adopters with a typed `$type → wire shape` overlay

package/src/langium/workspace/file-not-found.ts

@@ -9,15 +9,27 @@
 
 import { type URI } from '@hydranium/langium';
 
-// Not re-exported from the workspace barrel: the framework's providers share
-// it, and it is no API of theirs.
+// Not re-exported from the workspace barrel: the framework's providers and
+// the release handler share it, and it is no API of theirs.
 
 /**
  * A missing-file error shaped as a Node file system raises it, with code
  * `ENOENT` and the path: callers tell a missing file from any other failure by
- * those two fields, whichever provider is bound. The last close relies on it to
+ * those two fields, whichever provider is bound. The release relies on it to
  * tell a document gone meanwhile from any other failed rebuild.
  */
 export function notFound(message: string, uri: URI): Error {
    return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
 }
+
+/**
+ * Whether `err` reports that the file of `target` does not exist, as a Node
+ * file system and {@link notFound} do: code `ENOENT`, with `target`'s path. A
+ * missing file of another document is a different failure.
+ */
+export function isFileNotFound(err: unknown, target: URI): boolean {
+   if (typeof err !== 'object' || err === null || !('code' in err) || err.code !== 'ENOENT') {
+      return false;
+   }
+   return !('path' in err) || err.path === target.fsPath;
+}

package/src/lsp/hydranium-document-update-handler.ts

@@ -93,12 +93,12 @@ export interface HydraniumDocumentUpdateHandlerOptions {
  *     Both waits are capped by
  *     {@link HydraniumDocumentUpdateHandlerOptions.willSaveGateMs}.
  *
- * The revert to disk after a document's last close is not dispatched here:
- * the text store runs it for every head, the LSP head included, so a
- * `didCloseDocument` added in a subclass would build the document twice. A
- * change still debounced for the document is dropped when the store releases
- * it: the store's revert rebuilds the document from the file system provider
- * or removes it.
+ * What the build keeps after a document's last close is not dispatched here:
+ * the store hands the released document to the `DocumentReleaseHandler` for
+ * every head, the LSP head included, so a `didCloseDocument` added in a
+ * subclass would build the document twice. A change still debounced for the
+ * document is dropped when the store releases it: the release handler rebuilds
+ * the document from the file system provider or removes it.
  *
  * Adopters with their own handler subclass should extend this class
  * (not Langium's `DefaultDocumentUpdateHandler`) so all of them are
@@ -175,10 +175,10 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
          uri => this.pendingChanged.has(uri.toString()) || this.pendingDeleted.has(uri.toString())
       );
       // A change still debounced for a document the store has released would
-      // build it once more after the store's own revert: from the provider
-      // again, or, for a document the revert removed, by reading a file that
-      // is not there.
-      this.textDocuments.onDidCloseLastOpen(event => {
+      // build it once more after the release handler's build: from the
+      // provider again, or, for a document the release removed, by reading a
+      // file that is not there.
+      this.textDocuments.onDidReleaseDocument(event => {
          this.pendingChanged.delete(URI.parse(event.uri).toString());
          if (this.pendingChanged.size === 0 && this.pendingDeleted.size === 0) {
             this.pendingReason = undefined;

package/src/testing/make-test-services.ts

@@ -36,6 +36,7 @@ import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from '../langium/wor
 import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
 import { DefaultFileSystemTaskQueue, type FileSystemTaskQueue } from '../documents/file-system-task-queue.js';
 import { DefaultModelLedger, type ModelLedger } from '../documents/model-ledger.js';
+import { DefaultDocumentReleaseHandler, type DocumentReleaseHandler } from '../documents/document-release-handler.js';
 import { DefaultVersionSyncService, type VersionSyncService } from '../documents/version-sync-service.js';
 import type { FakeDocumentOptions } from './fake-document.js';
 import { makeStubDocumentBuilder, type StubDocumentBuilder } from './stub-document-builder.js';
@@ -115,6 +116,8 @@ export interface TestSharedServices<
       ModelLedger: ModelLedger;
       /** The REAL service, over this tree's stubs; it reconciles nothing against the stub store. */
       VersionSyncService: VersionSyncService;
+      /** The REAL handler, over this tree's stubs; the stub store releases nothing to it. */
+      DocumentReleaseHandler: DocumentReleaseHandler;
    };
    readonly model: {
       TransferEncoder: TransferEncoder<TTransferDiagnostic>;
@@ -378,8 +381,9 @@ export function makeTestServices<
          WorkspaceLock: workspaceLock,
          FileSystemTaskQueue: new DefaultFileSystemTaskQueue({ workspace: { DocumentUriPolicy: documentUriPolicy } }),
          ModelLedger: modelLedger,
-         // Patched in below: it reads the tree it belongs to.
-         VersionSyncService: {} as VersionSyncService
+         // Patched in below, as both read the tree they belong to.
+         VersionSyncService: {} as VersionSyncService,
+         DocumentReleaseHandler: {} as DocumentReleaseHandler
       },
       model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic>['model'],
       ServerLocale: {} as ServerLocale,
@@ -390,6 +394,7 @@ export function makeTestServices<
    // Patched in after the literal, like `model` below: both read the tree they
    // belong to, and the renderer reads the locale service.
    services.workspace.VersionSyncService = new DefaultVersionSyncService(sharedServices);
+   services.workspace.DocumentReleaseHandler = new DefaultDocumentReleaseHandler(sharedServices);
    const mutableMessages = services as { ServerLocale: ServerLocale; MessageRenderer: MessageRenderer };
    const serverLocale = new DefaultServerLocale(sharedServices);
    if (options.locale) {

package/src/testing/stub-hydranium-text-documents.ts

@@ -13,11 +13,11 @@ import { Disposable, Emitter } from 'vscode-languageserver';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
 import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
 import { ClientSessionRegistry } from '../documents/client-session-registry.js';
+import type { DocumentDirtyChangedEvent } from '../documents/dirty-state-tracker.js';
 import type {
    ClientTextDocumentChangeEvent,
-   DocumentDirtyChangedEvent,
    HydraniumTextDocuments,
-   LastOpenClosedEvent
+   DocumentReleasedEvent
 } from '../documents/hydranium-text-documents.js';
 
 /** Snapshot of an open document tracked by the stub. */
@@ -33,11 +33,11 @@ export interface StubTextDocumentEntry {
  * reads from on test paths — the content channel
  * (`notifyDidChangeTextDocument` / `applyContentChange` / `version` /
  * `getAuthor`), the open-state probes (`isOpenInLanguageClient` /
- * `isOpenInAnyClient` / `isOpenInClient` / `isRevertPending` /
+ * `isOpenInAnyClient` / `isOpenInClient` / `isReleaseDeferred` /
  * `openDocuments`), the push channel
  * to the language client (`applyEditToLanguageClient` / `stagePendingContent`),
  * the save / close notifications, the dirty state (`isDirty` / `textState` /
- * `onDidChangeDirty` / `updateDiskBaseline`, against a baseline {@link seedOpen}
+ * `onDidChangeDirty` / `setDiskBaseline`, against a baseline {@link seedOpen}
  * sets and a save that carries its text moves), and the client-session table
  * (`registerSession` / `closeSession` / `onDidCloseSession`), which is a real
  * `ClientSessionRegistry` — plus test-only helpers:
@@ -77,7 +77,7 @@ export interface StubHydraniumTextDocuments extends Pick<
    | 'getAuthor'
    | 'isOpenInLanguageClient'
    | 'isOpenInAnyClient'
-   | 'isRevertPending'
+   | 'isReleaseDeferred'
    | 'applyEditToLanguageClient'
    | 'stagePendingContent'
    | 'openDocuments'
@@ -86,11 +86,12 @@ export interface StubHydraniumTextDocuments extends Pick<
    | 'registerSession'
    | 'closeSession'
    | 'onDidCloseSession'
-   | 'onDidCloseLastOpen'
+   | 'onDidReleaseDocument'
    | 'isDirty'
    | 'textState'
+   | 'openedVersion'
    | 'onDidChangeDirty'
-   | 'updateDiskBaseline'
+   | 'setDiskBaseline'
 > {
    /**
     * Stub-tailored read accessor. Returns just the surface the framework's
@@ -114,9 +115,12 @@ export interface StubHydraniumTextDocuments extends Pick<
    /** Mark `uri` as open in the LSP textual language client (drives {@link isOpenInLanguageClient}). */
    seedOpenInLanguageClient(uri: string): void;
    /**
-    * Synchronously deliver `onDidClose` to subscribers, then `onDidCloseLastOpen`
-    * when no client has `uri` open any more. The stub keeps no revert grace, so
-    * a last close is announced at once.
+    * Synchronously deliver `onDidClose` to subscribers, then `onDidReleaseDocument`
+    * when no client has `uri` open any more, then the dirty flip of a dropped
+    * holder: the real store's order. The stub keeps no release grace and runs
+    * no release handler, so the flip comes at once and without text, where the
+    * real store announces it once the handler settles, with text while the
+    * build still has the document.
     */
    fireClose(uri: string, clientId: string): void;
    /**
@@ -162,8 +166,9 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
    // stand in for canonical URIs (one stub-boundary cast, like `fireClose`).
    const sessions = new ClientSessionRegistry();
    const key = (uri: string): CanonicalUri => uri as CanonicalUri;
-   const lastOpenClosed = new Emitter<LastOpenClosedEvent>();
+   const documentReleased = new Emitter<DocumentReleasedEvent>();
    const baselines = new Map<string, string | undefined>();
+   const openedVersions = new Map<string, number>();
    const dirty = new Set<string>();
    const dirtyChanged = new Emitter<DocumentDirtyChangedEvent>();
    // As the real store: dirty while held with text other than the baseline,
@@ -177,7 +182,12 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
          } else {
             dirty.delete(uri);
          }
-         dirtyChanged.fire({ uri: key(uri), text: { version: held?.version ?? 0, hash: textHash(held?.text ?? ''), dirty: now } });
+         // No build behind the stub, so a document no longer held is announced without text.
+         dirtyChanged.fire(
+            held === undefined
+               ? { uri: key(uri) }
+               : { uri: key(uri), text: { version: held.version, hash: textHash(held.text), dirty: now } }
+         );
       }
    };
 
@@ -201,6 +211,9 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       version(uri) {
          return docs.get(uri)?.version ?? 0;
       },
+      openedVersion(uri) {
+         return docs.has(uri) ? openedVersions.get(uri) : undefined;
+      },
       textState(uri) {
          const held = docs.get(uri);
          return held && { version: held.version, hash: textHash(held.text), dirty: dirty.has(uri) };
@@ -237,7 +250,7 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       },
       notifyDidSaveTextDocument(event, clientId) {
          if (event.text !== undefined) {
-            stub.updateDiskBaseline(event.textDocument.uri, event.text);
+            stub.setDiskBaseline(event.textDocument.uri, event.text);
          }
          saves.push({ uri: event.textDocument.uri, clientId });
          for (const listener of saveListeners.slice()) {
@@ -274,8 +287,9 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       isOpenInClient(uri, clientId) {
          return sessions.isOpenIn(key(uri), clientId);
       },
-      isRevertPending(uri) {
-         return sessions.isRevertPending(key(uri));
+      isReleaseDeferred() {
+         // The stub keeps no release grace.
+         return false;
       },
       attachClient(uri, clientId) {
          return docs.has(uri) && sessions.addOpen(key(uri), clientId);
@@ -298,8 +312,8 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       get onDidCloseSession() {
          return sessions.onDidCloseSession;
       },
-      get onDidCloseLastOpen() {
-         return lastOpenClosed.event;
+      get onDidReleaseDocument() {
+         return documentReleased.event;
       },
       isDirty(uri) {
          return dirty.has(uri);
@@ -307,7 +321,7 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       get onDidChangeDirty() {
          return dirtyChanged.event;
       },
-      updateDiskBaseline(uri, text) {
+      setDiskBaseline(uri, text) {
          if (docs.has(uri)) {
             baselines.set(uri, text);
             refreshDirty(uri);
@@ -331,6 +345,7 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       seedOpen(uri, text, clientId) {
          sessions.addOpen(key(uri), clientId);
          docs.set(uri, { uri, version: 1, text, clientId });
+         openedVersions.set(uri, 1);
          baselines.set(uri, text);
       },
       seedOpenInLanguageClient(uri) {
@@ -342,9 +357,9 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
          // class: listeners detect the last-close transition by consulting
          // `isOpenInAnyClient`, which reads the already-decremented state.
          const holder = docs.get(uri);
-         if (holder && holder.clientId === clientId) {
+         const dropped = holder !== undefined && holder.clientId === clientId;
+         if (dropped) {
             docs.delete(uri);
-            refreshDirty(uri);
          }
          const removed = sessions.removeOpen(key(uri), clientId);
          if (clientId === LANGUAGE_CLIENT_ID) {
@@ -355,7 +370,11 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
             listener(event);
          }
          if (removed && !sessions.isOpen(key(uri))) {
-            lastOpenClosed.fire({ uri: key(uri) });
+            documentReleased.fire({ uri: key(uri) });
+         }
+         // After the release event, in the order the real store announces them.
+         if (dropped) {
+            refreshDirty(uri);
          }
       },
       reset() {
@@ -366,6 +385,7 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
          appliedEdits.length = 0;
          staged.length = 0;
          baselines.clear();
+         openedVersions.clear();
          dirty.clear();
          saveListeners.length = 0;
          closeListeners.length = 0;

package/lib/documents/language-client-text-shadow.d.ts

@@ -1,133 +0,0 @@
-/********************************************************************************
- * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
- *
- * This program and the accompanying materials are made available under the
- * terms of the MIT License which is available in the project root.
- *
- * SPDX-License-Identifier: MIT
- ********************************************************************************/
-import { type TextEdit } from 'vscode-languageserver';
-import { TextDocument } from 'vscode-languageserver-textdocument';
-/**
- * The minimum surface the shadow needs from a `HydraniumTextDocuments`:
- * a `create` method that materialises a fresh text document via the
- * configured `TextDocumentsConfiguration`. Declared as a narrow
- * structural interface so the manager satisfies it without an explicit
- * import (sidestepping the circular `HydraniumTextDocuments → shadow → manager`
- * dependency) and so tests can stub it with a minimal object literal.
- */
-export interface ShadowDocumentSource {
-    create(uri: string, languageId: string, version: number, content: string): TextDocument;
-}
-/**
- * Whether `edits` is the single full-document replace {@link LanguageClientTextShadow.computeEdits}
- * emits when it has no usable baseline.
- *
- * The distinction matters at the `workspace/applyEdit` egress: a full replace is
- * position-INDEPENDENT and therefore lands correctly on any client buffer, while
- * a line-keyed diff only lands correctly on the exact text it was diffed
- * against. Only the latter needs a client-version gate.
- */
-export declare function isFullReplace(edits: readonly TextEdit[]): boolean;
-/**
- * Tracks the text content the language client (typically Monaco) is believed to
- * currently hold so outgoing `workspace/applyEdit` requests can ship minimal
- * diffs instead of full-document replaces.
- *
- * Why it matters: a full-range replace on a moderately-sized YAML or DSL source
- * forces Monaco to re-tokenise the entire document (observed multi-second hangs
- * on large diagrams), whereas line-level diffs usually reduce that to a handful
- * of small edits.
- *
- * Update points the caller is responsible for:
- *  - {@link computeEdits} after each outgoing server→client sync (updates the shadow optimistically).
- *  - {@link set} when the server receives a `didChange` from the language client (the client now
- *    holds that text; we shouldn't resend it).
- *  - {@link setOpenedText} when the client opens a document the server did not baseline for it —
- *    an equality-only baseline, since that text is a snapshot rather than a tracked one.
- *  - {@link invalidate} when the client rejects an edit (`applied=false`) or a doc is closed —
- *    the shadow is now stale and the next sync must fall back to a full replace.
- */
-export declare class LanguageClientTextShadow {
-    protected onFallback: (uri: string, reason: string) => void;
-    protected documents: ShadowDocumentSource;
-    protected shadow: Map<string, string>;
-    /**
-     * Per URI, the text the client declared it opened the document with, held
-     * only until a real baseline exists. Consulted by {@link computeEdits} when
-     * there is no shadow, and dropped on {@link invalidate}: a snapshot that
-     * outlived what the client holds would let the equality check skip an edit
-     * the client still needs.
-     */
-    protected opened: Map<string, string>;
-    /**
-     * @param onFallback invoked when {@link computeEdits} falls back to a full-range replace due to
-     *    apply-verify mismatch. Useful for logging regressions.
-     * @param documents the {@link ShadowDocumentSource} used to materialise the throwaway probe
-     *    document in {@link computeEdits}. In production this is the owning
-     *    `HydraniumTextDocuments` (whose `create` threads through its configured
-     *    `TextDocumentsConfiguration`); tests pass a minimal stub. Routing
-     *    through the manager rather than `TextDocument.create` directly avoids the
-     *    `instanceof FullTextDocument` gate in the bare LSP `TextDocument.update`,
-     *    keeping the verifier honest for adopters with a custom text-document type.
-     */
-    constructor(onFallback: (uri: string, reason: string) => void, documents: ShadowDocumentSource);
-    /** Record the text the language client is known to hold (e.g. after a `didChange` echo). */
-    set(uri: string, text: string): void;
-    /**
-     * Record the buffer the language client declared at `didOpen`, for a URI
-     * with no baseline yet.
-     *
-     * Deliberately NOT a {@link set}: this text is only ever compared for
-     * EQUALITY, never diffed against. A line-keyed diff is position-dependent,
-     * so keying one to a `didOpen` snapshot the client may have moved past
-     * splices its buffer — the failure {@link computeEdits}'s full-replace
-     * fallback exists to avoid.
-     */
-    setOpenedText(uri: string, text: string): void;
-    /**
-     * The text the language client is believed to hold: the tracked text, else
-     * the buffer it declared at `didOpen`.
-     *
-     * Read at the `workspace/applyEdit` egress BEFORE {@link computeEdits},
-     * which overwrites the tracked text and drops the opened snapshot. A change
-     * the client sends carries ranges addressing this text and nothing else, so
-     * losing it leaves that change unreconstructable — and applying its ranges
-     * to the already-advanced synced text splices lines they never addressed.
-     *
-     * Deliberately wider than what {@link computeEdits} may diff from: an
-     * opened snapshot is a position-dependent key to a buffer the client may
-     * have moved past, so keying a diff to it splices that buffer.
-     */
-    clientText(uri: string): string | undefined;
-    /**
-     * Whether a tracked text exists for `uri`, which is what decides whether a
-     * push can be diffed at all. Distinct from {@link clientText}, which also
-     * answers from the opened snapshot and so cannot settle this.
-     */
-    isTracked(uri: string): boolean;
-    /** Forget the shadow for a URI; next {@link computeEdits} falls back to a full-document replace. */
-    invalidate(uri: string): void;
-    /**
-     * Return the minimal LSP {@link TextEdit}s required to bring the language client's content from
-     * the tracked shadow to `newText`. Updates the shadow to `newText` so subsequent calls diff
-     * against it.
-     *
-     *  - Empty array when the shadow already equals `newText` (caller should skip the RPC),
-     *    or when there is no shadow and the client opened the document with exactly `newText`
-     *    (see {@link setOpenedText}) — pushing it anyway dirties the client's buffer on open.
-     *  - Full-range replace when there is no shadow (first sync or post-{@link invalidate}).
-     *  - Line-level diff otherwise. Before returning, we locally reconstruct `newText` by applying
-     *    the diff to `old`; if that doesn't match, we fall back to a full-range replace and notify
-     *    the fallback callback. This catches any algorithmic regression in {@link diffToEdits}
-     *    without risking client corruption.
-     */
-    computeEdits(uri: string, newText: string): TextEdit[];
-}
-/**
- * Convert a {@link diffLines} result to a list of LSP {@link TextEdit}s keyed on line positions
- * in the *old* text. Contiguous added/removed hunks are coalesced into a single replace so the
- * client sees one edit per changed region.
- */
-export declare function diffToEdits(oldText: string, newText: string): TextEdit[];
-//# sourceMappingURL=language-client-text-shadow.d.ts.map

package/lib/documents/language-client-text-shadow.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"language-client-text-shadow.d.ts","sourceRoot":"","sources":["../../src/documents/language-client-text-shadow.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAS,KAAK,QAAQ,EAAY,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IAClC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAAC;CAC1F;AAKD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAMjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,wBAAwB;IAwB/B,SAAS,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI;IAC3D,SAAS,CAAC,SAAS,EAAE,oBAAoB;IAxB5C,SAAS,CAAC,MAAM,sBAA6B;IAE7C;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,sBAA6B;IAE7C;;;;;;;;;;OAUG;IACH,YACa,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,EACjD,SAAS,EAAE,oBAAoB,EACxC;IAEJ,4FAA4F;IAC5F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEnC;IAED;;;;;;;;;OASG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7C;IAED;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1C;IAED;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9B;IAED,oGAAoG;IACpG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAO5B;IAED;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CAqBrD;CACH;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CA+BxE"}