@vuer-ai/vuer-rtc 0.7.0 → 0.8.2

package/src/operations/dispatcher.ts

@@ -12,7 +12,7 @@ import type { OpMeta } from './apply/types.js';
 import * as registry from './apply/index.js';
 
 /**
- * Handler map: otype -> apply function
+ * Handler map: ot -> apply function
  */
 const handlers: Record<string, (graph: SceneGraph, op: Operation, meta: OpMeta) => void> = {
   // Number operations
@@ -80,14 +80,50 @@ export function applyOperation(
   op: Operation,
   meta: OpMeta
 ): void {
-  const handler = handlers[op.otype];
+  const handler = handlers[op.ot];
   if (handler) {
     handler(graph, op, meta);
   } else {
-    console.warn(`Unknown otype: ${op.otype}`);
+    console.warn(`Unknown ot: ${op.ot}`);
   }
 }
 
+/**
+ * Compare operations for sorting by Lamport timestamp.
+ * CRDT invariant: operations must be applied in causal order (seq → ts → id).
+ *
+ * This ensures that:
+ * 1. Operations with lower Lamport clocks are applied first
+ * 2. If Lamport clocks are equal, wall-clock time breaks the tie
+ * 3. If both are equal, lexicographic ID order ensures determinism
+ *
+ * @param a - First operation
+ * @param b - Second operation
+ * @returns Negative if a < b, positive if a > b, 0 if equal
+ */
+function compareOperations(a: Operation, b: Operation): number {
+  const aOp = a as any;
+  const bOp = b as any;
+
+  // Compare by Lamport clock (seq)
+  if (aOp.seq !== undefined && bOp.seq !== undefined) {
+    if (aOp.seq !== bOp.seq) return aOp.seq - bOp.seq;
+  }
+
+  // If equal or missing, compare by wall-clock time (ts)
+  if (aOp.ts !== undefined && bOp.ts !== undefined) {
+    if (aOp.ts !== bOp.ts) return aOp.ts - bOp.ts;
+  }
+
+  // Final fallback: compare by ID (lexicographic)
+  if (aOp.id && bOp.id) {
+    return String(aOp.id).localeCompare(String(bOp.id));
+  }
+
+  // If no metadata, preserve original order
+  return 0;
+}
+
 /**
  * Shallow clone the graph and modified nodes
  */
@@ -112,24 +148,29 @@ export function applyMessage(graph: SceneGraph, msg: CRDTMessage): SceneGraph {
   const newGraph = shallowCloneGraph(graph);
 
   const meta: OpMeta = {
-    sessionId: msg.sessionId,
+    client: msg.client,
     clock: msg.clock,
-    lamportTime: msg.lamportTime,
-    timestamp: msg.timestamp,
+    lt: msg.lt,
+    ts: msg.ts,
   };
 
-  for (const op of msg.ops) {
+  // Sort operations by Lamport timestamp to ensure causal order
+  // This is critical for CRDT correctness, especially for text operations
+  // where replace ops may reference IDs from insert ops
+  const sortedOps = [...msg.ops].sort(compareOperations);
+
+  for (const op of sortedOps) {
     // Determine all node keys that this operation will mutate
     const keysToClone: string[] = [];
     if (op.key && newGraph.nodes[op.key]) {
       keysToClone.push(op.key);
     }
-    if (op.otype === 'node.move') {
+    if (op.ot === 'node.move') {
       const { nodeKey, newParent } = (op as any).value;
       if (nodeKey && newGraph.nodes[nodeKey]) keysToClone.push(nodeKey);
       if (newParent && newGraph.nodes[newParent]) keysToClone.push(newParent);
     }
-    if (op.otype === 'node.remove') {
+    if (op.ot === 'node.remove') {
       const nodeKey = (op as any).value;
       if (typeof nodeKey === 'string' && newGraph.nodes[nodeKey]) keysToClone.push(nodeKey);
     }
@@ -158,13 +199,16 @@ export function applyMessage(graph: SceneGraph, msg: CRDTMessage): SceneGraph {
  */
 export function applyMessageMut(graph: SceneGraph, msg: CRDTMessage): void {
   const meta: OpMeta = {
-    sessionId: msg.sessionId,
+    client: msg.client,
     clock: msg.clock,
-    lamportTime: msg.lamportTime,
-    timestamp: msg.timestamp,
+    lt: msg.lt,
+    ts: msg.ts,
   };
 
-  for (const op of msg.ops) {
+  // Sort operations by Lamport timestamp to ensure causal order
+  const sortedOps = [...msg.ops].sort(compareOperations);
+
+  for (const op of sortedOps) {
     applyOperation(graph, op, meta);
   }
 }

package/src/serdes.ts

@@ -22,7 +22,7 @@ export type WireMessage =
   | { mtype: 'error'; msgId: string; error: string }
   | { mtype: 'state'; snapshot: Snapshot; journal: CRDTMessage[] }
   | { mtype: 'sync'; vectorClock?: VectorClock; filter: Uint8Array; count: number }
-  | { mtype: 'heartbeat'; sessionId: string; vectorClock: VectorClock }
+  | { mtype: 'heartbeat'; client: string; vectorClock: VectorClock }
   | { mtype: 'room-reset' }
   | { mtype: 'compaction-watermark'; watermark: VectorClock };
 

package/src/state/ConflictResolver.ts

@@ -2,29 +2,29 @@
  * ConflictResolver - Operation-based property conflict resolution
  *
  * Merges concurrent property updates based on:
- * - Operation type (otype) which encodes dtype.operation
+ * - Operation type (ot) which encodes dtype.operation
  * - DType merge functions
  *
- * Schema-less: dtype and operation are derived from otype.
+ * Schema-less: dtype and operation are derived from ot.
  */
 
 import { DType, type ValueWithMeta } from './DType.js';
 
 /**
- * Parse otype string into dtype and operation
+ * Parse ot string into dtype and operation
  *
  * @example
  * parseOtype('vector3.add') // { dtype: 'vector3', operation: 'add' }
  * parseOtype('number.set')  // { dtype: 'number', operation: 'set' }
  */
-export function parseOtype(otype: string): { dtype: string; operation: string } {
-  const dotIndex = otype.indexOf('.');
+export function parseOtype(ot: string): { dtype: string; operation: string } {
+  const dotIndex = ot.indexOf('.');
   if (dotIndex === -1) {
-    return { dtype: otype, operation: 'set' };
+    return { dtype: ot, operation: 'set' };
   }
   return {
-    dtype: otype.slice(0, dotIndex),
-    operation: otype.slice(dotIndex + 1),
+    dtype: ot.slice(0, dotIndex),
+    operation: ot.slice(dotIndex + 1),
   };
 }
 
@@ -32,23 +32,23 @@ export class ConflictResolver {
   /**
    * Merge a single property from multiple concurrent updates
    *
-   * @param otype - Operation type (e.g., 'vector3.add', 'number.set')
+   * @param ot - Operation type (e.g., 'vector3.add', 'number.set')
    * @param values - Array of values with metadata
    * @returns Merged value
    */
   mergeProperty<T = any>(
-    otype: string,
+    ot: string,
     values: ValueWithMeta<T>[]
   ): T {
     if (values.length === 0) {
-      throw new Error(`Cannot merge empty values for otype: ${otype}`);
+      throw new Error(`Cannot merge empty values for ot: ${ot}`);
     }
 
     if (values.length === 1) {
       return values[0].value;
     }
 
-    const { dtype, operation } = parseOtype(otype);
+    const { dtype, operation } = parseOtype(ot);
 
     // Get merge function based on dtype and operation
     const mergeFn = this.getMergeFunction(dtype, operation);
@@ -72,14 +72,14 @@ export class ConflictResolver {
   mergeProperties(
     updates: Array<{
       properties: Record<string, any>;
-      otypes: Record<string, string>; // otype per property
-      lamportTime: number;
-      sessionId: string;
+      ots: Record<string, string>; // ot per property
+      lt: number;
+      client: string;
     }>
   ): Record<string, any> {
     // Group values by property name
     const valuesByProperty = new Map<string, ValueWithMeta[]>();
-    const otypeByProperty = new Map<string, string>();
+    const otByProperty = new Map<string, string>();
 
     for (const update of updates) {
       for (const [key, value] of Object.entries(update.properties)) {
@@ -89,13 +89,13 @@ export class ConflictResolver {
 
         valuesByProperty.get(key)!.push({
           value,
-          lamportTime: update.lamportTime,
-          sessionId: update.sessionId,
+          lt: update.lt,
+          client: update.client,
         });
 
-        // Store otype for this property
-        if (update.otypes?.[key]) {
-          otypeByProperty.set(key, update.otypes[key]);
+        // Store ot for this property
+        if (update.ots?.[key]) {
+          otByProperty.set(key, update.ots[key]);
         }
       }
     }
@@ -104,8 +104,8 @@ export class ConflictResolver {
     const result: Record<string, any> = {};
 
     for (const [propertyName, values] of valuesByProperty.entries()) {
-      const otype = otypeByProperty.get(propertyName) || 'any.set';
-      result[propertyName] = this.mergeProperty(otype, values);
+      const ot = otByProperty.get(propertyName) || 'any.set';
+      result[propertyName] = this.mergeProperty(ot, values);
     }
 
     return result;

package/src/state/DType.ts

@@ -12,8 +12,8 @@
  */
 export interface ValueWithMeta<T = any> {
   value: T;
-  lamportTime: number;
-  sessionId?: string;
+  lt: number;
+  client?: string;
 }
 
 /**
@@ -37,7 +37,7 @@ export const DType = {
      * SET - Last-Write-Wins
      */
     set: ((values: ValueWithMeta<number>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<number>,
 
@@ -78,7 +78,7 @@ export const DType = {
      * SET - Last-Write-Wins
      */
     set: ((values: ValueWithMeta<string>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<string>,
 
@@ -86,7 +86,7 @@ export const DType = {
      * CONCAT - Concatenate (ordered by lamport)
      */
     concat: ((values: ValueWithMeta<string>[], separator = '\n') => {
-      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      const sorted = [...values].sort((a, b) => a.lt - b.lt);
       return sorted.map((v) => v.value).join(separator);
     }) as MergeFn<string>,
   },
@@ -99,7 +99,7 @@ export const DType = {
      * SET - Last-Write-Wins
      */
     set: ((values: ValueWithMeta<boolean>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<boolean>,
 
@@ -130,7 +130,7 @@ export const DType = {
      * SET - Replace entire vector (preserves user intent)
      */
     set: ((values: ValueWithMeta<[number, number, number]>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<[number, number, number]>,
 
@@ -169,7 +169,7 @@ export const DType = {
      * SET - Replace entire quaternion
      */
     set: ((values: ValueWithMeta<[number, number, number, number]>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<[number, number, number, number]>,
 
@@ -177,7 +177,7 @@ export const DType = {
      * MULTIPLY - Quaternion multiplication (composition)
      */
     multiply: ((values: ValueWithMeta<[number, number, number, number]>[]) => {
-      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      const sorted = [...values].sort((a, b) => a.lt - b.lt);
       let result = sorted[0].value;
 
       for (let i = 1; i < sorted.length; i++) {
@@ -196,7 +196,7 @@ export const DType = {
      * SET - Replace color
      */
     set: ((values: ValueWithMeta<string>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<string>,
 
@@ -224,7 +224,7 @@ export const DType = {
      * SET - Replace entire array
      */
     set: ((values: ValueWithMeta<any[]>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<any[]>,
 
@@ -240,7 +240,7 @@ export const DType = {
      * APPEND - Append all (ordered by lamport)
      */
     append: ((values: ValueWithMeta<any[]>[]) => {
-      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      const sorted = [...values].sort((a, b) => a.lt - b.lt);
       return sorted.flatMap((v) => v.value);
     }) as MergeFn<any[]>,
   },
@@ -253,7 +253,7 @@ export const DType = {
      * SET - Replace entire object
      */
     set: ((values: ValueWithMeta<Record<string, any>>[]) => {
-      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      const sorted = [...values].sort((a, b) => b.lt - a.lt);
       return sorted[0].value;
     }) as MergeFn<Record<string, any>>,
 
@@ -266,9 +266,9 @@ export const DType = {
 
       for (const v of values) {
         for (const [key, value] of Object.entries(v.value)) {
-          if (!latestTimes[key] || v.lamportTime > latestTimes[key]) {
+          if (!latestTimes[key] || v.lt > latestTimes[key]) {
             result[key] = value;
-            latestTimes[key] = v.lamportTime;
+            latestTimes[key] = v.lt;
           }
         }
       }
@@ -287,7 +287,7 @@ export const DType = {
   immutable: {
     set: ((values: ValueWithMeta[]) => {
       // Return first value (creation value)
-      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      const sorted = [...values].sort((a, b) => a.lt - b.lt);
       return sorted[0].value;
     }) as MergeFn,
   },

package/src/state/VectorClock.ts

@@ -11,35 +11,35 @@ export type VectorClock = Record<string, number>;
 
 export class VectorClockManager {
   /**
-   * Create a new vector clock for a session
-   * Initializes the session's counter to 0
+   * Create a new vector clock for a client
+   * Initializes the client's counter to 0
    */
-  create(sessionId: string): VectorClock {
-    return { [sessionId]: 0 };
+  create(client: string): VectorClock {
+    return { [client]: 0 };
   }
 
   /**
-   * Increment the counter for a session
+   * Increment the counter for a client
    * Returns a new clock (immutable)
    */
-  increment(clock: VectorClock, sessionId: string): VectorClock {
-    const currentValue = clock[sessionId] || 0;
+  increment(clock: VectorClock, client: string): VectorClock {
+    const currentValue = clock[client] || 0;
     return {
       ...clock,
-      [sessionId]: currentValue + 1,
+      [client]: currentValue + 1,
     };
   }
 
   /**
    * Merge two vector clocks
-   * Takes the maximum value for each session
+   * Takes the maximum value for each client
    * Used when receiving remote operations
    */
   merge(clock1: VectorClock, clock2: VectorClock): VectorClock {
     const merged: VectorClock = { ...clock1 };
 
-    Object.entries(clock2).forEach(([sessionId, count]) => {
-      merged[sessionId] = Math.max(merged[sessionId] || 0, count);
+    Object.entries(clock2).forEach(([client, count]) => {
+      merged[client] = Math.max(merged[client] || 0, count);
     });
 
     return merged;
@@ -62,9 +62,9 @@ export class VectorClockManager {
     let clock1Greater = false;
     let clock2Greater = false;
 
-    allSessionIds.forEach((sessionId) => {
-      const val1 = clock1[sessionId] || 0;
-      const val2 = clock2[sessionId] || 0;
+    allSessionIds.forEach((client) => {
+      const val1 = clock1[client] || 0;
+      const val2 = clock2[client] || 0;
 
       if (val1 > val2) {
         clock1Greater = true;

package/src/state/index.ts

@@ -4,7 +4,7 @@
  * - VectorClock: Used by client for causal ordering
  * - DType, ConflictResolver: Server-side conflict resolution for concurrent updates
  *
- * Schema-less design: dtype and operation are derived from otype (e.g., 'vector3.add').
+ * Schema-less design: dtype and operation are derived from ot (e.g., 'vector3.add').
  */
 
 // Vector clock (used by client and server)