meridian-sdk 1.2.0 → 1.3.0

package/src/crdt/tree.ts

@@ -0,0 +1,367 @@
+import { Chunk, Effect, Stream } from "effect";
+import { encode } from "../codec.js";
+import type { WsTransport } from "../transport/websocket.js";
+import type { TreeDelta, TreeNodeValue } from "../sync/delta.js";
+import type { ConflictEvent, LwwOverwriteEvent, MoveDiscardedEvent, MoveReorderedEvent } from "../conflict/types.js";
+import type { DiscardedMove } from "../sync/delta.js";
+import { type CrdtValidator, runValidator } from "../validation/index.js";
+
+/**
+ * Low-level handle for a TreeCRDT — a convergent hierarchical tree.
+ *
+ * Obtained via `MeridianClient.tree()`. Supports add, move, update, and delete
+ * operations on tree nodes. Concurrent moves use Kleppmann et al. (2021)
+ * move semantics — cycles are prevented, all replicas converge.
+ *
+ * Node IDs are returned by `addNode()` as opaque strings of the form
+ * "wall_ms:logical:node_id" matching the Rust HLC serialization.
+ */
+export interface TreeNodeMeta {
+  parentId: string | null;
+  position: string;
+  /** HLC string "wall_ms:logical:node_id" of the last UpdateNode op on this node. */
+  updatedAt: string;
+  value: string;
+}
+
+/** Maximum number of conflict events retained in the in-memory log. */
+const CONFLICT_LOG_CAP = 200;
+
+export class TreeHandle {
+  private roots: TreeNodeValue[] = [];
+  private readonly crdtId: string;
+  private readonly clientId: number;
+  private readonly transport: WsTransport;
+  private readonly validator: CrdtValidator | undefined;
+  private readonly listeners = new Set<(value: { roots: TreeNodeValue[] }) => void>();
+  private readonly conflictListeners = new Set<(event: ConflictEvent) => void>();
+  private readonly conflictHistory: ConflictEvent[] = [];
+  private opCounter = 0;
+  /** Tracks parent, position, updatedAt, and value per node for undo support. */
+  private readonly nodeMetaMap = new Map<string, TreeNodeMeta>();
+
+  constructor(opts: {
+    crdtId: string;
+    clientId: number;
+    transport: WsTransport;
+    validator?: CrdtValidator;
+  }) {
+    this.crdtId = opts.crdtId;
+    this.clientId = opts.clientId;
+    this.transport = opts.transport;
+    this.validator = opts.validator;
+  }
+
+  /** The CRDT key this handle is bound to. */
+  get id(): string { return this.crdtId; }
+
+  /** Returns the current tree value. */
+  value(): { roots: TreeNodeValue[] } {
+    return { roots: this.roots };
+  }
+
+  /**
+   * Registers a listener called whenever the tree changes.
+   *
+   * @returns An unsubscribe function.
+   */
+  onChange(listener: (value: { roots: TreeNodeValue[] }) => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /** Returns an Effect Stream that emits the tree on every change. */
+  stream(): Stream.Stream<{ roots: TreeNodeValue[] }, never, never> {
+    return Stream.async<{ roots: TreeNodeValue[] }>((emit) => {
+      const unsub = this.onChange((value) => { void emit(Effect.succeed(Chunk.of(value))); });
+      return Effect.sync(unsub);
+    });
+  }
+
+  /**
+   * Adds a new node to the tree.
+   *
+   * @param parentId  - ID of the parent node, or null for a root-level node.
+   * @param position  - Fractional index string for sibling ordering (e.g. "a0", "b0").
+   * @param value     - String content of the node.
+   * @param ttlMs     - Optional TTL.
+   * @returns The new node's ID as a string.
+   */
+  addNode(parentId: string | null, position: string, value: string, ttlMs?: number): string {
+    runValidator(this.validator, value);
+    const wallMs = Date.now();
+    const logical = this.opCounter++;
+    const id = { wall_ms: wallMs, logical, node_id: this.clientId };
+    const idStr = `${wallMs}:${logical}:${this.clientId}`;
+
+    // Optimistic meta update — allows UndoManager to read state immediately.
+    this.nodeMetaMap.set(idStr, {
+      parentId,
+      position,
+      updatedAt: idStr,
+      value,
+    });
+
+    const op = encode({
+      Tree: {
+        AddNode: {
+          id,
+          parent_id: parentId !== null ? this.parseHlc(parentId) : null,
+          position,
+          value,
+        },
+      },
+    });
+
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: op,
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
+      },
+    });
+
+    return idStr;
+  }
+
+  /**
+   * Moves a node to a new parent and/or position.
+   *
+   * @param nodeId      - ID of the node to move.
+   * @param newParentId - New parent node ID, or null for root level.
+   * @param newPosition - New fractional index position.
+   * @param ttlMs       - Optional TTL.
+   */
+  moveNode(nodeId: string, newParentId: string | null, newPosition: string, ttlMs?: number): void {
+    const wallMs = Date.now();
+    const logical = this.opCounter++;
+    const opId = { wall_ms: wallMs, logical, node_id: this.clientId };
+
+    // Optimistic meta update.
+    const existing = this.nodeMetaMap.get(nodeId);
+    if (existing !== undefined) {
+      this.nodeMetaMap.set(nodeId, { ...existing, parentId: newParentId, position: newPosition });
+    }
+
+    const op = encode({
+      Tree: {
+        MoveNode: {
+          op_id: opId,
+          node_id: this.parseHlc(nodeId),
+          new_parent_id: newParentId !== null ? this.parseHlc(newParentId) : null,
+          new_position: newPosition,
+        },
+      },
+    });
+
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: op,
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
+      },
+    });
+  }
+
+  /**
+   * Updates the value of an existing node (LWW — last write wins).
+   *
+   * @param nodeId  - ID of the node to update.
+   * @param value   - New string value.
+   * @param ttlMs   - Optional TTL.
+   */
+  updateNode(nodeId: string, value: string, ttlMs?: number): void {
+    runValidator(this.validator, value);
+    const wallMs = Date.now();
+    const logical = this.opCounter++;
+    const updatedAt = { wall_ms: wallMs, logical, node_id: this.clientId };
+    const updatedAtStr = `${wallMs}:${logical}:${this.clientId}`;
+
+    // Optimistic meta update.
+    const existing = this.nodeMetaMap.get(nodeId);
+    if (existing !== undefined) {
+      this.nodeMetaMap.set(nodeId, { ...existing, value, updatedAt: updatedAtStr });
+    }
+
+    const op = encode({
+      Tree: {
+        UpdateNode: {
+          id: this.parseHlc(nodeId),
+          value,
+          updated_at: updatedAt,
+        },
+      },
+    });
+
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: op,
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
+      },
+    });
+  }
+
+  /**
+   * Tombstone-deletes a node. Children are preserved in the tree structure
+   * but become invisible until the node is undeleted via a concurrent move.
+   *
+   * @param nodeId - ID of the node to delete.
+   * @param ttlMs  - Optional TTL.
+   */
+  deleteNode(nodeId: string, ttlMs?: number): void {
+    const op = encode({
+      Tree: {
+        DeleteNode: {
+          id: this.parseHlc(nodeId),
+        },
+      },
+    });
+
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: op,
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
+      },
+    });
+  }
+
+  /**
+   * Returns the last-known metadata for a node (parent, position, value, updatedAt).
+   * Used by UndoManager to capture pre-op state before mutations.
+   */
+  getNodeMeta(nodeId: string): TreeNodeMeta | undefined {
+    return this.nodeMetaMap.get(nodeId);
+  }
+
+  /**
+   * Registers a listener called whenever a conflict is detected in an incoming delta.
+   * Conflicts include concurrent move resolutions, LWW overwrites, and discarded moves.
+   *
+   * @returns An unsubscribe function.
+   */
+  onConflict(listener: (event: ConflictEvent) => void): () => void {
+    this.conflictListeners.add(listener);
+    return () => { this.conflictListeners.delete(listener); };
+  }
+
+  /**
+   * Returns the last up-to-200 conflict events in chronological order.
+   * Useful for rendering an audit log or "track changes" UI.
+   */
+  conflictLog(): readonly ConflictEvent[] {
+    return this.conflictHistory;
+  }
+
+  /** Apply a delta received from the server. Replaces local state with authoritative tree. */
+  applyDelta(delta: TreeDelta): void {
+    this.detectConflicts(delta.roots, null, delta.discarded_moves ?? []);
+    this.roots = delta.roots;
+    this.rebuildMetaMap(delta.roots, null);
+    this.emit();
+  }
+
+  /** Emit a conflict event to all listeners and append to history. */
+  private emitConflict(event: ConflictEvent): void {
+    if (this.conflictHistory.length >= CONFLICT_LOG_CAP) {
+      this.conflictHistory.shift();
+    }
+    this.conflictHistory.push(event);
+    for (const listener of this.conflictListeners) listener(event);
+  }
+
+  /**
+   * Walks the incoming delta tree and compares each node's server-authoritative
+   * parent/position/value against what the local client last recorded.
+   * Also processes discarded_moves from the server to emit move_discarded events.
+   * Emits conflict events for discrepancies caused by concurrent op resolution.
+   */
+  private detectConflicts(
+    nodes: TreeNodeValue[],
+    serverParentId: string | null,
+    discardedMoves: DiscardedMove[],
+  ): void {
+    const now = Date.now();
+
+    // Emit move_discarded events for server-rejected cycle moves.
+    for (const dm of discardedMoves) {
+      const hlcToStr = (hlc: { wall_ms: number; logical: number; node_id: number }): string =>
+        `${hlc.wall_ms}:${hlc.logical}:${hlc.node_id}`;
+      const event: MoveDiscardedEvent = {
+        kind: "move_discarded",
+        nodeId: hlcToStr(dm.node_id),
+        attemptedParentId: dm.attempted_parent_id !== null ? hlcToStr(dm.attempted_parent_id) : null,
+        attemptedPosition: dm.attempted_position,
+        actualParentId: dm.actual_parent_id !== null ? hlcToStr(dm.actual_parent_id) : null,
+        actualPosition: dm.actual_position,
+        at: now,
+      };
+      this.emitConflict(event);
+    }
+
+    for (const node of nodes) {
+      const local = this.nodeMetaMap.get(node.id);
+      if (local !== undefined) {
+        // Detect move reordering: server placed the node somewhere different
+        // from what the local optimistic update recorded.
+        if (local.parentId !== serverParentId || local.position !== node.position) {
+          const event: MoveReorderedEvent = {
+            kind: "move_reordered",
+            nodeId: node.id,
+            localParentId: local.parentId,
+            localPosition: local.position,
+            serverParentId,
+            serverPosition: node.position,
+            at: now,
+          };
+          this.emitConflict(event);
+        }
+
+        // Detect LWW overwrite: server has a different value than local recorded.
+        if (local.value !== node.value) {
+          const event: LwwOverwriteEvent = {
+            kind: "lww_overwrite",
+            nodeId: node.id,
+            discardedValue: local.value,
+            winnerValue: node.value,
+            at: now,
+          };
+          this.emitConflict(event);
+        }
+      }
+      // Recurse into children — serverParentId for children is this node's id.
+      // discardedMoves are top-level only (already processed above).
+      this.detectConflicts(node.children, node.id, []);
+    }
+  }
+
+  /** Rebuilds nodeMetaMap from a full tree snapshot (called on each server delta). */
+  private rebuildMetaMap(nodes: TreeNodeValue[], parentId: string | null): void {
+    for (const node of nodes) {
+      const existing = this.nodeMetaMap.get(node.id);
+      this.nodeMetaMap.set(node.id, {
+        parentId,
+        position: node.position,
+        updatedAt: existing?.updatedAt ?? node.id,
+        value: node.value,
+      });
+      this.rebuildMetaMap(node.children, node.id);
+    }
+  }
+
+  private emit(): void {
+    const v = { roots: this.roots };
+    for (const listener of this.listeners) listener(v);
+  }
+
+  /** Parse an HLC string "wall_ms:logical:node_id" back to a Rust-compatible object. */
+  private parseHlc(id: string): { wall_ms: number; logical: number; node_id: number } {
+    const parts = id.split(":");
+    return {
+      wall_ms: Number(parts[0]),
+      logical: Number(parts[1]),
+      node_id: Number(parts[2]),
+    };
+  }
+}

