@korajs/merge 1.0.0-beta.12 → 1.0.0-beta.14

package/README.md

@@ -1,77 +1,59 @@
 # @korajs/merge
 
-Three-tier conflict resolution engine for Kora.js. Handles concurrent modifications across offline devices and produces deterministic, commutative merge results.
+Cross-record rules for Kora.js: constraint checks (unique, capacity, referential), referential
+integrity on delete, and rich-text helpers.
 
-> Most developers don't install this directly. Use [`korajs`](https://www.npmjs.com/package/korajs) instead.
+> Most apps do not install this directly. Records are merged by the per-field fold in
+> `@korajs/core` on every device and server; `createApp` and the sync server wire this package.
 
 ## Install
 
 ```bash
-pnpm add @korajs/merge
+pnpm add @korajs/merge@beta
 ```
 
-## How It Works
+## How Kora merges
 
-The merge engine resolves conflicts in three tiers:
+Since 1.0.0-beta.13 every replica computes a record from its operations with one deterministic
+per-field CRDT (the fold in `@korajs/core`), so the result depends only on the set of operations,
+not their order or duplicates:
 
-**Tier 1 -- Auto-Merge (default for all fields):**
-- `string`, `number`, `boolean`, `enum`, `timestamp` -- Last-Write-Wins via HLC
-- `array` -- Add-wins set (union of elements)
-- `richtext` -- Yjs CRDT (character-level merge)
+- strings, numbers, booleans, enums, timestamps: the later write wins (hybrid logical clock)
+- arrays: an element set (concurrent additions and removals both apply)
+- objects: per top-level key
+- rich text: Yjs, character by character
+- `.merge('counter' | 'max' | 'min' | 'append-only' | 'server-authoritative')` and custom
+  `resolve` functions where declared
 
-**Tier 2 -- Constraint Validation:**
-After auto-merge, constraints (unique, capacity, referential) are checked. Violations trigger the configured `onConflict` strategy.
-
-**Tier 3 -- Custom Resolvers:**
-For domain-specific logic that neither auto-merge nor constraints can handle.
-
-## Usage
+Constraints span records, so the **sync server** enforces them: a violating operation is refused,
+and races are corrected with deterministic server operations.
 
+<!-- docs-check: standalone -->
 ```typescript
-import { MergeEngine } from '@korajs/merge'
-
-const engine = new MergeEngine({ schema })
-
-// Merge two concurrent operations
-const result = engine.merge(localOperation, remoteOperation)
-
-// result.value   -- the resolved value
-// result.trace   -- full MergeTrace for debugging/DevTools
-// result.tier    -- which tier resolved it (1, 2, or 3)
-```
+import { defineSchema, t } from 'korajs'
 
-### Custom Resolver
-
-```typescript
-const schema = defineSchema({
+export const schema = defineSchema({
+  version: 1,
   collections: {
     inventory: {
       fields: {
-        productId: t.string(),
-        quantity: t.number(),
-      },
-      resolve: {
-        quantity: (local, remote, base) => {
-          // Additive merge: apply both deltas
-          const localDelta = local - base
-          const remoteDelta = remote - base
-          return Math.max(0, base + localDelta + remoteDelta)
-        },
+        sku: t.string(),
+        quantity: t.number().merge('counter'), // concurrent changes add up
       },
+      constraints: [{ type: 'unique', fields: ['sku'], onConflict: 'first-write-wins' }],
     },
   },
 })
 ```
 
-## Guarantees
+`MergeEngine` and the pairwise strategy functions implement the 1.0.0-beta.12 merge. They remain
+only for `experimental.legacyMerge` in this release and will be removed.
 
