@hydranium/core 1.0.0-next.39 → 1.0.0-next.391

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

@@ -9,6 +9,7 @@
 import { type Clock, Debouncer, type Tracer } from '@hydranium/protocol';
 import { type AstNode, DocumentState, type LangiumDocument, type LangiumDocuments } from '@hydranium/langium';
 import { type HydraniumTextDocuments } from '../../documents/hydranium-text-documents.js';
+import { type ModelLedger } from '../../documents/model-ledger.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
@@ -34,8 +35,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,31 +66,36 @@ 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;
 /**
- * Whether `document`'s CST has been shed by a residency policy: the AST root is
- * resident but its `$cstNode` was nulled. The built-state and present-root guards
- * exclude the `fromModel` INVALID placeholder and not-yet-parsed documents, which
- * legitimately have no CST. The single definition of "shed", shared by
- * {@link CstResidencyService} and the document builder's rehydrate-on-re-entry
- * seam so the two cannot drift.
+ * Whether `document` has a resident AST without a CST, and `ledger` holds the
+ * text to graft one from. That text is the one a residency policy recorded when
+ * it shed the CST, or the serialized text of a `fromModel` document. A
+ * not-yet-parsed document has no CST to graft, and nor has a `fromModel`
+ * document without a serializer. The single definition of "shed", shared by the
+ * document builder's rehydrate-on-re-entry seam and the server-state snapshot
+ * so the two cannot drift.
  */
-export declare function isCstShed(document: LangiumDocument): boolean;
+export declare function isCstShed(document: LangiumDocument, ledger: ModelLedger): 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 +105,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 +140,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 +174,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 +202,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,24 +227,43 @@ 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, since without one the ledger
+     * keeps no text to graft the CST back from, and `shed` refuses it for a
+     * caller that skips this check. 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;
     /**
      * Shed one document's CST: null every AST node's `$cstNode` and every
      * reference's `$refNode`. Returns the number of `$cstNode`s cleared (0 if the
-     * document is unparsed or already shed).
+     * document is unparsed, already shed, or has no recorded version).
      */
     protected shed(document: LangiumDocument): number;
     /**

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":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAa,KAAK,KAAK,EAAE,SAAS,EAAU,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EACJ,KAAK,OAAO,EAEZ,aAAa,EACb,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EAEvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,UAAY,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1I,4DAA4D;AAC5D,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACxD,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IACzC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,aAAqC,CAAC;AAEhF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAM5D;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACjC;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAE3C;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,qBAAa,0BAA2B,YAAW,mBAAmB;IAmBhE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAlB3D,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IAClD,mFAAmF;IACnF,SAAS,CAAC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IACrD,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAChC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACjD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,yBAAgC;IAC7D,SAAS,CAAC,SAAS,SAAK;gBAGF,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,mBAAwB;IAgBpC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI1C;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAOlC;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI;IAiB9D;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAU9C;;;;;OAKG;IACH,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAWnC,+EAA+E;IAC/E,iBAAiB,IAAI,IAAI;IAOzB;;;;;;;OAOG;IACH,SAAS,CAAC,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAIzD;;;;OAIG;IACH,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM;IAuBjD;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAGrD"}
+{"version":3,"file":"cst-residency-service.d.ts","sourceRoot":"","sources":["../../../src/langium/residency/cst-residency-service.ts"],"names":[],"mappings":"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"}