@hydranium/glsp-server 1.0.0-next.12 → 1.0.0-next.127

package/src/launcher/abstract-hydranium-glsp-diagram-module.ts

@@ -7,11 +7,19 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { DiagramModule } from '@eclipse-glsp/server';
+import {
+   type ActionHandlerConstructor,
+   type BindingTarget,
+   type CommandStack,
+   DiagramModule,
+   type InstanceMultiBinding
+} from '@eclipse-glsp/server';
 import { injectable, type interfaces } from 'inversify';
 import type { LanguageMetaData } from '@hydranium/langium';
 import { type ServerLanguageServices, type ServerSharedServices, typedMetadata } from '@hydranium/core';
 import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+import { HydraniumGlspRequestSaveModelActionHandler } from '../storage/hydranium-glsp-request-save-model-action-handler.js';
+import { HydraniumGlspCommandStack } from '../command/hydranium-glsp-command-stack.js';
 
 /**
  * Bind {@link HydraniumTypes}.DiagramLanguage on a GLSP **session** container
@@ -20,8 +28,10 @@ import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
  * Exported separately from {@link AbstractHydraniumGlspDiagramModule} for adopters
  * whose diagram module already extends an intermediate base of their own and
  * cannot take the framework base class; call it from `configure` after
- * `super.configure(...)`. The base class is the preferred entry point because
- * it makes the declaration non-optional.
+ * `super.configure(...)`, add {@link HydraniumGlspRequestSaveModelActionHandler}
+ * in `configureActionHandlers`, and return {@link HydraniumGlspCommandStack} from
+ * `bindCommandStack`, all of which the base also does. The base class is the
+ * preferred entry point because it makes the declaration non-optional.
  *
  * **Why the session tier.** GLSP builds its app container once per process,
  * before any document exists, so a per-language service bound there can only
@@ -114,4 +124,18 @@ export abstract class AbstractHydraniumGlspDiagramModule extends DiagramModule {
       super.configure(bind, unbind, isBound, rebind);
       bindDiagramLanguage(bind, this.declareLanguage());
    }
+
+   /** {@link HydraniumGlspCommandStack}, so the diagram is dirty exactly while a document it has open is. */
+   protected override bindCommandStack(): BindingTarget<CommandStack> {
+      return HydraniumGlspCommandStack;
+   }
+
+   /**
+    * Adds {@link HydraniumGlspRequestSaveModelActionHandler}, the save the
+    * Theia client sends, beside GLSP's own save handler.
+    */
+   protected override configureActionHandlers(binding: InstanceMultiBinding<ActionHandlerConstructor>): void {
+      super.configureActionHandlers(binding);
+      binding.add(HydraniumGlspRequestSaveModelActionHandler);
+   }
 }

package/src/launcher/hydranium-glsp-server.ts

@@ -15,6 +15,7 @@ import {
    type RequestAction,
    type ResponseAction
 } from '@eclipse-glsp/server';