package/src/index.ts

@@ -13,6 +13,7 @@ export type {
   PresenceSnapshotEntry,
   CRDTMapSnapshotEntry,
   RGASnapshotEntry,
+  TreeSnapshotEntry,
 } from "./client.js";
 
 // CRDT handles
@@ -27,6 +28,8 @@ export type { CrdtMapValue } from "./crdt/crdtmap.js";
 export { AwarenessHandle } from "./crdt/awareness.js";
 export type { AwarenessEntry } from "./crdt/awareness.js";
 export { RGAHandle } from "./crdt/rga.js";
+export { TreeHandle } from "./crdt/tree.js";
+export type { TreeNodeValue, TreeDelta } from "./sync/delta.js";
 
 // Transport
 export { HttpClient } from "./transport/http.js";
@@ -51,6 +54,9 @@ export {
 export {
   TokenClaims,
   Permissions,
+  PermissionsV1,
+  PermissionsV2,
+  PermEntry,
   VectorClock,
   ClientMsg,
   ServerMsg,
@@ -65,14 +71,38 @@ export {
 } from "./schema.js";
 export type { TimestampMs, ClientId } from "./schema.js";
 
-// AI Agents — Claude tool use helpers
+// Undo/redo
+export { UndoManager } from "./undo/UndoManager.js";
+export type { UndoEntry, UndoBatch, RgaInsertEntry, TreeAddEntry, TreeDeleteEntry, TreeMoveEntry, TreeUpdateEntry } from "./undo/types.js";
+
+// Fractional indexing — position helpers for TreeCRDT
+export { fi, between, before, after, start, end, spread } from "./utils/fractional.js";
+
+// Validation — runtime validators for CRDT string values
+export { CrdtValidationError, zodValidator, fnValidator } from "./validation/index.js";
+export type { CrdtValidator } from "./validation/index.js";
+
+// Conflict visualization — events emitted by TreeHandle on concurrent op resolution
+export type { ConflictEvent, MoveDiscardedEvent, MoveReorderedEvent, LwwOverwriteEvent } from "./conflict/types.js";
+export type { DiscardedMove } from "./sync/delta.js";
+
+// AI Agents — provider-agnostic tool use helpers (Anthropic, OpenAI, Gemini)
 export {
   getMeridianTools,
+  toOpenAITools,
+  toGeminiTools,
   executeMeridianTool,
+  executeOpenAITool,
+  executeGeminiTool,
 } from "./agents.js";
 export type {
   Tool,
+  OpenAITool,
+  GeminiFunctionDeclaration,
+  GeminiTool,
   ToolUseBlock,
+  OpenAIToolCall,
+  GeminiFunctionCall,
   MeridianAgentConfig,
 } from "./agents.js";
 

package/src/schema.ts

@@ -21,11 +21,34 @@ export const ClientId = Schema.Union(Schema.Number, Schema.BigIntFromSelf.pipe(S
 )));
 export type ClientId = number;
 
-export const Permissions = Schema.Struct({
+/** V1 permissions — glob-list style (legacy tokens). */
+export const PermissionsV1 = Schema.Struct({
   read: Schema.Array(Schema.String),
   write: Schema.Array(Schema.String),
   admin: Schema.Boolean,
 });
+export type PermissionsV1 = typeof PermissionsV1.Type;
+
+/** A single permission rule in a V2 token. */
+export const PermEntry = Schema.Struct({
+  p: Schema.String,
+  o: Schema.optional(Schema.Number),
+  e: Schema.optional(Schema.Number),
+});
+export type PermEntry = typeof PermEntry.Type;
+
+/** V2 fine-grained permissions. */
+export const PermissionsV2 = Schema.Struct({
+  v: Schema.Literal(2),
+  r: Schema.Array(PermEntry),
+  w: Schema.Array(PermEntry),
+  admin: Schema.Boolean,
+  rl: Schema.optional(Schema.Number),
+});
+export type PermissionsV2 = typeof PermissionsV2.Type;
+
+/** Token permissions — V1 or V2. */
+export const Permissions = Schema.Union(PermissionsV2, PermissionsV1);
 export type Permissions = typeof Permissions.Type;
 
 export const TokenClaims = Schema.Struct({

package/src/sync/delta.ts

@@ -81,13 +81,42 @@ export const decodeRGADelta = (bytes: Uint8Array): RGADelta => {
   return { text: raw.text ?? "" };
 };
 
+export interface TreeNodeValue {
+  id: string;
+  value: string;
+  /** Fractional index string for sibling ordering (e.g. "a0", "b0"). */
+  position: string;
+  children: TreeNodeValue[];
+}
+
+/** A MoveNode op that was rejected by the server due to cycle prevention. */
+export interface DiscardedMove {
+  node_id: { wall_ms: number; logical: number; node_id: number };
+  attempted_parent_id: { wall_ms: number; logical: number; node_id: number } | null;
+  attempted_position: string;
+  actual_parent_id: { wall_ms: number; logical: number; node_id: number } | null;
+  actual_position: string;
+}
+
+export interface TreeDelta {
+  roots: TreeNodeValue[];
+  /** MoveNode ops discarded due to cycle prevention. Empty in the common case. */
+  discarded_moves?: DiscardedMove[];
+}
+
+export const decodeTreeDelta = (bytes: Uint8Array): TreeDelta => {
+  const raw = decode(bytes) as { roots?: TreeNodeValue[]; discarded_moves?: DiscardedMove[] };
+  return { roots: raw.roots ?? [], discarded_moves: raw.discarded_moves ?? [] };
+};
+
 export type CrdtValueDelta =
   | { GCounter: GCounterDelta }
   | { PNCounter: PNCounterDelta }
   | { ORSet: ORSetDelta }
   | { LwwRegister: LwwDelta }
   | { Presence: PresenceDelta }
-  | { RGA: RGADelta };
+  | { RGA: RGADelta }
+  | { Tree: TreeDelta };
 
 export interface CRDTMapDelta {
   deltas: Record<string, CrdtValueDelta>;