-- **Deterministic** -- same operations always produce the same result
-- **Commutative** -- `merge(A, B)` equals `merge(B, A)`
-- **Idempotent** -- applying the same operation twice has no additional effect
-- **Traceable** -- every decision produces a `MergeTrace` for inspection
+## Documentation
+
+[Conflict Resolution](https://korajs.dev/guide/conflict-resolution) and the
+[Merge API reference](https://korajs.dev/api/merge).
 
 ## License
 
 MIT
-
-See the [full documentation](https://github.com/ehoneahobed/kora) for guides, API reference, and examples.

package/dist/index.cjs

@@ -64,69 +64,9 @@ function lastWriteWins(localValue, remoteValue, localTimestamp, remoteTimestamp)
 }
 
 // src/strategies/add-wins-set.ts
+var import_core2 = require("@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 (0, import_core2.mergeArraySet)(localArray, remoteArray, baseArray);
 }
 
 // src/strategies/object-merge.ts
@@ -295,7 +235,7 @@ function mergeAtomicOps(localAtomicOp, remoteAtomicOp, baseValue) {
 }
 
 // src/strategies/yjs-richtext.ts
-var import_core2 = require("@korajs/core");
+var import_core3 = require("@korajs/core");
 var Y = __toESM(require("yjs"), 1);
 var TEXT_KEY = "content";
 function mergeRichtext(localValue, remoteValue, baseValue) {
@@ -328,8 +268,8 @@ function toYjsUpdate(value) {
   if (value instanceof ArrayBuffer) {
     return new Uint8Array(value);
   }
-  if ((0, import_core2.isKoraBytesValue)(value) || (0, import_core2.isLegacyNumericByteObject)(value)) {
-    const decoded = (0, import_core2.decodeBytesFromOpData)(value);
+  if ((0, import_core3.isKoraBytesValue)(value) || (0, import_core3.isLegacyNumericByteObject)(value)) {
+    const decoded = (0, import_core3.decodeBytesFromOpData)(value);
     return decoded instanceof Uint8Array ? decoded : stringToRichtextUpdate(decoded);
   }
   throw new Error(
@@ -338,7 +278,7 @@ function toYjsUpdate(value) {
 }
 
 // src/strategies/schema-strategies.ts
-var import_core3 = require("@korajs/core");
+var import_core4 = require("@korajs/core");
 function counterMerge(localValue, remoteValue, baseValue) {
   const base = typeof baseValue === "number" ? baseValue : 0;
   const local = typeof localValue === "number" ? localValue : base;
@@ -740,7 +680,7 @@ async function checkSingleConstraint(constraint, mergedRecord, recordId, collect
   }
 }
 async function checkUniqueConstraint(constraint, mergedRecord, recordId, collection, ctx) {
-  const where = {};
+  const where = { ...constraint.where ?? {} };
   for (const field of constraint.fields) {
     where[field] = mergedRecord[field];
   }
@@ -810,13 +750,13 @@ function matchesWhere(record, where) {
 }
 
 // src/constraints/resolvers.ts
-var import_core4 = require("@korajs/core");
+var import_core5 = require("@korajs/core");
 function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp, baseState) {
   const startTime = Date.now();
   const { constraint } = violation;
   switch (constraint.onConflict) {
     case "last-write-wins": {
-      const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+      const comparison = import_core5.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
       const winner = comparison >= 0 ? localOp : remoteOp;
       const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
       return createResolution(
@@ -830,7 +770,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
       );
     }
     case "first-write-wins": {
-      const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+      const comparison = import_core5.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
       const winner = comparison <= 0 ? localOp : remoteOp;
       const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
       return createResolution(
@@ -846,7 +786,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
     case "priority-field": {
       const priorityField = constraint.priorityField;
       if (priorityField === void 0) {
-        const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+        const comparison = import_core5.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
         const winner2 = comparison >= 0 ? localOp : remoteOp;
         const resolvedRecord2 = applyWinnerFields(mergedRecord, winner2, violation.fields);
         return createResolution(
@@ -890,7 +830,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
     }
     case "custom": {
       if (constraint.resolve === void 0) {
-        const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+        const comparison = import_core5.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
         const winner = comparison >= 0 ? localOp : remoteOp;
         const resolvedRecord2 = applyWinnerFields(mergedRecord, winner, violation.fields);
         return createResolution(
@@ -982,7 +922,7 @@ function extractFields(record, fields) {
 }
 
 // src/constraints/referential-integrity.ts
-var import_core5 = require("@korajs/core");
+var import_core6 = require("@korajs/core");
 function buildMergeRelationLookup(schema) {
   const lookup = /* @__PURE__ */ new Map();
   const relationNames = Object.keys(schema.relations).sort();
@@ -1253,17 +1193,17 @@ function createDeleteVsInsertTrace(deleteOp, insertOp, relation, strategy, actio
 }
 
 // src/engine/merge-engine.ts
-var import_core7 = require("@korajs/core");
+var import_core8 = require("@korajs/core");
 
 // src/constraints/state-machine-constraint.ts
-var import_core6 = require("@korajs/core");
+var import_core7 = require("@korajs/core");
 function isValid(sm, from, to) {
   const constraint = {
     field: sm.field,
     collection: "",
     transitions: sm.transitions
   };
-  return (0, import_core6.validateTransition)(constraint, from, to).valid;
+  return (0, import_core7.validateTransition)(constraint, from, to).valid;
 }
 function resolveStateMachineMerge(fieldName, localOp, remoteOp, baseState, stateMachine) {
   const startTime = Date.now();
@@ -1324,7 +1264,7 @@ function resolveStateMachineMerge(fieldName, localOp, remoteOp, baseState, state
   const localValid = isValid(stateMachine, baseStateStr, localStr);
   const remoteValid = isValid(stateMachine, baseStateStr, remoteStr);
   if (localValid && remoteValid) {
-    const comparison = import_core6.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+    const comparison = import_core7.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
     const winner = comparison >= 0 ? localStr : remoteStr;
     return makeResult(
       winner,
@@ -1518,7 +1458,7 @@ var MergeEngine = class {
    */
   mergeWithDelete(input) {
     const { local, remote } = input;
-    const comparison = import_core7.HybridLogicalClock.compare(local.timestamp, remote.timestamp);
+    const comparison = import_core8.HybridLogicalClock.compare(local.timestamp, remote.timestamp);
     if (comparison >= 0) {
       if (local.type === "delete") {
         return { mergedData: {}, traces: [], appliedOperation: "local", sideEffects: [] };