@vuer-ai/vuer-rtc-server 0.2.3 → 0.4.1

package/src/journal/{JournalService.ts → GraphJournalService.ts}

@@ -1,8 +1,8 @@
 /**
- * Journal Service - Business logic for journal operations
+ * Graph Journal Service - Business logic for graph document journal operations
  *
  * Handles:
- * - Receiving and validating CRDTMessages
+ * - Receiving and validating CRDTMessages for graph documents
  * - Storing messages in journal
  * - Processing meta.undo/meta.redo operations
  * - Computing current graph state
@@ -21,8 +21,6 @@ import {
   OperationValidator,
   TextRope,
   compactRope,
-  toRaw,
-  fromRaw,
 } from '@vuer-ai/vuer-rtc';
 
 import { JournalRepository } from './JournalRepository.js';
@@ -31,7 +29,7 @@ import { DocumentRepository } from '../persistence/DocumentRepository.js';
 /**
  * Safely serialize an object, handling circular references by removing them.
  * Also strips 'parent' references which cause cycles in tree structures.
- * Properly serializes TextRope instances using toRaw().
+ * TextRope instances are automatically serialized to strings via toJSON().
  */
 function safeSerialize(obj: unknown): unknown {
   const seen = new WeakSet();
@@ -39,14 +37,6 @@ function safeSerialize(obj: unknown): unknown {
     // Skip parent references which cause cycles
     if (key === 'parent') return undefined;
 
-    // Properly serialize TextRope instances using toRaw()
-    if (value instanceof TextRope) {
-      return {
-        _textRope: true,
-        raw: toRaw(value),
-      };
-    }
-
     if (typeof value === 'object' && value !== null) {
       if (seen.has(value)) return undefined; // Circular reference
       seen.add(value);
@@ -71,49 +61,21 @@ export interface DocumentState {
   journal: JournalEntry[];
 }
 
-/**
- * Recursively walk an object and restore TextRope instances from their raw form.
- */
-function restoreTextRopes(obj: any): any {
-  if (obj === null || obj === undefined) return obj;
-
-  // Check if this is a serialized TextRope
-  if (typeof obj === 'object' && obj._textRope === true && obj.raw) {
-    return fromRaw(obj.raw);
-  }
-
-  // Recursively process arrays
-  if (Array.isArray(obj)) {
-    return obj.map(restoreTextRopes);
-  }
-
-  // Recursively process objects
-  if (typeof obj === 'object') {
-    const result: any = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = restoreTextRopes(value);
-    }
-    return result;
-  }
-
-  return obj;
-}
 
 /**
  * Safely parse a Document.currentState (Json) into a Snapshot,
  * providing defaults for any missing fields.
- * Restores TextRope instances from their serialized raw form.
+ * Text properties are stored as plain strings and lazy-upgraded to TextRope on edit.
  */
 function parseSnapshot(currentState: unknown): Snapshot {
   const raw = (currentState ?? {}) as Record<string, unknown>;
 
-  // Restore TextRope instances in the graph
-  const graph = restoreTextRopes(raw.graph as SceneGraph) || createEmptyGraph();
+  const graph = (raw.graph as SceneGraph) || createEmptyGraph();
 
   return {
     graph,
     vectorClock: (raw.vectorClock as Record<string, number>) || {},
-    lamportTime: (typeof raw.lamportTime === 'number' ? raw.lamportTime : 0),
+    lt: (typeof raw.lt === 'number' ? raw.lt : 0),
     journalIndex: (typeof raw.journalIndex === 'number' ? raw.journalIndex : 0),
   };
 }
@@ -159,7 +121,7 @@ function compactTextRopes(graph: SceneGraph): SceneGraph {
   return { ...graph, nodes };
 }
 
-export class JournalService {
+export class GraphJournalService {
   private journalRepo: JournalRepository;
   private documentRepo: DocumentRepository;
   private validator: OperationValidator;
@@ -231,10 +193,10 @@ export class JournalService {
     for (let i = 1; i < memberClocks.length; i++) {
       const clock = memberClocks[i];
       // For each session in result, take min with this clock
-      for (const sessionId of Object.keys(result)) {
-        result[sessionId] = Math.min(
-          result[sessionId],
-          clock[sessionId] ?? 0,
+      for (const client of Object.keys(result)) {
+        result[client] = Math.min(
+          result[client],
+          clock[client] ?? 0,
         );
       }
       // Sessions not in result but in clock are implicitly 0 in result,
@@ -249,8 +211,8 @@ export class JournalService {
    * watermark[S] >= clock[S].
    */
   isDominatedByWatermark(msgClock: VectorClock, watermark: VectorClock): boolean {
-    for (const [sessionId, time] of Object.entries(msgClock)) {
-      if ((watermark[sessionId] ?? 0) < time) {
+    for (const [client, time] of Object.entries(msgClock)) {
+      if ((watermark[client] ?? 0) < time) {
         return false;
       }
     }
@@ -308,7 +270,7 @@ export class JournalService {
     // getSince() now returns PersistedJournalEntry with deletedAt from DB.
     const persistedEntries = await this.journalRepo.getSince(
       documentId,
-      snapshot.lamportTime,
+      snapshot.lt,
     );
 
     const journal: JournalEntry[] = persistedEntries.map((entry) => ({
@@ -350,19 +312,19 @@ export class JournalService {
 
     // Process meta operations (undo/redo)
     for (const op of msg.ops) {
-      if (op.otype === 'meta.undo') {
+      if (op.ot === 'meta.undo') {
         const targetId = (op as any).targetMsgId;
         const target = state.journal.find((e) => e.msg.id === targetId);
         if (target) {
-          target.deletedAt = msg.timestamp;
-          // Persist deletedAt to DB (timestamp is seconds, DB stores as Date in ms)
+          target.deletedAt = msg.ts;
+          // Persist deletedAt to DB (ts is seconds, DB stores as Date in ms)
           await this.journalRepo.updateDeletedAt(
             documentId,
             targetId,
-            new Date(msg.timestamp * 1000),
+            new Date(msg.ts * 1000),
           );
         }
-      } else if (op.otype === 'meta.redo') {
+      } else if (op.ot === 'meta.redo') {
         const targetId = (op as any).targetMsgId;
         const target = state.journal.find((e) => e.msg.id === targetId);
         if (target) {
@@ -393,7 +355,7 @@ export class JournalService {
 
       // Filter out meta ops for graph computation
       const realOps = entry.msg.ops.filter(
-        (op) => !op.otype.startsWith('meta.')
+        (op) => !op.ot.startsWith('meta.')
       );
       if (realOps.length > 0) {
         graph = applyMessage(graph, { ...entry.msg, ops: realOps });
@@ -425,9 +387,9 @@ export class JournalService {
     // to handle out-of-order messages correctly after compaction
     const postSnapshotJournal = state.journal
       .filter((e) => {
-        // Include message if ANY session in its clock is ahead of snapshot
-        for (const [sessionId, time] of Object.entries(e.msg.clock)) {
-          if (time > (state.snapshot.vectorClock[sessionId] ?? 0)) {
+        // Include message if ANY client in its clock is ahead of snapshot
+        for (const [client, time] of Object.entries(e.msg.clock)) {
+          if (time > (state.snapshot.vectorClock[client] ?? 0)) {
             return true;
           }
         }
@@ -435,10 +397,8 @@ export class JournalService {
       })
       .map((e) => e.msg);
 
-    // Serialize TextRope instances in snapshot before sending to client.
-    // The in-memory snapshot contains TextRope instances (from restoreTextRopes),
-    // but MessagePack can't serialize class instances properly. Convert them to
-    // {_textRope: true, raw: [...]} format so the client can hydrate them.
+    // Serialize snapshot before sending to client. TextRope instances (if any)
+    // are automatically converted to plain strings via toJSON().
     const serializedSnapshot = safeSerialize(state.snapshot) as Snapshot;
 
     return {
@@ -485,27 +445,27 @@ export class JournalService {
       // Build new snapshot from entries [0..compactUpToIndex]
       let newGraph = state.snapshot.graph;
       let mergedClock = { ...state.snapshot.vectorClock };
-      let maxLamport = state.snapshot.lamportTime;
+      let maxLamport = state.snapshot.lt;
 
       for (let i = 0; i <= compactUpToIndex; i++) {
         const entry = state.journal[i];
         if (!entry.deletedAt) {
           // Filter out meta ops for graph computation
           const realOps = entry.msg.ops.filter(
-            (op) => !op.otype.startsWith('meta.')
+            (op) => !op.ot.startsWith('meta.')
           );
           if (realOps.length > 0) {
             newGraph = applyMessage(newGraph, { ...entry.msg, ops: realOps });
           }
         }
         // Merge clock and lamport regardless of deletedAt
-        for (const [sessionId, time] of Object.entries(entry.msg.clock)) {
-          mergedClock[sessionId] = Math.max(
-            mergedClock[sessionId] || 0,
+        for (const [client, time] of Object.entries(entry.msg.clock)) {
+          mergedClock[client] = Math.max(
+            mergedClock[client] || 0,
             time,
           );
         }
-        maxLamport = Math.max(maxLamport, entry.msg.lamportTime);
+        maxLamport = Math.max(maxLamport, entry.msg.lt);
       }
 
       // Collect batchIds of compacted entries before mutating state
@@ -526,7 +486,7 @@ export class JournalService {
       state.snapshot = {
         graph: newGraph,
         vectorClock: mergedClock,
-        lamportTime: maxLamport,
+        lt: maxLamport,
         journalIndex: maxLamport,
       };
 
@@ -585,7 +545,7 @@ export class JournalService {
       snapshot: {
         graph: createEmptyGraph(),
         vectorClock: {},
-        lamportTime: 0,
+        lt: 0,
         journalIndex: 0,
       },
       journal: [],
@@ -611,7 +571,7 @@ export class JournalService {
       snapshot: {
         graph: createEmptyGraph(),
         vectorClock: {},
-        lamportTime: 0,
+        lt: 0,
         journalIndex: 0,
       },
       journal: [],

package/src/journal/JournalRLE.ts

@@ -18,7 +18,7 @@ import type { CRDTMessage } from '@vuer-ai/vuer-rtc';
  * Compressed operation segment - groups consecutive ops from same agent
  */
 export interface RLESegment {
-  agentId: string;        // sessionId from first message in run
+  agentId: string;        // client from first message in run
   count: number;          // Number of messages in this run
   messages: CRDTMessage[]; // The actual messages (compressed payload)
 }
@@ -40,8 +40,8 @@ export interface RLEEncodedJournal {
 /**
  * Encode a sequence of CRDTMessages using RLE
  *
- * Groups consecutive messages from the same sessionId into segments.
- * Each segment stores the sessionId once and all messages in that run.
+ * Groups consecutive messages from the same client into segments.
+ * Each segment stores the client once and all messages in that run.
  */
 export function encodeJournalRLE(messages: CRDTMessage[]): RLEEncodedJournal {
   if (messages.length === 0) {
@@ -61,7 +61,7 @@ export function encodeJournalRLE(messages: CRDTMessage[]): RLEEncodedJournal {
   let currentSegment: RLESegment | null = null;
 
   for (const msg of messages) {
-    const agentId = msg.sessionId;
+    const agentId = msg.client;
 
     // Start a new segment if agent changes
     if (!currentSegment || currentSegment.agentId !== agentId) {
@@ -113,12 +113,12 @@ export function decodeJournalRLE(encoded: RLEEncodedJournal): CRDTMessage[] {
   const messages: CRDTMessage[] = [];
 
   for (const segment of encoded.segments) {
-    // Verify all messages in segment have correct sessionId
+    // Verify all messages in segment have correct client
     for (const msg of segment.messages) {
-      if (msg.sessionId !== segment.agentId) {
+      if (msg.client !== segment.agentId) {
         throw new Error(
-          `RLE decode error: sessionId mismatch in segment. ` +
-          `Expected ${segment.agentId}, got ${msg.sessionId}`
+          `RLE decode error: client mismatch in segment. ` +
+          `Expected ${segment.agentId}, got ${msg.client}`
         );
       }
       messages.push(msg);
@@ -184,9 +184,9 @@ export function verifyRLEIntegrity(
       errors.push(`Message ${i}: id mismatch (${orig.id} vs ${dec.id})`);
     }
 
-    // Check sessionId
-    if (orig.sessionId !== dec.sessionId) {
-      errors.push(`Message ${i}: sessionId mismatch`);
+    // Check client
+    if (orig.client !== dec.client) {
+      errors.push(`Message ${i}: client mismatch`);
     }
 
     // Check vector clock (deep equality)
@@ -204,13 +204,13 @@ export function verifyRLEIntegrity(
     }
 
     // Check lamport time
-    if (orig.lamportTime !== dec.lamportTime) {
-      errors.push(`Message ${i}: lamportTime mismatch`);
+    if (orig.lt !== dec.lt) {
+      errors.push(`Message ${i}: lt mismatch`);
     }
 
     // Check timestamp
-    if (orig.timestamp !== dec.timestamp) {
-      errors.push(`Message ${i}: timestamp mismatch`);
+    if (orig.ts !== dec.ts) {
+      errors.push(`Message ${i}: ts mismatch`);
     }
 
     // Check operations (deep equality)

package/src/journal/JournalRepository.ts

@@ -32,13 +32,13 @@ export class JournalRepository {
     return this.prisma.journalBatch.create({
       data: {
         documentId,
-        sessionId: msg.sessionId,
+        client: msg.client,
         batchId: msg.id,
         operations: msg.ops as any[],
         vectorClock: msg.clock as any,
-        lamportTime: msg.lamportTime,
-        startTime: new Date(msg.timestamp * 1000),
-        endTime: new Date(msg.timestamp * 1000),
+        lamportTime: msg.lt,
+        startTime: new Date(msg.ts * 1000),
+        endTime: new Date(msg.ts * 1000),
       },
     });
   }
@@ -67,10 +67,10 @@ export class JournalRepository {
     return batches.map((batch) => ({
       msg: {
         id: batch.batchId,
-        sessionId: batch.sessionId,
+        client: batch.client,
         clock: (batch.vectorClock as Record<string, number>) ?? {},
-        lamportTime: batch.lamportTime ?? 0,
-        timestamp: batch.startTime.getTime() / 1000,
+        lt: batch.lamportTime ?? 0,
+        ts: batch.startTime.getTime() / 1000,
         ops: batch.operations as any[],
       },
       deletedAt: batch.deletedAt

package/src/journal/RLECompression.ts

@@ -3,11 +3,11 @@
  *
  * Optimizes journal storage by:
  * 1. Run-length encoding consecutive operations (e.g., 10 sequential edits from same agent)
- * 2. Only storing agent/sessionId when it changes
+ * 2. Only storing agent/client when it changes
  * 3. Preserving CRDT semantics (no operations are combined or lost)
  *
- * Format: { sessionId, count: N, ops: [op1, op2, ...] }
- * - sessionId is stored with first op of each run
+ * Format: { client, count: N, ops: [op1, op2, ...] }
+ * - client is stored with first op of each run
  * - count tracks consecutive ops from same agent
  * - ops are stored as-is (no merging/combining)
  */
@@ -18,8 +18,8 @@ import type { CRDTMessage } from '@vuer-ai/vuer-rtc';
  * A run-length encoded journal entry
  */
 export interface RLEJournalEntry {
-  sessionId: string;        // Agent/session that performed this run
-  count: number;            // Number of consecutive operations from this session
+  client: string;           // Agent/client that performed this run
+  count: number;            // Number of consecutive operations from this client
   lamportTime: number;      // Start lamport time of this run
   endLamportTime: number;   // End lamport time (start + count - 1)
   ops: any[];               // Operations in this run (one per index)
@@ -27,14 +27,14 @@ export interface RLEJournalEntry {
 }
 
 /**
- * Encode consecutive operations from the same sessionId using RLE.
- * Returns a list of RLE entries where consecutive ops from same session are grouped.
+ * Encode consecutive operations from the same client using RLE.
+ * Returns a list of RLE entries where consecutive ops from same client are grouped.
  *
  * Example:
- *   Input: [msg1(sid=A), msg2(sid=A), msg3(sid=B), msg4(sid=B), msg5(sid=B)]
+ *   Input: [msg1(cid=A), msg2(cid=A), msg3(cid=B), msg4(cid=B), msg5(cid=B)]
  *   Output: [
- *     { sessionId: A, count: 2, ops: [msg1.ops[0], msg2.ops[0]], ... },
- *     { sessionId: B, count: 3, ops: [msg3.ops[0], msg4.ops[0], msg5.ops[0]], ... }
+ *     { client: A, count: 2, ops: [msg1.ops[0], msg2.ops[0]], ... },
+ *     { client: B, count: 3, ops: [msg3.ops[0], msg4.ops[0], msg5.ops[0]], ... }
  *   ]
  */
 export function encodeRLE(messages: CRDTMessage[]): RLEJournalEntry[] {
@@ -44,23 +44,23 @@ export function encodeRLE(messages: CRDTMessage[]): RLEJournalEntry[] {
   let currentRun: RLEJournalEntry | null = null;
 
   for (const msg of messages) {
-    if (!currentRun || currentRun.sessionId !== msg.sessionId) {
+    if (!currentRun || currentRun.client !== msg.client) {
       // Start new run
       if (currentRun) {
         encoded.push(currentRun);
       }
       currentRun = {
-        sessionId: msg.sessionId,
+        client: msg.client,
         count: 1,
-        lamportTime: msg.lamportTime,
-        endLamportTime: msg.lamportTime,
+        lamportTime: msg.lt,
+        endLamportTime: msg.lt,
         ops: [...msg.ops],
-        timestamp: msg.timestamp,
+        timestamp: msg.ts,
       };
     } else {
       // Extend current run
       currentRun.count++;
-      currentRun.endLamportTime = msg.lamportTime;
+      currentRun.endLamportTime = msg.lt;
       currentRun.ops.push(...msg.ops);
     }
   }
@@ -104,10 +104,10 @@ export function decodeRLE(
       // Reconstruct message
       messages.push({
         id: `msg-${lamportTime}`, // Note: Original IDs are lost; this is a limitation
-        sessionId: entry.sessionId,
+        client: entry.client,
         clock: {}, // Vector clock info is lost in current RLE format
-        lamportTime,
-        timestamp: entry.timestamp,
+        lt: lamportTime,
+        ts: entry.timestamp,
         ops: opsForMsg,
       });
 
@@ -143,8 +143,8 @@ export function encodeRLEWithMetadata(
   const vectorClocks: Record<number, Record<string, number>> = {};
 
   for (const msg of messages) {
-    messageIds[msg.lamportTime] = msg.id;
-    vectorClocks[msg.lamportTime] = msg.clock;
+    messageIds[msg.lt] = msg.id;
+    vectorClocks[msg.lt] = msg.clock;
   }
 
   return {
@@ -176,10 +176,10 @@ export function decodeRLEWithMetadata(
 
       messages.push({
         id: encoded.messageIds[lamportTime] || `msg-${lamportTime}`,
-        sessionId: entry.sessionId,
+        client: entry.client,
         clock: encoded.vectorClocks[lamportTime] || {},
-        lamportTime,
-        timestamp: entry.timestamp,
+        lt: lamportTime,
+        ts: entry.timestamp,
         ops: opsForMsg,
       });