@hydranium/core 1.0.0-next.7 → 1.0.0-next.71

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);
+      }
    }
 
    /**

package/src/langium/keys/containment.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/**
+ * Containment-array maintenance for callers that build or delete AST nodes
+ * programmatically — a GLSP operation handler being the usual one.
+ *
+ * **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
+ * `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
+ * wrong node. Shipping the constraint's statement without the code that
+ * discharges it leaves every adopter in that position re-deriving thirty lines
+ * from prose, and both failures are silent.
+ *
+ * The population is narrower than "anyone creating elements from a diagram": it
+ * takes a grammar with UNNAMED element types, programmatic creation or deletion
+ * of them, and this key provider. A grammar whose diagram elements are all
+ * named never reaches it, and the two ways out are named on the provider —
+ * give the type a name, or bind a provider whose fallback is content-derived.
+ *
+ * **Free functions, and deliberately not a step on the AST builder.** Building a
+ * node detached and appending it later is legitimate, so a containment step
+ * cannot be mandatory; and an optional fluent step could not check the index
+ * against the array unless it were handed the array, at which point it is these
+ * signatures with more ceremony. `AstNodeInit` already accepts the three fields
+ * for a caller who has them, which is the case these cover: it is the INDEX that
+ * cannot be known without reading the array.
+ */
+
+import type { AstNode } from '@hydranium/langium';
+import type { Mutable } from '@hydranium/protocol';
+
+/**
+ * Append `child` to `children`, stamping the Langium containment plumbing
+ * (`$container`, `$containerProperty`, `$containerIndex`) so a positional key
+ * can address it.
+ *
+ * `property` and `children` are separate parameters rather than one property
+ * name the function dereferences: the array is what the index is derived from,
+ * so taking it directly is what makes the two agree by construction instead of
+ * by a lookup that a typo could point elsewhere.
+ *
+ * @returns `child`, so a caller can append and use it in one expression.
+ */
+export function appendChild<TChild extends AstNode>(container: AstNode, property: string, children: TChild[], child: TChild): TChild {
+   const mutable = child as Mutable<TChild>;
+   mutable.$container = container;
+   mutable.$containerProperty = property;
+   mutable.$containerIndex = children.length;
+   children.push(child);
+   return child;
+}
+
+/**
+ * Remove every entry of `children` that is in `toRemove`, then renumber the
+ * survivors' `$containerIndex`.
+ *
+ * Mutates `children` in place rather than returning a new array, because the
+ * caller's array IS the AST's containment list — replacing the reference would
+ * leave the parent pointing at the old one.
+ *
+ * @returns how many entries were removed, so a caller can tell a no-op delete
+ * from one that changed the model without comparing lengths itself.
+ */
+export function removeChildren<TChild extends AstNode>(children: TChild[], toRemove: ReadonlySet<TChild>): number {
+   if (toRemove.size === 0) {
+      return 0;
+   }
+   const survivors = children.filter(child => !toRemove.has(child));
+   const removed = children.length - survivors.length;
+   children.length = 0;
+   for (const [index, child] of survivors.entries()) {
+      (child as Mutable<TChild>).$containerIndex = index;
+      children.push(child);
+   }
+   return removed;
+}

package/src/langium/keys/index.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './containment.js';
 export * from './element-key-provider.js';
 export * from './name-based-key-provider.js';
 export * from './positional-key-provider.js';

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

@@ -55,6 +55,10 @@ import { type NameProvider } from '../naming/name-provider.js';
  * - 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.
+ *
  * Adopters that need insert / delete stability for unnamed types should
  * give those types a name in the grammar, or bind a key provider whose
  * fallback is content-derived rather than positional.

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