+import { RequestSaveModelAction } from '@hydranium/protocol';
 import { injectable } from 'inversify';
 
 /**
@@ -26,9 +27,10 @@ import { injectable } from 'inversify';
  * `error.cause?.toString()` whenever the error is a {@link GLSPServerError},
  * and that one value feeds both the server log and the client's
  * {@link RejectAction}. A {@link GLSPServerError} carrying no `cause` therefore
- * reaches no reader at all — not the toast, not the details pane, not the log —
- * while a plain `Error` survives, because the other branch reads the error
- * itself. The typed error is the trap, and it is the one upstream's own
+ * reaches its readers as `undefined` — the log line and the client's
+ * action-dispatcher warning both print it — while a plain `Error` survives,
+ * because the other branch reads the error itself. The typed error is the trap,
+ * and it is the one upstream's own
  * `getOrThrow` helper raises: that helper's signature cannot pass a `cause`, so
  * an adopter using the sanctioned helper has no fix available on their side.
  * Restating the cause at each throw site is the alternative, and it costs
@@ -63,9 +65,12 @@ export class HydraniumGlspServer extends DefaultGLSPServer {
    /**
     * Lifted verbatim from `@eclipse-glsp/server` 2.7.0's
     * {@link DefaultGLSPServer.handleClientRequest}, with the detail computation
-    * delegated to {@link requestFailureDetail}. Nothing else here — the
-    * timeout branch, the response dispatch, the nested send-failure handling —
-    * relates to that fallback.
+    * delegated to {@link requestFailureDetail}, and one addition: a failed
+    * {@link RequestSaveModelAction} also raises the error notification a failed
+    * `SaveModelAction` raises. A rejection reaches only the client's log, and a
+    * Theia host only logs a rejected save, so without it a save that failed
+    * would tell the user nothing. Nothing else here — the timeout branch, the
+    * response dispatch, the nested send-failure handling — relates to either.
     *
     * **This body does not track upstream.** A release that changes request
     * handling would silently not apply, on the path every request takes. There
@@ -96,6 +101,11 @@ export class HydraniumGlspServer extends DefaultGLSPServer {
                detail
             });
             this.sendResponseToClient(clientId, reject);
+            // Inside the guard: `process` does not await this method, so a
+            // closed connection throwing here would be an unhandled rejection.
+            if (action.kind === RequestSaveModelAction.KIND) {
+               this.handleProcessError({ clientId, action }, error);
+            }
          } catch (sendError: unknown) {
             this.logger.error(`Failed to send rejection for request '${action.requestId}':`, sendError);
          }

package/src/messages/index.ts

@@ -0,0 +1,30 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Every user-facing message `@hydranium/glsp-server` raises.
+ *
+ * **Each one is rendered AT ITS RAISE SITE**, through the shared
+ * `MessageRenderer`, because GLSP's action protocol carries no slot for an
+ * identity on any of its actions — so the identity is gone the moment a raise
+ * site formats its text, and there is nothing at the error boundary to render
+ * from. That makes this head the one place where a new message can ship
+ * unrendered without any single chokepoint noticing, which is why the package's
+ * own test suite scans for a declaration reached by `.format()` instead.
+ *
+ * The barrel is also how an adopter rendering their own diagram chrome
+ * discovers the codes exist.
+ */
+
+export {
+   DIAGRAM_READONLY_PARSE_ERROR,
+   DIAGRAM_SESSION_REFUSED,
+   SAVE_TARGET_UNKNOWN,
+   SOURCE_URI_MISSING
+} from '../storage/hydranium-glsp-storage.js';

package/src/node/start-glsp-server.ts

@@ -16,8 +16,7 @@ import {
    defaultSocketLaunchOptions
 } from '@eclipse-glsp/server/node.js';
 import { Container, type ContainerModule } from 'inversify';
-import type { Logger } from '@hydranium/protocol';
-import { Deferred } from '@hydranium/langium';
+import { Deferred, type Logger } from '@hydranium/protocol';
 import type * as net from 'node:net';
 import type { IntegratedServer } from '@hydranium/core';
 import { createGlspFrameworkOverrides } from '../launcher/glsp-framework-overrides.js';
