@hydranium/glsp-server 1.0.0-next.10

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

@@ -0,0 +1,337 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 GModelElement, GModelIndex } from '@eclipse-glsp/server';
+import { inject, injectable, optional } 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 { HydraniumTypes } from './hydranium-shared-core-services.js';
+
+/**
+ * GLSP model index extended with an AST-node ↔ id map so adopters can
+ * resolve diagram elements back to their source-language nodes during
+ * action handling, layout, validation, and submission.
+ *
+ * Indexing strategy is hookable via {@link doFindId}: the framework default
+ * uses {@link ElementKeyProvider.getElementKey} — a document-scoped lookup
+ * token built from the node's named ancestors, falling back to positional
+ * segments for unnamed nodes. Under the bound default that key is name-based,
+ * so a GModel id survives an edit that does not rename the node or an ancestor
+ * and changes when one does; the positional strategy is the rename-stable
+ * alternative. Adopters with a different stability boundary override
+ * {@link doFindId}.
+ *
+ * **Duplicate-id degrade.** A GModel tree must have unique element ids. Two
+ * AST nodes that collide on their stable id — exactly the state the diagram is
+ * meant to *mark* — project to two GModel elements with the same id. The GLSP
+ * client's sprotty `SGraphIndex.add` throws on such a duplicate inside
+ * `SModelFactory.initializeRoot`, aborting the build and blanking the WHOLE
+ * diagram. {@link indexRoot} prunes the colliding element(s) from the tree —
+ * the same object `ModelSubmissionHandler`
+ * submits — so the wire payload stays well-formed for every client and the
+ * surviving (first, document-order) element still carries the diagnostic
+ * marker. {@link doIndex} keeps a log-and-skip guard for any path that
+ * re-indexes a subtree without going through {@link indexRoot}.
+ */
+@injectable()
+export class HydraniumGlspIndex extends GModelIndex {
+   @inject(HydraniumTypes.SharedCoreServices) protected readonly sharedServices!: ServerSharedServices;
+
+   protected idToSemanticNode = new Map<string, AstNode>();
+
+   /**
+    * 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
+    * element can be drawn as several GModel nodes — placed twice on the same
+    * canvas, or projected by several referencing nodes.
+    * Populated explicitly by adopters via {@link registerElementId} (the forward
+    * {@link idToSemanticNode} keys by GModel id and can't express the same
+    * element rendering more than once). Consumed by diagnostic→marker mapping to
+    * find every node to mark for a given element.
+    *
+    * Keyed by the element's stable id (a string), NOT the `AstNode` itself, so
+    * it never retains AST node references across rebuilds. Cleared with the
+    * forward index in {@link indexSourceRoot}; re-registration each GModel
+    * rebuild is idempotent (a Set), and any id no longer drawn is filtered by
+    * the consumer's rendered-check, so stale entries are harmless.
+    */
+   protected elementToIds = new Map<string, Set<string>>();
+
+   /**
+    * The uris of the documents whose elements can map to a marker on this
+    * diagram: the diagram's own document (seeded in {@link indexSourceRoot})
+    * plus every document reached through a reference projection (added in
+    * {@link registerElementId}). Lets the diagnostic→marker validator resolve
+    * only the documents that actually contribute rendered elements rather than
+    * every loaded document. Self-maintaining: every {@link registerElementId}
+    * caller auto-includes its document.
+    */
+   protected renderedDocUris = new Set<string>();
+
+   /**
+    * Return the GModel id assigned to `node`, or — when no id is found and
+    * a `fallback` is supplied — the value of `fallback()`. The two-overload
+    * shape preserves the caller's narrowing: with a `() => string` fallback
+    * the return is `string`; with a `() => string | undefined` (or no
+    * fallback) the return is `string | undefined`.
+    *
+    * A convenience over {@link doFindId}, NOT the id-strategy hook. Framework
+    * internals call `doFindId` directly (see {@link indexSourceRoot}), so an
+    * override here changes only what external callers of this method see —
+    * override `doFindId` to change how nodes are keyed.
+    */
+   findId(node: AstNode | undefined, fallback: () => string): string;
+   findId(node: AstNode | undefined, fallback?: () => string | undefined): string | undefined;
+   findId(node: AstNode | undefined, fallback: () => string | undefined = () => undefined): string | undefined {
+      return this.doFindId(node) ?? fallback();
+   }
+
+   /**
+    * Hook for the adopter id-assignment strategy. Framework default reads
+    * {@link ElementKeyProvider.getElementKey} from the language owning `node`,
+    * which under the bound default is name-based and falls back to positional
+    * segments for unnamed nodes.
+    *
+    * `keyProvider` is an optional hint: the provider for THIS node, already
+    * resolved by the caller. {@link indexSourceRoot} passes it because every
+    * node in a containment walk belongs to the root's document by
+    * construction, so the per-node lookup would re-derive one known answer N
+    * times. An override that ignores the parameter stays correct, at the cost
+    * of that lookup.
+    */
+   protected doFindId(node?: AstNode, keyProvider?: ElementKeyProvider): string | undefined {
+      return (keyProvider ?? this.elementKeyProviderFor(node))?.getElementKey(node);
+   }
+
+   /**
+    * 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.
+    *
+    * **Resolved per node on the cross-document entry points.** This index is
+    * deliberately cross-document — {@link registerElementId} and
+    * {@link findElementIds} key elements reached through a reference, and
+    * {@link renderedDocUris} exists precisely because those live in other
+    * documents. A single captured provider therefore keys foreign nodes under
+    * the wrong grammar as soon as two registered languages differ in their key
+    * strategy: a plausible-looking id that matches nothing, so selection,
+    * marker mapping and element lookup silently miss. Those entry points are a
+    * bounded set the adopter calls explicitly; the full-document walk in
+    * {@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 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 the GModel id assigned to `node` or throw if none is available.
+    *
+    * The failure names the node's type and position rather than its source
+    * text. Interpolating `$cstNode.text` would put the user's own model content
+    * into a string that reaches a log, a client toast and an adopter's
+    * telemetry alike, so the exposure does not depend on which surface
+    * receives it. Type and position identify the node for whoever is debugging
+    * without carrying any of it, and positions are 1-based so they match what
+    * an editor shows.
+    */
+   assertId(node?: AstNode): string {
+      const id = this.findId(node);
+      if (!id) {
+         const start = node?.$cstNode?.range.start;
+         const at = start === undefined ? '' : ` at ${start.line + 1}:${start.character + 1}`;
+         throw new Error(`Could not create ID for ${node?.$type ?? 'an absent node'}${at}`);
+      }
+      return id;
+   }
+
+   /**
+    * Walk the source root and index every reachable AST node with a resolvable
+    * id.
+    *
+    * `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.
+    *
+    * 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
+    * and therefore the language just resolved. Looking it up per node would
+    * walk the container chain and Langium's whole lookup ladder — declared
+    * 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 {
+      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));
+   }
+
+   /**
+    * Register that the GModel element `id` renders `element` — the reverse of
+    * the GModel-id keying. Adopters call this when a GModel element represents
+    * an AST element that is *not* keyed by its own id — most importantly a
+    * diagram node keyed by its own id while visually standing for the element
+    * it references. Additive: registering the same `element` under several ids
+    * records every occurrence.
+    */
+   registerElementId(element: AstNode, id: string): void {
+      const key = this.doFindId(element);
+      if (key === undefined) {
+         return;
+      }
+      const ids = this.elementToIds.get(key);
+      if (ids) {
+         ids.add(id);
+      } else {
+         this.elementToIds.set(key, new Set([id]));
+      }
+      this.addRenderedDocUri(element);
+   }
+
+   /** The uris of the documents that contribute elements rendered on this diagram. */
+   renderedDocumentUris(): readonly string[] {
+      return [...this.renderedDocUris];
+   }
+
+   /** 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();
+      if (uri !== undefined) {
+         this.renderedDocUris.add(uri);
+      }
+   }
+
+   /** The GModel ids registered (via {@link registerElementId}) as rendering `element`; empty if none. */
+   findElementIds(element?: AstNode): readonly string[] {
+      const key = element ? this.doFindId(element) : undefined;
+      const ids = key !== undefined ? this.elementToIds.get(key) : undefined;
+      return ids ? [...ids] : [];
+   }
+
+   /** `keyProvider` is {@link doFindId}'s already-resolved hint; see {@link indexSourceRoot}. */
+   protected indexAstNode(node: AstNode, keyProvider?: ElementKeyProvider): void {
+      const id = this.doFindId(node, keyProvider);
+      if (id) {
+         this.indexSemanticElement(id, node);
+      }
+   }
+
+   /** 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);
+   }
+
+   /** Look up the AST node previously indexed under `id`. */
+   findSemanticElement(id: string): AstNode | undefined;
+   findSemanticElement<T extends AstNode>(id: string, guard: (item: unknown) => item is T): T | undefined;
+   findSemanticElement<T extends AstNode>(id: string, guard?: (item: unknown) => item is T): T | AstNode | undefined {
+      const semanticNode = this.idToSemanticNode.get(id);
+      if (guard) {
+         return guard(semanticNode) ? semanticNode : undefined;
+      }
+      return semanticNode;
+   }
+
+   /**
+    * Prune duplicate-id elements from the GModel tree, then index it.
+    *
+    * {@link GModelIndex.indexRoot} runs on the exact object the submission
+    * handler later serializes (`DefaultModelState.updateRoot` assigns
+    * `this.root = newRoot` immediately before `this.index.indexRoot(newRoot)`),
+    * so removing duplicates here also removes them from the submitted payload —
+    * the only place the fix protects every client rather than one tolerant one.
+    */
+   override indexRoot(root: GModelElement): void {
+      this.pruneDuplicateIds(root);
+      super.indexRoot(root);
+   }
+
+   /**
+    * Remove every element whose id was already seen earlier in a depth-first
+    * walk; the first occurrence (document order) wins and a dropped element
+    * takes its whole subtree with it. Splices in place so the parent's
+    * `children` array identity is preserved; logs each drop via the bound
+    * logger. The root itself is the first id seen and can never be a duplicate.
+    */
+   protected pruneDuplicateIds(root: GModelElement): void {
+      const seen = new Set<string>([root.id]);
+      const visit = (element: GModelElement): void => {
+         const children = element.children;
+         let index = 0;
+         while (index < children.length) {
+            const child = children[index];
+            if (seen.has(child.id)) {
+               this.sharedServices.Logger.for('Index').warn('Dropping duplicate element id from submitted graph: ' + child.id);
+               children.splice(index, 1); // drop child + subtree; do not advance — the next child shifts into `index`
+            } else {
+               seen.add(child.id);
+               visit(child);
+               index++;
+            }
+         }
+      };
+      visit(root);
+   }
+
+   /**
+    * Log-and-skip guard for duplicate GModel ids. {@link indexRoot}'s prune
+    * already removes duplicates from the tree before this runs, so in the
+    * normal flow this never fires; it stays as a last line of defence for any
+    * path that re-indexes a subtree directly (where {@link GModelIndex.doIndex}
+    * would otherwise throw).
+    */
+   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);
+         return;
+      }
+      super.doIndex(element);
+   }
+}

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

