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

package/lib/langium/integrity/integrity-service.js

@@ -6,9 +6,12 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { isPromiseLike, Logger } from '@hydranium/protocol';
-import { AstUtils, DocumentState, interruptAndCheck, UriUtils } from '@hydranium/langium';
+import { describeErrorWithStack, isPromiseLike, Logger, textHash } from '@hydranium/protocol';
+import { AstUtils, DocumentState, interruptAndCheck, isMultiReference, isOperationCancelled, UriUtils } from '@hydranium/langium';
+import { CancellationToken } from 'vscode-languageserver';
 import { Registry } from '../../util/registry.js';
+import { hasSkippedText } from '../workspace/syntax-errors.js';
+import { isVirtualUri } from '../workspace/virtual-document.js';
 import { IntegrityPhase } from './integrity-rule.js';
 export var IntegrityService;
 (function (IntegrityService) {
@@ -23,11 +26,21 @@ export var IntegrityService;
      * at `DocumentState.Validated` and delivered separately via `publishDiagnostics`
      * or the `onModelUpdated` event.
      *
+     * A document whose parse lacks some of its text reaches this state
+     * unrepaired: no rule runs on it until it parses.
+     *
      * The AST is what this guarantees, not the text. For a closed document whose
      * repair was STAGED rather than written (`'editor'` sync mode),
      * `textDocument` still mirrors disk — read the repair off the AST, or from
      * the staged content the next open consumes.
      *
+     * A `Linked`-phase repair settles the documents that reference the repaired
+     * one in the same build against what the repair replaced. A build after it
+     * relinks them, and they settle again. Past `maxRelinkChain` such builds in
+     * a row they keep stale links. A closed `'editor'` document whose CST was
+     * shed re-reads its unrepaired text in that build and repeats the repair,
+     * so they resolve a renamed element by its old name until the next change.
+     *
      * Invariant: integrity rules only register at Parsed or Linked, so the build
      * is guaranteed post-integrity once it advances past `onBuildPhase(Linked)`
      * into `IndexedReferences`. {@link IntegrityService.register} enforces this at
@@ -36,6 +49,15 @@ export var IntegrityService;
      */
     IntegrityService.SettledState = DocumentState.IndexedReferences;
 })(IntegrityService || (IntegrityService = {}));
+/**
+ * The shared services of each server that has logged its first silent
+ * write-back. Every language of a server holds the same shared services, so
+ * keying on them makes {@link DefaultIntegrityService.noteSilentWrite} report once
+ * per server rather than once per language.
+ */
+const silentWriteReported = new WeakSet();
+/** The running builds that relink dependents, per server, because a repair in one language can extend a chain in another. */
+const runningRelinksByServer = new WeakMap();
 /**
  * Default {@link IntegrityService} implementation. Enforces rules,
  * resyncs document text after mutations, and propagates corrections.
@@ -60,13 +82,14 @@ export class DefaultIntegrityService {
     /** One logger per rule, created at registration and dropped on unregister. */
     ruleLoggers = new Map();
     /**
-     * Rules bucketed by the phase they target, preserving the registry's
-     * priority order within each bucket. Rebuilt lazily on the first
-     * `enforceIntegrity` call after a registry mutation — staleness is detected
-     * via reference identity of the registry's cached array (see
-     * {@link Registry.all}). Filtering the rule list per call would instead
-     * allocate one transient array per document per phase, which a workspace
-     * whose documents all settle at the same phase pays on every build.
+     * Rules bucketed by the phase they target, then by each `$type` from
+     * {@link nodeTypesFor}, preserving the registry's priority order within
+     * each bucket. Rebuilt lazily on the first `enforceIntegrity` call after a
+     * registry mutation — staleness is detected via reference identity of the
+     * registry's cached array (see {@link Registry.all}). Filtering the rule
+     * list per call would instead allocate one transient array per document per
+     * phase, which a workspace whose documents all settle at the same phase pays
+     * on every build.
      */
     phaseBuckets = new Map();
     phaseBucketsFor;