@@ -177,7 +176,7 @@ export function startGlspServer(options: GlspServerOptions): StartedGlspServer {
             if (options.lspConnection && options.portCommand) {
                options.lspConnection.onRequest(options.portCommand, () => portHandle.port);
             }
-            lifecycle?.info(`[GlspServer] Ready to accept new client requests on port: ${address.port}`);
+            lifecycle?.info(`[GlspServer] Ready to accept new client requests on ${address.address} port: ${address.port}`);
             started.resolve();
          } else {
             const message = address === null ? 'address is null' : `bound to non-TCP "${String(address)}"`;

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

@@ -12,6 +12,7 @@ import { Emitter, type Event } from 'vscode-jsonrpc';
 import { inject, injectable, optional } from 'inversify';
 import { type AstNode, DocumentState, URI } from '@hydranium/langium';
 import {
+   type ClientSession,
    type HydraniumScopeProvider,
    type LanguageTarget,
    type NameProvider,
@@ -19,7 +20,16 @@ import {
    type ServerLanguageServices,
    type ServerSharedServices
 } from '@hydranium/core';
-import type { ConflictResolver, Disposable, Logger, Tracer } from '@hydranium/protocol';
+import {
+   type BasedOn,
+   type SnapshotVersion,
+   type ConflictResolver,
+   type Logger,
+   type Tracer,
+   asSnapshotVersion,
+   NO_MATCHING_VERSION,
+   TIMED_OUT
+} from '@hydranium/protocol';
 import { type HydraniumGlspIndex } from './hydranium-glsp-index.js';
 import { HydraniumTypes } from './hydranium-shared-core-services.js';
 import { ModelReadyTimeoutError } from './model-ready-timeout-error.js';
@@ -87,12 +97,38 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
    /** Narrows {@link DefaultModelState.index} to the framework-extended index type. */
    declare readonly index: HydraniumGlspIndex;
 
+   /**
+    * The client session this diagram works as, registered under `clientId` by
+    * the source-model storage and ended with the GLSP client session.
+    * `undefined` for GLSP's placeholder client, and when the id was held by
+    * another participant, in which case the diagram does not load.
+    *
+    * Every write of the diagram goes through this session, which writes only a
+    * document it has open and opens nothing. A one-shot write to a document
+    * outside the write set goes through
+    * {@link ClientSession.withOpen}, and a document the diagram brings into
+    * existence through {@link ClientSession.create}.
+    */
+   modelSession?: ClientSession<AstNode>;
+
+   /**
+    * {@link modelSession}, or a throw without one: the diagram never loaded or
+    * has ended. Looking `clientId` up through `ModelService.getSession` instead
+    * would write as whichever participant holds that id.
+    */
+   protected requireModelSession(): ClientSession<AstNode> {
+      if (!this.modelSession) {
+         throw new Error(`No client session is registered for ${this.clientId}; the diagram cannot write`);
+      }
+      return this.modelSession;
+   }
+
    protected _sourceUri!: string;
    protected _sourceRoot!: TRoot;
    protected _tracer?: Tracer;
-   protected _version: number = 0;
-   /** Based-on versions of the secondary write set, keyed by URI. See {@link trackSecondaryDocument}. */
-   protected readonly _secondaryVersions = new Map<string, number>();
+   protected _basedOn: SnapshotVersion = asSnapshotVersion(0);
+   /** Snapshot versions of the secondary write set, keyed by URI. See {@link trackSecondaryDocument}. */
+   protected readonly _secondaryVersions = new Map<string, SnapshotVersion>();
 
    /** Backing emitter for {@link onSecondaryUrisChanged}; fired only on a membership change. */
    protected readonly secondaryUrisChangedEmitter = new Emitter<void>();
@@ -115,7 +151,7 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
    setSourceRoot(uri: string, root: TRoot): void {
       this._sourceUri = uri;
       this._sourceRoot = root;
-      this._version = this.readDocumentVersion(uri);
+      this._basedOn = this.readSnapshotVersion(uri);
       // Re-read the secondary write set for the same reason the primary is
       // re-read: the write that brought us here advanced their versions too, and
       // a stale based-on version would gate the NEXT command against a
@@ -124,7 +160,7 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
       this.refreshSecondaryVersions();
       this.set(SOURCE_URI_ARG, uri);
       this._tracer = this.baseTracer.withUri(uri);
-      this.tracer.debug(`Captured source root at doc.version=v${this._version}`);
+      this.tracer.debug(`Captured source root at doc.version=v${this._basedOn}`);
       this.checkDeclaredLanguage(uri);
       this.index.indexSourceRoot(root, uri);
    }
@@ -241,25 +277,36 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
    }
 
    /**
-    * Text-document version captured at the last {@link setSourceRoot}
-    * call. Mirrors the server-side `TextDocuments.version(uri)` counter
-    * at that point in time — frozen until the next `setSourceRoot`, then
-    * re-read from `LangiumDocuments`.
+    * Snapshot version taken at the last {@link setSourceRoot} call — frozen
+    * until the next one, then re-read from the document store.
     *
     * Threaded by `HydraniumGlspRecordingCommand` into
-    * {@link updateSourceModel}'s optional `version` parameter so the
-    * downstream `ModelService.update` / `.save` call can opt into the
-    * conflict gate against the captured based-on version. See
+    * {@link updateSourceModel} so the downstream session `update` / `save`
+    * gates against what the command was authored on. See
     * `@hydranium/protocol#ConflictError` for the detection contract.
     *
+    * **This, not a number read at write time, is what a write must be gated
+    * on.** A version read when the write is issued is the store's current one,
+    * so it matches by construction and the gate can never fire.
+    */
+   get basedOn(): SnapshotVersion {
+      return this._basedOn;
+   }
+
+   /**
+    * Text-document version of {@link basedOn}. Mirrors the server-side
+    * `TextDocuments.version(uri)` counter as of the snapshot, or is
+    * `NO_MATCHING_VERSION` when the store's text could not be tied to the
+    * root (see {@link readSnapshotVersion}).
+    *
     * Falls back to `0` when the document is absent from `LangiumDocuments`
-    * at capture time — the same observable state callers see for a doc
-    * that was never opened. Callers that need to distinguish
+    * when the snapshot is taken — the same observable state callers see for a
+    * doc that was never opened. Callers that need to distinguish
     * "never-versioned" from "v0" must consult the document registry
     * directly.
     */
    get version(): number {
-      return this._version;
+      return this._basedOn;
    }
 
    // ============================================================
@@ -267,8 +314,8 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
    // ============================================================
 
    /**
-    * Register `uri` as a document this state also writes, capturing its current
-    * text-document version.
+    * Register `uri` as a document this state also writes, snapshotting its
+    * current text-document version.
     *
     * A diagram whose layout lives in its own file, or whose canvas creates
     * elements in a referenced semantic document, writes more than the document
@@ -281,7 +328,7 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
     * identified once the operation names the node. What the framework supplies
     * is the part an adopter cannot reconstruct after the fact — the version each
     * document was at BEFORE the command mutated anything (see
-    * {@link capturedVersionOf}). Idempotent; registering the primary is ignored,
+    * {@link snapshotVersionOf}). Idempotent; registering the primary is ignored,
     * since {@link version} already tracks it. Registering a URI not already in
     * the set fires {@link onSecondaryUrisChanged}.
     */
@@ -290,7 +337,7 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
          return;
       }
       const added = !this._secondaryVersions.has(uri);
