@hydranium/core 1.0.0-next.38 → 1.0.0-next.380

package/lib/langium/project/single-project-manager.d.ts

@@ -11,7 +11,7 @@ import { type AstNode, type LangiumDocuments, type URI } from '@hydranium/langiu
 import { Disposable } from 'vscode-languageserver';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
-import type { ProjectChangeListener } from './project-change-event.js';
+import type { MemberRelinkFinishedListener, MemberRelinkStartedListener, ProjectChangeListener } from './project-change-event.js';
 import type { ProjectManager } from './project-manager.js';
 /**
  * Framework default {@link ProjectManager}. Exposes a single synthetic
@@ -44,6 +44,12 @@ export declare class SingleProjectManager implements ProjectManager {
     discoverProjects(): Promise<void>;
     /** Never fires — `SingleProjectManager` exposes a fixed registry. The returned disposable is a safe no-op. */
     onProjectsChanged(_listener: ProjectChangeListener): Disposable;
+    /** Never fires: a fixed registry has no member relink to defer. */
+    onMemberRelinkStarted(_listener: MemberRelinkStartedListener): Disposable;
+    /** Never fires, as {@link onMemberRelinkStarted} does not. */
+    onMemberRelinkFinished(_listener: MemberRelinkFinishedListener): Disposable;
+    /** Resolved at once: nothing is ever deferred. */
+    memberRelinkSettled(): Promise<void>;
     isProjectDescriptor(_uri: URI | string): boolean;
     /** Always `true` — single-project by definition. */
     isSingleProject(): boolean;

