@korajs/merge 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/index.d.cts

@@ -209,22 +209,31 @@ interface LWWResult {
 declare function lastWriteWins(localValue: unknown, remoteValue: unknown, localTimestamp: HLCTimestamp, remoteTimestamp: HLCTimestamp): LWWResult;
 
 /**
- * Add-wins set merge strategy for array fields.
+ * Add-wins set merge strategy for array fields (three-way, base-relative).
  *
- * When two sides concurrently modify an array, this strategy preserves all
- * additions from both sides. An element is only removed from the result if
- * BOTH sides independently removed it. This prevents data loss: if one side
- * adds an element while another removes a different element, both changes
- * are preserved.
+ * When two sides concurrently modify an array, every element either side ADDED
+ * survives, and every base element either side REMOVED is removed. An element
+ * one side left unchanged never resurrects an element the other side removed
+ * (MERGE-1, NEW-MERGE-1): "unchanged" is not a vote to keep it.
  *
  * Algorithm:
- *   added_local  = local - base
- *   added_remote = remote - base
- *   removed_local  = base - local
- *   removed_remote = base - remote
- *   result = (base ∪ added_local ∪ added_remote) - (removed_local ∩ removed_remote)
+ *   result = (local ∩ remote) ∪ (local − base) ∪ (remote − base)
+ *
+ * Equivalently: a base element is kept only if BOTH sides kept it; a non-base
+ * element is kept if EITHER side added it.
+ *
+ * Ordering is role-independent (the two devices performing this merge call
+ * opposite sides "local"): kept base elements first, in base order, then every
+ * other element sorted by its serialized form.
  *
  * Uses JSON.stringify for element comparison to handle primitives and objects.
+ * Delegates to `mergeArraySet` in `@korajs/core`.
+ *
+ * Interim (S1): this is still a pairwise merge. W7 replaces it with a per-element
+ * LWW set whose result is independent of merge order.
+ *
+ * @deprecated W7 (beta.13): arrays fold as an occurrence-indexed LWW element
+ * multiset in `@korajs/core`. Kept for `experimental.legacyMerge` (one beta).
  *
  * @param localArray - The local array after local modifications
  * @param remoteArray - The remote array after remote modifications
@@ -442,6 +451,11 @@ declare function resolveConstraintViolation(violation: ConstraintViolation, merg
 /**
  * Three-tier merge engine for resolving concurrent operations.
  *
+ * @deprecated W7 (beta.13): records are materialized by the per-field CRDT fold in
+ * `@korajs/core` (`mergeOp` / `foldRecord`), which produces the MergeTraces. This
+ * pairwise engine only backs `experimental.legacyMerge` for one beta and is
+ * removed afterwards. Constraint and referential checks stay in this package.
+ *
  * Tier 1: Auto-merge per field kind (LWW, add-wins set, CRDT)
  * Tier 3: Custom resolvers override Tier 1 for specific fields
  * Tier 2: Constraint validation against the candidate merged state

package/dist/index.d.ts

@@ -209,22 +209,31 @@ interface LWWResult {
 declare function lastWriteWins(localValue: unknown, remoteValue: unknown, localTimestamp: HLCTimestamp, remoteTimestamp: HLCTimestamp): LWWResult;
 
 /**
- * Add-wins set merge strategy for array fields.
+ * Add-wins set merge strategy for array fields (three-way, base-relative).
  *
- * When two sides concurrently modify an array, this strategy preserves all
- * additions from both sides. An element is only removed from the result if
- * BOTH sides independently removed it. This prevents data loss: if one side
- * adds an element while another removes a different element, both changes
- * are preserved.
+ * When two sides concurrently modify an array, every element either side ADDED
+ * survives, and every base element either side REMOVED is removed. An element
+ * one side left unchanged never resurrects an element the other side removed
+ * (MERGE-1, NEW-MERGE-1): "unchanged" is not a vote to keep it.
  *
  * Algorithm:
- *   added_local  = local - base
- *   added_remote = remote - base
- *   removed_local  = base - local
- *   removed_remote = base - remote
- *   result = (base ∪ added_local ∪ added_remote) - (removed_local ∩ removed_remote)
+ *   result = (local ∩ remote) ∪ (local − base) ∪ (remote − base)
+ *
+ * Equivalently: a base element is kept only if BOTH sides kept it; a non-base
+ * element is kept if EITHER side added it.
+ *
+ * Ordering is role-independent (the two devices performing this merge call
+ * opposite sides "local"): kept base elements first, in base order, then every
+ * other element sorted by its serialized form.
  *
  * Uses JSON.stringify for element comparison to handle primitives and objects.
+ * Delegates to `mergeArraySet` in `@korajs/core`.
+ *
+ * Interim (S1): this is still a pairwise merge. W7 replaces it with a per-element
+ * LWW set whose result is independent of merge order.
+ *
+ * @deprecated W7 (beta.13): arrays fold as an occurrence-indexed LWW element
+ * multiset in `@korajs/core`. Kept for `experimental.legacyMerge` (one beta).
  *
  * @param localArray - The local array after local modifications
  * @param remoteArray - The remote array after remote modifications
@@ -442,6 +451,11 @@ declare function resolveConstraintViolation(violation: ConstraintViolation, merg
 /**
  * Three-tier merge engine for resolving concurrent operations.
  *
+ * @deprecated W7 (beta.13): records are materialized by the per-field CRDT fold in
+ * `@korajs/core` (`mergeOp` / `foldRecord`), which produces the MergeTraces. This
+ * pairwise engine only backs `experimental.legacyMerge` for one beta and is
+ * removed afterwards. Constraint and referential checks stay in this package.
+ *
  * Tier 1: Auto-merge per field kind (LWW, add-wins set, CRDT)
  * Tier 3: Custom resolvers override Tier 1 for specific fields
  * Tier 2: Constraint validation against the candidate merged state

package/dist/index.js

@@ -9,69 +9,9 @@ function lastWriteWins(localValue, remoteValue, localTimestamp, remoteTimestamp)
 }
 
 // src/strategies/add-wins-set.ts
+import { mergeArraySet } from "@korajs/core";
 function addWinsSet(localArray, remoteArray, baseArray) {
-  const serialize = (v) => JSON.stringify(v);
-  const baseSet = new Set(baseArray.map(serialize));
-  const localSet = new Set(localArray.map(serialize));
-  const remoteSet = new Set(remoteArray.map(serialize));
-  const addedLocal = /* @__PURE__ */ new Set();
-  for (const s of localSet) {
-    if (!baseSet.has(s)) {
-      addedLocal.add(s);
-    }
-  }
-  const addedRemote = /* @__PURE__ */ new Set();
-  for (const s of remoteSet) {
-    if (!baseSet.has(s)) {
-      addedRemote.add(s);
-    }
-  }
-  const removedLocal = /* @__PURE__ */ new Set();
-  for (const s of baseSet) {
-    if (!localSet.has(s)) {
-      removedLocal.add(s);
-    }
-  }
-  const removedRemote = /* @__PURE__ */ new Set();
-  for (const s of baseSet) {
-    if (!remoteSet.has(s)) {
-      removedRemote.add(s);
-    }
-  }
-  const removedByBoth = /* @__PURE__ */ new Set();
-  for (const s of removedLocal) {
-    if (removedRemote.has(s)) {
-      removedByBoth.add(s);
-    }
-  }
-  const resultSerialized = /* @__PURE__ */ new Set();
-  const result = [];
-  const addIfNew = (serialized, value) => {
-    if (!resultSerialized.has(serialized) && !removedByBoth.has(serialized)) {
-      resultSerialized.add(serialized);
-      result.push(value);
-    }
-  };
-  for (const item of baseArray) {
-    addIfNew(serialize(item), item);
-  }
-  const additions = /* @__PURE__ */ new Map();
-  for (const item of localArray) {
-    const s = serialize(item);
-    if (addedLocal.has(s) && !additions.has(s)) {
-      additions.set(s, item);
-    }
-  }
-  for (const item of remoteArray) {
-    const s = serialize(item);
-    if (addedRemote.has(s) && !additions.has(s)) {
-      additions.set(s, item);
-    }
-  }
-  for (const s of [...additions.keys()].sort()) {
-    addIfNew(s, additions.get(s));
-  }
-  return result;
+  return mergeArraySet(localArray, remoteArray, baseArray);
 }
 
 // src/strategies/object-merge.ts