-      this._secondaryVersions.set(uri, this.readDocumentVersion(uri));
+      this._secondaryVersions.set(uri, this.readSnapshotVersion(uri));
       if (added) {
          this.secondaryUrisChangedEmitter.fire();
       }
@@ -310,14 +357,15 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
 
    /**
     * Fires whenever the secondary write set gains or loses a URI — never when a
-    * tracked document's captured version is merely refreshed, which happens on
+    * tracked document's snapshot version is merely refreshed, which happens on
     * every {@link setSourceRoot} and changes nothing a subscriber cares about.
     *
     * **This exists so no caller has to know when the set can change.** The set is
     * usually discovered rather than known, and the discovery point is an
-    * operation handler naming a node — not a capture. A subscriber that instead
-    * re-derived the set after each capture would miss exactly that case, and miss
-    * it silently: the document would simply never be watched, with nothing logged.
+    * operation handler naming a node — not a read of the source root. A
+    * subscriber that instead re-derived the set after each such read would miss
+    * exactly that case, and miss it silently: the document would simply never be
+    * watched, with nothing logged.
     * Announcing the change here moves the obligation to the one place that can
     * always discharge it.
     *
@@ -336,37 +384,69 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
    }
 
    /**
-    * Based-on version captured for `uri` — {@link version} for the primary, the
-    * value captured at {@link trackSecondaryDocument} (refreshed by
-    * {@link setSourceRoot}) for a secondary, `undefined` for anything untracked.
+    * Snapshot version for `uri` — {@link basedOn} for the primary, the version
+    * taken at {@link trackSecondaryDocument} (refreshed by {@link setSourceRoot})
+    * for a secondary, `undefined` for anything untracked.
     *
-    * `undefined` rather than `0` for an untracked URI deliberately: `0` is a real
+    * `undefined` rather than v0 for an untracked URI deliberately: `0` is a real
     * version meaning "present but never edited", so collapsing the two would let
-    * a caller gate a write against a document it never captured.
+    * a caller gate a write against a document this state never read.
     */
