meridian-sdk 1.2.1 → 1.4.0

package/src/crdt/tree.ts

@@ -2,6 +2,9 @@ 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.
@@ -13,24 +16,45 @@ import type { TreeDelta, TreeNodeValue } from "../sync/delta.js";
  * 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 };
@@ -64,11 +88,20 @@ export class TreeHandle {
    * @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: {
@@ -104,6 +137,12 @@ export class TreeHandle {
     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: {
@@ -132,9 +171,17 @@ export class TreeHandle {
    * @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: {
@@ -180,12 +227,129 @@ export class TreeHandle {
     });
   }
 
+  /**
+   * 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);

package/src/index.ts

@@ -5,6 +5,7 @@ export type {
   MeridianClientConfig,
   ClientSnapshot,
   DeltaEvent,
+  LiveQueryHandle,
   CRDTSnapshotEntry,
   GCounterSnapshotEntry,
   PNCounterSnapshotEntry,
@@ -54,6 +55,9 @@ export {
 export {
   TokenClaims,
   Permissions,
+  PermissionsV1,
+  PermissionsV2,
+  PermEntry,
   VectorClock,
   ClientMsg,
   ServerMsg,
@@ -65,17 +69,44 @@ export {
   CrdtGetResponse,
   CrdtOpResponse,
   ErrorResponse,
+  QuerySpec,
+  QueryResult,
+  LiveQueryResult,
 } 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({
@@ -59,6 +82,25 @@ export const ClientMsg = Schema.Union(
       data: Schema.Uint8ArrayFromSelf,
     }),
   }),
+  Schema.Struct({
+    SubscribeQuery: Schema.Struct({
+      query_id: Schema.String,
+      query: Schema.Struct({
+        from: Schema.String,
+        type: Schema.optional(Schema.String),
+        aggregate: Schema.String,
+        where: Schema.optional(
+          Schema.Struct({
+            contains: Schema.optional(Schema.Unknown),
+            updated_after: Schema.optional(Schema.Number),
+          }),
+        ),
+      }),
+    }),
+  }),
+  Schema.Struct({
+    UnsubscribeQuery: Schema.Struct({ query_id: Schema.String }),
+  }),
 );
 export type ClientMsg = typeof ClientMsg.Type;
 
@@ -80,6 +122,13 @@ export const ServerMsg = Schema.Union(
       data: Schema.Uint8ArrayFromSelf,
     }),
   }),
+  Schema.Struct({
+    QueryResult: Schema.Struct({
+      query_id: Schema.String,
+      value: Schema.Unknown,
+      matched: Schema.Number,
+    }),
+  }),
 );
 export type ServerMsg = typeof ServerMsg.Type;
 
@@ -135,3 +184,34 @@ export const ErrorResponse = Schema.Struct({
   message: Schema.String,
 });
 export type ErrorResponse = typeof ErrorResponse.Type;
+
+export const QuerySpec = Schema.Struct({
+  from: Schema.String,
+  type: Schema.optional(Schema.String),
+  aggregate: Schema.Literal(
+    "sum", "max", "min", "count",
+    "union", "intersection",
+    "latest", "collect",
+    "merge",
+  ),
+  where: Schema.optional(Schema.Struct({
+    contains: Schema.optional(Schema.Unknown),
+    updatedAfter: Schema.optional(Schema.Number),
+  })),
+});
+export type QuerySpec = typeof QuerySpec.Type;
+
+export const QueryResult = Schema.Struct({
+  value: Schema.Unknown,
+  matched: Schema.Number,
+  scanned: Schema.Number,
+  execution_ms: Schema.Number,
+});
+export type QueryResult = typeof QueryResult.Type;
+
+/** Result pushed by the server for a live query subscription (WebSocket only). */
+export const LiveQueryResult = Schema.Struct({
+  value: Schema.Unknown,
+  matched: Schema.Number,
+});
+export type LiveQueryResult = typeof LiveQueryResult.Type;

package/src/sync/delta.ts

@@ -84,16 +84,29 @@ export const decodeRGADelta = (bytes: Uint8Array): RGADelta => {
 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[] };
-  return { roots: raw.roots ?? [] };
+  const raw = decode(bytes) as { roots?: TreeNodeValue[]; discarded_moves?: DiscardedMove[] };
+  return { roots: raw.roots ?? [], discarded_moves: raw.discarded_moves ?? [] };
 };
 
 export type CrdtValueDelta =

package/src/transport/http.ts

@@ -6,7 +6,9 @@ import {
   CrdtOpResponse,
   TokenIssueResponse,
   ErrorResponse,
+  QueryResult,
   type VectorClock,
+  type QuerySpec,
 } from "../schema.js";
 import type { Permissions } from "../schema.js";
 
@@ -72,6 +74,10 @@ export class HttpClient {
     return this.requestJson(TokenIssueResponse, "POST", `/v1/namespaces/${ns}/tokens`, opts);
   }
 
+  query(ns: string, spec: QuerySpec): Effect.Effect<QueryResult, HttpError | NetworkError> {
+    return this.requestJson(QueryResult, "POST", `/v1/namespaces/${ns}/query`, spec);
+  }
+
   private requestJson<A, I>(
     responseSchema: Schema.Schema<A, I>,
     method: string,

package/src/transport/websocket.ts

@@ -49,6 +49,8 @@ export class WsTransport {
 
   // State change listeners (replacing fragile function-chain pattern)
   private readonly stateListeners = new Set<(state: WsState) => void>();
+  // Reconnect listeners — called each time a connection is (re-)established.
+  private readonly reconnectListeners = new Set<() => void>();
 
   private readonly subscriptions = new Map<string, VectorClock>();
 
@@ -178,6 +180,16 @@ export class WsTransport {
     return () => { this.stateListeners.delete(listener); };
   }
 
+  /**
+   * Register a callback that fires each time a WebSocket connection is
+   * (re-)established. Used by the client to re-send `SubscribeQuery` frames
+   * after a reconnect. Returns an unsubscribe function.
+   */
+  onReconnect(listener: () => void): () => void {
+    this.reconnectListeners.add(listener);
+    return () => { this.reconnectListeners.delete(listener); };
+  }
+
   get currentState(): WsState {
     return this.state;
   }
@@ -327,6 +339,9 @@ export class WsTransport {
       this.sendSubscribe(crdtId, vc);
     }
     this.flushPendingOps();
+    for (const listener of this.reconnectListeners) {
+      listener();
+    }
   }
 
   private flushPendingOps(): void {