@hydranium/glsp-server 1.0.0-next.8 → 1.0.0-next.85

package/lib/validation/hydranium-glsp-model-validator.js

@@ -75,7 +75,7 @@ let HydraniumGlspModelValidator = class HydraniumGlspModelValidator {
                 continue;
             }
             // Diagnostics are produced by the framework's `HydraniumDocumentValidator`,
-            // which emits `TransferLspDiagnostic` (LSP `Diagnostic` + `element` path).
+            // which emits `AstDiagnostic` (LSP `Diagnostic` + `element` path).
             // Parser/lexer diagnostics carry no `element`; the lookup drops them.
             const diagnostics = document.diagnostics;
             if (!diagnostics || diagnostics.length === 0) {

package/lib/validation/hydranium-glsp-model-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"hydranium-glsp-model-validator.js","sourceRoot":"","sources":["../../src/validation/hydranium-glsp-model-validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hydranium-glsp-model-validator.js","sourceRoot":"","sources":["../../src/validation/hydranium-glsp-model-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;;;;;;;;;;AAGlF,OAAO,EAAsB,UAAU,EAAuB,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAC5E,OAAO,EAAgC,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEI,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;IACyB,cAAc,CAAwB;IAC7D,UAAU,CAAqC;IAEtF,QAAQ,CAAC,SAA0B,EAAE,OAAgB;QAClD,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACJ,mEAAmE;QACnE,0EAA0E;QAC1E,wEAAwE;QACxE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAC;QACb,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QACpC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,uEAAuE;QACvE,qEAAqE;QACrE,cAAc;QACd,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,oBAAoB,EAAE,EAAE,CAAC;YAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,gBAAgB,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5F,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACb,SAAS;YACZ,CAAC;YACD,4EAA4E;YAC5E,mEAAmE;YACnE,sEAAsE;YACtE,MAAM,WAAW,GAAG,QAAQ,CAAC,WAA0C,CAAC;YACxE,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5C,SAAS;YACZ,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC;YACxC,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC;YACvG,MAAM,OAAO,GAA4B;gBACtC,cAAc,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC3E,cAAc,EAAE,OAAO,CAAC,EAAE;oBACvB,mEAAmE;oBACnE,sEAAsE;oBACtE,oEAAoE;oBACpE,sCAAsC;oBACtC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;oBAC1D,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;oBACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;wBAC1B,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBAC5B,CAAC;oBACD,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC;gBACrE,CAAC;aACH,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,OAAO,CAAC;IAClB,CAAC;CACH,CAAA;AA1DgE;IAA7D,MAAM,CAAC,cAAc,CAAC,kBAAkB,CAAC;;mEAA0D;AAC7D;IAAtC,MAAM,CAAC,UAAU,CAAC;;+DAAmE;AAF5E,2BAA2B;IADvC,UAAU,EAAE;GACA,2BAA2B,CA2DvC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/glsp-server",
-  "version": "1.0.0-next.8",
+  "version": "1.0.0-next.85",
   "description": "GLSP protocol head for the hydranium framework. Peer of @hydranium/core/lsp and @hydranium/data-server; built on @hydranium/core.",
   "keywords": [
     "hydranium",
@@ -48,6 +48,14 @@
       "types": "./lib/node/index.d.ts",
       "default": "./lib/node/index.js"
     },
+    "./messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
+    "./lib/messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
     "./testing": {
       "types": "./lib/testing/index.d.ts",
       "default": "./lib/testing/index.js"
@@ -79,9 +87,9 @@
   "devDependencies": {
     "@eclipse-glsp/protocol": "2.7.0",
     "@eclipse-glsp/server": "2.7.0",
-    "@hydranium/core": "1.0.0-next.8",
-    "@hydranium/langium": "1.0.0-next.8",
-    "@hydranium/protocol": "1.0.0-next.8",
+    "@hydranium/core": "1.0.0-next.85",
+    "@hydranium/langium": "1.0.0-next.85",
+    "@hydranium/protocol": "1.0.0-next.85",
     "inversify": "6.2.2",
     "reflect-metadata": "0.2.2",
     "rimraf": "^5.0.0",
@@ -92,12 +100,12 @@
   "peerDependencies": {
     "@eclipse-glsp/protocol": "^2.6.0",
     "@eclipse-glsp/server": "^2.6.0",
-    "@hydranium/core": "1.0.0-next.8",
-    "@hydranium/langium": "1.0.0-next.8",
-    "@hydranium/protocol": "1.0.0-next.8",
+    "@hydranium/core": "1.0.0-next.85",
+    "@hydranium/langium": "1.0.0-next.85",
+    "@hydranium/protocol": "1.0.0-next.85",
     "inversify": "^6.0.0",
     "reflect-metadata": "^0.2.2",
-    "vscode-jsonrpc": "^8.0.0 || ^9.0.0",
+    "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver-types": "^3.17.5"
   },
   "engines": {
@@ -106,6 +114,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. **This is the head where it is not enough**: `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship, so a first install of this package ALWAYS lands two copies and the adopter must pin the chain in their own manifest. docs/adopting/requirements.md carries the block to paste.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
   "//sideEffects": "The harness bare-imports `reflect-metadata`, which installs a global `Reflect` polyfill the inversify decorators in this package need before any container is built. That effect is invisible from the module's exports, so a bundler that treats the file as pure may reorder or drop the import and every `@injectable` resolution then fails at runtime. The rest of the package constructs no module-level state beyond frozen constants and DI symbols."
 }

package/src/command/hydranium-glsp-recording-command.ts

@@ -10,6 +10,7 @@
 import { type AnyObject, type JsonModelState, JsonRecordingCommand, type MaybePromise } from '@eclipse-glsp/server';
 import { type AstNode } from '@hydranium/langium';
 import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+import { type BasedOn } from '@hydranium/protocol';
 
 /**
  * Source-model state shape consumed by {@link HydraniumGlspRecordingCommand}.
@@ -46,25 +47,25 @@ export type HydraniumGlspRecordingState<TSourceModel extends AnyObject> = Abstra
  *
  * **postChange semantics.** GLSP's `JsonRecordingCommand.postChange` calls
  * `modelState.updateSourceModel(newModel)` with the model only. The
- * framework lift overrides `postChange` so it also threads the based-on
- * version captured at command start — letting the downstream
+ * framework lift overrides `postChange` so it also threads the snapshot
+ * version taken at command start — letting the downstream
  * `ModelService.update` opt into the `ConflictError` gate. Undo / redo
- * postChange calls run with version `undefined` (no gating): the user
- * authored against the recorded patch, not against a specific server
- * version, so re-applying it should succeed regardless of intervening
- * edits. The recorded patch itself encodes the semantic intent.
+ * postChange calls pass `'anything'`: the user authored against the recorded
+ * patch, not against a specific server version, so re-applying it should
+ * succeed regardless of intervening edits. The recorded patch itself encodes
+ * the semantic intent.
  */
 export class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> extends JsonRecordingCommand<TSourceModel> {
    declare protected modelState: HydraniumGlspRecordingState<TSourceModel>;
 
    /**
-    * Based-on version captured at {@link execute} start; threaded into
-    * {@link postChange} so {@link AbstractHydraniumGlspState.updateSourceModel}
-    * sees the version the user authored against. Cleared after `execute`
-    * returns so undo / redo paths fall through to `updateSourceModel`
-    * without a version (no gating).
+    * What the command was authored against, taken at {@link execute} start and
+    * threaded into {@link postChange} so
+    * {@link AbstractHydraniumGlspState.updateSourceModel} gates on it. Reset to
+    * `'anything'` after `execute` returns so undo / redo paths fall through
+    * ungated.
     */
-   protected activeVersion?: number;
+   protected activeBasedOn: BasedOn = 'anything';
 
    /**
     * Source-model snapshots captured at {@link execute} — the state the
@@ -98,20 +99,19 @@ export class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> exten
     * via {@link AbstractHydraniumGlspState.updateSourceModel}). The label combines
     * the operation name with the source-uri-stamped logger.
     *
-    * Captures {@link AbstractHydraniumGlspState.version} at start so {@link postChange}
-    * can thread the based-on version into `updateSourceModel`. The capture
-    * is `try`/`finally`-scoped so undo / redo paths invoked later do not
-    * see a stale captured version.
+    * Takes {@link AbstractHydraniumGlspState.basedOn} at start so {@link postChange}
+    * can thread it into `updateSourceModel`. Scoped with `try`/`finally` so undo
+    * / redo paths invoked later do not see a stale value.
     */
    override async execute(): Promise<void> {
       const logger = this.modelState.logger.for('HydraniumGlspRecordingCommand');
-      this.activeVersion = this.modelState.version;
-      logger.debug(`Executing '${this.label}' (based-on doc.version=v${this.activeVersion})`);
+      this.activeBasedOn = this.modelState.basedOn;
+      logger.debug(`Executing '${this.label}' (based-on doc.version=v${this.modelState.version})`);
       this.beforeSnapshot = this.deepClone(await this.getJsonObject());
       try {
          await this.modelState.tracer.for('HydraniumGlspRecordingCommand').time(`Execute command '${this.label}'`, () => super.execute());
       } finally {
-         this.activeVersion = undefined;
+         this.activeBasedOn = 'anything';
       }
       this.afterSnapshot = this.deepClone(await this.getJsonObject());
    }
@@ -119,15 +119,15 @@ export class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> exten
    /**
     * Override of GLSP's {@link JsonRecordingCommand.postChange} so the
     * call to {@link AbstractHydraniumGlspState.updateSourceModel} threads the
-    * captured based-on version alongside the new model.
+    * based-on version alongside the new model.
     *
-    * During {@link execute} the version is the snapshot captured at
-    * command start; during {@link undo} / {@link redo} it is `undefined`
-    * — replaying a recorded patch does not author against a specific
-    * server version, so no gate applies.
+    * During {@link execute} it is the snapshot version taken at command start;
+    * during {@link undo} / {@link redo} it is `'anything'` — replaying a
+    * recorded patch does not author against a specific server version, so no
+    * gate applies.
     */
    protected override postChange(newModel: TSourceModel): MaybePromise<void> {
-      return this.modelState.updateSourceModel(newModel, this.activeVersion);
+      return this.modelState.updateSourceModel(newModel, this.activeBasedOn);
    }
 
    /**

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

@@ -26,9 +26,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

package/src/messages/index.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * 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, SAVE_TARGET_UNKNOWN, SOURCE_URI_MISSING } from '../storage/hydranium-glsp-storage.js';

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

@@ -19,7 +19,15 @@ 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 Disposable,
+   type Logger,
+   type Tracer,
+   asSnapshotVersion
+} 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';
@@ -90,9 +98,9 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
    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 +123,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 +132,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 +249,34 @@ 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 `ModelService.update` /
+    * `.save` call 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.
+    *
     * 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 +284,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 +298,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 +307,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 +327,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 +354,44 @@ 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 the store does not know, matching what
+    * {@link version} reports for a document that was never opened.
     */
-   protected readDocumentVersion(uri: string): number {
-      return this.sharedServices.model.ModelService.getDocument(uri)?.textDocument?.version ?? 0;
+   protected readSnapshotVersion(uri: string): SnapshotVersion {
+      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));
       }
    }
 
@@ -417,8 +442,8 @@ export abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceM
       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.
+            // 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) {
                this.logger.warn(
@@ -491,13 +516,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 route through
+    * `ModelService.update` / `.save` forward it as the args' `basedOn` field;
+    * adopters whose write path doesn't go through `ModelService` 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. */
@@ -34,7 +34,7 @@ export interface FullTextSourceModel {
  *   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.
+ *   re-parsed root, gated on the caller's `basedOn`.
  *
  * No `baseline` / conflict reconcile: a whole-document model has exactly one
  * field, so every concurrent edit is a same-field collision and undo / redo
@@ -52,11 +52,12 @@ export class FullTextHydraniumGlspState<TRoot extends AstNode>
       return isPromiseLike(text) ? text.then(value => ({ text: value })) : { text };
    }
 
-   async updateSourceModel(model: FullTextSourceModel): Promise<void> {
+   async updateSourceModel(model: FullTextSourceModel, basedOn: BasedOn = this.basedOn): Promise<void> {
       const document = await this.sharedServices.model.ModelService.update({
          uri: this._sourceUri,
          model: model.text,
-         clientId: this.clientId
+         clientId: this.clientId,
+         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,11 +18,12 @@ 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. */
@@ -44,11 +45,11 @@ 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;
@@ -56,21 +57,23 @@ export async function reconcileSourceModelWrite<TModel extends object>(
       const outcome = await hooks.conflictResolver.resolve(hooks.baseline ?? 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;
       }
    }