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

package/src/state/reconciling-multi-document-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';
 
@@ -70,9 +70,10 @@ export interface MultiDocumentSourceModel<TPrimary extends TransferElement = Tra
  * 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.
+ * merged one — the atomicity problem again, one layer up. An adopter that wants
+ * a coarser check overrides {@link secondaryBasedOn} to return the version
+ * {@link AbstractHydraniumGlspState.snapshotVersionOf} already holds, and takes
+ * on the partial-write window named there.
  */
 @injectable()
 export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary extends TransferElement = TransferElement>
@@ -139,10 +140,10 @@ export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary e
     * `ConflictError` from the primary, 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(),
@@ -155,11 +156,11 @@ 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
+    * `basedOn`). 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.
     */
-   protected async persist(model: MultiDocumentSourceModel<TPrimary>, baseVersion?: number): Promise<{ root: TRoot }> {
+   protected async persist(model: MultiDocumentSourceModel<TPrimary>, basedOn: BasedOn): Promise<{ root: TRoot }> {
       for (const [uri, secondary] of Object.entries(model.secondaries)) {
          if (this.hasChanged(this.baseline?.secondaries[uri], secondary)) {
             await this.persistSecondary(uri, secondary);
@@ -170,7 +171,7 @@ export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary e
          // captured rather than round-tripping the document for no reason.
          return { root: this._sourceRoot };
       }
-      return this.persistPrimary(model.primary, baseVersion);
+      return this.persistPrimary(model.primary, basedOn);
    }
 
    /**
@@ -193,24 +194,51 @@ export class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary e
       return baseline === undefined || JSON.stringify(baseline) !== 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 }> {
+   /** Write the primary document, opting into the conflict gate unless `basedOn` is `'anything'`. */
+   protected async persistPrimary(model: TPrimary, basedOn: BasedOn): Promise<{ root: TRoot }> {
       const document = await this.sharedServices.model.ModelService.update({
          uri: this._sourceUri,
          model,
          clientId: this.clientId,
-         baseVersion
+         basedOn
       });
       return document as unknown as { root: TRoot };
    }
 
    /**
-    * 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.
+    * Write one secondary document, gated on whatever {@link secondaryBasedOn}
+    * returns. Override alongside {@link persistPrimary} when the round-trip
+    * differs per document role — a layout file and a semantic file need not
+    * share a serializer.
     */
    protected async persistSecondary(uri: string, model: TransferElement): Promise<void> {
-      await this.sharedServices.model.ModelService.update({ uri, model, clientId: this.clientId });
+      await this.sharedServices.model.ModelService.update({
+         uri,
+         model,
+         clientId: this.clientId,
+         basedOn: this.secondaryBasedOn(uri)
+      });
+   }
+
+   /**
+    * What a secondary write declares it was based on. Default `'anything'` —
+    * ungated, because gating the whole set needs a per-document reconcile whose
+    * outcomes can disagree, with no way to un-write an already-merged sibling.
+    *
+    * **The hook exists so that opting in is an override rather than a
+    * reimplementation.** The state already holds what such a check needs
+    * ({@link AbstractHydraniumGlspState.snapshotVersionOf}), and returning that
+    * value here is the whole opt-in; without it the only place to put the
+    * comparison is a copy of {@link persistSecondary}, which then has to be kept
+    * in step with the framework's write call.
+    *
+    * **Opting in buys a conflict report and costs atomicity.** A gated secondary
+    * throws mid-set, after earlier secondaries have already been written, and if
+    * the reconcile then drops the edit those writes stay. Weigh that against the
+    * default, which lets a foreign edit to a secondary be overwritten silently.
+    */
+   protected secondaryBasedOn(_uri: string): BasedOn {
+      return 'anything';
    }
 
    /**

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';
 
@@ -84,13 +84,13 @@ export class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourc
     * (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(),
@@ -108,12 +108,12 @@ export class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourc
     * round-trip differs override this; the orchestration in
     * {@link updateSourceModel} is unchanged.
     */
-   protected async persist(model: TSourceModel, baseVersion?: number): Promise<{ root: TRoot }> {
+   protected async persist(model: TSourceModel, basedOn: BasedOn): Promise<{ root: TRoot }> {
       const document = await this.sharedServices.model.ModelService.update({
          uri: this._sourceUri,
          model,
          clientId: this.clientId,
-         baseVersion
+         basedOn
       });
       return document as unknown as { root: TRoot };
    }