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

package/src/state/reconciling-multi-document-glsp-state.ts

@@ -10,7 +10,8 @@
 import { type JsonModelState } from '@eclipse-glsp/server';
 import { injectable } from 'inversify';
 import { type AstNode } from '@hydranium/langium';
-import { type TransferElement } from '@hydranium/protocol';
+import { type ClientSession, type ClientSessionWriteArgs } from '@hydranium/core';
+import { type BasedOn, type TransferElement } from '@hydranium/protocol';
 import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.js';
 import { reconcileSourceModelWrite } from './reconcile-source-model-write.js';
 
@@ -44,35 +45,22 @@ export interface MultiDocumentSourceModel<TPrimary extends TransferElement = Tra
  * defines them over the primary plus the secondary write set registered through
  * {@link AbstractHydraniumGlspState.trackSecondaryDocument}.
  *
- * **Writes are NOT atomic, deliberately, and the window is real.** Each document
- * goes through its own `ModelService.update`, so a failure after the first write
- * has landed leaves the set inconsistent on disk. There is no multi-document
- * transaction to lean on: `WorkspaceLock` serialises builds but does not roll
- * back, and the document store commits per URI. An adopter that cannot accept the
- * window should not span documents in one operation.
+ * **The write set is written all or none.** {@link persist} hands every
+ * changed document to one `ClientSession.updateAll` on the diagram's session,
+ * so a conflict on any document leaves every document of the set as it was,
+ * and write order carries no meaning.
  *
- * **What makes the window tolerable is write ORDER, and the rule is
- * referenced-before-referencing** — not "secondaries first" as such. Write the
- * document whose content the others point AT before the documents that point at
- * it, so a partial write leaves an unreferenced element (inert, and the direction
- * an integrity rule can repair) rather than a reference to something that does
- * not exist (a linking error). {@link persist} implements that as
- * secondaries-then-primary, which is correct for the common shape where the
- * primary is the DIAGRAM and the semantics it references are secondaries: the
- * user opened the diagram, so it is also the document the conflict gate should
- * guard. **An adopter whose primary is the referenced document — a semantic file
- * as the diagram source, with layout in a secondary — has the ordering backwards
- * and must override {@link persist} to write the primary first.** Overriding it
- * is the supported route; the base order is a default for the common case, not an
- * invariant of the class.
+ * **Every document of the set is gated.** The primary on the caller's
+ * `basedOn`, each secondary on {@link secondaryBasedOn}, by default the version
+ * it had when the source root was last read. A conflict on any of them is
+ * reconciled against the whole write set. A write based on `'anything'` — a
+ * merged retry, an undo or redo replaying a patch — forces every document of
+ * the set.
  *
- * **The conflict gate covers the primary only.** Secondaries are written without
- * a based-on version, so a concurrent foreign edit to one is overwritten rather
- * than reconciled. Gating them too would need a per-document reconcile whose
- * outcomes can disagree (merge one, conflict another) with no way to un-write the
- * merged one — the atomicity problem again, one layer up. The captured versions
- * ARE available via {@link AbstractHydraniumGlspState.capturedVersionOf}, so an
- * adopter that wants a coarser check can compare before writing.
+ * A secondary is written only while the diagram's session has it open. The
+ * storage opens it as it joins the write set, and {@link openForWrite} opens it
+ * again before each write; an adopter whose write set can name a document that
+ * does not exist yet overrides {@link openForWrite} to create it.
  */
 @injectable()
 export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary extends TransferElement = TransferElement>
