@git-stunts/git-warp 10.1.1

package/src/domain/crdt/Dot.js

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Dot - Unique Operation Identity for CRDT Semantics
+ *
+ * In distributed systems, concurrent operations can arrive in any order and may
+ * conflict. To resolve conflicts deterministically without coordination, each
+ * operation must carry a unique, globally recognizable identity. This is the
+ * role of a "dot."
+ *
+ * ## What is a Dot?
+ *
+ * A dot is a (writerId, counter) pair that uniquely identifies a single CRDT
+ * operation. Think of it as a "birth certificate" for an operation:
+ *
+ * - **writerId**: Identifies which writer created this operation. Each writer
+ *   in the system has a unique ID (e.g., "alice", "bob", or a UUID).
+ *
+ * - **counter**: A monotonically increasing integer for this writer. Each time
+ *   a writer creates an operation, it increments its counter. The first
+ *   operation is counter=1, the second is counter=2, and so on.
+ *
+ * Together, (writerId, counter) forms a globally unique identifier because:
+ * 1. No two writers share the same writerId
+ * 2. No single writer uses the same counter twice
+ *
+ * ## Why Dots Matter for CRDTs
+ *
+ * Dots enable "add-wins" semantics in OR-Sets. When an element is added, the
+ * add operation's dot is recorded. When an element is removed, only the dots
+ * that the remover has *observed* are tombstoned. This means:
+ *
+ * - Concurrent add + remove: The add wins (its dot wasn't observed by the remove)
+ * - Sequential add then remove: The remove wins (it observed the add's dot)
+ * - Re-add after remove: The new add wins (new dot wasn't observed by old remove)
+ *
+ * Without dots, you cannot distinguish "concurrent add" from "re-add after
+ * remove," leading to either lost updates or zombie elements.
+ *
+ * ## Dots and Causality
+ *
+ * Dots relate to causality through version vectors. A version vector is a map
+ * from writerId to the highest counter seen from that writer. If vv[writerId]
+ * >= dot.counter, then the dot has been "observed" or "included" in that causal
+ * context.
+ *
+ * This enables:
+ * - **Causality tracking**: Know which operations have been seen
+ * - **Safe garbage collection**: Only compact dots that all replicas have seen
+ * - **Conflict detection**: Concurrent operations have dots not in each other's context
+ *
+ * ## Encoding
+ *
+ * Dots are encoded as strings "writerId:counter" for use as Map/Set keys. The
+ * lastIndexOf(':') parsing handles writerIds that contain colons.
+ *
+ * @module crdt/Dot
+ */
+
+/**
+ * Dot - Unique operation identifier for CRDT operations.
+ * A dot is a (writerId, counter) pair that uniquely identifies an operation.
+ *
+ * @typedef {Object} Dot
+ * @property {string} writerId - Writer identifier (non-empty string)
+ * @property {number} counter - Monotonic counter (positive integer)
+ */
+
+/**
+ * Creates a validated Dot.
+ *
+ * @param {string} writerId - Must be non-empty string
+ * @param {number} counter - Must be positive integer (> 0)
+ * @returns {Dot}
+ * @throws {Error} If validation fails
+ */
+export function createDot(writerId, counter) {
+  if (typeof writerId !== 'string' || writerId.length === 0) {
+    throw new Error('writerId must be a non-empty string');
+  }
+
+  if (!Number.isInteger(counter) || counter <= 0) {
+    throw new Error('counter must be a positive integer');
+  }
+
+  return { writerId, counter };
+}
+
+/**
+ * Checks if two dots are equal.
+ *
+ * @param {Dot} a
+ * @param {Dot} b
+ * @returns {boolean}
+ */
+export function dotsEqual(a, b) {
+  return a.writerId === b.writerId && a.counter === b.counter;
+}
+
+/**
+ * Encodes a dot as a string for use as Set/Map keys.
+ * Format: "writerId:counter"
+ *
+ * @param {Dot} dot
+ * @returns {string}
+ */
+export function encodeDot(dot) {
+  return `${dot.writerId}:${dot.counter}`;
+}
+
+/**
+ * Decodes an encoded dot string back to a Dot object.
+ *
+ * @param {string} encoded - Format: "writerId:counter"
+ * @returns {Dot}
+ * @throws {Error} If format is invalid
+ */
+export function decodeDot(encoded) {
+  const lastColonIndex = encoded.lastIndexOf(':');
+  if (lastColonIndex === -1) {
+    throw new Error('Invalid encoded dot format: missing colon');
+  }
+
+  const writerId = encoded.slice(0, lastColonIndex);
+  const counterStr = encoded.slice(lastColonIndex + 1);
+  const counter = parseInt(counterStr, 10);
+
+  if (writerId.length === 0) {
+    throw new Error('Invalid encoded dot format: empty writerId');
+  }
+
+  if (isNaN(counter) || counter <= 0) {
+    throw new Error('Invalid encoded dot format: invalid counter');
+  }
+
+  return { writerId, counter };
+}
+
+/**
+ * Compares two dots lexicographically.
+ * Order: writerId -> counter
+ *
+ * NOTE: This is ONLY for deterministic serialization ordering,
+ * NOT for "newest wins" semantics. Dots are identity, not timestamps.
+ *
+ * @param {Dot} a
+ * @param {Dot} b
+ * @returns {number} -1 if a < b, 0 if equal, 1 if a > b
+ */
+export function compareDots(a, b) {
+  // 1. Compare writerId as string
+  if (a.writerId !== b.writerId) {
+    return a.writerId < b.writerId ? -1 : 1;
+  }
+
+  // 2. Compare counter numerically
+  if (a.counter !== b.counter) {
+    return a.counter < b.counter ? -1 : 1;
+  }
+
+  return 0;
+}

package/src/domain/crdt/LWW.js

@@ -0,0 +1,154 @@
+import { compareEventIds } from '../utils/EventId.js';
+
+/**
+ * @fileoverview LWW Register - Last-Write-Wins with Total Ordering
+ *
+ * An LWW (Last-Write-Wins) register is a CRDT that resolves concurrent writes
+ * by keeping the write with the "greatest" timestamp. This implementation uses
+ * EventId as the timestamp, providing a deterministic total order.
+ *
+ * ## Total Ordering Guarantee
+ *
+ * Unlike wall-clock timestamps which can have ties, EventId provides a **total
+ * order** - for any two distinct EventIds, one is definitively greater than
+ * the other. This eliminates non-determinism in conflict resolution.
+ *
+ * The EventId comparison order is:
+ *
+ * 1. **Lamport timestamp** (numeric, ascending)
+ *    Higher Lamport = later in causal order or concurrent with higher clock
+ *
+ * 2. **writerId** (string, lexicographic)
+ *    Tie-breaker when Lamport timestamps match
+ *
+ * 3. **patchSha** (hex string, lexicographic)
+ *    Tie-breaker for same writer, same Lamport (different patches)
+ *
+ * 4. **opIndex** (numeric, ascending)
+ *    Tie-breaker for multiple operations within the same patch
+ *
+ * This four-level comparison ensures:
+ * - Causally-later writes generally win (via Lamport)
+ * - Concurrent writes have deterministic winners (via writerId)
+ * - All replicas agree on the winner without coordination
+ *
+ * ## Deterministic Tie-Break Behavior
+ *
+ * When EventIds are exactly equal (same lamport, writerId, patchSha, opIndex),
+ * the lwwMax function returns the first argument. This is deterministic because:
+ *
+ * - Equal EventIds mean the same operation from the same patch
+ * - The values must be identical (same operation)
+ * - Returning first argument is an arbitrary but consistent choice
+ *
+ * In practice, equal EventIds should only occur when merging a register with
+ * itself (idempotence).
+ *
+ * ## Why Lamport First?
+ *
+ * Lamport timestamps respect causality: if operation A happens-before B, then
+ * A's Lamport < B's Lamport. By sorting Lamport first:
+ *
+ * - Sequential writes are ordered correctly
+ * - "Later" concurrent writes tend to win (higher local clock)
+ * - The system exhibits intuitive "last write wins" behavior
+ *
+ * However, Lamport timestamps alone don't provide total order (concurrent
+ * operations can have the same Lamport), hence the additional tie-breakers.
+ *
+ * ## Semilattice Properties
+ *
+ * lwwMax forms a join-semilattice over LWW registers:
+ * - **Commutative**: lwwMax(a, b) === lwwMax(b, a)
+ * - **Associative**: lwwMax(lwwMax(a, b), c) === lwwMax(a, lwwMax(b, c))
+ * - **Idempotent**: lwwMax(a, a) === a
+ *
+ * These properties ensure conflict-free merging regardless of operation order.
+ *
+ * @module crdt/LWW
+ */
+
+/**
+ * LWW Register - stores value with EventId for conflict resolution
+ * @template T
+ * @typedef {Object} LWWRegister
+ * @property {import('../utils/EventId.js').EventId} eventId
+ * @property {T} value
+ */
+
+/**
+ * Creates an LWW register with the given EventId and value.
+ * @template T
+ * @param {import('../utils/EventId.js').EventId} eventId
+ * @param {T} value
+ * @returns {LWWRegister<T>}
+ */
+export function lwwSet(eventId, value) {
+  return { eventId, value };
+}
+
+/**
+ * Returns the LWW register with the greater EventId.
+ * This is the join operation for LWW registers.
+ *
+ * ## EventId Comparison Logic
+ *
+ * Comparison proceeds through four levels until a difference is found:
+ *
+ * 1. **lamport** (number): Higher Lamport timestamp wins. This respects
+ *    causality - if A happened-before B, A's Lamport < B's Lamport.
+ *
+ * 2. **writerId** (string): Lexicographic comparison. Deterministic tie-break
+ *    for concurrent operations with the same Lamport clock.
+ *
+ * 3. **patchSha** (string): Lexicographic comparison of Git commit SHA.
+ *    Distinguishes operations in different patches from the same writer.
+ *
+ * 4. **opIndex** (number): Numeric comparison. Distinguishes multiple
+ *    property-set operations within the same patch.
+ *
+ * ## Deterministic Tie-Break
+ *
+ * On exactly equal EventIds (cmp === 0), returns the first argument `a`.
+ * This is arbitrary but deterministic - all replicas make the same choice.
+ * In practice, equal EventIds only occur when merging identical operations.
+ *
+ * ## Semilattice Properties
+ *
+ * - **Commutative**: lwwMax(a, b) === lwwMax(b, a) -- both return the one
+ *   with greater EventId, or `a` on tie (same value anyway)
+ * - **Associative**: lwwMax(lwwMax(a, b), c) === lwwMax(a, lwwMax(b, c))
+ * - **Idempotent**: lwwMax(a, a) === a
+ *
+ * @template T
+ * @param {LWWRegister<T> | null | undefined} a - First register (returned on tie)
+ * @param {LWWRegister<T> | null | undefined} b - Second register
+ * @returns {LWWRegister<T> | null} Register with greater EventId, or null if both null/undefined
+ */
+export function lwwMax(a, b) {
+  // Handle null/undefined cases
+  if ((a === null || a === undefined) && (b === null || b === undefined)) {
+    return null;
+  }
+  if (a === null || a === undefined) {
+    return b;
+  }
+  if (b === null || b === undefined) {
+    return a;
+  }
+
+  // Compare EventIds - return the one with greater EventId
+  // On equal EventIds, return first argument (deterministic)
+  const cmp = compareEventIds(a.eventId, b.eventId);
+  return cmp >= 0 ? a : b;
+}
+
+/**
+ * Extracts just the value from an LWW register.
+ * @template T
+ * @param {LWWRegister<T> | null | undefined} reg
+ * @returns {T | undefined}
+ */
+export function lwwValue(reg) {
+  return reg?.value;
+}

package/src/domain/crdt/ORSet.js

@@ -0,0 +1,371 @@
+import { encodeDot, decodeDot, compareDots } from './Dot.js';
+import { vvContains } from './VersionVector.js';
+
+/**
+ * @fileoverview ORSet - Observed-Remove Set with Add-Wins Semantics
+ *
+ * An ORSet (Observed-Remove Set) is a CRDT that allows concurrent add and
+ * remove operations on a set while guaranteeing convergence. This implementation
+ * uses "add-wins" semantics: when an add and remove happen concurrently, the
+ * add wins.
+ *
+ * ## Add-Wins Semantics
+ *
+ * The key insight of OR-Sets is that removals only affect adds they have
+ * *observed*. When you remove an element, you're really saying "remove all
+ * the add operations I've seen for this element." Any concurrent add (one
+ * you haven't seen) survives.
+ *
+ * This is implemented via dots:
+ * - Each add operation is tagged with a unique dot (writerId, counter)
+ * - Remove records which dots it has observed (the "observed set")
+ * - The element is present if ANY of its dots is not tombstoned
+ *
+ * Example of add-wins:
+ * ```
+ * Writer A: add("x") with dot (A,1)
+ * Writer B: (concurrently) remove("x") with observed dots {}
+ * Result: "x" is present (dot (A,1) was not observed by B's remove)
+ * ```
+ *
+ * Example of remove-wins (when add was observed):
+ * ```
+ * Writer A: add("x") with dot (A,1)
+ * Writer B: (after sync) remove("x") with observed dots {(A,1)}
+ * Result: "x" is absent (all its dots are tombstoned)
+ * ```
+ *
+ * ## Global Tombstones
+ *
+ * This implementation uses a **global tombstone set** rather than per-element
+ * tombstones. This is an optimization for space efficiency:
+ *
+ * - **Global tombstones**: A single Set<encodedDot> holds all tombstoned dots
+ *   across all elements. When checking if an element is present, we check if
+ *   ANY of its dots is NOT in the global tombstone set.
+ *
+ * - **Why global**: In a graph database, nodes and edges may be added/removed
+ *   many times. Per-element tombstone tracking would require storing removed
+ *   dots with each element forever. Global tombstones allow efficient compaction.
+ *
+ * - **Correctness**: Tombstones are dots, not elements. A dot uniquely identifies
+ *   one add operation. Tombstoning dot (A,5) only affects that specific add,
+ *   not any other add of the same element with a different dot.
+ *
+ * ## Semilattice Properties
+ *
+ * orsetJoin forms a join-semilattice:
+ * - **Commutative**: orsetJoin(a, b) equals orsetJoin(b, a)
+ * - **Associative**: orsetJoin(orsetJoin(a, b), c) equals orsetJoin(a, orsetJoin(b, c))
+ * - **Idempotent**: orsetJoin(a, a) equals a
+ *
+ * The join takes the union of both entries and tombstones. This ensures:
+ * - All adds from all replicas are preserved
+ * - All removes from all replicas are preserved
+ * - Convergence regardless of merge order
+ *
+ * ## Garbage Collection Safety
+ *
+ * The orsetCompact function removes tombstoned dots to reclaim memory, but
+ * must do so safely to avoid "zombie" resurrections:
+ *
+ * **GC Safety Invariant**: A tombstoned dot may only be compacted if ALL
+ * replicas have observed it. This is tracked via the version vector: if
+ * vvContains(includedVV, dot) is true for the "included" frontier, then
+ * all replicas have seen this dot and its tombstone.
+ *
+ * **What happens if violated**: If we compact (A,5) before replica B has seen
+ * it, and B later sends an add with dot (A,5), we'd have no tombstone to
+ * suppress it, causing a resurrection.
+ *
+ * @module crdt/ORSet
+ */
+
+/**
+ * ORSet (Observed-Remove Set) - A CRDT set that supports add and remove operations.
+ *
+ * This is a GLOBAL OR-Set (one per category, not per element). It tracks:
+ * - entries: Map<element, Set<encodedDot>> - elements and the dots that added them
+ * - tombstones: Set<encodedDot> - global tombstones for removed dots
+ *
+ * An element is present if it has at least one non-tombstoned dot.
+ *
+ * @typedef {Object} ORSet
+ * @property {Map<*, Set<string>>} entries - element -> dots that added it
+ * @property {Set<string>} tombstones - global tombstones
+ */
+
+/**
+ * Creates an empty ORSet.
+ *
+ * @returns {ORSet}
+ */
+export function createORSet() {
+  return {
+    entries: new Map(),
+    tombstones: new Set(),
+  };
+}
+
+/**
+ * Adds an element to the ORSet with the given dot.
+ * Mutates the set.
+ *
+ * @param {ORSet} set - The ORSet to mutate
+ * @param {*} element - The element to add
+ * @param {import('./Dot.js').Dot} dot - The dot representing this add operation
+ */
+export function orsetAdd(set, element, dot) {
+  const encoded = encodeDot(dot);
+
+  if (!set.entries.has(element)) {
+    set.entries.set(element, new Set());
+  }
+
+  set.entries.get(element).add(encoded);
+}
+
+/**
+ * Removes an element by adding its observed dots to the tombstones.
+ * Mutates the set.
+ *
+ * @param {ORSet} set - The ORSet to mutate
+ * @param {Set<string>} observedDots - The encoded dots to tombstone
+ */
+export function orsetRemove(set, observedDots) {
+  for (const encodedDot of observedDots) {
+    set.tombstones.add(encodedDot);
+  }
+}
+
+/**
+ * Checks if an element is present in the ORSet.
+ * An element is present if it has at least one non-tombstoned dot.
+ *
+ * @param {ORSet} set - The ORSet to check
+ * @param {*} element - The element to check
+ * @returns {boolean}
+ */
+export function orsetContains(set, element) {
+  const dots = set.entries.get(element);
+  if (!dots) {
+    return false;
+  }
+
+  for (const encodedDot of dots) {
+    if (!set.tombstones.has(encodedDot)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Returns all present elements in the ORSet.
+ * Only returns elements that have at least one non-tombstoned dot.
+ *
+ * @param {ORSet} set - The ORSet
+ * @returns {Array<*>} Array of present elements
+ */
+export function orsetElements(set) {
+  const result = [];
+
+  for (const element of set.entries.keys()) {
+    if (orsetContains(set, element)) {
+      result.push(element);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Returns the non-tombstoned dots for an element.
+ *
+ * @param {ORSet} set - The ORSet
+ * @param {*} element - The element
+ * @returns {Set<string>} Set of encoded dots that are not tombstoned
+ */
+export function orsetGetDots(set, element) {
+  const dots = set.entries.get(element);
+  if (!dots) {
+    return new Set();
+  }
+
+  const result = new Set();
+  for (const encodedDot of dots) {
+    if (!set.tombstones.has(encodedDot)) {
+      result.add(encodedDot);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Joins two ORSets by taking the union of entries and tombstones.
+ * Returns a new ORSet; does not mutate inputs.
+ *
+ * Properties:
+ * - Commutative: orsetJoin(a, b) equals orsetJoin(b, a)
+ * - Associative: orsetJoin(orsetJoin(a, b), c) equals orsetJoin(a, orsetJoin(b, c))
+ * - Idempotent: orsetJoin(a, a) equals a
+ *
+ * @param {ORSet} a
+ * @param {ORSet} b
+ * @returns {ORSet}
+ */
+export function orsetJoin(a, b) {
+  const result = createORSet();
+
+  // Union entries from a
+  for (const [element, dots] of a.entries) {
+    result.entries.set(element, new Set(dots));
+  }
+
+  // Union entries from b
+  for (const [element, dots] of b.entries) {
+    if (!result.entries.has(element)) {
+      result.entries.set(element, new Set());
+    }
+    const resultDots = result.entries.get(element);
+    for (const dot of dots) {
+      resultDots.add(dot);
+    }
+  }
+
+  // Union tombstones
+  for (const dot of a.tombstones) {
+    result.tombstones.add(dot);
+  }
+  for (const dot of b.tombstones) {
+    result.tombstones.add(dot);
+  }
+
+  return result;
+}
+
+/**
+ * Compacts the ORSet by removing tombstoned dots that are <= includedVV.
+ * Mutates the set.
+ *
+ * ## GC Safety Invariant
+ *
+ * This function implements safe garbage collection for OR-Set tombstones.
+ * The invariant is: **only compact dots that ALL replicas have observed**.
+ *
+ * The `includedVV` parameter represents the "stable frontier" - the version
+ * vector that all known replicas have reached. A dot (writerId, counter) is
+ * safe to compact if:
+ *
+ * 1. The dot is TOMBSTONED (it was removed)
+ * 2. The dot is <= includedVV (all replicas have seen it)
+ *
+ * ### Why both conditions?
+ *
+ * - **Condition 1 (tombstoned)**: Live dots must never be compacted. Removing
+ *   a live dot would make the element disappear incorrectly.
+ *
+ * - **Condition 2 (<= includedVV)**: If a replica hasn't seen this dot yet,
+ *   it might send it later. Without the tombstone, we'd have no record that
+ *   it was deleted, causing resurrection.
+ *
+ * ### Correctness Proof Sketch
+ *
+ * After compaction of dot D:
+ * - D is removed from entries (if present)
+ * - D is removed from tombstones
+ *
+ * If replica B later sends D:
+ * - Since D <= includedVV, B has already observed D
+ * - B's state must also have D tombstoned (or never had it)
+ * - Therefore B cannot send D as a live add
+ *
+ * @param {ORSet} set - The ORSet to compact
+ * @param {import('./VersionVector.js').VersionVector} includedVV - The stable frontier version vector.
+ *   All replicas are known to have observed at least this causal context.
+ */
+export function orsetCompact(set, includedVV) {
+  for (const [element, dots] of set.entries) {
+    for (const encodedDot of dots) {
+      const dot = decodeDot(encodedDot);
+      // Only compact if: (1) dot is tombstoned AND (2) dot <= includedVV
+      if (set.tombstones.has(encodedDot) && vvContains(includedVV, dot)) {
+        dots.delete(encodedDot);
+        set.tombstones.delete(encodedDot);
+      }
+    }
+    if (dots.size === 0) {
+      set.entries.delete(element);
+    }
+  }
+}
+
+/**
+ * Serializes an ORSet to a plain object for CBOR encoding.
+ * Entries are sorted by element (stringified), dots within entries are sorted.
+ * Tombstones are sorted.
+ *
+ * @param {ORSet} set
+ * @returns {{entries: Array<[*, string[]]>, tombstones: string[]}}
+ */
+export function orsetSerialize(set) {
+  // Serialize entries: convert Map to array of [element, sortedDots]
+  const entriesArray = [];
+  for (const [element, dots] of set.entries) {
+    const sortedDots = [...dots].sort((a, b) => {
+      const dotA = decodeDot(a);
+      const dotB = decodeDot(b);
+      return compareDots(dotA, dotB);
+    });
+    entriesArray.push([element, sortedDots]);
+  }
+
+  // Sort entries by element (stringified for consistency)
+  entriesArray.sort((a, b) => {
+    const keyA = String(a[0]);
+    const keyB = String(b[0]);
+    return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+  });
+
+  // Serialize tombstones: sorted array
+  const sortedTombstones = [...set.tombstones].sort((a, b) => {
+    const dotA = decodeDot(a);
+    const dotB = decodeDot(b);
+    return compareDots(dotA, dotB);
+  });
+
+  return {
+    entries: entriesArray,
+    tombstones: sortedTombstones,
+  };
+}
+
+/**
+ * Deserializes a plain object back to an ORSet.
+ *
+ * @param {{entries?: Array<[*, string[]]>, tombstones?: string[]}} obj
+ * @returns {ORSet}
+ */
+export function orsetDeserialize(obj) {
+  const set = createORSet();
+
+  // Deserialize entries
+  if (obj.entries && Array.isArray(obj.entries)) {
+    for (const [element, dots] of obj.entries) {
+      if (Array.isArray(dots)) {
+        set.entries.set(element, new Set(dots));
+      }
+    }
+  }
+
+  // Deserialize tombstones
+  if (obj.tombstones && Array.isArray(obj.tombstones)) {
+    for (const dot of obj.tombstones) {
+      set.tombstones.add(dot);
+    }
+  }
+
+  return set;
+}