@hydranium/core 1.0.0-next.37 → 1.0.0-next.371

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

@@ -8,15 +8,25 @@
  ********************************************************************************/
 
 import { isPromiseLike, Logger, type ProfileSession, type Tracer } from '@hydranium/protocol';
-import { type AstNode, AstUtils, DocumentState, interruptAndCheck, type LangiumDocument, UriUtils } from '@hydranium/langium';
-import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import {
+   type AstNode,
+   AstUtils,
+   DocumentState,
+   interruptAndCheck,
+   isOperationCancelled,
+   type LangiumDocument,
+   UriUtils
+} from '@hydranium/langium';
+import { CancellationToken, type Disposable } from 'vscode-languageserver';
 import { type HydraniumDocumentBuilder } from '../document-builder/document-builder.js';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type WritableFileSystemProvider } from '../workspace/file-system-provider.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumTextDocuments } from '../../documents/hydranium-text-documents.js';
 import { Registry } from '../../util/registry.js';
 import { type ServerLanguageServices } from '../language-module.js';
+import { type ServerSharedServices } from '../module.js';
+import { isVirtualUri } from '../workspace/virtual-document.js';
 import { type IntegrityRuleRegistry } from './integrity-contribution.js';
 import { IntegrityPhase, type IntegrityRule, type IntegritySyncMode } from './integrity-rule.js';
 
@@ -75,6 +85,11 @@ export namespace IntegrityService {
     * at `DocumentState.Validated` and delivered separately via `publishDiagnostics`
     * or the `onModelUpdated` event.
     *
+    * 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.
+    *
     * 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
@@ -84,6 +99,14 @@ export namespace IntegrityService {
    export const SettledState: DocumentState = DocumentState.IndexedReferences;
 }
 
+/**
+ * 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<ServerSharedServices>();
+
 /**
  * Construction options for {@link DefaultIntegrityService}. All fields
  * optional — the defaults reproduce the framework's behaviour exactly.
@@ -123,15 +146,16 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
    protected ruleLoggers = new Map<string, Logger>();
 
    /**
-    * 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.
     */
-   protected phaseBuckets = new Map<DocumentState, readonly IntegrityRule[]>();
+   protected phaseBuckets = new Map<DocumentState, ReadonlyMap<string, readonly IntegrityRule[]>>();
    protected phaseBucketsFor: readonly IntegrityRule[] | undefined;
 
    /** Controls how corrections are persisted for closed files. See {@link IntegritySyncMode}. */
@@ -142,9 +166,7 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
    protected readonly tracer: 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}).
     */
    protected readonly documentBuilder: HydraniumDocumentBuilder;
 
@@ -155,7 +177,7 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
       this.textDocuments = services.shared.workspace.TextDocuments;
       this.fileSystemProvider = services.shared.workspace.FileSystemProvider;
       this.tracer = services.shared.Tracer.for(options.logName ?? 'Integrity').trace('instantiated');
-      this.documentBuilder = services.shared.workspace.DocumentBuilder as HydraniumDocumentBuilder;
+      this.documentBuilder = services.shared.workspace.DocumentBuilder;
       this.syncMode = options.syncMode ?? 'silent';
 
       // Read the language's IntegrityRuleContribution group and let each