-   capturedVersionOf(uri: string): number | undefined {
+   snapshotVersionOf(uri: string): SnapshotVersion | undefined {
       if (uri === this._sourceUri) {
-         return this._version;
+         return this._basedOn;
       }
       return this._secondaryVersions.get(uri);
    }
 
    /**
-    * Read a document's current text-document version through the model service's
-    * canonicalizing gateway, so a URI spelled through a symlink still resolves to
-    * the document keyed by its real path rather than stranding at `0` (which
-    * would silently weaken the conflict gate). Optional-chained on `textDocument`
-    * so a fixture that omits it does not throw; real Langium documents always
-    * populate it.
+    * Read a document's version out of the live store and mark it as a snapshot,
+    * through the model service's canonicalizing gateway so a URI spelled through
+    * a symlink still resolves to the document keyed by its real path rather than
+    * stranding at `0` (which would silently weaken the conflict gate).
+    *
+    * **Call this only at the point the source root is read.** It is the one
+    * place the framework turns a live version into a snapshot one, and the value
+    * is true only because that is where it is called. Called at write time it
+    * answers with the version the write is about to be compared against, so the
+    * gate passes unconditionally.
+    *
+    * Falls back to v0 for a URI neither store knows, matching what
+    * {@link version} reports for a document that was never opened.
+    *
+    * **The version of the text store, which the gate compares against.**
+    * When the store holds the text the root was parsed from, that is its
+    * version, even while the built document still carries an older number.
+    * When the store holds other text, `NO_MATCHING_VERSION`, so the write
+    * conflicts instead of overwriting text the root never saw: the
+    * reconciling states reconcile it, `FullTextHydraniumGlspState` throws the
+    * `ConflictError`. When the root keeps no syntax tree to read its text
+    * from, the built document's text stands in for it, unless the built
+    * document IS the store's, whose text says nothing about what was parsed;
+    * that also gets `NO_MATCHING_VERSION`.
     */
-   protected readDocumentVersion(uri: string): number {
-      return this.sharedServices.model.ModelService.getDocument(uri)?.textDocument?.version ?? 0;
+   protected readSnapshotVersion(uri: string): SnapshotVersion {
+      const document = this.sharedServices.model.ModelService.getDocument(uri);
+      const stored = document && this.sharedServices.workspace.TextDocuments.get(uri);
+      if (stored) {
+         const parsed = document.parseResult.value.$cstNode?.root.fullText;
+         if (parsed !== undefined) {
+            return parsed === stored.getText() ? asSnapshotVersion(stored.version) : NO_MATCHING_VERSION;
+         }
+         if (document.textDocument === stored) {
+            return NO_MATCHING_VERSION;
+         }
+         if (stored.version !== document.textDocument.version && stored.getText() === document.textDocument.getText()) {
+            return asSnapshotVersion(stored.version);
+         }
+      }
+      return this.sharedServices.model.ModelService.snapshot(uri)?.version ?? asSnapshotVersion(0);
    }
 
-   /** Re-read every registered secondary's version from the document store. */
+   /** Re-take every registered secondary's snapshot version from the document store. */
    protected refreshSecondaryVersions(): void {
       for (const uri of [...this._secondaryVersions.keys()]) {
-         this._secondaryVersions.set(uri, this.readDocumentVersion(uri));
+         this._secondaryVersions.set(uri, this.readSnapshotVersion(uri));
       }
    }
 
@@ -392,6 +472,28 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
       }
    }
 