package/lib/langium/project/single-project-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"single-project-manager.d.ts","sourceRoot":"","sources":["../../../src/langium/project/single-project-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAiC,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IAkBrD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAjB3D;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,gBAAgB;IAEpD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAGjC;IACF,QAAQ,CAAC,KAAK,gBAAqB;IAEnC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,cAAmB;IAM/B,mDAAmD;IAC7C,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,8GAA8G;IAC9G,iBAAiB,CAAC,SAAS,EAAE,qBAAqB,GAAG,UAAU;IAI/D,mBAAmB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO;IAIhD,oDAAoD;IACpD,eAAe,IAAI,OAAO;IAI1B;;;;OAIG;IACH,6BAA6B,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO;IAI1D,4DAA4D;IAC5D,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS;IAInD,6DAA6D;IAC7D,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;IAItD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI/C,WAAW,IAAI,SAAS,OAAO,EAAE;IAIjC,oFAAoF;IACpF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,EAAE;IAOjD,mGAAmG;IACnG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAIxD,2FAA2F;IAC3F,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,OAAO;CAS3F"}
+{"version":3,"file":"single-project-manager.d.ts","sourceRoot":"","sources":["../../../src/langium/project/single-project-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAiC,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClI,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IAkBrD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAjB3D;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,gBAAgB;IAEpD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAGjC;IACF,QAAQ,CAAC,KAAK,gBAAqB;IAEnC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC,YACsB,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,cAAmB,EAI9B;IAED,mDAAmD;IAC7C,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEtC;IAED,8GAA8G;IAC9G,iBAAiB,CAAC,SAAS,EAAE,qBAAqB,GAAG,UAAU,CAE9D;IAED,mEAAmE;IACnE,qBAAqB,CAAC,SAAS,EAAE,2BAA2B,GAAG,UAAU,CAExE;IAED,8DAA8D;IAC9D,sBAAsB,CAAC,SAAS,EAAE,4BAA4B,GAAG,UAAU,CAE1E;IAED,kDAAkD;IAClD,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnC;IAED,mBAAmB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAE/C;IAED,oDAAoD;IACpD,eAAe,IAAI,OAAO,CAEzB;IAED;;;;OAIG;IACH,6BAA6B,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAEzD;IAED,4DAA4D;IAC5D,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAElD;IAED,6DAA6D;IAC7D,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAErD;IAED,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAE9C;IAED,WAAW,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED,oFAAoF;IACpF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,EAAE,CAKhD;IAED,mGAAmG;IACnG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEvD;IAED,2FAA2F;IAC3F,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,OAAO,CAQxF;CACH"}

package/lib/langium/project/single-project-manager.js

@@ -50,6 +50,18 @@ export class SingleProjectManager {
     onProjectsChanged(_listener) {
         return Disposable.create(() => undefined);
     }
+    /** Never fires: a fixed registry has no member relink to defer. */
+    onMemberRelinkStarted(_listener) {
+        return Disposable.create(() => undefined);
+    }
+    /** Never fires, as {@link onMemberRelinkStarted} does not. */
+    onMemberRelinkFinished(_listener) {
+        return Disposable.create(() => undefined);
+    }
+    /** Resolved at once: nothing is ever deferred. */
+    memberRelinkSettled() {
+        return Promise.resolve();
+    }
     isProjectDescriptor(_uri) {
         return false;
     }

package/lib/langium/project/single-project-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"single-project-manager.js","sourceRoot":"","sources":["../../../src/langium/project/single-project-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA6B,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,oBAAoB;IAkBR;IAjBtB;;;;OAIG;IACH,MAAM,CAAU,oBAAoB,GAAG,YAAY,CAAC;IAEjC,OAAO,GAAY;QACnC,EAAE,EAAE,oBAAoB,CAAC,oBAAoB;QAC7C,aAAa,EAAE,6BAA6B;KAC9C,CAAC;IACO,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAEhB,gBAAgB,CAAmB;IACnC,MAAM,CAAS;IAElC,YACsB,QAAqC,EACxD,UAA0B,EAAE;QADT,aAAQ,GAAR,QAAQ,CAA6B;QAGxD,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC,SAAS,CAAC,gBAAgB,CAAC;QAC5D,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACrG,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,gBAAgB;QACnB,QAAQ;IACX,CAAC;IAED,8GAA8G;IAC9G,iBAAiB,CAAC,SAAgC;QAC/C,OAAO,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,mBAAmB,CAAC,IAAkB;QACnC,OAAO,KAAK,CAAC;IAChB,CAAC;IAED,oDAAoD;IACpD,eAAe;QACZ,OAAO,IAAI,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,6BAA6B,CAAC,IAAkB;QAC7C,OAAO,IAAI,CAAC;IACf,CAAC;IAED,4DAA4D;IAC5D,UAAU,CAAC,IAAkB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,6DAA6D;IAC7D,iBAAiB,CAAC,KAAc;QAC7B,OAAO,IAAI,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,cAAc,CAAC,EAAU;QACtB,OAAO,EAAE,KAAK,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACtF,CAAC;IAED,WAAW;QACR,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAED,oFAAoF;IACpF,cAAc,CAAC,SAAiB;QAC7B,IAAI,SAAS,KAAK,oBAAoB,CAAC,oBAAoB,EAAE,CAAC;YAC3D,OAAO,EAAE,CAAC;QACb,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC1E,CAAC;IAED,mGAAmG;IACnG,kBAAkB,CAAC,SAAiB;QACjC,OAAO,SAAS,KAAK,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrH,CAAC;IAED,2FAA2F;IAC3F,SAAS,CAAC,eAAuB,EAAE,eAAuB,EAAE,WAAW,GAAG,KAAK;QAC5E,IAAI,eAAe,KAAK,oBAAoB,CAAC,oBAAoB,EAAE,CAAC;YACjE,OAAO,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,eAAe,KAAK,eAAe,EAAE,CAAC;YACvC,OAAO,WAAW,CAAC;QACtB,CAAC;QACD,OAAO,KAAK,CAAC;IAChB,CAAC"}
+{"version":3,"file":"single-project-manager.js","sourceRoot":"","sources":["../../../src/langium/project/single-project-manager.ts"],"names":[],"mappings":"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"}

package/lib/langium/residency/cst-residency-service.d.ts

@@ -34,8 +34,12 @@ export declare const CST_RESIDENCY_PASS_PRIORITY = 1000000;
  *   "off" toggle.
  * - `{ kind: 'shed-closed-when-idle', idleMs }`: shed a closed document's CST
  *   once it has been idle (not in any build) for `idleMs`, keeping the AST
- *   resident. Open documents are always kept. `idleMs: 0` sheds as soon as a
- *   document is closed (a pure close-triggered threshold of this strategy).
+ *   resident. Open documents are always kept. The timer starts when a build
+ *   includes the document, so `idleMs: 0` sheds a closed document on the tick
+ *   after each such build. A shed document that re-enters a build has its CST
+ *   grafted back, which parses its text, so a window shorter than the gap
+ *   between a document's builds parses a closed document on every build it
+ *   rides in.
  */
 export type CstResidencyStrategy = {
     readonly kind: 'always-keep';
@@ -61,13 +65,14 @@ export interface CstResidencyOptions extends LogNameOptions {
     readonly estimatedBytesPerShedNode?: number;
 }
 /**
- * The build state a shed document must be reset to so the next build re-parses it
- * and rebuilds its CST — and every `reference.$refNode` — before it is relinked or
- * re-indexed (rehydration). It is `DocumentState.Changed` by necessity: the only
- * state below `Parsed`, hence the only one that forces a re-parse rather than an
- * in-place relink. Exposed as a named landmark of the residency feature (cf.
- * `IntegrityService.SettledState`) so the document builder references the feature's
- * declared recovery contract instead of a bare enum value.
+ * The build state a shed document is reset to when the identity-preserving graft
+ * fails, so the next build re-parses it and rebuilds its CST — and every
+ * `reference.$refNode` — before it is relinked or re-indexed. It is
+ * `DocumentState.Changed` by necessity: the only state below `Parsed`, hence
+ * the only one that forces a re-parse rather than an in-place relink. Exposed
+ * as a named landmark of the residency feature (cf.
+ * `IntegrityService.SettledState`) so the document builder references the
+ * feature's declared recovery contract instead of a bare enum value.
  */
 export declare const CST_REHYDRATION_RESET_STATE: DocumentState;
 /**
@@ -80,12 +85,15 @@ export declare const CST_REHYDRATION_RESET_STATE: DocumentState;
  */
 export declare function isCstShed(document: LangiumDocument): boolean;
 /**
- * Residency policy that reclaims memory by shedding the concrete syntax tree
- * (CST) of closed documents while keeping their AST resident. Each build refreshes
- * the idle window of the documents in its batch; when a closed, sheddable
- * document's window elapses, every AST node's `$cstNode` and every reference's
- * `$refNode` are nulled, and the CST root, `Range`s and `Position`s become
- * unreachable and are collected.
+ * Keeps a document's CST available to the readers that need one, shedding it
+ * for documents that have gone idle and re-grafting on demand.
+ *
+ * Each build refreshes the idle window of the documents in its batch. When a
+ * closed, sheddable document's window elapses, every AST node's `$cstNode` and
+ * every reference's `$refNode` are nulled, and the CST becomes unreachable with
+ * the `Range`s and `Position`s only it holds. The reference index's segments, and a
+ * description's segments once read, share the CST's `Range` objects, so
+ * those stay.
  *
  * **Terminology.** *Residency* is the state axis (is the CST in memory? —
  * `resident` vs `shed`); *shed* is both the act and the policy vocabulary (drop
@@ -95,21 +103,25 @@ export declare function isCstShed(document: LangiumDocument): boolean;
  * retained source text and graft it back, identity-preserving — deliberately not
  * "reload", which would suggest bytes coming back unchanged).
  *
- * **Re-entry is safe.** A shed document that later re-enters a build (because it
- * is relinked as an affected dependent, re-validated, or edited) is re-parsed
- * first by `HydraniumDocumentBuilder.resetToState`
- * ("rehydrate-on-re-entry"), which rebuilds the CST and every `$refNode`. That
+ * **Re-entry is safe.** A shed document that later re-enters a build has its
+ * CST and every `$refNode` grafted back first ("rehydrate-on-re-entry"),
+ * keeping its AST nodes so dependents outside the build stay linked to them.
+ * `HydraniumDocumentBuilder.rehydrateShedDocuments` grafts a document that is
+ * relinked or re-validated, before the build's phases, and
+ * `HydraniumLangiumDocumentFactory.update` one reset to `Changed` whose text
+ * has not changed. An edited document is re-parsed, and so is one whose graft
+ * is refused or diverges, and a build after it relinks its dependents. That
  * matters because Langium derives the reference index — and thus
- * `IndexManager.isAffected` and the `segment` used by rename / find-references —
- * from `$refNode`; without rehydration a re-index would silently drop the
- * document's cross-references and its dependents would stop being relinked.
+ * `IndexManager.isAffected` and the `segment` used by rename /
+ * find-references — from `$refNode`. Without rehydration a re-index would
+ * silently drop the document's cross-references, and it would no longer be
+ * relinked when its targets change.
  *
  * Constructed with `(services, options)` and self-registers a `Validated`
- * `BuildPhasePass`, which
- * is why the framework constructs it eagerly — the pass must be registered before
- * the first build. Shedding itself is opt-in: the bound default strategy is
- * `always-keep`, so the pass runs and sheds nothing until an adopter rebinds the
- * slot with a shedding strategy.
+ * `BuildPhasePass`, which is why the framework constructs it eagerly — the pass
+ * must be registered before the first build. Shedding itself is opt-in: the
+ * bound default strategy is `always-keep`, so the pass runs and sheds nothing
+ * until an adopter rebinds the slot with a shedding strategy.
  *
  * **Read-side navigation under a shedding strategy.** Read-only LSP requests do
  * not run a build, so they do not trigger the build-side rehydrate. Features that
@@ -126,21 +138,20 @@ export declare function isCstShed(document: LangiumDocument): boolean;
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
  * `HydraniumLangiumDocuments.getOrCreateDocument`.
  */
-/**
- * Keeps a document's CST available to the readers that need one, shedding it
- * for documents that have gone idle and re-grafting on demand.
- */
 export interface CstResidencyService {
     /**
-     * Ensure `document` has a CST, re-parsing its retained text if it was shed.
-     * A resident document is left exactly as it is, so this is safe to call on
-     * a hot path and safe to call twice.
+     * Ensure `document` has a CST, re-parsing its retained text if it was shed
+     * and that text is the one its AST was parsed from. A resident document is
+     * left exactly as it is, so this is safe to call on a hot path and safe to
+     * call twice. A document whose graft diverged is not attempted again on the
+     * same text.
      */
     rehydrate(document: LangiumDocument): void;
     /**
      * Node-level convenience over {@link rehydrate}, cheap enough for an
      * unconditional call: a node whose `$cstNode` is already set returns
-     * without resolving its document.
+     * without resolving its document, and a node outside any document, such as
+     * a detached synthetic node, has nothing to restore and returns too.
      */
     rehydrateNode(node: AstNode): void;
 }
@@ -161,12 +172,20 @@ export declare class DefaultCstResidencyService implements CstResidencyService {
      * cycles, and all cancelled by {@link dispose}.
      */
     protected readonly idleTimers: Map<string, Debouncer>;
+    /**
+     * The text each document's graft diverged on. Until its text changes, the
+     * document is not shed again: an AST the build keeps mutating away from its
+     * text would otherwise cost a graft, a re-parse and a build on every
+     * re-entry. Keyed by document, because the re-parse after a divergence
+     * replaces the root.
+     */
+    protected readonly diverged: WeakMap<LangiumDocument<AstNode>, string>;
     protected shedTotal: number;
     constructor(services: ServerSharedServicesMinimal, options?: CstResidencyOptions);
     /**
      * Restore `document`'s shed CST on demand — the ergonomic entry point over
-     * {@link rehydrateCst} (resolves the document factory itself). No-op `true`
-     * when the CST is resident, so read-side seams call it unconditionally.
+     * {@link rehydrateCst} (resolves the document factory itself). A no-op when
+     * the CST is resident, so read-side seams call it unconditionally.
      *
      * **Residency note (deliberate).** Rehydration does NOT count as a "use" for
      * the `shed-closed-when-idle` idle timer (which is refreshed only by build
@@ -181,7 +200,7 @@ export declare class DefaultCstResidencyService implements CstResidencyService {
     /**
      * Node-level convenience over {@link rehydrate}: a resident node (its
      * `$cstNode` is set — true for every node of a non-shed document) returns
-     * `true` without even resolving the document, so hot read paths
+     * without even resolving the document, so hot read paths
      * (`getNameNode`, comment lookup) call this unconditionally.
      */
     rehydrateNode(node: AstNode): void;
@@ -206,18 +225,36 @@ export declare class DefaultCstResidencyService implements CstResidencyService {
      * Idle-timer fire: shed the document's CST if it is still closed and resident.
      * Re-checks open-state (a reopen within the window cancels the timer, but guard
      * anyway) and resolves the current document by URI (it may have been deleted,
-     * or its object replaced by a rebuild).
+     * or its object replaced by a rebuild). Re-checks {@link canShed} and
+     * {@link isSheddable} too. The timer was armed by an earlier build, and the
+     * document may since be mid-rebuild or have gained an unresolved reference
+     * in a cancelled build.
      */
     protected onIdle(uri: string): void;
     /** Cancel every armed shed, so a document that has gone idle keeps its CST. */
     cancelPendingShed(): void;
+    /** Whether `document`'s graft diverged on the text its root was parsed from. */
+    protected hasDiverged(document: LangiumDocument): boolean;
+    /**
+     * Whether `document` can be shed without losing its AST identity or its
+     * references. Only a `Validated` document qualifies: the idle timer can fire
+     * while a build waits between documents, and a build that indexes a
+     * document's references without their CST drops them from the reference
+     * index. Its root needs a recorded version, because `shed` then records no
+     * text and the graft refuses it. A document whose graft diverged on its
+     * current text would cost a parse on every re-entry. Checked before
+     * {@link isSheddable}, so an override of that policy keeps these guards.
+     */
+    protected canShed(document: LangiumDocument): boolean;
     /**
      * Whether a closed document may have its CST shed. Only documents whose text
-     * a re-parse on re-entry can recover are sheddable; the default admits
-     * `file`-scheme documents (re-read from disk) and excludes synthetic / in-memory
-     * documents — e.g. built-in definitions registered under a custom URI scheme —
-     * whose text lives only in the CST and would be lost irrecoverably (a later
-     * relink would `readFile` a non-existent path). Adopters override to refine.
+     * a re-parse can recover are sheddable, because a re-entry whose graft
+     * diverges re-parses from disk. The default admits `file`-scheme documents
+     * and excludes synthetic / in-memory documents — e.g. built-in definitions
+     * registered under a custom URI scheme — for which that re-parse would
+     * `readFile` a non-existent path. A document with an unresolved
+     * reference stays resident too: Langium relinks it on every update, so a shed
+     * would only buy a re-graft each time. Adopters override to refine.
      */
     protected isSheddable(document: LangiumDocument): boolean;
     /**

package/lib/langium/residency/cst-residency-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cst-residency-service.d.ts","sourceRoot":"","sources":["../../../src/langium/residency/cst-residency-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cst-residency-service.d.ts","sourceRoot":"","sources":["../../../src/langium/residency/cst-residency-service.ts"],"names":[],"mappings":"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"}

package/lib/langium/residency/cst-residency-service.js

@@ -6,8 +6,8 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { asMutable, Debouncer, Format } from '@hydranium/protocol';
-import { AstUtils, DocumentState, URI } from '@hydranium/langium';
+import { asMutable, Debouncer, Format, UNRECORDED_VERSION } from '@hydranium/protocol';
+import { AstUtils, DocumentState, isAstNode, isMultiReference, isReference, URI } from '@hydranium/langium';
 /**
  * Default priority of the CST-residency pass. Deliberately very high so it runs
  * *last* among `Validated` build-phase passes (the registry iterates priority
@@ -21,13 +21,14 @@ import { AstUtils, DocumentState, URI } from '@hydranium/langium';
  */
 export const CST_RESIDENCY_PASS_PRIORITY = 1_000_000;
 /**
- * The build state a shed document must be reset to so the next build re-parses it
- * and rebuilds its CST — and every `reference.$refNode` — before it is relinked or
- * re-indexed (rehydration). It is `DocumentState.Changed` by necessity: the only
- * state below `Parsed`, hence the only one that forces a re-parse rather than an
- * in-place relink. Exposed as a named landmark of the residency feature (cf.
- * `IntegrityService.SettledState`) so the document builder references the feature's
- * declared recovery contract instead of a bare enum value.
+ * The build state a shed document is reset to when the identity-preserving graft
+ * fails, so the next build re-parses it and rebuilds its CST — and every
+ * `reference.$refNode` — before it is relinked or re-indexed. It is
+ * `DocumentState.Changed` by necessity: the only state below `Parsed`, hence
+ * the only one that forces a re-parse rather than an in-place relink. Exposed
+ * as a named landmark of the residency feature (cf.
+ * `IntegrityService.SettledState`) so the document builder references the
+ * feature's declared recovery contract instead of a bare enum value.
  */
 export const CST_REHYDRATION_RESET_STATE = DocumentState.Changed;
 /**
@@ -44,8 +45,8 @@ export function isCstShed(document) {
         document.parseResult.value.$cstNode === undefined);
 }
 /**
- * Reattach a CST to a shed document **on demand**, without a rebuild — the
- * read-side counterpart of the build-side rehydrate-on-re-entry seam. Re-parses
+ * Reattach a CST to a shed document **on demand**, without a rebuild. Both the
+ * read side and the build-side rehydrate-on-re-entry seam use it. Re-parses
  * the document's retained text into a throwaway document, then **grafts** the
  * fresh CST onto the already-built, resident AST nodes — preserving AST node
  * identity, so every cross-reference *into* this document (resolved to a resident
@@ -72,10 +73,12 @@ export function isCstShed(document) {
  * `reference.$refNode` is restored the same way (paired over
  * {@link AstUtils.streamReferences}).
  *
- * **Safe degrade.** If the re-parse diverges structurally from the resident AST
- * (different node count — should not happen for unchanged text, but a guard
- * against drift) the graft is abandoned and the document stays shed; the caller
- * degrades exactly as it did before (no wrong attachment).
+ * **Safe degrade.** If the re-parse diverges from the resident AST (a
+ * different node count, or a different type, container slot, reference slots
+ * or grammar value on any node — should not happen for unchanged text, but a
+ * guard against an AST changed in place) the graft is abandoned before any
+ * write and the document stays shed. A read-side caller degrades as it did
+ * before (no wrong attachment), and the build re-parses.
  *
  * **Module-private mechanism.** The public entry points are
  * {@link CstResidencyService.rehydrateNode} / {@link CstResidencyService.rehydrate},
@@ -87,7 +90,7 @@ export function isCstShed(document) {
  * @returns `true` if the document now has a resident CST (already-resident is a
  * no-op `true`); `false` if the text is unrecoverable or the re-parse diverged.
  */
-function rehydrateCst(document, factory) {
+function rehydrateCst(document, factory, reflection) {
     const root = document.parseResult?.value;
     if (root === undefined) {
         return false;
@@ -103,9 +106,27 @@ function rehydrateCst(document, factory) {
     const fresh = factory.fromString(text, document.uri);
     const existingNodes = [...AstUtils.streamAst(root)];
     const freshNodes = [...AstUtils.streamAst(fresh.parseResult.value)];
-    if (existingNodes.length !== freshNodes.length) {
+    // Pre-order follows property order, so a property re-added in place would
+    // pair siblings of one type crosswise. Their container slots tell them
+    // apart, and their grammar values tell apart siblings that traded slots too.
+    const pairsDiffer = (node, freshNode) => node.$type !== freshNode.$type ||
+        node.$containerProperty !== freshNode.$containerProperty ||
+        node.$containerIndex !== freshNode.$containerIndex ||
+        Object.keys(reflection.getTypeMetaData(node.$type).properties).some(property => !sameGrammarValue(Reflect.get(node, property), Reflect.get(freshNode, property)));
+    if (existingNodes.length !== freshNodes.length || existingNodes.some((node, index) => pairsDiffer(node, freshNodes[index]))) {
         return false; // structural divergence — stay shed rather than mis-attach
     }
+    // `streamReferences` yields a node's *own* cross-references only (not its
+    // descendants'), in property enumeration order, which a property re-added
+    // in place changes. So each pair must hold one property and array index.
+    // Checked before any write, so a divergence leaves the document shed rather
+    // than half grafted.
+    const residentRefs = existingNodes.map(node => [...AstUtils.streamReferences(node)]);
+    const freshRefs = freshNodes.map(node => [...AstUtils.streamReferences(node)]);
+    const refsDiffer = (refs, fresh) => refs.length !== fresh.length || refs.some((ref, index) => ref.property !== fresh[index].property || ref.index !== fresh[index].index);
+    if (residentRefs.some((refs, index) => refsDiffer(refs, freshRefs[index]))) {
+        return false;
+    }
     for (let index = 0; index < existingNodes.length; index++) {
         const residentNode = existingNodes[index];
         const freshNode = freshNodes[index];
@@ -117,20 +138,39 @@ function rehydrateCst(document, factory) {
             // at the resident node so CST→AST navigation reaches the linked AST.
             asMutable(freshCst).astNode = residentNode;
         }
-        // Restore each reference's `$refNode` from the fresh parse. `streamReferences`
-        // yields a node's *own* cross-references only (not its descendants'), so this
-        // must run per node — paired by the stable key/array order a re-parse of the
-        // same text reproduces. The resolved `.ref` link is untouched (still resident).
-        const residentRefs = [...AstUtils.streamReferences(residentNode)];
-        const freshRefs = [...AstUtils.streamReferences(freshNode)];
-        if (residentRefs.length === freshRefs.length) {
-            for (let refIndex = 0; refIndex < residentRefs.length; refIndex++) {
-                asMutable(residentRefs[refIndex].reference).$refNode = freshRefs[refIndex].reference.$refNode;
-            }
-        }
+        // Restore each reference's `$refNode` from the fresh parse. The resolved
+        // `.ref` link is untouched (still resident).
+        residentRefs[index].forEach((resident, refIndex) => {
+            asMutable(resident.reference).$refNode = freshRefs[index][refIndex].reference.$refNode;
+        });
     }
     return true;
 }
+/**
+ * Whether two values of one grammar property match. Child nodes are paired on
+ * their own, so a reference counts by its text. A converter's `Date` counts by
+ * its time, and any other object as equal, since its equality is unknown.
+ */
+function sameGrammarValue(value, freshValue) {
+    if (Array.isArray(value)) {
+        return (Array.isArray(freshValue) &&
+            value.length === freshValue.length &&
+            value.every((item, index) => sameGrammarValue(item, freshValue[index])));
+    }
+    if (isReference(value) || isMultiReference(value)) {
+        return (isReference(freshValue) || isMultiReference(freshValue)) && value.$refText === freshValue.$refText;
+    }
+    if (isAstNode(value)) {
+        return isAstNode(freshValue);
+    }
+    if (value instanceof Date) {
+        return freshValue instanceof Date && value.getTime() === freshValue.getTime();
+    }
+    if (typeof value === 'object' && value !== null) {
+        return typeof freshValue === 'object' && freshValue !== null;
+    }
+    return Object.is(value, freshValue);
+}
 export class DefaultCstResidencyService {
     services;
     strategy;
@@ -148,6 +188,14 @@ export class DefaultCstResidencyService {
      * cycles, and all cancelled by {@link dispose}.
      */
     idleTimers = new Map();
+    /**
+     * The text each document's graft diverged on. Until its text changes, the
+     * document is not shed again: an AST the build keeps mutating away from its
+     * text would otherwise cost a graft, a re-parse and a build on every
+     * re-entry. Keyed by document, because the re-parse after a divergence
+     * replaces the root.
+     */
+    diverged = new WeakMap();
     shedTotal = 0;
     constructor(services, options = {}) {
         this.services = services;
@@ -159,15 +207,15 @@ export class DefaultCstResidencyService {
         this.langiumDocs = services.workspace.LangiumDocuments;
         services.workspace.BuildPhasePassService.register({
             id: 'framework:cst-residency:shed',
-            state: DocumentState.Validated,
+            phase: DocumentState.Validated,
             priority: options.priority ?? CST_RESIDENCY_PASS_PRIORITY,
             run: documents => this.onBuild(documents)
         });
     }
     /**
      * Restore `document`'s shed CST on demand — the ergonomic entry point over
-     * {@link rehydrateCst} (resolves the document factory itself). No-op `true`
-     * when the CST is resident, so read-side seams call it unconditionally.
+     * {@link rehydrateCst} (resolves the document factory itself). A no-op when
+     * the CST is resident, so read-side seams call it unconditionally.
      *
      * **Residency note (deliberate).** Rehydration does NOT count as a "use" for
      * the `shed-closed-when-idle` idle timer (which is refreshed only by build
@@ -179,19 +227,36 @@ export class DefaultCstResidencyService {
      * method is where that hook goes.
      */
     rehydrate(document) {
-        rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
+        const root = document.parseResult?.value;
+        // A graft from other text would attach its CST to nodes it does not
+        // describe. `shed` records the text the AST was parsed from.
+        // A diverged graft diverges again on the same text, so it is not parsed twice.
+        const parsedFrom = root === undefined ? undefined : this.services.workspace.ModelLedger.textOf(root);
+        if (root === undefined ||
+            root.$cstNode !== undefined ||
+            parsedFrom === undefined ||
+            parsedFrom !== document.textDocument?.getText() ||
+            this.hasDiverged(document)) {
+            return;
+        }
+        if (!rehydrateCst(document, this.services.workspace.LangiumDocumentFactory, this.services.AstReflection)) {
+            this.diverged.set(document, parsedFrom);
+        }
     }
     /**
      * Node-level convenience over {@link rehydrate}: a resident node (its
      * `$cstNode` is set — true for every node of a non-shed document) returns
-     * `true` without even resolving the document, so hot read paths
+     * without even resolving the document, so hot read paths
      * (`getNameNode`, comment lookup) call this unconditionally.
      */
     rehydrateNode(node) {
         if (node.$cstNode !== undefined) {
             return;
         }
-        this.rehydrate(AstUtils.getDocument(node));
+        const document = AstUtils.findRootNode(node).$document;
+        if (document) {
+            this.rehydrate(document);
+        }
     }
     /**
      * After each build, refresh the idle timer of every document in the batch: an
@@ -208,13 +273,10 @@ export class DefaultCstResidencyService {
         }
         for (const document of documents) {
             const uri = document.uri.toString();
-            if (this.textDocuments.isOpenInAnyClient(uri)) {
+            if (this.textDocuments.isOpenInAnyClient(uri) || !this.canShed(document) || !this.isSheddable(document)) {
                 this.idleTimers.get(uri)?.cancel();
                 continue;
             }
-            if (!this.isSheddable(document)) {
-                continue;
-            }
             this.idleTimerFor(uri).schedule();
         }
     }
@@ -237,14 +299,17 @@ export class DefaultCstResidencyService {
      * Idle-timer fire: shed the document's CST if it is still closed and resident.
      * Re-checks open-state (a reopen within the window cancels the timer, but guard
      * anyway) and resolves the current document by URI (it may have been deleted,
-     * or its object replaced by a rebuild).
+     * or its object replaced by a rebuild). Re-checks {@link canShed} and
+     * {@link isSheddable} too. The timer was armed by an earlier build, and the
+     * document may since be mid-rebuild or have gained an unresolved reference
+     * in a cancelled build.
      */
     onIdle(uri) {
         if (this.textDocuments.isOpenInAnyClient(uri)) {
             return;
         }
         const document = this.langiumDocs.getDocument(URI.parse(uri));
-        if (document === undefined) {
+        if (document === undefined || !this.canShed(document) || !this.isSheddable(document)) {
             return;
         }
         this.shedTotal += this.shed(document);
@@ -256,16 +321,38 @@ export class DefaultCstResidencyService {
         }
         this.idleTimers.clear();
     }
+    /** Whether `document`'s graft diverged on the text its root was parsed from. */
+    hasDiverged(document) {
+        const text = this.diverged.get(document);
+        return text !== undefined && text === this.services.workspace.ModelLedger.textOf(document.parseResult.value);
+    }
+    /**
+     * Whether `document` can be shed without losing its AST identity or its
+     * references. Only a `Validated` document qualifies: the idle timer can fire
+     * while a build waits between documents, and a build that indexes a
+     * document's references without their CST drops them from the reference
+     * index. Its root needs a recorded version, because `shed` then records no
+     * text and the graft refuses it. A document whose graft diverged on its
+     * current text would cost a parse on every re-entry. Checked before
+     * {@link isSheddable}, so an override of that policy keeps these guards.
+     */
+    canShed(document) {
+        return (document.state === DocumentState.Validated &&
+            !this.hasDiverged(document) &&
+            this.services.workspace.ModelLedger.versionOf(document.parseResult.value) !== UNRECORDED_VERSION);
+    }
     /**
      * Whether a closed document may have its CST shed. Only documents whose text
-     * a re-parse on re-entry can recover are sheddable; the default admits
-     * `file`-scheme documents (re-read from disk) and excludes synthetic / in-memory
-     * documents — e.g. built-in definitions registered under a custom URI scheme —
-     * whose text lives only in the CST and would be lost irrecoverably (a later
-     * relink would `readFile` a non-existent path). Adopters override to refine.
+     * a re-parse can recover are sheddable, because a re-entry whose graft
+     * diverges re-parses from disk. The default admits `file`-scheme documents
+     * and excludes synthetic / in-memory documents — e.g. built-in definitions
+     * registered under a custom URI scheme — for which that re-parse would
+     * `readFile` a non-existent path. A document with an unresolved
+     * reference stays resident too: Langium relinks it on every update, so a shed
+     * would only buy a re-graft each time. Adopters override to refine.
      */
     isSheddable(document) {
-        return document.uri.scheme === 'file';
+        return document.uri.scheme === 'file' && !document.references.some(reference => reference.error !== undefined);
     }
     /**
      * Shed one document's CST: null every AST node's `$cstNode` and every
@@ -277,6 +364,15 @@ export class DefaultCstResidencyService {
         if (root === undefined || root.$cstNode === undefined) {
             return 0;
         }
+        // Readers of the parsed text, the `'text-diagnostics'` fingerprint among
+        // them, otherwise see none once the CST is gone. Recorded in the ledger
+        // directly: no root is produced, and reconciling it with the store would
+        // step a closed document's sequence for a root behind its text.
+        const ledger = this.services.workspace.ModelLedger;
+        const version = ledger.versionOf(root);
+        if (version !== UNRECORDED_VERSION) {
+            ledger.record(root, version, ledger.textOf(root));
+        }
         let cleared = 0;
         for (const node of AstUtils.streamAst(root)) {
             if (node.$cstNode) {