@@ -0,0 +1,92 @@
+/********************************************************************************
+ * 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 { ServerLanguageServices, ServerSharedServices } from '@hydranium/core';
+import type { ConflictResolver, Tracer } from '@hydranium/protocol';
+import { serviceIdentifier } from '../util/service-identifier.js';
+
+/**
+ * Inversify service-identifier registry for the framework services the
+ * `@hydranium/glsp-server` runtime exposes to `@injectable()` GLSP
+ * components. Framework GLSP-side classes are `@injectable()` and need an
+ * Inversify token to receive the Langium-style services the rest of the
+ * 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.
+ *
+ * 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** — 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`
+ *   when supplied, else a default `ReconcilingConflictResolver` (field-level
+ *   three-way merge) unless the adopter opts into `ForceConflictResolver`.
+ * - **Tracer** — the measure-and-emit observability handle (timing, memory,
+ *   profiling). Bound per-request, auto-tagged with the requesting class name
+ *   (mirroring GLSP's `LoggerFactory` caller-tagging), so an `@injectable()`
+ *   GLSP class that times just injects it and its timing lines carry its own
+ *   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
+ * `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
+ * component asks about several documents over its life — the diagram's own,
+ * the element it is editing, a drop target — so an injected provider instance
+ * answers as if there were one right answer and the routing decision vanishes
+ * from the call site. `this.candidateProvider` reads as language-neutral, and
+ * nothing prompts the author to ask which document the reference lives in;
+ * that is exactly how a foreign node ends up named under the diagram's
+ * grammar, producing a plausible string that matches nothing.
+ *
+ * So callers name the language they mean: `modelState.diagramLanguage` for a
+ * 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

@@ -0,0 +1,17 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './hydranium-glsp-index.js';
+export * from './abstract-hydranium-glsp-state.js';
+export * from './reconcile-source-model-write.js';
+export * from './reconciling-transfer-hydranium-glsp-state.js';
+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';

package/src/state/model-ready-timeout-error.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Thrown by `AbstractHydraniumGlspState.ready` when the wait for a document
+ * build state exceeds `AbstractHydraniumGlspState.readyTimeoutMs`. A dedicated
+ * error class so callers can distinguish a genuine hang from other failures
+ * via `instanceof`.
+ *
+ * The optional `diagnostic` carries a build-status snapshot so a captured log
+ * line is self-explanatory without correlating the timeout entry against
+ * earlier rebuild traces. `AbstractHydraniumGlspState.buildReadyTimeoutError`
+ * fills it from the document builder; a caller constructing the error directly
+ * may leave it empty.
+ */
+export class ModelReadyTimeoutError extends Error {
+   constructor(
+      public readonly uri: string,
+      public readonly targetState: string,
+      public readonly elapsedMs: number,
+      public readonly diagnostic: string = ''
+   ) {
+      const suffix = diagnostic ? ` ${diagnostic}` : '';
+      super(`Timed out after ${elapsedMs}ms waiting for state '${targetState}' on ${uri}.${suffix}`);
+      this.name = 'ModelReadyTimeoutError';
+   }
+}

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

@@ -0,0 +1,77 @@
+/********************************************************************************
+ * 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 ConflictResolver, type Logger, isConflictError } 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;
+   readonly logger: Logger;
+   /** Invoked when the edit is dropped, so the caller can resync its own state. */
+   onConflictDropped(): 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.
+ *
+ * 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".
+ */
+export async function reconcileSourceModelWrite<TModel extends object>(
+   model: TModel,
+   version: number | undefined,
+   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;
+      }
+   }
+}