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

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 Disposable,
+   type Logger,
+   type Tracer,
+   asSnapshotVersion,
+   NO_MATCHING_VERSION
+} 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
@@ -417,8 +519,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 +593,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;
       }
    }