@hydranium/glsp-server 1.0.0-next.31 → 1.0.0-next.313

package/src/state/diagram-status.ts

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+import type { ProposalString, SeverityLevel } from '@eclipse-glsp/server';
+
+/**
+ * Why a diagram is in a state its client has to show: the key an entry is set
+ * and withdrawn under in {@link AbstractHydraniumGlspState.setStatus}.
+ *
+ * Open, as GLSP's `EditMode` is: an adopter keys its own statuses with any
+ * other string. Each writer withdraws only its own key, so no writer clears a
+ * status another one still holds.
+ */
+export const DiagramStatus = {
+   /** The document does not parse, so the canvas refuses edits until it does. */
+   PARSE_ERROR: 'parse-error',
+   /** Live validation of the model is running. */
+   VALIDATION: 'validation',
+   /** The source model is loading. */
+   MODEL_LOAD: 'model-load',
+   /** The client asked for the diagram to be read-only. */
+   CLIENT_REQUEST: 'client-request'
+} as const;
+
+export type DiagramStatus = ProposalString<(typeof DiagramStatus)[keyof typeof DiagramStatus]>;
+
+/** What an active {@link DiagramStatus} does to the diagram. */
+export interface DiagramStatusEntry {
+   /** Shown in the client's status overlay; omitted when the status has nothing to say. */
+   readonly message?: string;
+   /** Picks which message is shown when several statuses carry one; the most recently set wins a tie. */
+   readonly severity?: Exclude<SeverityLevel, 'NONE' | 'OK'>;
+   /** Blocks editing while the status is active. */
+   readonly readonly?: boolean;
+}

package/src/state/full-text-hydranium-glsp-state.ts

@@ -11,7 +11,7 @@ import { type JsonModelState } from '@eclipse-glsp/server';
 import { injectable } from 'inversify';
 import { type AstNode } from '@hydranium/langium';
 import { URI } from '@hydranium/langium';
-import { isPromiseLike, type MaybePromise } from '@hydranium/protocol';
+import { type BaseVersion, isConflictError, isPromiseLike, type MaybePromise } from '@hydranium/protocol';
 import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.js';
 
 /** Whole-document-text source model: the serialised text of the source root. */