@@ -11,6 +11,7 @@ import {
    type CanonicalUri,
    type CloseModelArgs,
    ConflictError,
+   defineMessage,
    Logger,
    type MaybeObservableValue,
    type MaybePromise,
@@ -34,6 +35,23 @@ import { labelPhaseListener } from '../document-builder/labeled-phase-listener.j
 import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
 import { type ServerSharedServices } from '../module.js';
 
+/**
+ * The undo-stack entry for a server-authored write pushed to the editor.
+ *
+ * **A user-facing LABEL, not a log string**, which is easy to miss because it
+ * travels as an options field rather than as a message: LSP specifies
+ * `ApplyWorkspaceEditParams.label` as "presented in the user interface for
+ * example on an undo stack to undo the workspace edit". So a user who edits
+ * through a form or drags a diagram node reads this in their editor's undo menu
+ * — which is why it is rendered like any other message the server sends rather
+ * than left as the English literal it was.
+ *
+ * Parameterless deliberately. The obvious improvement is to name the document,
+ * and it is the wrong one: an undo menu is already grouped under the file, so
+ * the URI would be noise in the one place it is redundant.
+ */
+export const MODEL_UPDATE_EDIT = defineMessage('hydranium/core/model-update-edit', 'Update Model');
+
 /** Max time {@link ModelService.settleSave} waits for the build to settle and the sync chain to drain. */
 const SAVE_SETTLE_TIMEOUT_MS = 10_000;
 
@@ -182,7 +200,74 @@ export interface ModelServiceOptions extends LogNameOptions {
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
  */
-export class ModelService<
+/**
+ * The seam every non-LSP head talks to: the data server, the GLSP head and an
+ * adopter's own services reach documents through this slot rather than through
+ * the workspace stores.
+ *
+ * **Two families, and the distinction matters more than the names suggest.**
+ * `waitFor*` is a pure wait — it never triggers a build, so a caller waiting on
+ * a document no build has touched waits until something else builds it.
+ * `ensureDocumentState` and the phase shorthands over it *dispatch*: warm
+ * documents are awaited, cold ones are built.
+ *
+ * **Diagnostics are typed `never` below `Validated`.** Validation is the last
+ * phase, so at any earlier landmark the array either is not yet computed or
+ * still holds the previous build's, and reading it would take stale results
+ * for fresh ones. A caller that needs diagnostics asks for {@link validated}.
+ *
+ * What the `never` buys, exactly: reading a field off an element is a compile
+ * error, and nothing can be appended. It does NOT stop a caller assigning an
+ * element to a typed variable, because `never` is assignable to everything — so
+ * this is a guard against reaching for diagnostics by accident, not a seal
+ * against doing it deliberately.
+ *
+ * The waits resolve at or ABOVE their target, so an already-validated document
+ * does carry usable diagnostics and the `never` over-forbids there. That
+ * direction is the safe one: the alternative permits stale reads silently. A
+ * member taking a phase as a PARAMETER cannot judge statically and so returns
+ * `TDiagnostic`, leaving the choice to the caller.
+ */
+export interface ModelService<TAst extends AstNode, TDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement> {
+   /**
+    * Resolves once the workspace has been initialised and its first build has
+    * completed — the gate every read should wait behind, since a document
+    * queried before it may be unbuilt and reach no phase.
+    *
+    * A property rather than a method, matching `ProjectManager.ready` and
+    * Langium's `WorkspaceManager.ready`. An implementation needing a stricter
+    * gate supplies a Promise that awaits its own concern as well.
+    */
+   readonly ready: Promise<void>;
+
+   // Pure waits — never trigger a build.
+   waitForDocumentState(uri: string, state: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   waitForBuilderState(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+
+   // Wait if warm, build if cold.
+   ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   rebuild(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   open(args: OpenModelArgs): Promise<Disposable>;
+   close(args: CloseModelArgs): Promise<void>;
+   isOpen(uri: string): boolean;
+   getDocument(uri: string): LangiumDocument | undefined;
+
+   onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+}
+
+export class DefaultModelService<
    TAst extends AstNode,
    TDiagnostic = TransferDiagnostic,
    /**
@@ -195,7 +280,7 @@ export class ModelService<
     * integrity service) that pass AST roots remain compatible.
     */
    TTransfer extends TransferElement = TransferElement
-> {
+> implements ModelService<TAst, TDiagnostic, TTransfer> {
    protected readonly tracer: Tracer;
    /**
     * The single document-identity seam (`services.workspace.DocumentUriPolicy`),
@@ -329,8 +414,12 @@ export class ModelService<
     * {@link waitForDocumentState} for the common "wait until content is stable"
     * case (e.g. settling a save). Pure wait — does not trigger a build.
     */
-   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken);
+   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
+      return (await this.waitForDocumentStateCanonical(
+         this.uriPolicy.canonicalUri(uri),
+         IntegrityService.SettledState,
+         cancelToken
+      )) as AstDocument<TAst, never>;
    }
 
    /**
@@ -484,11 +573,22 @@ export class ModelService<
     *
     * Phase invariants encoded in the return type:
     * - `parsed` / `linked` / `settled` / `indexed` return
-    *   `AstDocument<TAst, never>` — diagnostics array is empty by phase
-    *   contract.
+    *   `AstDocument<TAst, never>` — no diagnostics have been computed at
+    *   those phases.
     * - `validated` returns `AstDocument<TAst, TDiagnostic>` — diagnostics
     *   are populated.
     *
+    * **The `never` is a claim about the PHASE, not a guarantee about the
+    * instance, and the gap is reachable rather than theoretical.** The wait
+    * underneath resolves at or ABOVE the requested state, so a document
+    * something else already carried past `Validated` comes back from
+    * `settled()` with a populated diagnostics array typed `never`. Nothing
+    * strips it — the envelope copies the live document's array verbatim — and
+    * any host that validates its workspace before a consumer asks produces
+    * exactly that. So read an empty array as "none were computed, or there are
+    * none", never as "this document is clean", and call {@link validated} when
+    * the answer has to mean the second.
+    *
     * `settled` is the integrity-overlay name for "all integrity rules
     * have fired"; it maps to {@link IntegrityService.SettledState} (which
     * equals `DocumentState.IndexedReferences`), but the dedicated method
@@ -598,19 +698,29 @@ export class ModelService<
       // created from the payload rather than read from the filesystem — `update`
       // is an upsert. For an already-open document `open` refreshes content (the
       // text is ignored on that branch), so existing-document behaviour is
-      // unchanged. `version` is intentionally NOT forwarded to `open`: a cold
-      // create stays at its initial version, so a based-on-`version` update of a
-      // not-yet-existing document still trips the conflict gate below.
+      // unchanged. `version` is intentionally NOT forwarded to `open`, so a cold
+      // create stays at its initial version rather than adopting a number the
+      // caller chose.
+      //
+      // The gate's version is read BEFORE that open, and must be: for a document
+      // no client holds open, the open assigns the shared version from the
+      // INCOMING text, so a version read afterwards has already absorbed the
+      // caller's own write. Gating on it rejected every modifying write to a
+      // closed document, having compared the caller's `baseVersion` against a
+      // number the caller itself produced — and a serialised round-trip that is
+      // not byte-identical to the stored text was enough to trigger it. Reading
+      // first keeps both cases the gate exists for: an unknown URI answers 0, so
+      // a based-on-version update of a not-yet-existing document still trips it,
+      // and a genuine conflict still trips it, another writer having advanced the
+      // sequence past the version the caller read.
+      const currentVersion = this.services.workspace.TextDocuments.version(uri);
       const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
       await run('open', () => this.open({ uri, clientId: args.clientId, text }));
-      if (args.baseVersion !== undefined) {
-         const current = this.services.workspace.TextDocuments.version(uri);
-         if (current !== args.baseVersion) {
-            // Distinct from the post-build "superseded" debug line below: this is a
-            // based-on-stale rejection (the write never applies), not two writes racing.
-            this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${current}`);
-            throw new ConflictError(uri, args.baseVersion, current);
-         }
+      if (args.baseVersion !== undefined && currentVersion !== args.baseVersion) {
+         // Distinct from the post-build "superseded" debug line below: this is a
+         // based-on-stale rejection (the write never applies), not two writes racing.
+         this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${currentVersion}`);
+         throw new ConflictError(uri, args.baseVersion, currentVersion);
       }
       const appliedVersion = await run('apply', () => this.services.workspace.AstDocumentManager.update(uri, text, args.clientId));
       // Dispatch through the public `rebuild` (which re-canonicalizes the already-
@@ -834,17 +944,17 @@ export class ModelService<
     *
     * The signal is "a known client other than the language client authored this
     * version **and** the URI was in the last build's changed set
-    * (`isDirectChange`)". A framework-internal rebuild reports no author
+    * (`isTriggeringEdit`)". A framework-internal rebuild reports no author
     * (`getAuthor` → `undefined`), so it fails `hasKnownAuthor` without comparing
     * against a sentinel. This is NOT redundant with content/registration — it
     * distinguishes "client edited" from "framework rebuilt", which neither the
-    * shadow nor `isDirectChange` alone can.
+    * shadow nor `isTriggeringEdit` alone can.
     */
    protected isNonLanguageClientEdit(document: LangiumDocument): boolean {
       const documents = this.services.workspace.AstDocumentManager;
       const author = documents.getAuthor(document);
       const hasKnownAuthor = !!author && author !== LANGUAGE_CLIENT_ID;
-      return hasKnownAuthor && documents.isDirectChange(document.textDocument.uri);
+      return hasKnownAuthor && documents.isTriggeringEdit(document.textDocument.uri);
    }
 
    /**
@@ -878,13 +988,26 @@ export class ModelService<
       this.syncChains.set(uri, chain);
    }
 
+   /**
+    * The undo-stack label for a server-authored write, in the locale the server
+    * was handed at init.
+    *
+    * One method rather than the literal at each `applyEdit`, because the two
+    * call sites are the same edit — a push and its full-replace retry — and an
+    * undo menu showing two different words for one operation would read as two
+    * operations.
+    */
+   protected editLabel(): string {
+      return this.services.MessageRenderer.renderMessage(MODEL_UPDATE_EDIT);
+   }
+
    protected async drainSyncQueue(uri: string): Promise<void> {
       const uriLogger = this.tracer.withUri(uri);
       while (this.pendingSync.has(uri)) {
          const text = this.pendingSync.get(uri)!;
          this.pendingSync.delete(uri);
          try {
-            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
             if (result?.applied === false && !this.pendingSync.has(uri)) {
                // The push is addressed at the client's LAST DECLARED VERSION, so a
                // rejection normally means the client's buffer moved while the
@@ -905,7 +1028,7 @@ export class ModelService<
                // queued — best-effort, since a settle arriving later simply pushes
                // after this and still wins.
                uriLogger.warn(`Language client rejected applyEdit at its declared version — re-pushing a full replace`);
-               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
                if (result?.applied === false) {
                   uriLogger.warn(`Language client rejected the full-replace retry too — client content is stale`);
                }