+   /**
+    * The root that `uri`'s text parses to (the text store's, or the built
+    * document's when the store holds none), read once the document has
+    * validated; `undefined` when it cannot be read.
+    *
+    * **Parsed afresh, never the built root.** Operation handlers edit the
+    * built root in place, so until a rebuild replaces it, it already holds
+    * the edit being reconciled, and replaying the edit onto it applies it
+    * twice. The root is parsed, not linked: an encoder hook reading a
+    * reference's `ref` sees `undefined` on it.
+    */
+   protected async readCurrentRoot(uri: string): Promise<AstNode | undefined> {
+      const modelService = this.sharedServices.model.ModelService;
+      if (!(await modelService.validated(uri).catch(() => undefined))) {
+         return undefined;
+      }
+      const text = this.sharedServices.workspace.TextDocuments.get(uri)?.getText() ?? modelService.getDocument(uri)?.textDocument.getText();
+      return text === undefined
+         ? undefined
+         : this.sharedServices.workspace.LangiumDocumentFactory.fromString(text, URI.parse(uri)).parseResult.value;
+   }
+
    /**
     * Wait until the captured document reaches `state`, then run
     * {@link onReadyRefreshed} so consumers see a fresh AST. Wraps the
@@ -412,31 +514,21 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
    protected async readyWithTimeout(state: DocumentState): Promise<void> {
       const uri = this._sourceUri;
       const stopwatch = this.sharedServices.Clock.stopwatch();
-      let timer: Disposable | undefined;
-
-      const timeout = new Promise<void>((resolve, reject) => {
-         timer = this.sharedServices.Clock.setTimer(() => {
-            const elapsed = Math.round(stopwatch.elapsedMs);
-            // Via the canonicalizing gateway (see `readDocumentVersion`), so a
-            // symlinked `_sourceUri` is not reported as a hard timeout.
-            const doc = this.sharedServices.model.ModelService.getDocument(uri);
-            if (doc && doc.state >= state) {
-               this.logger.warn(
-                  `Missed '${DocumentState[state]}' notification after ${elapsed}ms; document is already at state ` +
-                     `'${DocumentState[doc.state]}'. Likely a Langium build-phase event race.`
-               );
-               resolve();
-            } else {
-               reject(this.buildReadyTimeoutError(state, elapsed));
-            }
-         }, this.readyTimeoutMs);
-      });
-
-      try {
-         await Promise.race([this.sharedServices.model.ModelService.waitForDocumentState(uri, state), timeout]);
-      } finally {
-         timer?.dispose();
+      const reached = this.sharedServices.model.ModelService.waitForDocumentState(uri, state);
+      if ((await this.sharedServices.Clock.raceTimer(reached, this.readyTimeoutMs)) !== TIMED_OUT) {
+         return;
+      }
+      const elapsed = Math.round(stopwatch.elapsedMs);
+      // Through the model service's canonicalizing gateway, so a symlinked
+      // `_sourceUri` is not reported as a hard timeout.
+      const doc = this.sharedServices.model.ModelService.getDocument(uri);
+      if (!doc || doc.state < state) {
+         throw this.buildReadyTimeoutError(state, elapsed);
       }
+      this.logger.warn(
+         `Missed '${DocumentState[state]}' notification after ${elapsed}ms; document is already at state ` +
+            `'${DocumentState[doc.state]}'. Likely a Langium build-phase event race.`
+      );
    }
 
    /**
@@ -491,13 +583,22 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
     * `JsonModelState` shape meet the framework state via structural
     * intersection at the recording-command call site.
     *
-    * `version` is the based-on text-document version captured at command
-    * start by `HydraniumGlspRecordingCommand.execute`. Adopters that
-    * route through `ModelService.update` / `.save` pass it as the args'
-    * `version` field to opt into the conflict gate; adopters that don't
-    * care (or whose write path doesn't go through `ModelService`) ignore
-    * the parameter. Undefined when the writer is not the recording-command
-    * (e.g. external storage refresh paths).
+    * `basedOn` is the snapshot version taken at command start by
+    * `HydraniumGlspRecordingCommand.execute`. Adopters that write through the
+    * diagram's session forward it as the args' `basedOn` field; adopters whose
+    * write path doesn't go through the session ignore it.
+    * `'anything'` when the writer is not the recording command (an external
+    * storage refresh, an undo replaying a recorded patch), which is a write
+    * authored against no particular server version.
+    *
+    * **Optional, and every implementation must default it to {@link basedOn}
+    * rather than to `'anything'`.** Optional is forced: GLSP's `JsonModelState`
+    * declares a one-parameter `updateSourceModel` and calls it with one
+    * argument, so a second required parameter makes the state unassignable to
+    * the slot it has to fill. Defaulting to the state's own snapshot version is
+    * what keeps that from costing anything — an operation handler calling
+    * `updateSourceModel(model)` gets the gate, and skipping it has to be typed
+    * out as `'anything'`.
     */
