@hydranium/core 1.0.0-next.4 → 1.0.0-next.40

package/src/langium/document-builder/document-builder.ts

@@ -9,6 +9,7 @@
 
 import { type Clock, type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
 import {
+   type AstNode,
    type BuildOptions,
    DefaultDocumentBuilder,
    type DocumentPhaseListener,
@@ -20,12 +21,17 @@ import {
    interruptAndCheck,
    isOperationCancelled
 } from '@hydranium/langium';
-import { CancellationToken, type Diagnostic } from 'vscode-languageserver-protocol';
+// `Diagnostic` as a VALUE: `renderDiagnostics` needs its `getMessageString`
+// namespace helper to read the `string | MarkupContent` union without
+// restating it.
+import { CancellationToken, Diagnostic } from 'vscode-languageserver-protocol';
 import { type LogNameOptions } from '../diagnostics/logger.js';
+import type { MessageRenderer } from '../../messages/renderer.js';
 import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residency-service.js';
 import { type ExtendedServiceRegistry } from '../service-registry.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
+import { BuildSession, type BuildSessionContext } from './build-session.js';
 import { type LabeledPhaseListener, labelPhaseListener } from './labeled-phase-listener.js';
 
 /** Document states a phase-reached line is emitted for by default — every built phase. */
@@ -78,6 +84,18 @@ export interface DocumentBuilderOptions extends LogNameOptions {
     * logged. Default: `25`. Read per phase; accepts a {@link MaybeObservableValue}.
     */
    readonly slowBuildMs?: MaybeObservableValue<number>;
+   /**
+    * Build duration at or above which a build's phase-reached and slow-listener
+    * lines are emitted; they are held for the duration of the build and dropped
+    * when it finishes faster. Default `0` — no buffering, every line emitted as
+    * it is produced, which is the only setting that keeps lines interleaved with
+    * the rest of the log in real time.
+    *
+    * Set it to make a fast rebuild log nothing but its one build line. The
+    * decision needs the build's TOTAL duration, so it cannot be made by any
+    * per-line hook. Read once per build; accepts a {@link MaybeObservableValue}.
+    */
+   readonly phaseDetailMs?: MaybeObservableValue<number>;
    /**
     * Refresh cross-document `ComputedScopes` derivations when a referencing
     * document is cascade-rebuilt (see
@@ -105,15 +123,24 @@ export interface DocumentBuilderOptions extends LogNameOptions {
  * - **In-place rebuild helpers** — {@link reparse} and
  *   {@link reparseAndRelink} — for a build-phase listener that mutated a
  *   document's AST and must reconcile it within the same build.
- * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}).
+ * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}), followed
+ *   by the **one server-side message render** every head inherits
+ *   ({@link renderDiagnostics}).
+ * - **Build sessions** ({@link BuildSession}): each `update` / `build` call is
+ *   one correlated unit carrying an id, a trigger label, a start time and
+ *   cancellation lineage, so every line of a rebuild reads as belonging to it
+ *   and a preempted build is distinguishable from the winner.
  * - **Logging instrumentation** (default on, opt-out via `logLevel: 'off'`):
- *   phase-reached lines, slow-listener breakdowns on `notifyDocumentPhase`,
- *   and slow-build-phase totals on `notifyBuildPhase`.
+ *   a per-build line, phase-reached lines, slow-listener breakdowns on
+ *   `notifyDocumentPhase`, and slow-build-phase totals on `notifyBuildPhase`.
  *
  * Adopters extend this class — the configuration knobs cover what most
  * adopters need; the `format*Line` methods, `formatUri`, and
  * `collectDeletedURIs` are protected so subclasses can customise wording or
- * domain-aware cascades without re-implementing surrounding logic.
+ * domain-aware cascades without re-implementing surrounding logic. An adopter
+ * with build-scoped state of its own subclasses {@link BuildSession} and
+ * overrides {@link createBuildSession}, which puts that state under the same
+ * preemption-correct teardown rather than a reimplementation of it.
  */
 export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly tracer: Tracer;
@@ -127,8 +154,11 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly slowListenerMs: ObservableValue<number>;
    /** Live slow-build-phase-total threshold; read `.value` per phase. */
    protected readonly slowBuildMs: ObservableValue<number>;
+   /** Live phase-detail buffering threshold; read `.value` once per build, onto the session. */
+   protected readonly phaseDetailMs: ObservableValue<number>;
    protected readonly uriPolicy: DocumentUriPolicy;
    protected readonly clock: Clock;
+   protected readonly messageRenderer: MessageRenderer;
    /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
    protected readonly languageRegistry: ExtendedServiceRegistry;
    protected languageFileExtensions: string[] = [];
@@ -139,18 +169,36 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly refreshCrossDocumentComputedScopes: boolean;
    /** LSP event name (e.g. `'didChangeWatchedFiles'`) staged for the next `update()` call. */
    protected pendingUpdateReason?: string;
+   /**
+    * The build currently in progress, or `undefined` between builds.
+    *
+    * A subclass carrying its own build-scoped state returns a {@link BuildSession}
+    * subclass from {@link createBuildSession} and narrows this with a typeguard
+    * where it reads that state — rather than redeclaring the field, whose
+    * initialiser would run after `super()` and clear a session opened during
+    * construction.
+    */
+   protected activeSession?: BuildSession;
+   /**
+    * `traceId` of the last build that ended in cancellation, for the successor's
+    * "cancels #N" tag. Held here rather than on a session because the session
+    * that carries it is already gone by the time its successor is opened.
+    */
+   protected lastCancelledTraceId?: number;
 
    constructor(services: ServerSharedServicesMinimal, options: DocumentBuilderOptions = {}) {
       super(services);
       this.languageRegistry = services.ServiceRegistry;
       this.uriPolicy = services.workspace.DocumentUriPolicy;
       this.clock = services.Clock;
+      this.messageRenderer = services.MessageRenderer;
       this.tracer = services.Tracer.for(options.logName ?? 'DocumentBuilder').trace('instantiated');
       this.logLevel = options.logLevel ?? 'debug';
       this.loggedPhases = options.loggedPhases ?? DEFAULT_LOGGED_PHASES;
       this.slowPhaseMs = ObservableValue.from(options.slowPhaseMs ?? 25);
       this.slowListenerMs = ObservableValue.from(options.slowListenerMs ?? 5);
       this.slowBuildMs = ObservableValue.from(options.slowBuildMs ?? 25);
+      this.phaseDetailMs = ObservableValue.from(options.phaseDetailMs ?? 0);
       this.refreshCrossDocumentComputedScopes = options.refreshCrossDocumentComputedScopes ?? false;
       if (this.logLevel !== 'off') {
          this.registerPhaseListeners();
@@ -193,7 +241,16 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       const doc = this.langiumDocuments.getDocument(UriUtils.toUri(this.uriPolicy.canonicalUri(uri)));
       const docState = doc ? DocumentState[doc.state] : 'unknown (document not loaded)';
       const lastPhase = this.lastPhaseMs > 0 ? `${Math.round(performance.now() - this.lastPhaseMs)}ms ago` : 'no phase observed';
-      return `current state: '${docState}', last phase: ${lastPhase}`;
+      return `current state: '${docState}', last phase: ${lastPhase}, active build: ${this.formatSession(this.activeSession)}`;
+   }
+
+   /** Render a session for a status line. `undefined` — no build in progress — reads as `none`. */
+   protected formatSession(session: BuildSession | undefined): string {
+      if (!session) {
+         return 'none';
+      }
+      const id = session.traceId !== undefined ? `#${session.traceId}` : 'untimed';
+      return `${id} (${session.trigger}, ${Math.round(performance.now() - session.startMs)}ms in)`;
    }
 
    // ============================================================
@@ -409,7 +466,35 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       this.ensureLanguageFileExtensions();
       const changedURIs = changed.flatMap(uri => this.flattenAndAdaptURI(uri));
       const deletedURIs = deleted.flatMap(uri => this.collectDeletedURIs(uri));
-      return super.update(changedURIs, deletedURIs, cancelToken);
+      return this.runInSession(
+         {
+            kind: 'update',
+            trigger: this.buildTriggerLabel(changedURIs, deletedURIs),
+            triggerCountsDocs: changedURIs.length + deletedURIs.length !== 1,
+            changed: changedURIs,
+            deleted: deletedURIs
+         },
+         this.rebuildLabel(changedURIs, deletedURIs),
+         () => super.update(changedURIs, deletedURIs, cancelToken)
+      );
+   }
+
+   /**
+    * The workspace-initialization entry point, bracketed by a session like
+    * {@link update}. Langium's `update` reaches `buildDocuments` directly rather
+    * than through here, so the two never nest.
+    */
+   override build<T extends AstNode>(
+      documents: Array<LangiumDocument<T>>,
+      options?: BuildOptions,
+      cancelToken?: CancellationToken
+   ): Promise<void> {
+      const uris = documents.map(document => document.uri);
+      return this.runInSession(
+         { kind: 'build', trigger: `${documents.length} docs`, triggerCountsDocs: true, changed: uris, deleted: [] },
+         `Build documents (${documents.length} docs)`,
+         () => super.build(documents, options, cancelToken)
+      );
    }
 
    /**
@@ -615,6 +700,149 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       ];
    }
 
+   // ============================================================
+   // Build sessions — one rebuild as a correlated unit
+   // ============================================================
+
+   /**
+    * Open a session, run `body` inside it, and close it — the bracket every
+    * line of a rebuild is emitted within.
+    *
+    * The session is installed **synchronously**, before the timed body runs, so
+    * that state a subclass computed in {@link createBuildSession} is already
+    * readable by the time Langium's `update` consults `shouldRelink`.
+    *
+    * Teardown is preemption-correct, which is the reason this is framework code
+    * rather than a recipe. Langium's write mutex cancels an in-flight build when
+    * a later one arrives, so two sessions overlap: the successor installs itself
+    * as {@link activeSession} while the predecessor is still unwinding, and the
+    * predecessor's `finally` runs LAST. Clearing unconditionally there would
+    * discard the winner's state mid-build. Only the session that is still
+    * current clears — and the check is reference equality on the session object,
+    * not on {@link BuildSession.traceId}, which is `undefined` for every build
+    * whenever the timing level is suppressed and would compare equal to itself
+    * across two different builds.
+    *
+    * Re-entrancy is not hypothetical even without an adopter: {@link
+    * requeueOrphaned} calls `update` from inside a wait, while a build may be
+    * running.
+    */
+   protected runInSession(context: BuildSessionContext, label: string, body: () => Promise<void>): Promise<void> {
+      // Read before installing the new session: the id being superseded belongs
+      // to the OUTGOING build, or — when the previous one already finished
+      // cancelled — to the id it parked for its successor.
+      const supersededId = this.activeSession?.traceId ?? this.lastCancelledTraceId;
+      this.lastCancelledTraceId = undefined;
+      const reason = this.pendingUpdateReason;
+      this.pendingUpdateReason = undefined;
+      const tags: string[] = [];
+      if (reason) {
+         tags.push(`event: ${reason}`);
+      }
+      if (supersededId !== undefined) {
+         tags.push(`cancels #${supersededId}`);
+      }
+
+      const session = this.createBuildSession(context);
+      this.activeSession = session;
+      // A phase's "since previous phase" must measure from the build's start,
+      // not from whenever the last build's final phase happened to land.
+      this.lastPhaseMs = session.startMs;
+      return this.tracer.time(
+         label,
+         async () => {
+            try {
+               await body();
+            } catch (err: unknown) {
+               if (isOperationCancelled(err)) {
+                  session.cancelled = true;
+               }
+               throw err;
+            } finally {
+               this.endSession(session);
+            }
+         },
+         this.logLevel,
+         {
+            logAfterMs: 0,
+            forceMemoryAboveMs: session.buffers ? session.detailThresholdMs : undefined,
+            captureId: id => {
+               session.traceId = id;
+            },
+            tags
+         }
+      );
+   }
+
+   /**
+    * Construct the session for one build. Override to return a
+    * {@link BuildSession} subclass carrying adopter build-scoped state — it is
+    * called before the build body, so anything derived here is readable
+    * throughout it.
+    */
+   protected createBuildSession(context: BuildSessionContext): BuildSession {
+      return new BuildSession(performance.now(), context.trigger, context.triggerCountsDocs, this.phaseDetailMs.value);
+   }
+
+   /**
+    * Close `session`: flush what it buffered, then release it if it is still the
+    * current one (see {@link runInSession} on why that check is conditional).
+    * The flush is unconditional — a preempted build's lines still describe work
+    * that happened.
+    */
+   protected endSession(session: BuildSession): void {
+      this.flushSession(session);
+      if (this.activeSession === session) {
+         this.activeSession = undefined;
+         if (session.cancelled) {
+            this.lastCancelledTraceId = session.traceId;
+         }
+      }
+   }
+
+   /**
+    * Emit the lines `session` held back, if it ran long enough to be worth the
+    * detail; drop them otherwise. Emits through {@link emit} rather than
+    * {@link log}, which would route them straight back into the buffer.
+    */
+   protected flushSession(session: BuildSession): void {
+      const elapsedMs = performance.now() - session.startMs;
+      if (elapsedMs >= session.detailThresholdMs) {
+         for (const line of session.bufferedLines) {
+            this.emit(line);
+         }
+      }
+      session.bufferedLines.length = 0;
+   }
+
+   /** Label for the build's own log line. Override to customise wording. */
+   protected rebuildLabel(changed: URI[], deleted: URI[]): string {
+      if (changed.length === 0 && deleted.length === 0) {
+         return 'Rebuild documents (nothing to do)';
+      }
+      if (changed.length === 1 && deleted.length === 0) {
+         return `Rebuild document: ${this.formatUri(changed[0])}`;
+      }
+      if (changed.length === 0 && deleted.length === 1) {
+         return `Rebuild after delete: ${this.formatUri(deleted[0])}`;
+      }
+      return `Rebuild documents (${changed.length} changed, ${deleted.length} deleted)`;
+   }
+
+   /** Short description of what triggered the build, repeated on every phase line. Override to customise wording. */
+   protected buildTriggerLabel(changed: URI[], deleted: URI[]): string {
+      if (changed.length === 0 && deleted.length === 0) {
+         return 'nothing';
+      }
+      if (changed.length === 1 && deleted.length === 0) {
+         return this.formatUri(changed[0]);
+      }
+      if (changed.length === 0 && deleted.length === 1) {
+         return `deleted ${this.formatUri(deleted[0])}`;
+      }
+      return `${changed.length} changed, ${deleted.length} deleted`;
+   }
+
    // ============================================================
    // Logging — phase-reached listeners
    // ============================================================
@@ -630,13 +858,35 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       const now = performance.now();
       const elapsedMs = Math.round(now - this.lastPhaseMs);
       this.lastPhaseMs = now;
+      // Counted before the line is formatted, so the formatter stays a pure
+      // function of state a caller can also set up in a test.
+      if (this.activeSession) {
+         this.activeSession.phasesLogged++;
+      }
       this.log(this.phaseReachedLine(state, documents, elapsedMs));
    }
 
-   /** Format the phase-reached log line. Override to customise wording. */
+   /**
+    * Format the phase-reached log line. Override to customise wording.
+    *
+    * Within a session the line names what triggered the build, so a phase read
+    * in isolation still says which rebuild it belongs to. `elapsedMs` is ignored
+    * for the FIRST phase of a session: it measures from the previous build's
+    * last phase, an idle gap that says nothing about this build.
+    */
    protected phaseReachedLine(state: DocumentState, documents: LangiumDocument[], elapsedMs: number): string {
-      const docInfo = documents.length === 1 ? this.formatUri(documents[0].uri) : `${documents.length} docs`;
-      return `Reached phase '${DocumentState[state]}' [${docInfo}, ${elapsedMs}ms since previous phase]`;
+      const session = this.activeSession;
+      let docInfo: string;
+      if (session) {
+         docInfo = session.triggerCountsDocs ? `building ${session.trigger}` : `building ${session.trigger}, ${documents.length} docs`;
+      } else {
+         docInfo = documents.length === 1 ? this.formatUri(documents[0].uri) : `${documents.length} docs`;
+      }
+      const elapsedInfo =
+         session && session.phasesLogged <= 1
+            ? `${Math.round(performance.now() - session.startMs)}ms since build start`
+            : `${elapsedMs}ms since previous phase`;
+      return `Reached phase '${DocumentState[state]}' [${docInfo}, ${elapsedInfo}]`;
    }
 
    // ============================================================
@@ -651,8 +901,12 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       // build settling inside that window therefore appends after this call has
       // already deduped, and the appended duplicate is published by the listener
       // of the build that deduped. Only `serializeBuilds` closes the window.
+      //
+      // Dedupe before rendering: rendering is deterministic, so it cannot
+      // change which entries are structurally equal, and fewer survive to render.
       if (state === DocumentState.Validated) {
          this.dedupeDiagnostics(document);
+         this.renderDiagnostics(document);
       }
       if (this.logLevel === 'off') {
          return super.notifyDocumentPhase(document, state, cancelToken);
@@ -828,12 +1082,86 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       }
    }
 
+   /**
+    * Render every diagnostic on `document` through the bound message renderer,
+    * in ONE pass over the finished list.
+    *
+    * All three heads read `document.diagnostics` — the LSP publish,
+    * `TransferEncoder.toTransferDiagnostic` and the GLSP validation path — so
+    * one pass here is what keeps the render from happening per head. It is also
+    * the only placement that covers lexer and parser errors, which Langium
+    * pushes onto the document without routing them through `toDiagnostic`.
+    *
+    * Running here rather than from a `Validated` phase listener needs no
+    * ordering assumption: Langium publishes from `addDiagnosticsHandler`, a free
+    * function it registers as such a listener, which can only be outrun.
+    *
+    * **It inherits {@link dedupeDiagnostics}'s window, and therefore the same
+    * precondition.** A build settling inside the listener window appends
+    * diagnostics this pass never saw, and the publisher of the build that
+    * rendered sends them — unrendered. `ModelServiceOptions.serializeBuilds`
+    * closes it and defaults to `true`, so "every diagnostic is rendered" holds
+    * by default and is an opt-out rather than a guarantee. Opting out accepts
+    * unrendered diagnostics on exactly the terms it already accepts duplicates.
+    *
+    * Entries are REPLACED rather than mutated: `sendDiagnostics` passes the
+    * array by reference and serialises later, so an in-place message mutation
+    * reaches the wire even when it runs after the publisher — which would make
+    * a test for the ordering pass in either state.
+    */
+   protected renderDiagnostics(document: LangiumDocument): void {
+      const diagnostics = document.diagnostics;
+      if (!diagnostics || diagnostics.length === 0) {
+         return;
+      }
+      let changed = false;
+      // No try/catch: `renderDiagnostic` carries a no-throw contract, because an
+      // error escaping this phase strands the document at `Validated` with
+      // Langium's publisher never invoked.
+      const rendered = diagnostics.map(diagnostic => {
+         const text = this.messageRenderer.renderDiagnostic(diagnostic);
+         // Against the message's STRING FORM, not the field. `renderDiagnostic`
+         // answers a `string` by contract, while `Diagnostic.message` is
+         // `string | MarkupContent` since LSP 3.17 — so comparing the answer
+         // against the field never matches for a markup message, and a pass
+         // that replaced on mismatch flattened every un-identified markup
+         // diagnostic to its own plain text. That is silent data loss on the
+         // path whose whole job is to leave such entries alone.
+         if (text === Diagnostic.getMessageString(diagnostic)) {
+            return diagnostic;
+         }
+         changed = true;
+         return { ...diagnostic, message: text };
+      });
+      if (changed) {
+         document.diagnostics = rendered;
+      }
+   }
+
    // ============================================================
    // Internal helpers
    // ============================================================
 
-   /** Dispatch a log line at the configured log level; a no-op when `logLevel === 'off'`. */
+   /**
+    * Dispatch a log line at the configured log level; a no-op when `logLevel ===
+    * 'off'`.
+    *
+    * Held on the active session when it buffers, so the "was this build worth a
+    * per-phase breakdown" decision — which needs the build's total duration, and
+    * so cannot be taken by anything that runs while the lines are produced — is
+    * deferred to {@link flushSession}.
+    */
    protected log(message: string): void {
+      const session = this.activeSession;
+      if (session?.buffers) {
+         session.bufferedLines.push(message);
+         return;
+      }
+      this.emit(message);
+   }
+
+   /** Write a line out, bypassing session buffering. The single sink every framework log line reaches. */
+   protected emit(message: string): void {
       this.tracer.logAt(this.logLevel, message);
    }
 }

