@hydranium/core 1.0.0-next.8 → 1.0.0-next.85

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

@@ -37,6 +37,7 @@ import {
    OptionalVersionedTextDocumentIdentifier,
    type RequestHandler,
    type TextDocumentChangeEvent,
+   TextDocumentContentChangeEvent as ContentChange,
    TextDocumentEdit,
    TextDocumentSyncKind,
    type TextDocumentWillSaveEvent,
@@ -165,15 +166,15 @@ interface ConnectionWithTextDocumentSync {
  */
 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.
+    * The text the client held BEFORE this push, and therefore the text its
+    * echo addresses with its ranges. Wider than the baseline the push's edits
+    * were diffed against: a full replace is sent with no diff baseline and
+    * still lands on a buffer the echo is keyed to.
     *
-    * `undefined` when the push was a full replace sent with no baseline (a
-    * first sync, or the recovery push after a rejection). There is then no
-    * knowing what the client held, so the echo is reconstructed against the
-    * synced text instead — which is sound for a full replace, whose
-    * application is position-independent.
+    * `undefined` only when that buffer is unknown — the client never declared
+    * one, or a rejection invalidated what was tracked. The echo is then
+    * reconstructed against the synced text, which is sound only for a
+    * position-independent (full-text) change.
     */
    readonly before: string | undefined;
    /** {@link contentHash} of the text this push moves the client to. */
@@ -182,18 +183,25 @@ interface PendingPush {
 
 /**
  * What an incoming language-client change turns out to be once reconstructed
- * against the pushes still in flight — the return of
+ * against the buffer its ranges address — 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.
+    * 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 };
+   | { 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' };
 
 /**
  * Cheap, stable, non-cryptographic content hash (cyrb53) for the version
@@ -229,7 +237,7 @@ function contentHash(text: string): string {
  *     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.
+ *     silently past based-on 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.
@@ -256,7 +264,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * that record is deleted on last close, while the version sequence must
     * survive it — the shared version is a server-owned, monotonic,
     * advances-iff-content-changes counter that never resets while the server
-    * lives. That invariant is what makes an optimistic `baseVersion` gate
+    * lives. That invariant is what makes an optimistic based-on 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.
@@ -471,15 +479,16 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          }
          record.clientVersions.set(clientId, td.version);
 
-         // A language-client change arriving while one of our own pushes is in
-         // flight is keyed to the buffer the client held BEFORE that push, NOT
-         // to the synced text — the authored write already advanced the latter.
+         // A language-client change is keyed to the buffer that client holds,
+         // which is the synced text only while the two agree — an authored
+         // write advances the synced text without the client knowing, and a
+         // push in flight moves the client without the store knowing.
          // Resolve which it is, and against what, before touching anything.
-         const inFlight =
+         const origin =
             clientId === LANGUAGE_CLIENT_ID
                ? this.classifyLanguageClientChange(this.toLanguageClientUri(td.uri), document, changes)
                : undefined;
-         if (inFlight?.kind === 'echo') {
+         if (origin?.kind === 'echo') {
             // The client is reporting a text we pushed it, so the synced
             // document is ALREADY there and the changes must not be applied a
             // second time. Nothing is minted and no rebuild fires. The
@@ -491,19 +500,23 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             this.logUri(uri, `Skip rebuild: echo of a server-authored push (client version ${td.version})`, 'debug');
             return;
          }
+         if (origin?.kind === 'unreconstructable') {
+            this.tracer.with(uri).warn(`Drop change: no known client buffer for its ranges (client version ${td.version})`);
+            return;
+         }
 
          // The SHARED version advances iff the content actually changes — the
-         // invariant optimistic `baseVersion` gates rely on. The new text is
+         // invariant optimistic based-on gates rely on. The new text is
          // only known after applying the (possibly incremental) changes, so
          // apply at a tentative +1 and roll the version back on an identical
          // result (an empty-changes update only re-stamps the version).
          //
-         // A divergent in-flight change is applied as its RECONSTRUCTED text
-         // rather than as its own ranges: the ranges address the pre-push
-         // baseline, so applying them here would splice the wrong lines.
+         // A divergent change is applied as its RECONSTRUCTED text rather than
+         // as its own ranges: those ranges address the client's own buffer, so
+         // applying them here would splice the wrong lines.
          const previousText = document.getText();
          const sharedVersion = document.version;
-         document = this.configuration.update(document, inFlight === undefined ? changes : [{ text: inFlight.text }], sharedVersion + 1);
+         document = this.configuration.update(document, origin === undefined ? changes : [{ text: origin.text }], sharedVersion + 1);
          const changed = document.getText() !== previousText;
          if (!changed) {
             document = this.configuration.update(document, [], sharedVersion);
@@ -544,7 +557,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * 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.
+    * based-on versions stay valid.
     *
     * Returns the resulting shared version. Throws when the document is not
     * open — callers (`AstDocumentManager.update`) open first.
@@ -644,18 +657,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       if (this.isOpenInClient(uri, clientId)) {
          // Already open for this client under this canonical identity. If this is a
          // NEW client-facing URI for the same file (a second tab reached via a
-         // divergent path, e.g. a symlink and its real path), record it and baseline
-         // its shadow so outbound edits reach this tab too — but do NOT re-fire
-         // open/rebuild; the document is already live.
+         // divergent path, e.g. a symlink and its real path), record it so outbound
+         // edits reach this tab too — but do NOT re-fire open/rebuild; the document
+         // is already live.
          if (clientId === LANGUAGE_CLIENT_ID) {
             const clientFacing = this.toLanguageClientUri(td.uri);
             const record = this.__documents.get(uri);
             if (record && !record.languageClientUris?.has(clientFacing)) {
                (record.languageClientUris ??= new Set<LanguageClientUri>()).add(clientFacing);
-               const open = this.__syncedDocuments.get(uri);
-               if (open) {
-                  this.__shadow.set(clientFacing, open.getText());
-               }
+               // This tab's own buffer, NOT the synced text: a second tab is a second
+               // client model, read from disk, so a server-authored write already
+               // applied to the first tab leaves it BEHIND the synced document. Keying
+               // a diff to the synced text here addresses lines this tab does not have
+               // and drops content it does.
+               this.__shadow.setOpenedText(clientFacing, td.text);
             }
          }
          return;
@@ -679,7 +694,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          const source = pendingText ? ', source=pending' : '';
          // The SHARED version is server-assigned: continue the persisted
          // sequence — same version when the content is unchanged since the
-         // last close (so watchers' `baseVersion` pointers stay valid), one
+         // last close (so watchers' based-on versions stay valid), one
          // step when it changed (so no stale pointer can coincidentally pass
          // the optimistic gate). Only a first-ever open adopts the client's
          // declared id as the sequence seed.
@@ -694,22 +709,77 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // Baseline the shadow to what Monaco just opened so the next outbound
             // applyEditToLanguageClient diffs against the right starting point. Keyed by the
             // language-client URI (what Monaco holds), not the canonical document key.
-            this.__shadow.set(this.toLanguageClientUri(td.uri), document.getText());
+            //
+            // The CLIENT's declared text, never the synced document: staged content
+            // consumed above leaves the two different, and a baseline asserting the
+            // client already holds the staged text suppresses the one sync that would
+            // deliver it. Skipped entirely when a push is already outstanding for this
+            // URI — an `applyEdit` to a closed file has the client open from disk and
+            // apply afterwards, so that shadow records what it is about to hold and
+            // disk text would key the next diff to a buffer nobody has.
+            const clientFacing = this.toLanguageClientUri(td.uri);
+            if (!this.__shadow.isTracked(clientFacing)) {
+               this.__shadow.set(clientFacing, td.text);
+            }
          }
          const toFire = Object.freeze({ document, clientId });
          this.__onDidOpen.fire(toFire);
          this.__onDidChangeContent.fire(toFire);
       } else {
          // An additional client attaches to a document already open by another client.
-         this.log(
-            uri,
-            `Attach client: ${clientId} joined existing document (version ${document.version}, ` +
-               `now open in: ${[...existingClients, clientId].join(', ')})`
-         );
+         this.logClientJoined(uri, clientId, document.version, existingClients);
+         if (clientId === LANGUAGE_CLIENT_ID) {
+            // Monaco's own buffer, which on this path is NOT the synced text — another
+            // client opened the document and may already have changed it. Recorded as
+            // an equality-only baseline (never a diff one, see `setOpenedText`) so the
+            // refresh below does not push a full replace of content Monaco already
+            // holds, which would dirty the file on open.
+            this.__shadow.setOpenedText(this.toLanguageClientUri(td.uri), td.text);
+         }
          this.refreshContent(uri, clientId);
       }
    }
 
+   /**
+    * Record `clientId` as an additional holder of a document another client
+    * already has open.
+    *
+    * Unlike the attach branch of {@link notifyDidOpenTextDocument} this does
+    * not refresh. That branch re-renders an attaching TEXTUAL view; a client
+    * reaching a document through a non-textual route has nothing to re-render,
+    * and refreshing per attach turns each into a Langium rebuild and dependent
+    * relink cascade.
+    *
+    * The staleness guard baselines at the SYNCED version, not a declared buffer
+    * version, because a client arriving this way holds no buffer of its own.
+    * Unifying the two routes therefore rebaselines a textual client's guard to a
+    * version it never declared.
+    *
+    * Returns whether a hold was added — `false` when `uri` is not open, or
+    * `clientId` already holds it.
+    */
+   attachClient(uri: DocumentUri, clientId: string): boolean {
+      const key = this.documentKey(uri);
+      const document = this.__syncedDocuments.get(key);
+      if (!document || this.isOpenInClient(key, clientId)) {
+         return false;
+      }
+      const record = this.trackingFor(key);
+      const existingClients = [...record.clients];
+      record.clients.add(clientId);
+      record.clientVersions.set(clientId, document.version);
+      this.logClientJoined(key, clientId, document.version, existingClients);
+      return true;
+   }
+
+   protected logClientJoined(uri: DocumentUri, clientId: string, version: number, existingClients: readonly string[]): void {
+      this.log(
+         uri,
+         `Attach client: ${clientId} joined existing document (version ${version}, ` +
+            `now open in: ${[...existingClients, clientId].join(', ')})`
+      );
+   }
+
    refreshContent(uri: DocumentUri, clientId: string): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(uri));
       if (syncedDocument) {
@@ -790,7 +860,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * `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 (based-on gates): version unchanged ⇔
     * content unchanged.
     */
    version(uri: DocumentUri): number {
@@ -967,10 +1037,11 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       const targets: Iterable<LanguageClientUri> = recorded && recorded.size > 0 ? recorded : [this.toLanguageClientUri(uri)];
       let lastResult: ApplyWorkspaceEditResult | undefined;
       for (const targetUri of targets) {
-         // Read BEFORE computeEdits, which overwrites it. This is the text the
-         // edits below are keyed to, and therefore the only text the client's
-         // echo of them can be reconstructed against.
-         const before = this.__shadow.get(targetUri);
+         // Read BEFORE computeEdits, which overwrites the baseline and drops
+         // the opened snapshot. This is the text the client holds, and
+         // therefore the only text its echo of this push can be reconstructed
+         // against — whether or not the push below is keyed to it.
+         const before = this.__shadow.clientText(targetUri);
          const edits = this.__shadow.computeEdits(targetUri, newText);
          if (edits.length === 0) {
             continue;
@@ -985,9 +1056,20 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // it is exactly what the caller retries with after a rejection, so
             // gating it there would refuse the recovery too.
             const version = isFullReplace(edits) ? UNKNOWN_CLIENT_VERSION : this.languageClientVersion(uri);
+            // A full `ApplyWorkspaceEditParams`, `edit` and all — NOT a bare
+            // `WorkspaceEdit` with a `label` beside it. `applyEdit` takes
+            // `ApplyWorkspaceEditParams | WorkspaceEdit` and discriminates on
+            // `!!value.edit`, so `{ label, documentChanges }` is wrapped as
+            // `{ edit: { label, documentChanges } }` — putting the label inside
+            // the edit, where LSP defines no such field and no client reads it.
+            // The union is also what hides it at compile time: excess-property
+            // checking admits a property present in EITHER member, so an object
+            // matching neither type-checks against the union.
             const result = await connection.workspace.applyEdit({
                label: options?.label,
-               documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               edit: {
+                  documentChanges: [TextDocumentEdit.create(OptionalVersionedTextDocumentIdentifier.create(targetUri, version), edits)]
+               }
             });
             if (result && result.applied === false) {
                this.__shadow.invalidate(targetUri);
@@ -1043,12 +1125,17 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
 
    /**
     * Decide what an incoming language-client change actually is, by
-    * reconstructing the client's resulting buffer against the OLDEST push still
-    * in flight for `clientFacing`.
+    * reconstructing the client's resulting buffer against the text its ranges
+    * address — the pre-push buffer of the OLDEST push still in flight for
+    * `clientFacing`, else whatever that client is believed to hold.
     *
-    * `undefined` when nothing of ours is in flight, which is the ordinary path:
-    * the client's ranges then address the synced text and the caller applies
-    * them to it directly.
+    * `undefined` when the client's ranges address the synced text itself —
+    * nothing in flight, and no evidence the client holds anything else. That
+    * is the ordinary path, and the caller then applies the ranges directly.
+    * The two texts part company without a push in flight whenever a client
+    * attaches to a document another client has already written: it opened
+    * from disk, so applying its ranges to the synced text splices lines they
+    * never addressed.
     *
     * **Why the oldest, and why reconstruct at all.** The client applies our
     * pushes in order and echoes each against the buffer it held before that
@@ -1079,22 +1166,41 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       document: T,
       changes: TextDocumentContentChangeEvent[]
    ): LanguageClientChangeOrigin | undefined {
-      const pending = this.__pendingPushes.get(clientFacing);
-      if (pending === undefined || pending.length === 0) {
+      const queued = this.__pendingPushes.get(clientFacing);
+      const pending = queued?.length ? queued : undefined;
+      // The text the client's ranges address: the buffer it held before the
+      // oldest push still in flight, else the buffer it is believed to hold.
+      const clientText = pending?.[0].before ?? this.__shadow.clientText(clientFacing);
+      if (pending === undefined && (clientText === undefined || clientText === document.getText())) {
          return undefined;
       }
+      if (pending !== undefined && pending[0].before === undefined && changes.some(change => ContentChange.isIncremental(change))) {
+         // A push sent to a client whose buffer was unknown — a first sync, or
+         // the recovery push after a rejection. The shadow now holds the text
+         // that push MOVES the client to, which is the one text the echo's
+         // ranges provably do not address, so the fallback above is a baseline
+         // known to be wrong rather than merely unverified. Drop the queue and
+         // the shadow: the next sync is then a full replace, which lands on
+         // whatever the client holds. A full-text change is exempt because it
+         // reconstructs identically against any baseline.
+         pending.length = 0;
+         this.__shadow.invalidate(clientFacing);
+         return { kind: 'unreconstructable' };
+      }
       // Through the configured factories, not `TextDocument` directly, so an
       // adopter's custom text-document type governs how the ranges are applied
       // here exactly as it does on the synced document.
-      const probe = this.create(clientFacing, document.languageId, 0, pending[0].before ?? document.getText());
-      const clientText = this.update(probe, changes, 0).getText();
-      const matchIndex = pending.findIndex(push => push.afterHash === contentHash(clientText));
-      if (matchIndex >= 0) {
-         pending.splice(0, matchIndex + 1);
-         return { kind: 'echo' };
+      const probe = this.create(clientFacing, document.languageId, 0, clientText ?? document.getText());
+      const reconstructed = this.update(probe, changes, 0).getText();
+      if (pending !== undefined) {
+         const matchIndex = pending.findIndex(push => push.afterHash === contentHash(reconstructed));
+         if (matchIndex >= 0) {
+            pending.splice(0, matchIndex + 1);
+            return { kind: 'echo' };
+         }
+         pending.length = 0;
       }
-      pending.length = 0;
-      return { kind: 'divergent', text: clientText };
+      return { kind: 'divergent', text: reconstructed };
    }
 
    /**

package/src/documents/language-client-text-shadow.ts

@@ -57,12 +57,23 @@ export function isFullReplace(edits: readonly TextEdit[]): boolean {
  *  - {@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 class LanguageClientTextShadow {
    protected shadow = new 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 = new 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.
@@ -85,23 +96,54 @@ export class LanguageClientTextShadow {
    }
 
    /**
-    * The text the language client is believed to hold, or `undefined` when
-    * there is no baseline (first sync, or after an {@link invalidate}).
+    * 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 {
+      this.opened.set(uri, text);
+   }
+
+   /**
+    * 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 it: a push's minimal edits are keyed to this text, so an
-    * echo of that push carries ranges addressing it and nothing else. Losing
-    * it is what makes an incremental echo unreconstructable, and applying such
-    * an echo to the already-advanced synced text duplicates every inserted
-    * line.
+    * 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.
     */
-   get(uri: string): string | undefined {
-      return this.shadow.get(uri);
+   clientText(uri: string): string | undefined {
+      return this.shadow.get(uri) ?? this.opened.get(uri);
+   }
+
+   /**
+    * 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 {
+      return this.shadow.has(uri);
    }
 
    /** Forget the shadow for a URI; next {@link computeEdits} falls back to a full-document replace. */
    invalidate(uri: string): void {
       this.shadow.delete(uri);
+      // Drops the opened snapshot too, and this is the only place that has to:
+      // `computeEdits` clears it whenever it consults it, so the sole way it can
+      // outlive what the client holds is surviving under a live shadow until that
+      // shadow is dropped here.
+      this.opened.delete(uri);
    }
 
    /**
@@ -109,7 +151,9 @@ export class LanguageClientTextShadow {
     * 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).
+    *  - 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
@@ -124,7 +168,11 @@ export class LanguageClientTextShadow {
       this.shadow.set(uri, newText);
       const fullReplace: TextEdit = { range: FULL_RANGE, newText };
       if (old === undefined) {
-         return [fullReplace];
+         // The opened snapshot has served its purpose either way: the shadow above
+         // is now the baseline, so leaving it would only risk a later stale match.
+         const openedText = this.opened.get(uri);
+         this.opened.delete(uri);
+         return openedText === newText ? [] : [fullReplace];
       }
       const edits = diffToEdits(old, newText);
       const verifyDoc = this.documents.create(uri, 'plaintext', 0, old);

package/src/documents/self-save-registry.ts

@@ -22,10 +22,32 @@ export interface SelfSaveRegistryOptions {
 /**
  * Tracks `mtime` of files written by the server itself so the echo
  * `didChangeWatchedFiles` event from the OS file watcher can be suppressed,
- * avoiding redundant rebuilds after each save. Entries are matched by mtime
- * (not by a time window) and expire after a TTL.
+ * avoiding redundant rebuilds after each save.
  */
-export class SelfSaveRegistry {
+export interface SelfSaveRegistry {
+   /**
+    * Record a self-write, and drop any registration already past its TTL.
+    *
+    * Keyed by `fsPath` rather than URI string, because the two sides of a
+    * suppression see different URI forms for one file.
+    */
+   register(fsPath: string, mtimeMs: number): void;
+
+   /**
+    * Whether `fsPath` carries a live registration at exactly `mtimeMs`.
+    *
+    * A registration expires after the TTL, so a write recorded longer ago than
+    * that answers `false` — the caller's decision holds only while the echo it
+    * suppresses could still be in flight. A query never mutates the registry.
+    */
+   isRegistered(fsPath: string, mtimeMs: number): boolean;
+}
+
+/**
+ * Compares entries by mtime rather than by a time window, so the echo of a
+ * save whose content is unchanged is still recognised.
+ */
+export class DefaultSelfSaveRegistry implements SelfSaveRegistry {
    protected readonly entries = new Map<string, { mtimeMs: number; registeredAt: number }>();
    /**
     * Read time through the shared {@link Clock} rather than `Date.now()`: the
@@ -59,23 +81,40 @@ export class SelfSaveRegistry {
       return isCaseInsensitiveFileSystem() ? fsPath.toLowerCase() : fsPath;
    }
 
-   /** Record a self-write. Key by `fsPath` (not URI string) to avoid URI-form mismatches. */
    register(fsPath: string, mtimeMs: number): void {
+      this.evictExpired();
       this.entries.set(this.key(fsPath), { mtimeMs, registeredAt: this.clock.now() });
    }
 
-   /** True if `mtimeMs` matches a recent self-write. Evicts stale entries. Not consumed on match. */
-   matches(fsPath: string, mtimeMs: number): boolean {
-      const key = this.key(fsPath);
-      const entry = this.entries.get(key);
-      if (!entry) {
-         return false;
-      }
-      if (this.clock.now() - entry.registeredAt > this.ttlMs) {
-         this.entries.delete(key);
+   isRegistered(fsPath: string, mtimeMs: number): boolean {
+      const entry = this.entries.get(this.key(fsPath));
+      if (!entry || this.isExpired(entry.registeredAt)) {
          return false;
       }
       // Accept mtime equality (some filesystems have 1-second precision).
       return entry.mtimeMs === mtimeMs;
    }
+
+   /**
+    * Drop every expired registration.
+    *
+    * On the WRITE path, so the query stays free of side effects. Evicting from
+    * the query instead reaches only the keys something happens to ask about,
+    * and a path written once and never queried again is then retained for the
+    * life of the process. Bounded by the paths self-written inside one TTL
+    * window, so the sweep is over a handful of entries and sits behind a file
+    * write either way.
+    */
+   protected evictExpired(): void {
+      for (const [key, entry] of this.entries) {
+         if (this.isExpired(entry.registeredAt)) {
+            this.entries.delete(key);
+         }
+      }
+   }
+
+   /** Strictly greater, so an entry aged exactly to the TTL is still eligible. */
+   protected isExpired(registeredAt: number): boolean {
+      return this.clock.now() - registeredAt > this.ttlMs;
+   }
 }

package/src/index.ts

@@ -35,5 +35,10 @@ export * from './langium/workspace/index.js';
 export * from './langium/service-registry.js';
 export * from './langium/language-types.js';
 export * from './launcher/index.js';
+export * from './locale/index.js';
+// The renderer only. The `./messages` subpath additionally enumerates this
+// package's own declarations, which the root barrel already re-exports through
+// the modules that raise them.
+export * from './messages/renderer.js';
 export * from './documents/index.js';
 export * from './util/index.js';