-   abstract updateSourceModel(model: TSourceModel, version?: number): MaybePromise<void>;
+   abstract updateSourceModel(model: TSourceModel, basedOn?: BasedOn): MaybePromise<void>;
 }

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 BasedOn, 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. */
@@ -32,11 +32,11 @@ export interface FullTextSourceModel {
  *   `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.
+ * - {@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 `basedOn`; 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
  * `ReconcilingTransferHydraniumGlspState` instead.
@@ -52,12 +52,8 @@ export class FullTextHydraniumGlspState<TRoot extends AstNode>
       return isPromiseLike(text) ? text.then(value => ({ text: value })) : { text };
    }
 
-   async updateSourceModel(model: FullTextSourceModel): Promise<void> {
-      const document = await this.sharedServices.model.ModelService.update({
-         uri: this._sourceUri,
-         model: model.text,
-         clientId: this.clientId
-      });
+   async updateSourceModel(model: FullTextSourceModel, basedOn: BasedOn = this.basedOn): Promise<void> {
+      const document = await this.requireModelSession().update({ uri: this._sourceUri, model: model.text, basedOn });
       this.setSourceRoot(this._sourceUri, document.root as TRoot);
    }
 }

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

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type ConflictResolver, type Logger, isConflictError } from '@hydranium/protocol';
+import { type BasedOn, type ConflictResolver, type Logger, isConflictError } from '@hydranium/protocol';
 
 /**
  * The I/O and policy a {@link reconcileSourceModelWrite} call needs. Deliberately
@@ -18,15 +18,16 @@ import { type ConflictResolver, type Logger, isConflictError } from '@hydranium/
  */
 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.
+    * Write `model` and record the resulting state. Called with the caller's own
+    * `basedOn` on the first attempt (opting into the `ConflictError` gate) and
+    * with `'anything'` on the merged / forced retries, where the reconcile has
+    * already decided to win and the point is to land the write.
     */
-   persist(model: TModel, baseVersion?: number): Promise<void>;
+   persist(model: TModel, basedOn: BasedOn): 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;
+   /** The last in-sync projection the user's intent is measured against. */
+   readonly base: TModel | undefined;
    readonly conflictResolver: ConflictResolver;
    readonly logger: Logger;
    /** Invoked when the edit is dropped, so the caller can resync its own state. */
@@ -44,33 +45,35 @@ export interface SourceModelWriteHooks<TModel> {
  */
 export async function reconcileSourceModelWrite<TModel extends object>(
    model: TModel,
-   version: number | undefined,
+   basedOn: BasedOn,
    hooks: SourceModelWriteHooks<TModel>
 ): Promise<void> {
    try {
-      await hooks.persist(model, version);
+      await hooks.persist(model, basedOn);
    } catch (err) {
       if (!isConflictError(err)) {
          throw err;
       }
-      const outcome = await hooks.conflictResolver.resolve(hooks.baseline ?? model, model, () => hooks.refetch());
+      const outcome = await hooks.conflictResolver.resolve(hooks.base ?? model, model, () => hooks.refetch());
       switch (outcome.status) {
          case 'merged':
-            await hooks.persist(outcome.merged);
+            await hooks.persist(outcome.merged, 'anything');
             return;
          case 'no-op':
-            hooks.logger.debug(`updateSourceModel no-op (v${err.expected} → v${err.actual}); already in sync`);
+            hooks.logger.debug(`updateSourceModel no-op (v${err.expectedVersion} → v${err.actualVersion}); already in sync`);
             return;
          case 'conflict':
             hooks.logger.warn(
-               `updateSourceModel conflict (v${err.expected} → v${err.actual}); dropping the diagram edit — ` +
+               `updateSourceModel conflict (v${err.expectedVersion} → v${err.actualVersion}); 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);
+            hooks.logger.warn(
+               `updateSourceModel refetch unavailable (v${err.expectedVersion} → v${err.actualVersion}); forcing without version`
+            );
+            await hooks.persist(model, 'anything');
             return;
       }
    }