package/src/langium/document-builder/index.ts

@@ -8,5 +8,6 @@
  ********************************************************************************/
 
 export * from './build-pipeline-integration.js';
+export * from './build-session.js';
 export * from './document-builder.js';
 export * from './labeled-phase-listener.js';

package/src/langium/integration-services.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { inject, type Module } from '@hydranium/langium';
+import { type DeepPartial, inject, type Module } from '@hydranium/langium';
 import {
    createDefaultModule,
    createDefaultSharedModule,
@@ -98,6 +98,31 @@ export interface IntegrationServicesOptions<
        * it is silently inert.
        */
       extra?: ReadonlyArray<Module<TShared, PartialLangiumSharedServices>>;
+      /**
+       * Shared modules composed LAST — after `adopter` — and partial over
+       * `TShared` rather than over Langium's shared services.
+       *
+       * Both differences are the point, and neither is served by
+       * {@link extra}. Most framework shared services are constructed with
+       * no options (`ModelService: services => new DefaultModelService(services)`),
+       * so rebinding the slot is the only way to boot one configured
+       * differently; a caller that needs that is usually a test, and the slot
+       * it needs is as often a framework ADDITION (`Clock`, `Tracer`,
+       * `ProjectManager`) as a Langium one. `extra` can express neither: it
+       * is typed `DeepPartial<LangiumSharedServices>`, and it loses to
+       * `adopter` on every slot the adopter binds.
+       *
+       * Kept separate rather than widening `extra` because `extra` is the
+       * protocol-head tier, and a head must NOT outrank the adopter. Widening
+       * it also does not typecheck — `Module<I, T>` puts `T` in factory
+       * return position, so a head module declaring Langium slot types stops
+       * being assignable once `T` becomes `DeepPartial<TShared>`.
+       *
+       * Composing last means an override wins over everything, including the
+       * adopter. That is what makes it usable for the slots an adopter binds
+       * itself, and why production code should not reach for it.
+       */
+      overrides?: ReadonlyArray<Module<TShared, DeepPartial<TShared>>>;
    };
 
    /**
@@ -134,6 +159,23 @@ export interface IntegrationServicesOptions<
        * still win over heads.
        */
       extra?: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