@@ -30,15 +30,17 @@ export interface FullTextSourceModel {
  * nothing beyond narrowing `TRoot` and their index:
  * - {@link sourceModel} serialises the source root through the per-URI
  *   `serializer.Serializer` reached via `sharedServices.ServiceRegistry`
- *   (so multi-grammar workspaces route to the right serializer). `MaybePromise`
- *   because serialization may be async; the sync fast path is preserved.
- * - {@link updateSourceModel} pushes the text back through
- *   `ModelService.update` (which accepts a raw text payload) and captures the
- *   re-parsed root.
+ *   (so multi-grammar workspaces route to the right serializer), keeping the
+ *   document's comments. `MaybePromise` because serialization may be async;
+ *   the sync fast path is preserved.
+ * - {@link updateSourceModel} pushes the text back through the diagram's
+ *   session (`update` accepts a raw text payload) and captures the re-parsed
+ *   root, gated on the caller's `baseVersion`; it throws without a session.
  *
- * No `baseline` / conflict reconcile: a whole-document model has exactly one
+ * No `base` / conflict reconcile: a whole-document model has exactly one
  * field, so every concurrent edit is a same-field collision and undo / redo
- * degrade to drop-on-divergence. Adopters that need field-level undo use
+ * degrade to drop-on-divergence, unless the text already holds what they
+ * write. Adopters that need field-level undo use
  * `ReconcilingTransferHydraniumGlspState` instead.
  */
 @injectable()
@@ -46,18 +48,44 @@ export class FullTextHydraniumGlspState<TRoot extends AstNode>
    extends AbstractHydraniumGlspState<TRoot, FullTextSourceModel>
    implements JsonModelState<FullTextSourceModel>
 {
+   /**
+    * The source root serialised, with the comments of the built document the
+    * captured root was parsed from re-attached through the language's trivia
+    * service, as a structured write's text gets them. The serializer emits
+    * none, so without them every write, undo and redo would delete them.
+    */
    get sourceModel(): MaybePromise<FullTextSourceModel> {
-      const serializer = this.sharedServices.ServiceRegistry.getServices(URI.parse(this._sourceUri)).serializer.Serializer;
-      const text = serializer.serializeAst(this._sourceRoot);
-      return isPromiseLike(text) ? text.then(value => ({ text: value })) : { text };
+      const uri = URI.parse(this._sourceUri);
+      const services = this.sharedServices.ServiceRegistry.getServices(uri);
+      const trivia = services.trivia?.TriviaService;
+      const document = this._sourceRoot.$document;
+      const extracted = trivia !== undefined && document !== undefined ? trivia.extract(document) : undefined;
+      const withTrivia = (text: string): FullTextSourceModel => ({
+         text: trivia !== undefined && extracted !== undefined ? trivia.apply(text, extracted, uri) : text
+      });
+      const text = services.serializer.Serializer.serializeAst(this.sourceRoot);
+      return isPromiseLike(text) ? text.then(withTrivia) : withTrivia(text);
    }
 
-   async updateSourceModel(model: FullTextSourceModel): Promise<void> {
-      const document = await this.sharedServices.model.ModelService.update({
-         uri: this._sourceUri,
-         model: model.text,
-         clientId: this.clientId
-      });
-      this.setSourceRoot(this._sourceUri, document.root as TRoot);
+   /**
+    * A write that conflicts while the store already holds `model.text`, as
+    * when an undo's side effect brought the text to the undo's result, is
+    * taken as applied; any other conflict is thrown.
+    */
+   async updateSourceModel(model: FullTextSourceModel, baseVersion: BaseVersion = this.baseVersion): Promise<void> {
+      let document: { root: AstNode };
+      try {
+         document = await this.requireModelSession().update({ uri: this._sourceUri, model: model.text, baseVersion });
+      } catch (error: unknown) {
+         if (isConflictError(error) && this.sharedServices.workspace.TextDocuments.get(this._sourceUri)?.getText() === model.text) {
+            this.logger.debug(
+               `updateSourceModel already applied (model v${error.baseVersion} / text v${error.actualVersion}); the document already holds the diagram edit`
+            );
+            this.captureBuiltRoot();
+            return;
+         }
+         throw error;
+      }
+      this.captureWrittenRoot(document.root as TRoot);
    }
 }

package/src/state/hydranium-glsp-index.ts

@@ -8,10 +8,11 @@
  ********************************************************************************/
 
 import { type GModelElement, GModelIndex } from '@eclipse-glsp/server';
-import { inject, injectable, optional } from 'inversify';
+import { inject, injectable } from 'inversify';
 import { type AstNode, AstUtils, type URI } from '@hydranium/langium';
-import * as uuid from 'uuid';
 import { type ElementKeyProvider, type ServerLanguageServices, type ServerSharedServices } from '@hydranium/core';
+import { randomUuid } from '@hydranium/protocol';
+import { workingUriOfCopy } from '../command/hydranium-glsp-operation-command.js';
 import { HydraniumTypes } from './hydranium-shared-core-services.js';
 
 /**
@@ -46,34 +47,24 @@ export class HydraniumGlspIndex extends GModelIndex {
 
    protected idToSemanticNode = new Map<string, AstNode>();
 
+   /**
+    * The entries {@link indexSemanticElement} added outside the walk, by id.
+    * Kept across {@link reindexSemanticElements}, which walks containment
+    * only and so cannot rebuild them, and moved with {@link remapSemanticAliases}.
+    */
+   protected semanticAliases = new Map<string, AstNode>();
+
+   /** Whether {@link reindexSemanticElements} is walking, so an entry it adds is not an alias. */
+   protected walking = false;
+
    /**
     * The language services of the diagram's OWN document, captured from the
     * source root in {@link indexSourceRoot}. Used only as the fallback for a
     * node that routes nowhere — a synthetic or freshly-built node with no
     * `$document` yet, which a GModel factory legitimately hands us mid-edit.
-    *
-    * Captured rather than injected because it is the language the loaded
-    * document ACTUALLY routes to, which is not necessarily the one the diagram
-    * module declared — precisely the drift
-    * `AbstractHydraniumGlspState.checkDeclaredLanguage` warns about. (Not
-    * a cost argument: {@link HydraniumTypes}.DiagramLanguage is bound
-    * `inSingletonScope`, so injecting it would resolve once per session too.)
     */
    protected diagramLanguage?: ServerLanguageServices;
 
-   /**
-    * The grammar the diagram module declared, as the last resort behind
-    * {@link diagramLanguage}.
-    *
-    * Order-independent where the captured one is not: GLSP builds every
-    * operation handler at `InitializeClientSession`, so a document-less node
-    * can reach {@link createId} before the first {@link indexSourceRoot} — and
-    * with no language at all that mints an unstable `fallback_<uuid>` where a
-    * stable positional key was available. `@optional()` so a harness that binds
-    * no diagram module still resolves.
-    */
-   @inject(HydraniumTypes.DiagramLanguage) @optional() protected readonly declaredLanguage?: ServerLanguageServices;
-
    /**
     * Reverse map: the *stable id* of the AST element a GModel element
     * represents → the GModel id(s) that render it. Multi-valued because one
@@ -140,8 +131,8 @@ export class HydraniumGlspIndex extends GModelIndex {
 
    /**
     * The {@link ElementKeyProvider} of the language owning `node`'s document,
-    * falling back to the language the diagram document routes to and then to
-    * the one its module declared, for a node that routes nowhere.
+    * falling back to the language the diagram document routes to for a node
+    * that routes nowhere.
     *
     * **Resolved per node on the cross-document entry points.** This index is
     * deliberately cross-document — {@link registerElementId} and
@@ -155,13 +146,24 @@ export class HydraniumGlspIndex extends GModelIndex {
     * {@link indexSourceRoot} needs no per-node lookup and does not pay for one.
     */
    protected elementKeyProviderFor(node?: AstNode): ElementKeyProvider | undefined {
-      const language = this.sharedServices.ServiceRegistry.getServicesFor(node) ?? this.diagramLanguage ?? this.declaredLanguage;
-      return language?.references.ElementKeyProvider;
+      return this.languageServicesFor(node)?.references.ElementKeyProvider;
+   }
+
+   /**
+    * The language services owning `node`, falling back to the diagram's
+    * language for a node that routes nowhere. A per-language lookup an index
+    * subclass adds goes through this, so an operation's copy of a node from
+    * another document reaches that document's language, as its built node does.
+    */
+   languageServicesFor(node?: AstNode): ServerLanguageServices | undefined {
+      // A copy node has no `$document`; it routes by its working root's URI.
+      const route = node === undefined ? undefined : workingUriOfCopy(node);
+      return this.sharedServices.ServiceRegistry.getServicesFor(route ?? node) ?? this.diagramLanguage;
    }
 
    /** Return the GModel id assigned to `node`, falling back to a fresh `fallback_<uuid>`. */
    createId(node?: AstNode): string {
-      return this.findId(node, () => 'fallback_' + uuid.v4());
+      return this.findId(node, () => 'fallback_' + randomUuid());
    }
 
    /**
@@ -186,14 +188,31 @@ export class HydraniumGlspIndex extends GModelIndex {
    }
 
    /**
-    * Walk the source root and index every reachable AST node with a resolvable
-    * id.
+    * Index `root` as a new source root: forget what {@link registerElementId}
+    * and {@link indexSemanticElement} recorded, seed the diagram document as
+    * rendered, and index the nodes through {@link reindexSemanticElements}.
+    */
+   indexSourceRoot(root: AstNode, uri?: URI | string): void {
+      this.semanticAliases.clear();
+      this.elementToIds.clear();
+      this.renderedDocUris.clear();
+      this.addRenderedDocUri(root);
+      this.reindexSemanticElements(root, uri);
+   }
+
+   /**
+    * Index the nodes of `root` by id, keeping what {@link registerElementId}
+    * and, outside the walk, {@link indexSemanticElement} recorded. For a root
+    * carrying the same ids as the one indexed, such as a working copy: those
+    * are made only when the GModel is built, and clearing them leaves
+    * diagnostics with no marker and an alias resolving to nothing until the
+    * next build. An alias still names its node; move it with
+    * {@link remapSemanticAliases}.
     *
-    * `uri` is the diagram document's URI, supplied by
-    * `AbstractHydraniumGlspState.setSourceRoot`, and is used only to
-    * resolve the diagram's language when `root` carries no `$document` —
-    * always the case for a synthesised root, and the more authoritative signal
-    * either way since it is what the caller declared it was loading.
+    * `uri` is the diagram document's URI and is used only to resolve the
+    * diagram's language when `root` carries no `$document` — always the case
+    * for a synthesised root or a working copy, and the more authoritative
+    * signal either way since it is what the caller declared it was loading.
     *
     * The walk resolves the key provider ONCE and threads it: `streamAllContents`
     * is containment-only, so every node it yields has `root` as its root node
@@ -202,15 +221,37 @@ export class HydraniumGlspIndex extends GModelIndex {
     * languageId, file name, extension — for an answer already in hand, on every
     * diagram open and every source-root refresh.
     */
-   indexSourceRoot(root: AstNode, uri?: URI | string): void {
+   reindexSemanticElements(root: AstNode, uri?: URI | string): void {
       this.idToSemanticNode.clear();
-      this.elementToIds.clear();
-      this.renderedDocUris.clear();
       const registry = this.sharedServices.ServiceRegistry;
       this.diagramLanguage = registry.getServicesFor(root) ?? registry.getServicesFor(uri);
-      this.addRenderedDocUri(root);
       const keyProvider = this.elementKeyProviderFor(root);
-      AstUtils.streamAllContents(root).forEach(node => this.indexAstNode(node, keyProvider));
+      this.walking = true;
+      try {
+         AstUtils.streamAllContents(root).forEach(node => this.indexAstNode(node, keyProvider));
+      } finally {
+         this.walking = false;
+      }
+      for (const [id, node] of this.semanticAliases) {
+         this.idToSemanticNode.set(id, node);
+      }
+   }
+
+   /**
+    * Point every alias {@link indexSemanticElement} added at `map(node)`, or
+    * drop it where that is `undefined`: the node it named is gone.
+    */
+   remapSemanticAliases(map: (node: AstNode) => AstNode | undefined): void {
+      for (const [id, node] of [...this.semanticAliases]) {
+         const mapped = map(node);
+         if (mapped === undefined) {
+            this.semanticAliases.delete(id);
+            this.idToSemanticNode.delete(id);
+         } else {
+            this.semanticAliases.set(id, mapped);
+            this.idToSemanticNode.set(id, mapped);
+         }
+      }
    }
 
    /**
@@ -242,7 +283,7 @@ export class HydraniumGlspIndex extends GModelIndex {
 
    /** Record `node`'s document uri (if it has one) as contributing rendered elements. */
    protected addRenderedDocUri(node: AstNode): void {
-      const uri = AstUtils.findRootNode(node).$document?.uri.toString();
+      const uri = AstUtils.findRootNode(node).$document?.uri.toString() ?? workingUriOfCopy(node);
       if (uri !== undefined) {
          this.renderedDocUris.add(uri);
       }
@@ -266,6 +307,9 @@ export class HydraniumGlspIndex extends GModelIndex {
    /** Insert an AST node under `id` directly — for adopters that need to seed entries outside the standard walk. */
    indexSemanticElement<T extends AstNode>(id: string, element: T): void {
       this.idToSemanticNode.set(id, element);
+      if (!this.walking) {
+         this.semanticAliases.set(id, element);
+      }
    }
 
    /** Look up the AST node previously indexed under `id`. */
@@ -329,7 +373,7 @@ export class HydraniumGlspIndex extends GModelIndex {
     */
    protected override doIndex(element: GModelElement): void {
       if (this.idToElement.has(element.id)) {
-         this.sharedServices.Logger.for('Index').error('Duplicate element id in graph: ' + element.id);
+         this.sharedServices.Logger.for('Index').warn('Skipping duplicate element id in graph: ' + element.id);
          return;
       }
       super.doIndex(element);

package/src/state/hydranium-shared-core-services.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { ServerLanguageServices, ServerSharedServices } from '@hydranium/core';
+import type { ServerSharedServices } from '@hydranium/core';
 import type { ConflictResolver, Tracer } from '@hydranium/protocol';
 import { serviceIdentifier } from '../util/service-identifier.js';
 
@@ -19,37 +19,23 @@ import { serviceIdentifier } from '../util/service-identifier.js';
  * framework hands around via plain constructor arguments.
  *
  * Every token here is a service whose value is **fixed for the container tier
- * that binds it** — process-wide shared services, a per-session conflict
- * policy, the grammar a diagram type edits. That is the whole membership rule,
- * and it is why the registry is short: see below for what deliberately does
- * NOT get a token.
+ * that binds it**: the shared services and the conflict policy for the
+ * process, the tracer for each request. That is the whole membership rule, and
+ * it is why the registry is short: see below for what deliberately does NOT
+ * get a token.
  *
  * Grouped under one object (rather than top-level `Hydranium<Role>` consts)
  * so the token identity is decoupled from the implementation class name.
  * Mirrors GLSP's own `TYPES` registry idiom.
  *
- * Bound by the adopter from their services trees — the app-tier ones directly,
- * the session-tier language by declaring a grammar on the diagram module.
- * Inject with the real service type as the field type.
- *
- * **Split by tier, because GLSP has no language tier.** GLSP's containers are
- * app (per process) -> server (per connection) -> session (per open diagram);
- * Langium's are shared (per process) -> language (per grammar, routed by URI).
- * Only the outermost pair line up. A per-language service therefore CANNOT be
- * bound at the app tier — that container is built before any document exists,
- * so it can only ever hold one grammar's services. The tokens below are split
- * accordingly:
+ * `SharedCoreServices` and `ConflictResolver` are bound by
+ * `HydraniumGlspAppModule`, `Tracer` by the launchers. Inject each with the
+ * real service type as the field type.
  *
  * - **SharedCoreServices** — the framework's Langium-style shared services
  *   tree ({@link ServerSharedServices}); the services-tree root that state /
  *   index classes inject. Bound once at the app tier. Carries
  *   `ServiceRegistry`, which is how everything below reaches a language.
- * - **DiagramLanguage** — the {@link ServerLanguageServices} of the grammar a
- *   diagram type edits, bound at the SESSION tier by
- *   `AbstractHydraniumGlspDiagramModule` from its declared `declareLanguage()`.
- *   Static (a diagram type has one grammar), so it is safe for the eagerly
- *   constructed handlers GLSP builds at `InitializeClientSession`. Read it
- *   through `AbstractHydraniumGlspState.diagramLanguage`.
  * - **ConflictResolver** — the policy the GLSP state consults when a write
  *   (forward-write, undo, redo, save) races a foreign edit.
  *   `HydraniumGlspAppModule` binds it to `options.conflictResolver`
@@ -62,8 +48,14 @@ import { serviceIdentifier } from '../util/service-identifier.js';
  *   component — no manual `for(...)`. The non-injectable recording command,
  *   which can't inject, borrows the state's `tracer` getter instead.
  *
- * **No per-language SERVICE has a token — only the language does.** There is
- * no `ElementKeyProvider`, `NameProvider`, `ScopeProvider` or
+ * **No language and no per-language service has a token, because GLSP has no
+ * language tier.** GLSP's containers are app (per process) -> server (per
+ * connection) -> session (per open diagram); Langium's are shared (per
+ * process) -> language (per grammar, routed by URI). Only the outermost pair
+ * line up. The app container is built before any document exists, and a
+ * session's handlers before its document is loaded, so neither knows the
+ * diagram's language: the one its loaded document routes to. Nor is there an
+ * `ElementKeyProvider`, `NameProvider`, `ScopeProvider` or
  * `CandidateProvider` symbol, because every one of them is keyed by a document
  * that the container cannot know: the target node's, for naming and keying;
  * the one a reference is WRITTEN in, for scope and candidates. A GLSP
@@ -79,14 +71,9 @@ import { serviceIdentifier } from '../util/service-identifier.js';
  * reference written on the canvas, `modelState.languageServicesFor(node)` for
  * anything reached through a reference. `ServiceRegistry.getServicesFor(target)`
  * serves the same purpose where no model state is at hand.
- *
- * The app-tier tokens are bound by `HydraniumGlspAppModule`, the
- * session-tier one by `AbstractHydraniumGlspDiagramModule`. A multi-grammar
- * adopter declares a language per diagram module and needs nothing else.
  */
 export const HydraniumTypes = {
    SharedCoreServices: serviceIdentifier<ServerSharedServices>('HydraniumSharedCoreServices'),
-   DiagramLanguage: serviceIdentifier<ServerLanguageServices>('HydraniumDiagramLanguage'),
    ConflictResolver: serviceIdentifier<ConflictResolver>('HydraniumConflictResolver'),
    Tracer: serviceIdentifier<Tracer>('HydraniumTracer')
 } as const;

package/src/state/index.ts

@@ -15,3 +15,4 @@ export * from './reconciling-multi-document-glsp-state.js';
 export * from './full-text-hydranium-glsp-state.js';
 export * from './hydranium-shared-core-services.js';
 export * from './model-ready-timeout-error.js';
+export * from './diagram-status.js';

package/src/state/reconcile-source-model-write.ts

@@ -7,71 +7,69 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type ConflictResolver, type Logger, isConflictError } from '@hydranium/protocol';
+import { type BaseVersion, type Logger, type ReconcileWriteHooks, reconcileWrite } from '@hydranium/protocol';
 
-/**
- * The I/O and policy a {@link reconcileSourceModelWrite} call needs. Deliberately
- * a plain record rather than a base class: the states that use it differ in what
- * "persist" and "project" mean but not at all in how a conflict is handled, and
- * pulling the orchestration out is what keeps that second half from being
- * written once per state.
- */
-export interface SourceModelWriteHooks<TModel> {
-   /**
-    * Write `model` and capture the resulting state. Called with a `baseVersion`
-    * on the first attempt (opting into the `ConflictError` gate) and without one
-    * on the merged / forced retries, where the point is to land the write.
-    */
-   persist(model: TModel, baseVersion?: number): Promise<void>;
-   /** Current server-side projection, or `undefined` when unavailable. */
-   refetch(): Promise<TModel | undefined>;
-   /** Last in-sync projection the user's intent is measured against. */
-   readonly baseline: TModel | undefined;
-   readonly conflictResolver: ConflictResolver;
+/** The I/O and policy a {@link reconcileSourceModelWrite} call needs. */
+export interface SourceModelWriteHooks<TModel> extends Omit<ReconcileWriteHooks<TModel>, 'onUnavailable'> {
    readonly logger: Logger;
    /** Invoked when the edit is dropped, so the caller can resync its own state. */
    onConflictDropped(): void;
+   /** Invoked when the document already held the edit, so the caller can take its built root. */
+   onAlreadyApplied(): void;
 }
 
 /**
- * Persist `model`, and on a `ConflictError` reconcile the user's intent against
- * the current server state via the injected policy and act on the outcome.
+ * {@link reconcileWrite} for a diagram edit: logs the outcome it ends, and
+ * resyncs through `onConflictDropped` when the edit is dropped, through
+ * `onAlreadyApplied` when the document already held it.
  *
- * One declarative policy shared by forward-write, undo and redo: force =
- * last-writer-wins, reconciling = field-level merge. A non-conflict error is
- * re-thrown untouched — this function only knows how to handle the specific
- * failure of "the based-on version was superseded".
+ * A conflict whose refetch is unavailable, the current text not readable to
+ * reconcile against, throws the `ConflictError` the write raised: forcing the
+ * edit would overwrite text the diagram never saw. An operation then rolls
+ * back and an undo or redo fails, as for any write that throws.
  */
 export async function reconcileSourceModelWrite<TModel extends object>(
    model: TModel,
-   version: number | undefined,
+   baseVersion: BaseVersion,
    hooks: SourceModelWriteHooks<TModel>
 ): Promise<void> {
-   try {
-      await hooks.persist(model, version);
-   } catch (err) {
-      if (!isConflictError(err)) {
-         throw err;
-      }
-      const outcome = await hooks.conflictResolver.resolve(hooks.baseline ?? model, model, () => hooks.refetch());
-      switch (outcome.status) {
-         case 'merged':
-            await hooks.persist(outcome.merged);
-            return;
-         case 'no-op':
-            hooks.logger.debug(`updateSourceModel no-op (v${err.expected} → v${err.actual}); already in sync`);
-            return;
-         case 'conflict':
-            hooks.logger.warn(
-               `updateSourceModel conflict (v${err.expected} → v${err.actual}); dropping the diagram edit — ` +
-                  'a foreign writer changed the same field'
-            );
-            hooks.onConflictDropped();
-            return;
-         case 'unavailable':
-            hooks.logger.warn(`updateSourceModel refetch unavailable (v${err.expected} → v${err.actual}); forcing without version`);
-            await hooks.persist(model);
-            return;
-      }
+   const outcome = await reconcileWrite(model, baseVersion, {
+      persist: (candidate, candidateBaseVersion) => hooks.persist(candidate, candidateBaseVersion),
+      refetch: () => hooks.refetch(),
+      base: hooks.base,
+      conflictResolver: hooks.conflictResolver,
+      maxWrites: hooks.maxWrites
+   });
+   if (outcome.status === 'persisted') {
+      return;
+   }
+   const { conflict, writes } = outcome;
+   const versions = `model v${conflict.baseVersion} / text v${conflict.actualVersion}`;
+   if (outcome.status === 'unavailable') {
+      // The conflict carries both versions to whoever ends the failure, which logs it; why it was not reconciled is diagnosis.
+      hooks.logger.debug(`updateSourceModel refetch unavailable (${versions}); the diagram edit fails rather than overwrite unread text`);
+      throw conflict;
+   }
+   switch (outcome.status) {
+      case 'merged':
+         hooks.logger.debug(`updateSourceModel merged (${versions}); landed on write ${writes}`);
+         return;
+      case 'already-applied':
+         hooks.logger.debug(`updateSourceModel already applied (${versions}); the document already holds the diagram edit`);
+         hooks.onAlreadyApplied();
+         return;
+      case 'unchanged':
+         hooks.logger.debug(`updateSourceModel no-op (${versions}); the diagram is behind, its update catches it up`);
+         return;
+      case 'conflict':
+         hooks.logger.warn(`updateSourceModel conflict (${versions}); dropping the diagram edit — a foreign writer changed the same field`);
+         hooks.onConflictDropped();
+         return;
+      case 'dropped':
+         hooks.logger.warn(
+            `updateSourceModel still conflicting after ${writes} ${writes === 1 ? 'write' : 'writes'} (${versions}); dropping the diagram edit`
+         );
+         hooks.onConflictDropped();
+         return;
    }
 }