@@ -184,7 +206,7 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     * rule set to completion against a doomed build.
     */
    async enforceBatch(documents: readonly LangiumDocument[], phase: DocumentState, cancelToken: CancellationToken): Promise<void> {
-      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
@@ -194,13 +216,17 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          const changed = await this.enforceIntegrity(document, phase, cancelToken, session);
          if (changed) {
             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');
@@ -219,6 +245,14 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          );
       }
       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: () => {
@@ -255,8 +289,10 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     * 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: LangiumDocument,
@@ -268,29 +304,34 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          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;
       }
       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)}`);
-               }
-               changed = mutated || changed;
+         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) {
+               ruleLogger.trace(`[${relativeUri}] Mutated ${this.formatNode(node)}`);
             }
+            changed = mutated || changed;
          }
          if (cancelToken !== undefined) {
-            await interruptAndCheck(cancelToken);
+            try {
+               await interruptAndCheck(cancelToken);
+            } catch (err: unknown) {
+               if (changed && isOperationCancelled(err)) {
+                  return true;
+               }
+               throw err;
+            }
          }
       }
       return changed;
@@ -300,34 +341,120 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     * 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.
     */
    protected async resyncDocument(document: LangiumDocument, cancelToken?: CancellationToken): Promise<void> {
-      if (cancelToken?.isCancellationRequested) {
-         return;
-      }
       const root = document.parseResult.value as TRoot;
-      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;
       }
 
-      // 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 }], document.textDocument.version);
+      const version = document.textDocument.version;
+      // 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.
+         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);
+      await this.syncCorrections(textDocument, parsedFrom);
 
+      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.
+    */
+   protected async reconcileDocument(document: LangiumDocument, cancelToken?: CancellationToken): Promise<void> {
       if (document.state <= DocumentState.Parsed) {
          // Parsed-phase correction: re-parse only. The build pipeline still runs
          // IndexedContent → ComputedScopes → Linked → … on the fresh AST afterwards,
          // so the document reconciles naturally with no extra work here.
+         //
+         // Except for a closed document whose repair did not reach disk — `'editor'`
+         // sync mode stages it instead of writing it — where the re-parse is SKIPPED:
+         // Langium's factory gates the parse on the CST's `fullText`, which still
+         // equals the disk text the same call re-reads and redefines `textDocument`
+         // over. So `document.textDocument` is NOT post-integrity for such a
+         // document — it mirrors disk, and the AST is the only place the repair is
+         // legible, until an open consumes the staging.
          await this.documentBuilder.reparse(document, cancelToken);
       } else {
          // Linked-phase (or later) correction. The rule mutated the AST in place but
@@ -347,34 +474,149 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     * 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.
     */
-   protected async syncCorrections(document: TextDocument): Promise<void> {
-      // 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`.
+   protected async syncCorrections(document: TextDocument, parsedFrom?: string): Promise<void> {
+      // 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.
+    */
+   protected async persistIfDiskMatches(document: TextDocument, parsedFrom: string): Promise<void> {
+      const uri = UriUtils.toUri(document.uri);
+      const repaired = document.getText();
+      await this.services.shared.workspace.FileSystemTaskQueue.enqueue(document.uri, async () => {
+         let onDisk: string;
+         try {
+            onDisk = await this.fileSystemProvider.readFile(uri);
+         } catch (error: unknown) {
+            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.
+    */
+   protected noteSilentWrite(uri: string): void {
+      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.
+    */
+   protected reportSilentWrite(uri: string): void {
+      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
@@ -400,17 +642,37 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
       return label ? `${node.$type}('${label}')` : node.$type;
    }
 
-   protected getPhaseBucket(phase: DocumentState): readonly IntegrityRule[] {
+   /**
+    * 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.
+    */
+   protected nodeTypesFor(rule: IntegrityRule): Iterable<string> {
+      // A type the reflection does not know still matches itself.
+      return [rule.nodeType, ...this.services.shared.AstReflection.getAllSubTypes(rule.nodeType)];
+   }
+
+   protected getPhaseBucket(phase: DocumentState): ReadonlyMap<string, readonly IntegrityRule[]> {
       const current = this.rules.all();
       if (this.phaseBucketsFor !== current) {
-         const next = new Map<DocumentState, IntegrityRule[]>();
+         const next = new Map<DocumentState, Map<string, IntegrityRule[]>>();
          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;
@@ -419,5 +681,6 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
    }
 }
 
-/** Shared empty result so `getPhaseBucket` doesn't allocate per call on the cold path. */
-const EMPTY_PHASE_BUCKET: readonly IntegrityRule[] = Object.freeze([]);
+// Shared empty results so neither the cold path nor a node no rule matches allocates.
+const EMPTY_PHASE_BUCKET: ReadonlyMap<string, readonly IntegrityRule[]> = new Map();
+const NO_RULES: readonly IntegrityRule[] = Object.freeze([]);

package/src/langium/keys/containment.ts

@@ -13,8 +13,9 @@
  *
  * **These live beside the key provider because the constraint is the key
  * provider's.** `NameBasedKeyProvider` keys a node the `NameProvider` gives no
- * name from its position, as `` `${$containerProperty}@${$containerIndex}` ``,
- * so a node appended with a bare `array.push` carries neither and
+ * name from its position, as `` `${$containerProperty}@${$containerIndex}` ``
+ * (`` `${$containerProperty}@` `` in a single-valued property), so a node
+ * appended with a bare `array.push` carries neither and
  * `getElementKey` answers `undefined` — the element has no key at all, and the
  * GLSP index cannot address it. Deleting from the middle of such a list must
  * renumber the survivors, or an id derived later in the same command names the

package/src/langium/keys/name-based-key-provider.ts

@@ -44,20 +44,25 @@ import { type NameProvider } from '../naming/name-provider.js';
  * `NameProvider` gives no name. For grammars with unnamed element types the
  * reorder / insert / delete stability above does NOT apply to those nodes:
  * their keys move when their index moves, so a mid-array insert or delete
- * renumbers every later sibling.
+ * renumbers every later sibling. A node held in a single-valued property has
+ * no `$containerIndex` and falls back to `` `${$containerProperty}@` ``; the
+ * trailing `@` keeps its key apart from a sibling named after the property.
  *
  * Two consequences for a caller creating such nodes programmatically
  * (a GLSP operation handler is the usual case):
  *
- * - A node appended with a bare `array.push` has no `$containerProperty` /
- *   `$containerIndex`, so `getElementKey` returns `undefined` and the node
- *   has no key at all. The containment plumbing has to be stamped.
+ * - A node appended with a bare `array.push`, or assigned to a single-valued
+ *   property without its `$containerProperty`, has no container position, so
+ *   `getElementKey` returns `undefined` and the node has no key at all. The
+ *   containment plumbing has to be stamped.
  * - After a removal, surviving siblings need their `$containerIndex`
  *   renumbered, or a key derived afterwards addresses the wrong node.
  *
- * {@link appendChild} and {@link removeChildren} discharge both, and ship
- * beside this provider because the constraint is this provider's rather than
- * any caller's.
+ * {@link appendChild} and {@link removeChildren} discharge both for arrays,
+ * and ship beside this provider because the constraint is this provider's
+ * rather than any caller's. A single-valued property needs no helper: build
+ * the node with its `$container` and `$containerProperty`, which
+ * `buildAstNode` accepts.
  *
  * Adopters that need insert / delete stability for unnamed types should
  * give those types a name in the grammar, or bind a key provider whose
@@ -137,14 +142,21 @@ export class NameBasedKeyProvider implements ElementKeyProvider {
    }
 
    /**
-    * Fallback segment for unnamed intermediate ancestors —
-    * `containerProperty@containerIndex`. Returns `undefined` when the
-    * node has no container position, which short-circuits the walk.
+    * Segment for a node the `NameProvider` gives no name —
+    * `containerProperty@containerIndex`, or `containerProperty@` when the
+    * container holds no array in that property, attached or not. Returns
+    * `undefined` when the node has no container position: the node itself
+    * then has no key, and an ancestor's level is left out of the key.
     */
    protected unidentifiedSegment(node: AstNode): string | undefined {
-      if (node.$containerProperty === undefined || node.$containerIndex === undefined) {
+      const property = node.$containerProperty;
+      if (property === undefined) {
          return undefined;
       }
-      return `${node.$containerProperty}@${node.$containerIndex}`;
+      if (node.$containerIndex !== undefined) {
+         return `${property}@${node.$containerIndex}`;
+      }
+      // An array member without its index stays keyless rather than share `property@` with its siblings.
+      return Array.isArray((node.$container as Record<string, unknown> | undefined)?.[property]) ? undefined : `${property}@`;
    }
 }