+      /**
+       * Modules composed LAST, after `adopter`, and partial over `TLanguage`
+       * rather than over Langium's per-language services. The language-tier
+       * twin of {@link IntegrationServicesOptions.sharedModules}'s
+       * `overrides`, and both differences carry the same weight they do
+       * there.
+       *
+       * A per-language framework service is constructed by the framework's
+       * own module with no options
+       * (`IntegrityService: services => new DefaultIntegrityService(services)`),
+       * so booting one configured differently means rebinding the slot.
+       * {@link extra} serves neither half of that: it composes BEFORE
+       * `adopter` and so loses every slot the adopter binds, and it is typed
+       * `PartialLangiumServices`, which cannot express a framework ADDITION
+       * like `IntegrityService` or `AstExtensionService` at all.
+       */
+      overrides?: ReadonlyArray<Module<TLanguage, DeepPartial<TLanguage>>>;
    };
 
    /**
@@ -197,6 +239,8 @@ export interface AdditionalLanguageModules<
    adopter?: (shared: TShared) => Module<TLanguage, PartialLangiumServices>;
    /** Protocol-head modules for this language. Defaults to the primary language's. */
    extra?: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
+   /** Last-composed overrides for this language. Defaults to the primary language's. */
+   overrides?: ReadonlyArray<Module<TLanguage, DeepPartial<TLanguage>>>;
 }
 
 /**
@@ -247,7 +291,9 @@ export function createIntegrationServices<
       sharedModules.generated,
       sharedModule,
       ...(sharedModules.extra ?? []),
-      sharedModules.adopter
+      sharedModules.adopter,
+      // Last, so an override outranks the adopter too — see `overrides`.
+      ...((sharedModules.overrides ?? []) as ReadonlyArray<Module<TShared, PartialLangiumSharedServices>>)
    ) as unknown as TShared;
 
    // Each language gets its OWN `createDefaultModule({ shared })` — the
@@ -256,19 +302,34 @@ export function createIntegrationServices<
    const composeLanguage = (
       generated: Module<TLanguage, PartialLangiumServices>,
       adopter: (shared: TShared) => Module<TLanguage, PartialLangiumServices>,
-      extra: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>
+      extra: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>,
+      overrides: ReadonlyArray<Module<TLanguage, DeepPartial<TLanguage>>>
    ): TLanguage => {
       const defaultLanguageModule = createDefaultModule({ shared }) as unknown as Module<TLanguage, PartialLangiumServices>;
       const serverLanguageModule = createServerLanguageModule(context) as unknown as Module<TLanguage, PartialLangiumServices>;
-      return inject(defaultLanguageModule, generated, serverLanguageModule, ...extra, adopter(shared)) as unknown as TLanguage;
+      return inject(
+         defaultLanguageModule,
+         generated,
+         serverLanguageModule,
+         ...extra,
+         adopter(shared),
+         // Last, so an override outranks the adopter too — see `overrides`.
+         ...(overrides as ReadonlyArray<Module<TLanguage, PartialLangiumServices>>)
+      ) as unknown as TLanguage;
    };
 
    const primaryExtra = (languageModules.extra ?? []) as ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
-   const language = composeLanguage(languageModules.generated, languageModules.adopter, primaryExtra);
+   const primaryOverrides = languageModules.overrides ?? [];
+   const language = composeLanguage(languageModules.generated, languageModules.adopter, primaryExtra, primaryOverrides);
    const languages = [
       language,
       ...additionalLanguages.map(additional =>
-         composeLanguage(additional.generated, additional.adopter ?? languageModules.adopter, additional.extra ?? primaryExtra)
+         composeLanguage(
+            additional.generated,
+            additional.adopter ?? languageModules.adopter,
+            additional.extra ?? primaryExtra,
+            additional.overrides ?? primaryOverrides
+         )
       )
    ];
 

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

@@ -75,6 +75,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
@@ -317,10 +322,11 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          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 }], document.textDocument.version);
+      const textDocument = this.textDocuments.update(document.textDocument, [{ text: newText }], version);
 
       await this.syncCorrections(textDocument);
 
@@ -328,6 +334,14 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          // 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
@@ -340,6 +354,26 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          // 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);
+      }
    }
 
    /**