@@ -77,11 +100,28 @@ export class DefaultIntegrityService {
     tracer;
     /**
      * The framework document builder, used to re-parse + re-link a document in place after a
-     * Linked-phase correction (see {@link resyncDocument}). The framework binds
-     * `shared.workspace.DocumentBuilder` to {@link HydraniumDocumentBuilder}; the narrowing
-     * cast surfaces its single-document phase runner.
+     * Linked-phase correction (see {@link resyncDocument}).
      */
     documentBuilder;
+    /** Each document's {@link DependentRelink}, from its request until it settles. See {@link relinkDependents}. */
+    relinkBuilds = new WeakMap();
+    /** The {@link replayKey} of the latest repair of each document that {@link stagesRepairs}, with the hash of the text it came from. */
+    replayKeys = new WeakMap();
+    /** The relinks the check inside the lock found needed, until their build starts. */
+    scheduledRelinks = new WeakSet();
+    /** The relinks of every language whose build runs, from its start until it settles or the next build starts. */
+    runningRelinks;
+    /** The rules of a repair while a relink's build waited or ran. Only one while it ran gets the next build in the chain. */
+    repairedAgain = new WeakMap();
+    /**
+     * Marks {@link scheduledRelinks} running as their builds start. Set on the
+     * first request only so it subscribes once, and never disposed.
+     */
+    relinkStarts;
+    /** See {@link IntegrityServiceOptions.maxRelinkChain}. */
+    maxRelinkChain;
+    /** The rules that mutated each document in its latest `Linked`-phase {@link enforceIntegrity} pass, so a warning can name them. */
+    mutatingRules = new WeakMap();
     constructor(services, options = {}) {
         this.services = services;
         this.textDocuments = services.shared.workspace.TextDocuments;
@@ -89,6 +129,12 @@ export class DefaultIntegrityService {
         this.tracer = services.shared.Tracer.for(options.logName ?? 'Integrity').trace('instantiated');
         this.documentBuilder = services.shared.workspace.DocumentBuilder;
         this.syncMode = options.syncMode ?? 'silent';
+        this.maxRelinkChain = options.maxRelinkChain ?? 3;
+        if (!Number.isInteger(this.maxRelinkChain) || this.maxRelinkChain < 1) {
+            throw new RangeError(`The integrity service's maxRelinkChain option must be an integer of at least 1, not ${this.maxRelinkChain}.`);
+        }
+        this.runningRelinks = runningRelinksByServer.get(services.shared) ?? new Set();
+        runningRelinksByServer.set(services.shared, this.runningRelinks);
         // Read the language's IntegrityRuleContribution group and let each
         // contribution register one or many rules through this service (the
         // declarative path; equivalent to imperative `register(rule)` calls).
@@ -114,24 +160,35 @@ export class DefaultIntegrityService {
      * rule set to completion against a doomed build.
      */
     async enforceBatch(documents, phase, cancelToken) {
-        const phaseStart = performance.now();
+        const sincePhaseStart = this.services.shared.Clock.stopwatch();
         let mutatedCount = 0;
         // Per-rule self-time profiling is opt-in: only spin up a session when the
         // debug threshold is active, so the production `info` path allocates
         // nothing and the hot rule loop stays a single const-branch off `session`.
         const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`integrity ${DocumentState[phase]}`) : undefined;
+        // Before any skip or cancel, so text with parse errors also ends a replay.
+        for (const document of documents) {
+            this.forgetReplayOfOtherText(document);
+        }
         for (const document of documents) {
-            const changed = await this.enforceIntegrity(document, phase, cancelToken, session);
-            if (changed) {
+            if (this.isStructurallyBroken(document)) {
+                this.tracer.with(document.uri.toString()).debug('Parse errors: rules skipped until the document parses');
+            }
+            else if (await this.enforceIntegrity(document, phase, cancelToken, session)) {
                 mutatedCount++;
-                await this.resyncDocument(document, cancelToken);
+                // Not cancellable: see `resyncDocument`.
+                await this.resyncDocument(document, CancellationToken.None);
             }
             await interruptAndCheck(cancelToken);
         }
-        const totalMs = Math.round(performance.now() - phaseStart);
-        if (totalMs >= 25 || mutatedCount > 0) {
+        const totalMs = Math.round(sincePhaseStart.elapsedMs);
+        // A repair is the operator's to know of; the timing alone is diagnosis.
+        if (mutatedCount > 0) {
             this.tracer.info(`enforce ${DocumentState[phase]}: docs=${documents.length}, mutated=${mutatedCount} [${totalMs}ms]`);
         }
+        else if (totalMs >= 25) {
+            this.tracer.debug(`enforce ${DocumentState[phase]}: docs=${documents.length}, mutated=${mutatedCount} [${totalMs}ms]`);
+        }
         // One line per rule (count + self-% + self-ms), sorted by cost — only when profiling.
         session?.report('debug');
     }
@@ -146,6 +203,12 @@ export class DefaultIntegrityService {
                 'Allowed phases are Parsed and Linked.');
         }
         const disposable = this.rules.register(rule);
+        // No parsed node carries a type the reflection does not know, so such a
+        // rule never runs. A warning, not a throw: a test reflection may omit the type.
+        if (!this.services.shared.AstReflection.getAllTypes().includes(rule.nodeType)) {
+            this.tracer.warn(`Integrity rule '${this.formatRule(rule)}' is keyed on node type '${rule.nodeType}', ` +
+                'which the AST reflection does not know, so no parsed node matches it.');
+        }
         this.ruleLoggers.set(rule.id, this.tracer.sub(IntegrityPhase.toString(rule.phase)).sub(rule.label ?? rule.id));
         return {
             dispose: () => {
@@ -162,6 +225,14 @@ export class DefaultIntegrityService {
         }
         return removed;
     }
+    /**
+     * Seam: does the parse of `document` lack some of its text? {@link enforceBatch}
+     * runs no rule on such a document, because a repair is written back by
+     * serializing the AST, and a recovered AST lacks what the parser skipped.
+     */
+    isStructurallyBroken(document) {
+        return hasSkippedText(document);
+    }
     /**
      * Run all rules for the given phase against matching AST nodes. Returns
      * `true` if any rule mutated the AST.
@@ -180,37 +251,58 @@ export class DefaultIntegrityService {
      * full rule sweep) — coarser than per (node × rule) to avoid a microtask
      * per inner iteration, finer than per-document so a long-running rule set
      * on a large file can still interrupt mid-stream. Throws
-     * `OperationCancelled` when the token is cancelled; Langium's build
-     * pipeline absorbs the throw at the lock-holder.
+     * `OperationCancelled` when the token is cancelled before any rule mutated
+     * the AST; Langium's build pipeline absorbs the throw at the lock-holder.
+     * After a mutation it stops the sweep and returns `true` instead, so the
+     * caller can resync what was mutated before the cancellation unwinds.
      */
     async enforceIntegrity(document, phase, cancelToken, session) {
         if (cancelToken?.isCancellationRequested) {
             return false;
         }
         let changed = false;
-        const rulesForPhase = this.getPhaseBucket(phase);
-        if (rulesForPhase.length === 0) {
+        const rulesByType = this.getPhaseBucket(phase);
+        if (rulesByType.size === 0) {
             return false;
         }
+        // Read only after a Linked-phase repair. Cleared when such a pass starts, so
+        // one that records nothing leaves no older record to be named in its place.
+        const recorded = phase > DocumentState.Parsed;
+        if (recorded) {
+            this.mutatingRules.delete(document);
+        }
+        let mutating;
         const relativeUri = this.services.shared.workspace.WorkspaceManager.wsRelativePath(document.uri);
         for (const node of AstUtils.streamAst(document.parseResult.value)) {
-            for (const rule of rulesForPhase) {
-                if (node.$type === rule.nodeType) {
-                    const ruleLogger = this.ruleLoggers.get(rule.id).with(relativeUri);
-                    // Scope per rule so the session aggregates self-time by rule id across all
-                    // nodes; off the profiling path `session` is undefined and we call directly.
-                    const enforced = session
-                        ? session.scope(rule.id, () => rule.enforce(node, document, ruleLogger))
-                        : rule.enforce(node, document, ruleLogger);
-                    const mutated = isPromiseLike(enforced) ? await enforced : enforced;
-                    if (mutated) {
-                        ruleLogger.trace(`[${relativeUri}] Mutated ${this.formatNode(node)}`);
+            for (const rule of rulesByType.get(node.$type) ?? NO_RULES) {
+                const ruleLogger = this.ruleLoggers.get(rule.id).with(relativeUri);
+                // Scope per rule so the session aggregates self-time by rule id across all
+                // nodes; off the profiling path `session` is undefined and we call directly.
+                const enforced = session
+                    ? session.scope(rule.id, () => rule.enforce(node, document, ruleLogger))
+                    : rule.enforce(node, document, ruleLogger);
+                const mutated = isPromiseLike(enforced) ? await enforced : enforced;
+                if (mutated) {
+                    if (recorded && mutating === undefined) {
+                        // Only a mutating pass leads to a read, so a pass that mutates nothing allocates nothing.
+                        mutating = new Set();
+                        this.mutatingRules.set(document, mutating);
                     }
-                    changed = mutated || changed;
+                    mutating?.add(rule);
+                    ruleLogger.trace(`[${relativeUri}] Mutated ${this.formatNode(node)}`);
                 }
+                changed = mutated || changed;
             }
             if (cancelToken !== undefined) {
-                await interruptAndCheck(cancelToken);
+                try {
+                    await interruptAndCheck(cancelToken);
+                }
+                catch (err) {
+                    if (changed && isOperationCancelled(err)) {
+                        return true;
+                    }
+                    throw err;
+                }
             }
         }
         return changed;
@@ -219,27 +311,112 @@ export class DefaultIntegrityService {
      * Re-serialise the document text after AST mutations, propagate corrections,
      * and re-parse at Parsed phase (safe because linking hasn't occurred yet).
      *
-     * `cancelToken` is checked at entry so a preempted build skips the
-     * serialise / disk-write atomic; the steps inside resync are not further
-     * subdivided because each is a single fast operation that does not yield
-     * a natural interruption point.
+     * Runs to the end whatever `cancelToken` says: the AST is already mutated,
+     * and skipping the resync leaves it against unchanged text that the next
+     * build does not re-parse. `cancelToken` reaches only the re-parse.
      */
     async resyncDocument(document, cancelToken) {
-        if (cancelToken?.isCancellationRequested) {
-            return;
-        }
         const root = document.parseResult.value;
-        const newText = await this.services.serializer.Serializer.serializeAst(root);
+        // Extracted while `document` still holds the text being replaced — the
+        // resync that follows overwrites it with `newText`. Absent on a test
+        // stub that binds no trivia group; `createServerLanguageModule` always
+        // provides it, and an empty registry is already the no-op.
+        const trivia = this.services.trivia?.TriviaService;
+        const extracted = trivia?.extract(document);
+        const serialized = await this.services.serializer.Serializer.serializeAst(root);
+        const newText = extracted === undefined ? serialized : trivia.apply(serialized, extracted, UriUtils.toUri(document.textDocument.uri));
         const oldText = document.textDocument.getText();
         if (oldText === newText) {
             return;
         }
         const version = document.textDocument.version;
-        // Keep the same version so HydraniumTextDocuments doesn't reject subsequent client edits.
-        // Use manager.update so the `instanceof FullTextDocument` gate in the bare
-        // `TextDocument.update` doesn't trip on adopter-custom text-document types.
-        const textDocument = this.textDocuments.update(document.textDocument, [{ text: newText }], version);
-        await this.syncCorrections(textDocument);
+        // Commit into the store's own document when the URI is open there, rather
+        // than into whichever text-document object this build is holding. The two
+        // are the same on the LSP path and are NOT when the document was built for
+        // an already-open URI through `fromString`: repairing only the build's copy
+        // leaves the store — the server's authority on what an open document says —
+        // on the unrepaired text, and the reconciling re-parse then redefines
+        // `textDocument` onto the store's object and discards the repair with it.
+        //
+        // Compared against the CST's own text, not against `document.textDocument`.
+        // That object IS the store's on the LSP path, so asking it whether the
+        // store still agrees compares the store with itself and can only ever say
+        // yes — the guard would be vacuous exactly where an editor race can happen.
+        // The CST's `fullText` is the text that actually produced this AST, which
+        // is the only thing a repair derived from it is valid against. A document
+        // with no CST (built from a model rather than parsed) has no better answer
+        // than the text it is carrying.
+        const parsedFrom = document.parseResult.value.$cstNode?.root.fullText ?? oldText;
+        const commit = this.textDocuments.commitRepair(document.textDocument.uri, parsedFrom, newText);
+        if (commit.status === 'stale') {
+            // An edit landed after the parse this repair came from, so the repair
+            // describes text the store has already replaced. Abandon it rather than
+            // hand it to `syncCorrections`: an override that persists from there
+            // would write a correction over the edit that superseded it. That edit
+            // drives a build of its own, which re-runs these rules against what the
+            // document actually says.
+            //
+            // Abandoning the WRITE is only half of it. The build carries on to its
+            // settled phase with whatever AST is registered, and every settled
+            // consumer reads that AST rather than the store — so leaving the rule's
+            // mutation in place would answer questions about this document from a
+            // parse of text nobody has. Reconciling discards it by re-reading the
+            // store, which is what the document now has to agree with.
+            //
+            // No dependents are relinked, because the edit's build relinks them.
+            await this.reconcileDocument(document, cancelToken);
+            return;
+        }
+        // A committed repair is a new version; a document no client has open keeps
+        // its number here, and the re-versioning below moves it once the build
+        // has reconciled. Through the store's `update`, so the `instanceof
+        // FullTextDocument` gate in the bare `TextDocument.update` does not trip
+        // on adopter-custom text-document types.
+        const textDocument = commit.status === 'committed' ? commit.document : this.textDocuments.update(document.textDocument, [{ text: newText }], version);
+        await this.syncCorrections(textDocument, parsedFrom);
+        if (document.state > DocumentState.Parsed) {
+            // Requested before the in-place relink, and an error logged, so neither skips the other.
+            try {
+                this.relinkDependents(document, { from: parsedFrom, to: newText });
+            }
+            catch (error) {
+                this.tracer
+                    .with(document.uri.toString())
+                    .error(`Relinking the dependents of a repaired document failed. ${describeErrorWithStack(error)}`);
+            }
+        }
+        await this.reconcileDocument(document, cancelToken);
+        // Re-version against the REPAIRED text, after either branch. The repair is
+        // a content change the store has not seen: whatever reconciliation ran
+        // during the re-parse saw the text on disk, which in `'editor'` sync mode
+        // is the PRE-repair text. Leave the sequence describing that and the next
+        // open hashes the repair, finds a mismatch and steps the version again, so
+        // every base version taken from this build is stale before it is used.
+        // An open document keeps the store's own version, which is not this
+        // method's to move.
+        //
+        // Deliberately NOT gated on cancellation, unlike the entry to this method:
+        // `syncCorrections` has already written or staged the repair by now, so a
+        // preempted build that skipped this would leave the sequence describing
+        // text that is no longer there.
+        if (!this.textDocuments.isOpen(document.textDocument.uri)) {
+            // The root describes the repair too; left at the re-parse's number, a
+            // syncing read waits for a build nothing requests. The CST is still
+            // the unrepaired text, so the repair is reported as the parsed text.
+            this.services.shared.workspace.VersionSyncService.modelProduced(document, { text: newText });
+        }
+    }
+    /**
+     * Bring `document` back into agreement with the text it is supposed to
+     * describe, after a rule has mutated its AST.
+     *
+     * Used for a correction that was applied and for one that was abandoned,
+     * because the document is left inconsistent either way: applied, the text
+     * moved under the CST; abandoned, the AST carries a mutation the text never
+     * had. Both are the same question — re-read and re-derive — and the phase is
+     * what decides how far that has to go.
+     */
+    async reconcileDocument(document, cancelToken) {
         if (document.state <= DocumentState.Parsed) {
             // Parsed-phase correction: re-parse only. The build pipeline still runs
             // IndexedContent → ComputedScopes → Linked → … on the fresh AST afterwards,
@@ -265,24 +442,216 @@ export class DefaultIntegrityService {
             // stays in the builder, its proper home, rather than being duplicated here.
             await this.documentBuilder.reparseAndRelink(document, cancelToken);
         }
-        // Re-version against the REPAIRED text, after either branch. The repair is
-        // a content change the store has not seen: whatever reconciliation ran
-        // during the re-parse saw the text on disk, which in `'editor'` sync mode
-        // is the PRE-repair text. Leave the sequence describing that and the next
-        // open hashes the repair, finds a mismatch and steps the version again, so
-        // every `baseVersion` taken from this build is stale before it is used.
-        // Falls back to the pre-re-parse number for a URI the store never tracked,
-        // where there is no sequence to advance; an OPEN document answers
-        // `undefined` and keeps the store's own version, which is not this
-        // method's to move.
-        //
-        // Deliberately NOT gated on cancellation, unlike the entry to this method:
-        // `syncCorrections` has already written or staged the repair by now, so a
-        // preempted build that skipped this would leave the sequence describing
-        // text that is no longer there.
-        const reconciled = this.textDocuments.reconcileExternalContent(document.textDocument.uri, newText) ?? version;
-        if (document.textDocument.version !== reconciled) {
-            this.textDocuments.update(document.textDocument, [], reconciled);
+    }
+    /**
+     * Relink the documents that reference `document` in a build after this
+     * one, where it counts as changed. They were linked before the repair, so
+     * they hold nodes a re-parse replaced, or names the repair changed.
+     *
+     * Each document has at most one such build, its {@link DependentRelink},
+     * which goes through four steps.
+     *
+     * 1. Requested here, and kept in {@link relinkBuilds}. A repair while it
+     *    waits is relinked by it.
+     * 2. Checked inside the lock, which skips it unless {@link isRelinkNeeded}.
+     *    A needed one joins {@link scheduledRelinks}. While a build outside the
+     *    lock runs, it is requested again once that build ends.
+     * 3. Started, when `onUpdate` reports its build. An explicit `build` starts
+     *    none. It is in {@link runningRelinks} until it settles or the next
+     *    build starts that overlaps no other. A repair while it runs is kept in
+     *    {@link repairedAgain} and gets the next build.
+     * 4. Settled, when its request resolves, which drops it from every record.
+     *
+     * A repair of a document that a running build relinked continues that
+     * build's chain, which {@link maxRelinkChain} bounds. A repair with the
+     * {@link replayKey} of the one before requests none.
+     */
+    relinkDependents(document, repair) {
+        const key = this.replayKey(document, repair);
+        if (key !== undefined && this.replayKeys.get(document)?.key === key) {
+            return;
+        }
+        const rules = [...(this.mutatingRules.get(document) ?? [])];
+        const pending = this.relinkBuilds.get(document);
+        let requested = true;
+        if (pending !== undefined) {
+            this.repairedAgain.set(pending, rules);
+        }
+        else {
+            const causes = [...this.runningRelinks].filter(relink => this.isRelinkedBy(document, relink.document));
+            requested = this.relinkInChain(document, Math.max(0, ...causes.map(relink => relink.chain)) + 1, rules);
+        }
+        // Recorded after the request, so one that throws or is past the bound leaves no key that skips the next repair.
+        if (key !== undefined && requested) {
+            this.replayKeys.set(document, { key, fromHash: textHash(repair.from) });
+        }
+    }
+    /**
+     * Whether a build where `changed` counts as changed relinks `document`, as
+     * Langium's `shouldRelink` decides. Read from the document's links, because
+     * its build has dropped its indexed references until it indexes again.
+     */
+    isRelinkedBy(document, changed) {
+        const target = changed.uri.toString();
+        return document.references.some(reference => {
+            const descriptions = isMultiReference(reference)
+                ? reference.items.map(item => item.$nodeDescription)
+                : [reference.$nodeDescription];
+            return reference.error !== undefined || descriptions.some(description => description?.documentUri.toString() === target);
+        });
+    }
+    /**
+     * Request the build at `chain`, or warn naming `rules` past
+     * {@link maxRelinkChain} and drop the {@link replayKey} of `document`.
+     * Returns whether it requested the build.
+     */
+    relinkInChain(document, chain, rules) {
+        if (chain > this.maxRelinkChain) {
+            this.replayKeys.delete(document);
+            const builds = this.maxRelinkChain === 1 ? '1 build in a row that relinks' : `${this.maxRelinkChain} builds in a row that relink`;
+            this.tracer
+                .with(document.uri.toString())
+                .warn(`${this.formatRules(rules)} repaired documents in ${builds} their dependents, ` +
+                'which keep stale links until the next change. A rule that does not settle causes this, ' +
+                'or documents with linking errors that rules repair one after another.');
+            return false;
+        }
+        this.requestRelink(document, chain);
+        return true;
+    }
+    /** Request the build {@link relinkInChain} decided on, skipped unless {@link isRelinkNeeded}. */
+    requestRelink(document, chain) {
+        const uri = document.uri;
+        this.relinkStarts ??= this.documentBuilder.onUpdate(changed => this.startRelinks(changed));
+        const relink = { document, chain };
+        let unlockedBuild;
+        const stillNeeded = () => {
+            // No locked build runs during the lock read, so one seen here runs outside the lock.
+            unlockedBuild = this.documentBuilder.activeBuild;
+            if (unlockedBuild !== undefined) {
+                return false;
+            }
+            // Marked before the deferral check, so a deferred relink stays scheduled until it settles.
+            const needed = this.isRelinkNeeded(document);
+            if (needed) {
+                this.scheduledRelinks.add(relink);
+            }
+            return needed;
+        };
+        const settled = () => {
+            this.relinkBuilds.delete(document);
+            this.scheduledRelinks.delete(relink);
+            this.runningRelinks.delete(relink);
+        };
+        const requestFailed = (error) => {
+            // No build relinks the dependents, so the same repair again needs one.
+            this.replayKeys.delete(document);
+            this.tracer
+                .with(uri.toString())
+                .error(`Requesting the next build that relinks the dependents of a repaired document failed. ${describeErrorWithStack(error)}`);
+        };
+        const request = this.services.shared.workspace.VersionSyncService.requestRecoveryBuild(uri, { stillNeeded });
+        // Recorded after the request, so one that throws leaves no relink that never settles.
+        this.relinkBuilds.set(document, relink);
+        request
+            .then(() => {
+            if (unlockedBuild !== undefined) {
+                // Requested again once that build ends, so the two never overlap. A repair meanwhile waits for it.
+                unlockedBuild
+                    .then(() => {
+                    settled();
+                    this.requestRelink(document, chain);
+                })
+                    .catch(requestFailed);
+                return;
+            }
+            // A build that never started, or was cancelled and not run again,
+            // leaves the repair to the build that held it back. Read before the
+            // next build's `onUpdate` clears it, which the lock's queue orders later.
+            const ran = this.runningRelinks.has(relink);
+            settled();
+            const again = this.repairedAgain.get(relink);
+            if (ran && again !== undefined) {
+                this.relinkInChain(document, chain + 1, again);
+            }
+        }, (error) => {
+            settled();
+            // The dependents were not relinked, so the same repair again needs its build.
+            this.replayKeys.delete(document);
+            this.tracer
+                .with(uri.toString())
+                .error(`The build that relinks the dependents of a repaired document failed. ${describeErrorWithStack(error)}`);
+        })
+            .catch(requestFailed);
+    }
+    /** Mark the {@link scheduledRelinks} of the `changed` documents running, as the build that carries them starts. */
+    startRelinks(changed) {
+        // An explicit build relinks no dependents and ends no build it overlaps.
+        if (this.documentBuilder.isInsideBuildUpdate()) {
+            return;
+        }
+        // The build before this one ended, done or cancelled, so its relinks run no more,
+        // unless this one overlaps it, as a reentrant build does.
+        // The set is shared by every language. Each service clears only its own,
+        // because another's listener may already have marked this build's relinks running.
+        if (!this.documentBuilder.overlapsRunningBuild()) {
+            for (const relink of this.runningRelinks) {
+                if (this.relinkBuilds.get(relink.document) === relink) {
+                    this.runningRelinks.delete(relink);
+                }
+            }
+        }
+        const documents = this.services.shared.workspace.LangiumDocuments;
+        for (const uri of changed) {
+            const document = documents.getDocument(uri);
+            const relink = document === undefined ? undefined : this.relinkBuilds.get(document);
+            if (relink !== undefined && this.scheduledRelinks.delete(relink)) {
+                // The starting build relinks any repair while it waited.
+                this.repairedAgain.delete(relink);
+                this.runningRelinks.add(relink);
+            }
+        }
+    }
+    /**
+     * Whether a build where `document` counts as changed relinks another
+     * document, by the builder's own test, which counts a document a cancelled
+     * build left unindexed as relinked.
+     */
+    isRelinkNeeded(document) {
+        const documents = this.services.shared.workspace.LangiumDocuments;
+        const changed = new Set([document.uri.toString()]);
+        return (documents.getDocument(document.uri) === document &&
+            documents.all.some(other => other !== document && this.documentBuilder.shouldRelink(other, changed)));
+    }
+    /**
+     * Whether `document` stages its repairs rather than writing them, as a
+     * closed document does in `'editor'` mode, so its source keeps the
+     * unrepaired text.
+     */
+    stagesRepairs(document) {
+        return this.syncMode === 'editor' && !this.textDocuments.isOpen(document.textDocument.uri);
+    }
+    /**
+     * What tells `repair` made again from the same text apart from a new one,
+     * for a document that {@link stagesRepairs}, which reads the unrepaired
+     * text again in every build that re-parses it after its CST was shed. Such
+     * a repair requests no build, because the build that re-parsed the
+     * document relinked its dependents, and another would replay it again.
+     * Hashes, so the record keeps no text the shed freed.
+     */
+    replayKey(document, repair) {
+        return this.stagesRepairs(document) ? textHash(repair.from) + textHash(repair.to) : undefined;
+    }
+    /**
+     * Drop the {@link replayKey} of `document` once it was parsed from other
+     * text than its repair came from, such as a save and a revert. A repair of
+     * that text again is a new one, whose dependents need their build.
+     */
+    forgetReplayOfOtherText(document) {
+        const recorded = this.replayKeys.get(document);
+        const parsedFrom = document.parseResult.value.$cstNode?.root.fullText;
+        if (recorded !== undefined && parsedFrom !== undefined && recorded.fromHash !== textHash(parsedFrom)) {
+            this.replayKeys.delete(document);
         }
     }
     /**
@@ -290,40 +659,155 @@ export class DefaultIntegrityService {
      * already in the synced store (in-place in {@link resyncDocument}); this
      * method routes the out-of-band part by document registration:
      *
-     * - **Open in the language client** → nothing to push here. The AST mutation
-     *   rode the current build, so `ModelService.syncToLanguageClient` (the
-     *   persistent integrity-settled listener) mirrors the corrected text to the
-     *   client by *content* (shadow diff) — no authorship rewrite, no second
-     *   rebuild.
+     * - **Open in the language client** → nothing to push here. The AST
+     *   mutation rode the current build, so
+     *   `DefaultModelService.syncToLanguageClient` (the persistent
+     *   integrity-settled listener) mirrors it to the client by
+     *   *content* (shadow diff), and the editor shows it as an unsaved change.
+     * - **Held only through the data or GLSP head**, or waiting out the release
+     *   grace after its last client's connection was lost → the store is the
+     *   authority, and those heads read the correction from the settled build.
+     *   In silent mode it is also written to disk when the text it was computed
+     *   from is what disk holds, since the repair is then the only difference;
+     *   otherwise it waits for the next save. Editor mode always waits, and the
+     *   repair leaves the document dirty until a save.
      * - **Closed, silent mode** → write to disk directly (disk is authoritative).
-     * - **Closed, editor mode** → stage so the next open picks it up via applyEdit.
+     * - **Closed, editor mode** → stage, so the next open takes the correction
+     *   over the disk text.
+     *
+     * A held URI is not closed. Writing it as one persists the holder's unsaved
+     * edits with the repair, and staging it leaves text no open reads, because
+     * only a first open consumes the stage.
+     *
+     * `parsedFrom` is the text the repaired AST was parsed from. Without it a
+     * held URI's repair is left to the next save.
      */
-    async syncCorrections(document) {
-        // Open files: delivery is the ModelService settled listener's job (by
-        // content, via the shadow) — nothing to do here. Only the open/closed
-        // question is asked, so no reverse address resolution is needed: a file
-        // open under a symlinked path still answers `true`.
+    async syncCorrections(document, parsedFrom) {
+        // Only the open/closed question is asked, so no reverse address
+        // resolution is needed: a file open under a symlinked path still answers
+        // `true`.
         if (this.textDocuments.isOpenInLanguageClient(document.uri)) {
             return;
         }
+        // A virtual document has no disk backing, so neither persisting nor
+        // staging applies: there is no file to write and no editor that could open
+        // one. `URI.fsPath` yields a path for any scheme, so handing this to the
+        // provider would address `<cwd>/<contributor>/<name>` — an unrelated
+        // location a disk-backed provider refuses outright, turning a repair that
+        // was never persistable into a build failure. The correction is already on
+        // the AST and in the text store, which is the whole of where a virtual
+        // document lives, so there is nothing further to propagate.
+        if (isVirtualUri(document.uri)) {
+            this.tracer.with(document.uri).debug('Virtual document: correction kept in memory, nothing to persist');
+            return;
+        }
+        // A document waiting out the release grace still holds its lost client's
+        // unsaved text, so writing it as a closed file would persist that text.
+        if (this.textDocuments.isOpenInAnyClient(document.uri) || this.textDocuments.isReleaseDeferred(document.uri)) {
+            if (this.syncMode === 'silent' && parsedFrom !== undefined) {
+                await this.persistIfDiskMatches(document, parsedFrom);
+            }
+            return;
+        }
         // Closed files, silent mode: write to disk directly.
         if (this.syncMode === 'silent') {
+            const repaired = document.getText();
             // Async write so the integrity pass does not block the event loop on a slow filesystem.
-            await this.fileSystemProvider.writeFile(UriUtils.toUri(document.uri), document.getText());
+            // In the file's task queue, behind any save already queued: written
+            // beside one, the older repair can land last and stay on disk.
+            await this.services.shared.workspace.FileSystemTaskQueue.enqueue(document.uri, () => this.fileSystemProvider.writeFile(UriUtils.toUri(document.uri), repaired));
+            this.noteSilentWrite(document.uri);
             return;
         }
-        // Closed files, editor mode: stage content so the next open picks it up via applyEdit.
+        // Closed files, editor mode: stage content for the next open.
         this.textDocuments.stagePendingContent(document.uri, document.getText());
     }
+    /**
+     * Write the repair in `document` to disk when disk still holds `parsedFrom`,
+     * the text the repair was computed from — so the write carries the repair
+     * and nothing a holder could still discard.
+     *
+     * The read, the compare and the write run as one task in the file's task
+     * queue, so no save of the file lands between them. The store is compared
+     * again once the read returns, and the write is skipped if it no longer
+     * holds the repair: an edit does not wait for the queue, and writing the
+     * older repair then puts text on disk that no participant holds. The
+     * skipped repair loses nothing: the edit drives a build of its own, and a
+     * save writes the store's text. A file that cannot be read is left alone
+     * too: there is no evidence it matches. So is a file an editor opened in the
+     * meantime: the editor receives the repair as an unsaved change, and writing
+     * it would change the file under the editor.
+     */
+    async persistIfDiskMatches(document, parsedFrom) {
+        const uri = UriUtils.toUri(document.uri);
+        const repaired = document.getText();
+        await this.services.shared.workspace.FileSystemTaskQueue.enqueue(document.uri, async () => {
+            let onDisk;
+            try {
+                onDisk = await this.fileSystemProvider.readFile(uri);
+            }
+            catch (error) {
+                this.tracer.with(document.uri).debug(`Held document unreadable on disk, repair left to the next save: ${String(error)}`);
+                return;
+            }
+            // The file itself, not the store's disk baseline: the baseline moves
+            // only when the server hears of a change, so it can still hold the
+            // parsed text after another process rewrote the file and before the
+            // watcher reports it, and this write would then replace that change.
+            if (onDisk !== parsedFrom) {
+                return;
+            }
+            if (this.textDocuments.get(document.uri)?.getText() !== repaired) {
+                this.tracer.with(document.uri).debug('Held document changed while disk was read, repair left to that change');
+                return;
+            }
+            if (this.textDocuments.isOpenInLanguageClient(document.uri)) {
+                this.tracer.with(document.uri).debug('Editor attached while disk was read, repair left to its save');
+                return;
+            }
+            await this.fileSystemProvider.writeFile(uri, repaired);
+            this.textDocuments.setDiskBaseline(document.uri, repaired);
+            this.noteSilentWrite(document.uri);
+        });
+    }
+    /**
+     * Hand the first repair written to disk in `'silent'` sync mode to
+     * {@link reportSilentWrite}. Once per server, whichever language writes,
+     * rather than per file: a workspace-wide repair pass would otherwise log a
+     * line per document.
+     */
+    noteSilentWrite(uri) {
+        if (silentWriteReported.has(this.services.shared)) {
+            return;
+        }
+        silentWriteReported.add(this.services.shared);
+        this.reportSilentWrite(uri);
+    }
+    /**
+     * Log a server's first silent write-back, so an adopter learns that
+     * integrity rules edit their files and which setting controls it.
+     */
+    reportSilentWrite(uri) {
+        this.tracer.info(`Wrote an integrity repair to ${uri}. The integrity service's syncMode option is 'silent', ` +
+            "which writes repairs to disk; 'editor' leaves disk alone. Later repairs are written without this line.");
+    }
     /**
      * Format a rule's name for inclusion in user-facing diagnostic strings
-     * (error messages thrown during registration). Defaults to
+     * (error messages thrown during registration, and log lines). Defaults to
      * `label ?? id`. Adopters override when their error reporting needs
      * richer rule context.
      */
     formatRule(rule) {
         return rule.label ?? rule.id;
     }
+    /** `rules` as the subject of a log line, or a rule left unnamed when an override recorded none. */
+    formatRules(rules) {
+        if (rules.length === 0) {
+            return 'An integrity rule';
+        }
+        const names = rules.map(rule => `'${this.formatRule(rule)}'`).join(', ');
+        return rules.length === 1 ? `Integrity rule ${names}` : `Integrity rules ${names}`;
+    }
     /**
      * Format an AST node for the per-mutation `trace` log line. Returns
      * `'TypeName'` or `"TypeName('label')"` when the node carries a string
@@ -338,6 +822,17 @@ export class DefaultIntegrityService {
         const label = fromName ?? fromId;
         return label ? `${node.$type}('${label}')` : node.$type;
     }
+    /**
+     * The `$type`s `rule` runs on. Defaults to its `nodeType` and every subtype,
+     * as Langium's validation registry does: no node carries an abstract or union
+     * type as its `$type`, so an exact match never runs a rule keyed on one.
+     * Read only when the phase buckets rebuild after a registration change, so an
+     * override must not depend on anything else.
+     */
+    nodeTypesFor(rule) {
+        // A type the reflection does not know still matches itself.
+        return [rule.nodeType, ...this.services.shared.AstReflection.getAllSubTypes(rule.nodeType)];
+    }
     getPhaseBucket(phase) {
         const current = this.rules.all();
         if (this.phaseBucketsFor !== current) {
@@ -345,10 +840,18 @@ export class DefaultIntegrityService {
             for (const rule of current) {
                 let bucket = next.get(rule.phase);
                 if (!bucket) {
-                    bucket = [];
+                    bucket = new Map();
                     next.set(rule.phase, bucket);
                 }
-                bucket.push(rule);
+                // Deduplicated, or a rule runs twice on a node of its own type.
+                for (const nodeType of new Set(this.nodeTypesFor(rule))) {
+                    let rules = bucket.get(nodeType);
+                    if (!rules) {
+                        rules = [];
+                        bucket.set(nodeType, rules);
+                    }
+                    rules.push(rule);
+                }
             }
             this.phaseBuckets = next;
             this.phaseBucketsFor = current;
@@ -356,6 +859,7 @@ export class DefaultIntegrityService {
         return this.phaseBuckets.get(phase) ?? EMPTY_PHASE_BUCKET;
     }
 }
-/** Shared empty result so `getPhaseBucket` doesn't allocate per call on the cold path. */
-const EMPTY_PHASE_BUCKET = Object.freeze([]);
+// Shared empty results so neither the cold path nor a node no rule matches allocates.
+const EMPTY_PHASE_BUCKET = new Map();
+const NO_RULES = Object.freeze([]);
 //# sourceMappingURL=integrity-service.js.map