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

package/lib/state/reconciling-multi-document-glsp-state.d.ts

@@ -8,7 +8,8 @@
  ********************************************************************************/
 import { type JsonModelState } from '@eclipse-glsp/server';
 import { type AstNode } from '@hydranium/langium';
-import { type TransferElement } from '@hydranium/protocol';
+import { type ClientSession } from '@hydranium/core';
+import { type BasedOn, type TransferElement } from '@hydranium/protocol';
 import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.js';
 /**
  * Source model spanning more than one document: the primary document's
@@ -39,43 +40,30 @@ 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.
  */
 export declare class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary extends TransferElement = TransferElement> extends AbstractHydraniumGlspState<TRoot, MultiDocumentSourceModel<TPrimary>> implements JsonModelState<MultiDocumentSourceModel<TPrimary>> {
     /**
      * 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
      * encoder's `'grammar'` mode (authored state only — cross-references as
@@ -93,14 +81,14 @@ export declare class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TP
      * 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.
@@ -108,49 +96,61 @@ export declare class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TP
     protected trackWriteSet(_uri: string): void;
     /**
      * 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.
      */
-    updateSourceModel(model: MultiDocumentSourceModel<TPrimary>, version?: number): Promise<void>;
+    updateSourceModel(model: MultiDocumentSourceModel<TPrimary>, basedOn?: BasedOn): Promise<void>;
     /**
-     * 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 persist(model: MultiDocumentSourceModel<TPrimary>, baseVersion?: number): Promise<{
+    protected persist(model: MultiDocumentSourceModel<TPrimary>, basedOn: BasedOn): Promise<{
         root: TRoot;
     }>;
     /**
-     * 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;
-    /** Write the primary document, opting into the conflict gate when `baseVersion` is given. */
-    protected persistPrimary(model: TPrimary, baseVersion?: number): Promise<{
-        root: TRoot;
-    }>;
+    protected hasChanged(base: object | undefined, candidate: object): boolean;
+    /**
+     * 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>;
     /**
-     * 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 persistSecondary(uri: string, model: TransferElement): Promise<void>;
+    protected secondaryBasedOn(uri: string): BasedOn;
     /**
-     * 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.

package/lib/state/reconciling-multi-document-glsp-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconciling-multi-document-glsp-state.d.ts","sourceRoot":"","sources":["../../src/state/reconciling-multi-document-glsp-state.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAGhF;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB,CAAC,QAAQ,SAAS,eAAe,GAAG,eAAe;IACzF,gFAAgF;IAChF,OAAO,EAAE,QAAQ,CAAC;IAClB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,iCAAiC,CAAC,KAAK,SAAS,OAAO,EAAE,QAAQ,SAAS,eAAe,GAAG,eAAe,CACrH,SAAQ,0BAA0B,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAC5E,YAAW,cAAc,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAE7D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAExD;;;;;;;;;;OAUG;IACH,IAAI,WAAW,IAAI,wBAAwB,CAAC,QAAQ,CAAC,CASpD;IAEQ,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;IAMtD;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3C;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnG;;;;;OAKG;cACa,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAclH;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAI9E,6FAA6F;cAC7E,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAU/F;;;;OAIG;cACa,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF;;;;;;OAMG;cACa,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IAelF,wFAAwF;IACxF,SAAS,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAKnE,oFAAoF;IACpF,SAAS,CAAC,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC;CAGtF"}
+{"version":3,"file":"reconciling-multi-document-glsp-state.d.ts","sourceRoot":"","sources":["../../src/state/reconciling-multi-document-glsp-state.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAA+B,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAGhF;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB,CAAC,QAAQ,SAAS,eAAe,GAAG,eAAe;IACzF,gFAAgF;IAChF,OAAO,EAAE,QAAQ,CAAC;IAClB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBACa,iCAAiC,CAAC,KAAK,SAAS,OAAO,EAAE,QAAQ,SAAS,eAAe,GAAG,eAAe,CACrH,SAAQ,0BAA0B,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAC5E,YAAW,cAAc,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAE7D;;;;OAIG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAEpD;;;;;;;;;;OAUG;IACH,IAAI,WAAW,IAAI,wBAAwB,CAAC,QAAQ,CAAC,CASpD;IAEQ,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;IAMtD;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3C;;;;;OAKG;IACG,iBAAiB,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAE,OAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAclH;;;;;;;;;OASG;cACa,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAqB9G;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAI1E;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInF;;;;;;;OAOG;IACH,SAAS,CAAC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhD;;;;;;;OAOG;cACa,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IAelF,wFAAwF;IACxF,SAAS,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAKnE,oFAAoF;IACpF,SAAS,CAAC,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC;CAGtF"}

package/lib/state/reconciling-multi-document-glsp-state.js

@@ -28,43 +28,30 @@ import { reconcileSourceModelWrite } from './reconcile-source-model-write.js';
  * 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.
  */
 let ReconcilingMultiDocumentGlspState = class ReconcilingMultiDocumentGlspState extends AbstractHydraniumGlspState {
     /**
      * 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.
      */
-    baseline;
+    base;
     /**
      * Projection of the primary plus every registered secondary, in the framework
      * encoder's `'grammar'` mode (authored state only — cross-references as
@@ -89,20 +76,20 @@ let ReconcilingMultiDocumentGlspState = class ReconcilingMultiDocumentGlspState
     setSourceRoot(uri, root) {
         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.
@@ -112,98 +99,113 @@ let ReconcilingMultiDocumentGlspState = class ReconcilingMultiDocumentGlspState
     }
     /**
      * 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, version) {
-        return reconcileSourceModelWrite(model, version, {
-            persist: async (candidate, baseVersion) => {
-                const { root } = await this.persist(candidate, baseVersion);
+    async updateSourceModel(model, basedOn = this.basedOn) {
+        return reconcileSourceModelWrite(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()
         });
     }
     /**
-     * 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}).
      */
-    async persist(model, baseVersion) {
+    async persist(model, basedOn) {
+        const primaryChanged = this.hasChanged(this.base?.primary, model.primary);
+        const updates = 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 : 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.
      */
-    hasChanged(baseline, candidate) {
-        return baseline === undefined || JSON.stringify(baseline) !== JSON.stringify(candidate);
+    hasChanged(base, candidate) {
+        return base === undefined || JSON.stringify(base) !== JSON.stringify(candidate);
     }
-    /** Write the primary document, opting into the conflict gate when `baseVersion` is given. */
-    async persistPrimary(model, baseVersion) {
-        const document = await this.sharedServices.model.ModelService.update({
-            uri: this._sourceUri,
-            model,
-            clientId: this.clientId,
-            baseVersion
-        });
-        return document;
+    /**
+     * 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.
+     */
+    openForWrite(session, uri) {
+        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.
      */
-    async persistSecondary(uri, model) {
-        await this.sharedServices.model.ModelService.update({ uri, model, clientId: this.clientId });
+    secondaryBasedOn(uri) {
+        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.
      */
     async refetch() {
-        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 = {};
         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);
+            const root = await this.readCurrentRoot(uri);
+            if (root) {
+                secondaries[uri] = this.projectRoot(root);
             }
         }
-        return { primary: this.projectRoot(fresh.root), secondaries };
+        return { primary: this.projectRoot(theirs), secondaries };
     }
     /** Project a currently-loaded document's root, or `undefined` when it is not loaded. */
     projectDocument(uri) {

package/lib/state/reconciling-multi-document-glsp-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"reconciling-multi-document-glsp-state.js","sourceRoot":"","sources":["../../src/state/reconciling-multi-document-glsp-state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reconciling-multi-document-glsp-state.js","sourceRoot":"","sources":["../../src/state/reconciling-multi-document-glsp-state.ts"],"names":[],"mappings":"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"}

package/lib/state/reconciling-transfer-hydranium-glsp-state.d.ts

@@ -8,7 +8,7 @@
  ********************************************************************************/
 import { type JsonModelState } from '@eclipse-glsp/server';
 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';
 /**
  * Editable GLSP state for adopters whose source model is a **structured
@@ -23,16 +23,16 @@ import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.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
@@ -44,12 +44,12 @@ import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.js';
 export declare class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourceModel extends TransferElement> extends AbstractHydraniumGlspState<TRoot, TSourceModel> implements JsonModelState<TSourceModel> {
     /**
      * 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
      * {@link JsonModelState} read side and recorded for field-level undo / redo.
@@ -63,28 +63,29 @@ export declare class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode
     /**
      * 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.
      */
-    updateSourceModel(model: TSourceModel, version?: number): Promise<void>;
+    updateSourceModel(model: TSourceModel, basedOn?: BasedOn): Promise<void>;
     /**
      * 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 persist(model: TSourceModel, baseVersion?: number): Promise<{
+    protected persist(model: TSourceModel, basedOn: BasedOn): Promise<{
         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 refetch(): Promise<TSourceModel | undefined>;
 }

package/lib/state/reconciling-transfer-hydranium-glsp-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconciling-transfer-hydranium-glsp-state.d.ts","sourceRoot":"","sources":["../../src/state/reconciling-transfer-hydranium-glsp-state.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAGhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,qCAAqC,CAAC,KAAK,SAAS,OAAO,EAAE,YAAY,SAAS,eAAe,CAC3G,SAAQ,0BAA0B,CAAC,KAAK,EAAE,YAAY,CACtD,YAAW,cAAc,CAAC,YAAY,CAAC;IAEvC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IAElC;;;;;;;OAOG;IACH,IAAI,WAAW,IAAI,YAAY,CAE9B;IAEQ,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;IAKtD;;;;;;;OAOG;IACG,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB7E;;;;;;OAMG;cACa,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAU5F;;;;;;OAMG;cACa,OAAO,IAAI,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;CAI9D"}
+{"version":3,"file":"reconciling-transfer-hydranium-glsp-state.d.ts","sourceRoot":"","sources":["../../src/state/reconciling-transfer-hydranium-glsp-state.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAGhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,qCAAqC,CAAC,KAAK,SAAS,OAAO,EAAE,YAAY,SAAS,eAAe,CAC3G,SAAQ,0BAA0B,CAAC,KAAK,EAAE,YAAY,CACtD,YAAW,cAAc,CAAC,YAAY,CAAC;IAEvC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAE9B;;;;;;;OAOG;IACH,IAAI,WAAW,IAAI,YAAY,CAE9B;IAEQ,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;IAKtD;;;;;;;OAOG;IACG,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,OAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB5F;;;;;;;OAOG;cACa,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAKxF;;;;;;OAMG;cACa,OAAO,IAAI,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;CAI9D"}