@@ -81,10 +69,10 @@ export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary e
 {
    /**
     * Last in-sync projection across the whole write set, captured on every
-    * {@link setSourceRoot}. Same role as the single-document baseline: the state a
+    * {@link setSourceRoot}. Same role as the single-document base: the state a
     * forward-write conflict reconciles the user's intent against.
     */
-   protected baseline?: MultiDocumentSourceModel<TPrimary>;
+   protected base?: MultiDocumentSourceModel<TPrimary>;
 
    /**
     * Projection of the primary plus every registered secondary, in the framework
@@ -111,21 +99,21 @@ export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary e
    override setSourceRoot(uri: string, root: TRoot): void {
       super.setSourceRoot(uri, root);
       this.trackWriteSet(uri);
-      this.baseline = this.sourceModel;
+      this.base = this.sourceModel;
    }
 
    /**
     * Register the secondary documents that belong to the primary at `uri`, via
     * {@link AbstractHydraniumGlspState.trackSecondaryDocument}. Called on every
     * {@link setSourceRoot}, after the primary is captured (so `sourceUri` is
-    * current) and BEFORE the baseline is taken (so the baseline includes them).
+    * current) and BEFORE the base is taken (so the base includes them).
     * Default: no secondaries.
     *
     * This hook exists because that ordering is a trap an adopter would otherwise
     * hit silently. Registering from an overridden `setSourceRoot` *after*
-    * `super.setSourceRoot(...)` runs too late — the baseline has already been
+    * `super.setSourceRoot(...)` runs too late — the base has already been
     * captured without the secondaries, so the first conflict reconcile measures
-    * the user's intent against a baseline missing half the write set and the
+    * the user's intent against a base missing half the write set and the
     * secondary edits look like foreign changes. Registering *before* the super
     * call is too early for a URI derived from the new primary. Overriding this
     * instead removes the choice.
@@ -136,17 +124,18 @@ export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary e
 
    /**
     * Persist the whole write set, then capture the resulting primary root. On a
-    * `ConflictError` from the primary, reconcile via the injected policy exactly
-    * as the single-document state does — the orchestration is shared.
+    * `ConflictError` from any document of the set, reconcile via the injected
+    * policy exactly as the single-document state does — the orchestration is
+    * shared.
     */
-   async updateSourceModel(model: MultiDocumentSourceModel<TPrimary>, version?: number): Promise<void> {
-      return reconcileSourceModelWrite<MultiDocumentSourceModel<TPrimary>>(model, version, {
-         persist: async (candidate, baseVersion) => {
-            const { root } = await this.persist(candidate, baseVersion);
+   async updateSourceModel(model: MultiDocumentSourceModel<TPrimary>, basedOn: BasedOn = this.basedOn): Promise<void> {
+      return reconcileSourceModelWrite<MultiDocumentSourceModel<TPrimary>>(model, basedOn, {
+         persist: async (candidate, candidateBasedOn) => {
+            const { root } = await this.persist(candidate, candidateBasedOn);
             this.setSourceRoot(this._sourceUri, root);
          },
          refetch: () => this.refetch(),
-         baseline: this.baseline,
+         base: this.base,
          conflictResolver: this.conflictResolver,
          logger: this.logger,
          onConflictDropped: () => this.refreshSourceRoot()
@@ -154,85 +143,99 @@ export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary e
    }
 
    /**
-    * Write hook — secondaries first (ungated), primary last (gated on
-    * `baseVersion`). The order is the failure-mode choice documented on the
-    * class, not incidental: override this when the primary is the document the
-    * others REFERENCE, since then this order writes the references first.
+    * Write hook — every document of `model` that changed, opened first through
+    * {@link openForWrite}, in one `updateAll` on the diagram's session: the
+    * primary gated on `basedOn`, each secondary on {@link secondaryBasedOn}, or
+    * every document on `'anything'` when `basedOn` is `'anything'`. Resolves to
+    * the primary's root, the one already captured when the primary did not
+    * change. A write that bypasses `updateAll` gives up the all-or-none
+    * guarantee the class describes. Throws without a session
+    * ({@link requireModelSession}).
     */
-   protected async persist(model: MultiDocumentSourceModel<TPrimary>, baseVersion?: number): Promise<{ root: TRoot }> {
+   protected async persist(model: MultiDocumentSourceModel<TPrimary>, basedOn: BasedOn): Promise<{ root: TRoot }> {
+      const primaryChanged = this.hasChanged(this.base?.primary, model.primary);
+      const updates: ClientSessionWriteArgs<TransferElement>[] = primaryChanged
+         ? [{ uri: this._sourceUri, model: model.primary, basedOn }]
+         : [];
       for (const [uri, secondary] of Object.entries(model.secondaries)) {
-         if (this.hasChanged(this.baseline?.secondaries[uri], secondary)) {
-            await this.persistSecondary(uri, secondary);
+         if (this.hasChanged(this.base?.secondaries[uri], secondary)) {
+            updates.push({ uri, model: secondary, basedOn: basedOn === 'anything' ? 'anything' : this.secondaryBasedOn(uri) });
          }
       }
-      if (!this.hasChanged(this.baseline?.primary, model.primary)) {
-         // Nothing to write, so nothing to gate either — return the root already
-         // captured rather than round-tripping the document for no reason.
+      if (updates.length === 0) {
          return { root: this._sourceRoot };
       }
-      return this.persistPrimary(model.primary, baseVersion);
+      const session = this.requireModelSession();
+      for (const update of updates) {
+         await this.openForWrite(session, update.uri);
+      }
+      const documents = await session.updateAll({ updates });
+      return { root: primaryChanged ? (documents[0].root as unknown as TRoot) : this._sourceRoot };
    }
 
    /**
-    * Whether `candidate` differs from the baseline projection of the same
+    * Whether `candidate` differs from the base projection of the same
     * document, and therefore needs writing.
     *
     * **Skipping unchanged documents is correctness, not an optimisation.** A
-    * write goes through `ModelService.update`, which re-serializes from the AST —
-    * so writing a document that did not change still rewrites its text, and a
-    * serializer is free to normalise formatting and cannot preserve comments.
-    * Persisting the whole write set unconditionally therefore means a pure layout
-    * drag reflows the semantic file and strips its comments, which is a data
-    * loss the user never asked for and would struggle to attribute.
+    * write re-serializes from the AST, so writing a document that did not
+    * change still rewrites its text in the serializer's own layout. Persisting
+    * the whole write set unconditionally therefore means a pure layout drag
+    * reflows the semantic file, a change the user never asked for and would
+    * struggle to attribute. Comments survive that rewrite, but the
+    * hand-formatting around them does not.
     *
     * Compared by serialised form. Both sides come from the same encoder walking
     * the same shape, so key order is stable and a string compare is sound here;
     * it is also cheap enough to run per document per write.
     */
-   protected hasChanged(baseline: object | undefined, candidate: object): boolean {
-      return baseline === undefined || JSON.stringify(baseline) !== JSON.stringify(candidate);
+   protected hasChanged(base: object | undefined, candidate: object): boolean {
+      return base === undefined || JSON.stringify(base) !== JSON.stringify(candidate);
    }
 
-   /** Write the primary document, opting into the conflict gate when `baseVersion` is given. */
-   protected async persistPrimary(model: TPrimary, baseVersion?: number): Promise<{ root: TRoot }> {
-      const document = await this.sharedServices.model.ModelService.update({
-         uri: this._sourceUri,
-         model,
-         clientId: this.clientId,
-         baseVersion
-      });
-      return document as unknown as { root: TRoot };
+   /**
+    * Make sure the diagram's session has `uri` open before the write set is
+    * written. Default: open it, a no-op for a document the session already
+    * has open. Override to create a document the write set names before it
+    * exists, through `session.create`: `updateAll` opens nothing.
+    */
+   protected openForWrite(session: ClientSession<AstNode>, uri: string): Promise<void> {
+      return session.open(uri);
    }
 
    /**
-    * Write one secondary document. Ungated by design (see the class doc); override
-    * alongside {@link persistPrimary} when the round-trip differs per document
-    * role — a layout file and a semantic file need not share a serializer.
+    * What a secondary write declares it was based on. Default: the version the
+    * secondary had when the source root was last read
+    * ({@link AbstractHydraniumGlspState.snapshotVersionOf}), so a foreign edit
+    * to it since is reported as a conflict and reconciled rather than
+    * overwritten; `'anything'` for a secondary with no recorded version.
+    * Return `'anything'` to force secondary writes.
     */
-   protected async persistSecondary(uri: string, model: TransferElement): Promise<void> {
-      await this.sharedServices.model.ModelService.update({ uri, model, clientId: this.clientId });
+   protected secondaryBasedOn(uri: string): BasedOn {
+      return this.snapshotVersionOf(uri) ?? 'anything';
    }
 
    /**
-    * Refetch hook — the current settled projection across the write set, used by
-    * the conflict resolver to replay the user's intent against fresh state.
+    * Refetch hook — the current projection across the write set, each document
+    * read through {@link AbstractHydraniumGlspState.readCurrentRoot}: theirs,
+    * which the conflict resolver replays the user's intent onto.
     * Returns `undefined` when the PRIMARY cannot be read, since a reconcile
     * without it has nothing to merge into; an unreadable secondary is omitted the
     * same way {@link sourceModel} omits one.
     */
    protected async refetch(): Promise<MultiDocumentSourceModel<TPrimary> | undefined> {
-      const fresh = await this.sharedServices.model.ModelService.validated(this._sourceUri).catch(() => undefined);
-      if (!fresh) {
+      const theirs = await this.readCurrentRoot(this._sourceUri);
+      if (!theirs) {
          return undefined;
       }
       const secondaries: Record<string, TransferElement> = {};
       for (const uri of this.secondaryUris) {
-         const settled = await this.sharedServices.model.ModelService.validated(uri).catch(() => undefined);
-         if (settled) {
-            secondaries[uri] = this.projectRoot(settled.root as unknown as AstNode);
+         const root = await this.readCurrentRoot(uri);
+         if (root) {
+            secondaries[uri] = this.projectRoot(root);
          }
       }
-      return { primary: this.projectRoot(fresh.root as unknown as AstNode) as TPrimary, secondaries };
+      return { primary: this.projectRoot<TPrimary>(theirs), secondaries };
    }
 
    /** Project a currently-loaded document's root, or `undefined` when it is not loaded. */

package/src/state/reconciling-transfer-hydranium-glsp-state.ts

@@ -10,7 +10,7 @@
 import { type JsonModelState } from '@eclipse-glsp/server';
 import { injectable } from 'inversify';
 import { type AstNode } from '@hydranium/langium';
-import { type TransferElement } from '@hydranium/protocol';
+import { type BasedOn, type TransferElement } from '@hydranium/protocol';
 import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.js';
 import { reconcileSourceModelWrite } from './reconcile-source-model-write.js';
 
@@ -27,16 +27,16 @@ import { reconcileSourceModelWrite } from './reconcile-source-model-write.js';
  *   field-level shape is what lets `fast-json-patch` diff per field, so undo /
  *   redo and forward-write reconcile act per field instead of clobbering the
  *   whole document.
- * - {@link baseline} — the last in-sync projection, captured on every
+ * - {@link base} — the last in-sync projection, captured on every
  *   {@link setSourceRoot}. A forward-write conflict reconciles the user's
- *   intent (baseline → attempted) against the fresh server root.
+ *   intent (base → ours) against the server's current root (theirs).
  * - {@link updateSourceModel} — the concrete reconcile template: persist,
  *   and on a `ConflictError` consult the injected `conflictResolver` and act
  *   on the merged / no-op / conflict / unavailable outcome.
  * - {@link persist} / {@link refetch} — the only I/O seams. Defaults route
- *   through `ModelService.update` / `.validated` (reachable from the base via
- *   `sharedServices.model`); adopters whose document round-trip differs
- *   override these without touching the orchestration.
+ *   through the diagram session's `update` and `ModelService.validated`;
+ *   adopters whose document round-trip differs override these without
+ *   touching the orchestration.
  *
  * Adopters whose source model is whole-document text (a bare `{ text }`
  * source model) or that are read-only do NOT extend this class — they extend
@@ -52,12 +52,12 @@ export class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourc
 {
    /**
     * Last in-sync source-model projection, captured on every
-    * {@link setSourceRoot} (initial load + post-update). The baseline a
+    * {@link setSourceRoot} (initial load + post-update). The base a
     * forward-write conflict reconciles against: it stays the pre-command
     * state because operation handlers mutate `_sourceRoot` in place during
     * `execute` while `setSourceRoot` only re-runs once the write commits.
     */
-   protected baseline?: TSourceModel;
+   protected base?: TSourceModel;
 
    /**
     * Persisted-shape projection of the current source root, consumed by GLSP's
@@ -73,28 +73,28 @@ export class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourc
 
    override setSourceRoot(uri: string, root: TRoot): void {
       super.setSourceRoot(uri, root);
-      this.baseline = this.sourceModel;
+      this.base = this.sourceModel;
    }
 
    /**
     * Persist `model` back to the document store, then capture the resulting
     * AST root. On a `ConflictError` (the based-on version was superseded),
-    * reconcile the user's intent against the fresh server root via the bound
+    * reconcile the user's intent against the server's current root via the bound
     * `conflictResolver` and act on the outcome — one declarative policy
     * (force = last-writer-wins, reconciling = field-level merge) shared with
     * undo / redo.
     */
-   async updateSourceModel(model: TSourceModel, version?: number): Promise<void> {
+   async updateSourceModel(model: TSourceModel, basedOn: BasedOn = this.basedOn): Promise<void> {
       // Orchestration lives in `reconcileSourceModelWrite` so the multi-document
       // state gets the identical conflict handling; this method supplies only
       // the single-document meaning of persist / project.
-      return reconcileSourceModelWrite<TSourceModel>(model, version, {
-         persist: async (candidate, baseVersion) => {
-            const { root } = await this.persist(candidate, baseVersion);
+      return reconcileSourceModelWrite<TSourceModel>(model, basedOn, {
+         persist: async (candidate, candidateBasedOn) => {
+            const { root } = await this.persist(candidate, candidateBasedOn);
             this.setSourceRoot(this._sourceUri, root);
          },
          refetch: () => this.refetch(),
-         baseline: this.baseline,
+         base: this.base,
          conflictResolver: this.conflictResolver,
          logger: this.logger,
          onConflictDropped: () => this.refreshSourceRoot()
@@ -103,30 +103,26 @@ export class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourc
 
    /**
     * Persist hook — the only write-side I/O. Default routes the structured
-    * model through `ModelService.update` (serialize → reparse), opting into
-    * the `ConflictError` gate when `version` is given. Adopters whose document
+    * model through the diagram session's `update` (serialize → reparse),
+    * opting into the `ConflictError` gate unless `basedOn` is `'anything'`,
+    * and throws without a session. Adopters whose document
     * round-trip differs override this; the orchestration in
     * {@link updateSourceModel} is unchanged.
     */
-   protected async persist(model: TSourceModel, baseVersion?: number): Promise<{ root: TRoot }> {
-      const document = await this.sharedServices.model.ModelService.update({
-         uri: this._sourceUri,
-         model,
-         clientId: this.clientId,
-         baseVersion
-      });
+   protected async persist(model: TSourceModel, basedOn: BasedOn): Promise<{ root: TRoot }> {
+      const document = await this.requireModelSession().update({ uri: this._sourceUri, model, basedOn });
       return document as unknown as { root: TRoot };
    }
 
    /**
-    * Refetch hook — reads the current settled server root as a persisted-shape
-    * projection (or `undefined` when unavailable). The `conflictResolver`
-    * replays the user's intent against this fresh state. Default uses
-    * `ModelService.validated` + the framework encoder's `'grammar'` mode;
-    * adopters override alongside {@link persist}.
+    * Refetch hook — the stored text parsed afresh, as a persisted-shape
+    * projection (or `undefined` when unavailable): theirs, which the
+    * `conflictResolver` replays the user's intent onto. Default uses
+    * {@link AbstractHydraniumGlspState.readCurrentRoot} + the framework
+    * encoder's `'grammar'` mode; adopters override alongside {@link persist}.
     */
    protected async refetch(): Promise<TSourceModel | undefined> {
-      const fresh = await this.sharedServices.model.ModelService.validated(this._sourceUri).catch(() => undefined);
-      return fresh ? (this.sharedServices.model.TransferEncoder.toTransfer(fresh.root, 'grammar') as unknown as TSourceModel) : undefined;
+      const theirs = await this.readCurrentRoot(this._sourceUri);
+      return theirs ? (this.sharedServices.model.TransferEncoder.toTransfer(theirs, 'grammar') as unknown as TSourceModel) : undefined;
    }
 }