reflectdb 0.1.0

package/dist/cjs/client/index.cjs

@@ -0,0 +1,1252 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/core/types.ts
+var exports_types = {};
+__export(exports_types, {
+  reasonFromError: () => reasonFromError,
+  isErrorReason: () => isErrorReason,
+  TransportSendError: () => TransportSendError,
+  TOMBSTONE_RETENTION_MS: () => TOMBSTONE_RETENTION_MS,
+  SUPPORTED_PROTOCOL_VERSIONS: () => SUPPORTED_PROTOCOL_VERSIONS,
+  SERVER_TOMBSTONE_RETENTION_MS: () => SERVER_TOMBSTONE_RETENTION_MS,
+  PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  MutationError: () => MutationError,
+  MAX_CLOCK_DRIFT_MS: () => MAX_CLOCK_DRIFT_MS,
+  MAX_BATCH_SIZE: () => MAX_BATCH_SIZE
+});
+function isErrorReason(value) {
+  return typeof value === "string" && VALID_ERROR_REASONS.has(value);
+}
+function reasonFromError(err) {
+  if (err instanceof MutationError && isErrorReason(err.reason)) {
+    return err.reason;
+  }
+  return "server_error";
+}
+var TransportSendError, PROTOCOL_VERSION = 1, SUPPORTED_PROTOCOL_VERSIONS, MAX_CLOCK_DRIFT_MS, MAX_BATCH_SIZE = 100, TOMBSTONE_RETENTION_MS, SERVER_TOMBSTONE_RETENTION_MS, MutationError, VALID_ERROR_REASONS;
+var init_types = __esm(() => {
+  TransportSendError = class TransportSendError extends Error {
+    clientId;
+    cause;
+    constructor(clientId, message, cause) {
+      super(message);
+      this.clientId = clientId;
+      this.cause = cause;
+      this.name = "TransportSendError";
+    }
+  };
+  SUPPORTED_PROTOCOL_VERSIONS = [1];
+  MAX_CLOCK_DRIFT_MS = 5 * 60 * 1000;
+  TOMBSTONE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+  SERVER_TOMBSTONE_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+  MutationError = class MutationError extends Error {
+    reason;
+    constructor(reason, message) {
+      super(message ?? reason);
+      this.reason = reason;
+    }
+  };
+  VALID_ERROR_REASONS = new Set([
+    "outside_shape",
+    "readonly_query",
+    "rate_limited",
+    "buffer_full",
+    "server_conflict",
+    "custom_conflict",
+    "merge_stale",
+    "clock_drift",
+    "replay",
+    "batch_too_large",
+    "schema_outdated",
+    "auth_revoked",
+    "compacted",
+    "mutation_rejected",
+    "server_error",
+    "unknown_query"
+  ]);
+});
+
+// src/client/index.ts
+var exports_client = {};
+__export(exports_client, {
+  pushSafely: () => pushSafely,
+  createSyncClient: () => createSyncClient,
+  createOpCreator: () => createOpCreator,
+  createMemoryStorage: () => createMemoryStorage,
+  SyncClient: () => SyncClient,
+  ClientStore: () => ClientStore
+});
+module.exports = __toCommonJS(exports_client);
+
+// src/core/hlc.ts
+init_types();
+var MS_PAD = 19;
+var COUNTER_PAD = 4;
+var COUNTER_MAX = 9999;
+function createHlc(nodeId) {
+  return { ms: 0, counter: 0, nodeId };
+}
+function normalize(ms, counter, nodeId) {
+  if (counter > COUNTER_MAX) {
+    return { ms: ms + 1, counter: 0, nodeId };
+  }
+  return { ms, counter, nodeId };
+}
+function sendHlc(local) {
+  const wall = Date.now();
+  const ms = Math.max(wall, local.ms);
+  const counter = ms === local.ms ? local.counter + 1 : 0;
+  return normalize(ms, counter, local.nodeId);
+}
+function receiveHlc(local, remote) {
+  const wall = Date.now();
+  const clampedRemoteMs = Math.min(remote.ms, wall + MAX_CLOCK_DRIFT_MS);
+  const ms = Math.max(wall, local.ms, clampedRemoteMs);
+  const counter = ms === local.ms && ms === clampedRemoteMs ? Math.max(local.counter, remote.counter) + 1 : ms === local.ms ? local.counter + 1 : ms === clampedRemoteMs ? remote.counter + 1 : 0;
+  return normalize(ms, counter, local.nodeId);
+}
+function packHlc(hlc) {
+  const ms = String(hlc.ms).padStart(MS_PAD, "0");
+  const counter = String(hlc.counter).padStart(COUNTER_PAD, "0");
+  return `${ms}.${counter}.${hlc.nodeId}`;
+}
+function unpackHlc(packed) {
+  const firstDot = packed.indexOf(".");
+  const secondDot = firstDot < 0 ? -1 : packed.indexOf(".", firstDot + 1);
+  if (firstDot < 0 || secondDot < 0) {
+    throw new Error(`Malformed HLC: ${packed}`);
+  }
+  const ms = Number(packed.slice(0, firstDot));
+  const counter = Number(packed.slice(firstDot + 1, secondDot));
+  const nodeId = packed.slice(secondDot + 1);
+  if (!Number.isFinite(ms) || !Number.isFinite(counter) || nodeId.length === 0) {
+    throw new Error(`Malformed HLC: ${packed}`);
+  }
+  return { ms, counter, nodeId };
+}
+function compareHlc(a, b) {
+  if (a < b)
+    return -1;
+  if (a > b)
+    return 1;
+  return 0;
+}
+
+// src/client/ops.ts
+function randomUUID() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID)
+    return c.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (c?.getRandomValues) {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0;i < 16; i++)
+      bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [];
+  for (let i = 0;i < 16; i++)
+    hex.push(bytes[i].toString(16).padStart(2, "0"));
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
+function createOpCreator(nodeId, initialHlc) {
+  let hlc = initialHlc ?? { ms: 0, counter: 0, nodeId };
+  function nextOp(table, op, rowId, payload) {
+    hlc = sendHlc(hlc);
+    return {
+      id: randomUUID(),
+      table,
+      op,
+      rowId,
+      payload,
+      hlc: packHlc(hlc)
+    };
+  }
+  return {
+    insert(table, rowId, payload) {
+      return nextOp(table, "insert", rowId, payload);
+    },
+    update(table, rowId, payload) {
+      return nextOp(table, "update", rowId, payload);
+    },
+    delete(table, rowId) {
+      return nextOp(table, "delete", rowId, null);
+    },
+    createBatch(ops) {
+      const batchId = randomUUID();
+      return ops.map((spec, i) => {
+        const op = nextOp(spec.table, spec.op, spec.rowId, spec.payload);
+        return {
+          ...op,
+          batchId,
+          batchSize: ops.length,
+          batchSeq: i
+        };
+      });
+    },
+    getHlc() {
+      return hlc;
+    }
+  };
+}
+// src/client/store.ts
+class ClientStore {
+  pendingOps = [];
+  rows = new Map;
+  tableMeta = new Map;
+  storage;
+  pendingWrites = [];
+  writeChain = Promise.resolve();
+  constructor(storage) {
+    this.storage = storage ?? null;
+  }
+  async hydrate(options) {
+    if (!this.storage)
+      return;
+    const storage = this.storage;
+    const scoped = options?.tables;
+    const [allRows, pendingOps, tableMetaJson] = await Promise.all([
+      scoped ? Promise.all(scoped.map((table) => storage.getRows(table))).then((r) => r.flat()) : storage.getAllRows(),
+      storage.getPendingOps(),
+      storage.getMeta("tableMeta")
+    ]);
+    for (const row of allRows) {
+      let tableMap = this.rows.get(row.table);
+      if (!tableMap) {
+        tableMap = new Map;
+        this.rows.set(row.table, tableMap);
+      }
+      tableMap.set(row.rowId, row);
+    }
+    this.pendingOps = pendingOps;
+    if (tableMetaJson) {
+      const parsed = JSON.parse(tableMetaJson);
+      for (const [table, m] of Object.entries(parsed)) {
+        this.tableMeta.set(table, {
+          serverSet: m.serverSet,
+          readonly: m.readonly,
+          broadcast: m.broadcast ?? "consistent",
+          pk: m.pk ?? "id"
+        });
+      }
+    }
+  }
+  async flush() {
+    this.pendingWrites = [];
+    await this.writeChain;
+  }
+  enqueue(fn) {
+    if (!this.storage)
+      return;
+    this.writeChain = this.writeChain.then(fn).catch((err) => {
+      console.error("[reflectdb] storage write failed:", err);
+    });
+    this.pendingWrites.push(this.writeChain);
+  }
+  addPendingOp(op) {
+    const existing = this.getRow(op.table, op.rowId);
+    const pendingOp = {
+      op,
+      status: "pending",
+      rejectedReason: null,
+      createdAt: Date.now(),
+      preState: existing ? {
+        data: existing.data,
+        colClocks: { ...existing.colClocks },
+        serverHlc: existing.serverHlc
+      } : null
+    };
+    this.pendingOps.push(pendingOp);
+    this.enqueue(() => this.storage.appendPendingOps([pendingOp]));
+  }
+  getPendingOps() {
+    return this.pendingOps.filter((p) => p.status === "pending");
+  }
+  markSynced(opIds) {
+    const idSet = new Set(opIds);
+    this.pendingOps = this.pendingOps.filter((p) => !idSet.has(p.op.id));
+    this.enqueue(() => this.storage.removePendingOps(opIds));
+  }
+  markRejected(opId, reason) {
+    const pending = this.pendingOps.find((p) => p.op.id === opId);
+    if (pending) {
+      pending.status = "rejected";
+      pending.rejectedReason = reason;
+      this.enqueue(() => this.storage.updatePendingOps([pending]));
+    }
+    this.autoTrimRejected();
+  }
+  rejectBatch(batchId, reason) {
+    const updated = [];
+    for (const p of this.pendingOps) {
+      if (p.op.batchId === batchId) {
+        p.status = "rejected";
+        p.rejectedReason = reason;
+        updated.push(p);
+      }
+    }
+    if (updated.length > 0) {
+      this.enqueue(() => this.storage.updatePendingOps(updated));
+    }
+    this.autoTrimRejected();
+  }
+  autoTrimRejected() {
+    const cutoff = Date.now() - 60000;
+    const before = this.pendingOps.length;
+    this.pendingOps = this.pendingOps.filter((p) => p.status !== "rejected" || p.createdAt > cutoff);
+    if (this.pendingOps.length < before) {
+      this.enqueue(() => this.storage.putPendingOps([...this.pendingOps]));
+    }
+  }
+  clearRejected() {
+    this.pendingOps = this.pendingOps.filter((p) => p.status !== "rejected");
+    this.enqueue(() => this.storage.putPendingOps([...this.pendingOps]));
+  }
+  setRow(table, rowId, data, colClocks, serverHlc) {
+    if (data === null && serverHlc === null) {
+      this.rows.get(table)?.delete(rowId);
+      this.enqueue(() => this.storage.deleteRow(table, rowId));
+      return;
+    }
+    let tableMap = this.rows.get(table);
+    if (!tableMap) {
+      tableMap = new Map;
+      this.rows.set(table, tableMap);
+    }
+    const row = { table, rowId, data, colClocks, serverHlc };
+    tableMap.set(rowId, row);
+    this.enqueue(() => this.storage.putRow(table, rowId, row));
+  }
+  getRow(table, rowId) {
+    const row = this.rows.get(table)?.get(rowId);
+    if (!row || row.data === null)
+      return;
+    return row;
+  }
+  getRowEntry(table, rowId) {
+    return this.rows.get(table)?.get(rowId);
+  }
+  getRows(table, includeDeleted = false) {
+    const tableMap = this.rows.get(table);
+    if (!tableMap)
+      return [];
+    const result = [];
+    for (const row of tableMap.values()) {
+      if (row.data !== null) {
+        if (!includeDeleted && (row.data.deletedAt != null || row.data.deleted_at != null)) {
+          continue;
+        }
+        result.push(row);
+      }
+    }
+    return result;
+  }
+  clearTable(table) {
+    this.rows.delete(table);
+    this.enqueue(() => this.storage.clearTable(table));
+  }
+  applySnapshot(table, rows, colClocks, append = false, pk) {
+    if (!append) {
+      this.clearTable(table);
+    }
+    const effectivePk = pk ?? this.tableMeta.get(table)?.pk ?? "id";
+    for (const row of rows) {
+      const rowId = row[effectivePk] ?? "";
+      const clocks = colClocks[rowId] ?? {};
+      this.setRow(table, rowId, row, clocks, clocks._row ?? null);
+    }
+    for (const p of this.pendingOps) {
+      if (p.status === "pending" && p.op.table === table) {
+        this.applyOptimistic(p.op);
+      }
+    }
+  }
+  applyDelta(table, op, rowId, payload, hlc, colClocks) {
+    const existing = this.getRowEntry(table, rowId);
+    if (op === "delete") {
+      if (existing?.serverHlc && compareHlc(hlc, existing.serverHlc) <= 0) {
+        return;
+      }
+      this.setRow(table, rowId, null, {}, hlc);
+      return;
+    }
+    if (op === "insert" || !existing) {
+      if (existing?.serverHlc && compareHlc(hlc, existing.serverHlc) <= 0) {
+        return;
+      }
+      this.setRow(table, rowId, payload ?? {}, colClocks ?? { _row: hlc }, hlc);
+      return;
+    }
+    const incomingClocks = colClocks ?? {};
+    const mergedData = { ...existing.data };
+    const mergedClocks = { ...existing.colClocks };
+    let anyApplied = false;
+    for (const [col, value] of Object.entries(payload ?? {})) {
+      const incomingClock = incomingClocks[col] ?? hlc;
+      const existingClock = existing.colClocks[col];
+      if (!existingClock || compareHlc(incomingClock, existingClock) > 0) {
+        mergedData[col] = value;
+        mergedClocks[col] = incomingClock;
+        anyApplied = true;
+      }
+    }
+    if (!anyApplied) {
+      return;
+    }
+    const newRowHlc = existing.serverHlc && compareHlc(existing.serverHlc, hlc) >= 0 ? existing.serverHlc : hlc;
+    mergedClocks._row = newRowHlc;
+    this.setRow(table, rowId, mergedData, mergedClocks, newRowHlc);
+  }
+  revertOp(opId, serverRow) {
+    const pending = this.pendingOps.find((p) => p.op.id === opId);
+    if (!pending)
+      return;
+    const { table, rowId } = pending.op;
+    if (serverRow != null) {
+      const existing = this.getRow(table, rowId);
+      this.setRow(table, rowId, serverRow, existing?.colClocks ?? {}, existing?.serverHlc ?? null);
+    } else if (pending.preState) {
+      this.setRow(table, rowId, pending.preState.data, pending.preState.colClocks, pending.preState.serverHlc);
+    } else {
+      const tableMap = this.rows.get(table);
+      if (tableMap) {
+        tableMap.delete(rowId);
+        this.enqueue(() => this.storage.deleteRow(table, rowId));
+      }
+    }
+    this.pendingOps = this.pendingOps.filter((p) => p.op.id !== opId);
+    this.enqueue(() => this.storage.removePendingOps([opId]));
+  }
+  setTableMeta(meta) {
+    for (const [table, m] of Object.entries(meta)) {
+      this.tableMeta.set(table, {
+        serverSet: m.serverSet,
+        readonly: m.readonly,
+        broadcast: m.broadcast ?? "consistent",
+        pk: m.pk ?? "id"
+      });
+    }
+    this.enqueue(() => this.storage.setMeta("tableMeta", JSON.stringify(Object.fromEntries(this.tableMeta))));
+  }
+  getTableMeta(table) {
+    return this.tableMeta.get(table);
+  }
+  applyOptimistic(op) {
+    const meta = this.tableMeta.get(op.table);
+    let payload = op.payload;
+    if (payload && meta?.serverSet.length) {
+      payload = { ...payload };
+      for (const field of meta.serverSet) {
+        delete payload[field];
+      }
+    }
+    if (op.op === "delete") {
+      this.setRow(op.table, op.rowId, null, { _row: op.hlc }, op.hlc);
+    } else if (op.op === "insert") {
+      this.setRow(op.table, op.rowId, payload ?? {}, { _row: op.hlc }, op.hlc);
+    } else {
+      const existing = this.getRow(op.table, op.rowId);
+      if (existing?.data) {
+        const merged = { ...existing.data, ...payload };
+        this.setRow(op.table, op.rowId, merged, existing.colClocks, existing.serverHlc);
+      }
+    }
+  }
+  async clear() {
+    try {
+      await this.writeChain;
+    } catch {}
+    this.rows.clear();
+    this.pendingOps = [];
+    this.tableMeta.clear();
+    this.pendingWrites = [];
+    this.writeChain = Promise.resolve();
+    if (this.storage) {
+      await this.storage.clear();
+    }
+  }
+}
+// src/client/sync-client.ts
+init_types();
+class SyncClient {
+  config;
+  transport;
+  opCreator;
+  store;
+  state = "disconnected";
+  negotiatedProtocolVersion = null;
+  syncedTables = new Set;
+  serverHlc = null;
+  listeners = new Set;
+  version = 0;
+  tableVersions = new Map;
+  tableListeners = new Map;
+  connectResolve = null;
+  connectReject = null;
+  connectInFlight = null;
+  ephemeralListeners = new Map;
+  totalCounts = new Map;
+  syncOptions = new Map;
+  bootstrapScheduled = false;
+  initialized = false;
+  syncParams = new Map;
+  reconnectTimer = null;
+  reconnectAttempts = 0;
+  closed = false;
+  inFlightOps = new Map;
+  static IN_FLIGHT_TTL_MS = 30000;
+  pushChain = Promise.resolve();
+  pushPending = null;
+  constructor(config) {
+    this.config = config;
+    this.transport = config.transport;
+    this.opCreator = createOpCreator(`client:${config.clientId}`);
+    this.store = new ClientStore(config.storage);
+    this.transport.subscribe((message) => {
+      this.handleMessage(message);
+    });
+  }
+  async init() {
+    if (!this.config.storage) {
+      this.initialized = true;
+      return;
+    }
+    this.state = "hydrating";
+    this.notify();
+    const subsJson = await this.config.storage.getMeta("syncSubscriptions");
+    if (subsJson) {
+      const subs = JSON.parse(subsJson);
+      for (const sub of subs) {
+        this.syncedTables.add(sub.table);
+        if (sub.params) {
+          this.syncParams.set(sub.table, sub.params);
+        }
+        if (sub.options) {
+          this.syncOptions.set(sub.table, sub.options);
+        }
+      }
+    }
+    await this.store.hydrate(this.config.hydrateAllTables || this.syncedTables.size === 0 ? undefined : { tables: [...this.syncedTables] });
+    const serverHlcStr = await this.config.storage.getMeta("serverHlc");
+    if (serverHlcStr) {
+      this.serverHlc = serverHlcStr;
+    }
+    const currentNodeId = `client:${this.config.clientId}`;
+    const hlcJson = await this.config.storage.getMeta("hlcState");
+    let restoredHlc = null;
+    if (hlcJson) {
+      const parsed = JSON.parse(hlcJson);
+      restoredHlc = { ...parsed, nodeId: currentNodeId };
+      this.opCreator = createOpCreator(currentNodeId, restoredHlc);
+    }
+    const pendingOps = this.store.getPendingOps();
+    if (pendingOps.length > 0) {
+      let maxMs = restoredHlc?.ms ?? 0;
+      let maxCounter = restoredHlc?.counter ?? 0;
+      for (const p of pendingOps) {
+        const opHlc = unpackHlc(p.op.hlc);
+        if (opHlc.ms > maxMs || opHlc.ms === maxMs && opHlc.counter > maxCounter) {
+          maxMs = opHlc.ms;
+          maxCounter = opHlc.counter;
+        }
+      }
+      this.opCreator = createOpCreator(currentNodeId, {
+        ms: maxMs,
+        counter: maxCounter,
+        nodeId: currentNodeId
+      });
+    }
+    this.state = "disconnected";
+    this.initialized = true;
+    this.notify();
+  }
+  async connect() {
+    if (!this.initialized && this.config.storage) {
+      await this.init();
+    }
+    if (this.connectInFlight)
+      return this.connectInFlight;
+    this.state = "connecting";
+    this.connectInFlight = new Promise((resolve, reject) => {
+      this.connectResolve = resolve;
+      this.connectReject = reject;
+    }).finally(() => {
+      this.connectInFlight = null;
+    });
+    await this.transport.send({
+      type: "hello",
+      protocolVersion: PROTOCOL_VERSION,
+      supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
+      clientId: this.config.clientId,
+      token: this.config.token
+    });
+    return this.connectInFlight;
+  }
+  async close() {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.state = "disconnected";
+    this.notify();
+    try {
+      await this.store.flush();
+    } catch (err) {
+      console.error("[reflectdb] store flush during close failed:", err);
+    }
+    await this.transport.close();
+  }
+  getState() {
+    return this.state;
+  }
+  getProtocolVersion() {
+    return this.negotiatedProtocolVersion;
+  }
+  async sync(table, params, options) {
+    this.syncedTables.add(table);
+    if (params) {
+      this.syncParams.set(table, params);
+    }
+    if (options) {
+      this.syncOptions.set(table, options);
+    }
+    this.persistSyncSubscriptions();
+    await this.transport.send({
+      type: "sync_declare",
+      table,
+      params,
+      window: options?.window
+    });
+  }
+  async loadMore(table, count) {
+    await this.transport.send({
+      type: "load_more",
+      table,
+      count
+    });
+  }
+  getTotalCount(table) {
+    return this.totalCounts.get(table) ?? null;
+  }
+  async unsync(table) {
+    this.syncedTables.delete(table);
+    this.syncOptions.delete(table);
+    this.syncParams.delete(table);
+    this.totalCounts.delete(table);
+    this.store.clearTable(table);
+    this.persistSyncSubscriptions();
+    this.notify([table]);
+    await this.transport.send({
+      type: "unsync",
+      table
+    });
+  }
+  async bootstrap() {
+    this.state = "bootstrapping";
+    await this.transport.send({
+      type: "bootstrap"
+    });
+  }
+  scheduleBootstrap() {
+    if (this.bootstrapScheduled)
+      return;
+    this.bootstrapScheduled = true;
+    queueMicrotask(() => {
+      this.bootstrapScheduled = false;
+      this.bootstrap();
+    });
+  }
+  async resume() {
+    if (!this.serverHlc) {
+      return this.bootstrap();
+    }
+    await this.transport.send({
+      type: "resume",
+      since: this.serverHlc
+    });
+  }
+  insert(table, rowId, payload) {
+    const op = this.opCreator.insert(table, rowId, payload);
+    this.store.addPendingOp(op);
+    this.store.applyOptimistic(op);
+    this.notify([table]);
+    return op;
+  }
+  update(table, rowId, payload) {
+    const op = this.opCreator.update(table, rowId, payload);
+    this.store.addPendingOp(op);
+    this.store.applyOptimistic(op);
+    this.notify([table]);
+    return op;
+  }
+  delete(table, rowId) {
+    const op = this.opCreator.delete(table, rowId);
+    this.store.addPendingOp(op);
+    this.store.applyOptimistic(op);
+    this.notify([table]);
+    return op;
+  }
+  batch(ops) {
+    const batchOps = this.opCreator.createBatch(ops);
+    for (const op of batchOps) {
+      this.store.addPendingOp(op);
+      this.store.applyOptimistic(op);
+    }
+    this.notify([...new Set(batchOps.map((o) => o.table))]);
+    return batchOps;
+  }
+  push() {
+    if (this.pushPending)
+      return this.pushPending;
+    const run = this.pushChain.catch(() => {}).then(() => {
+      this.pushPending = null;
+      return this.doPush();
+    });
+    this.pushPending = run;
+    this.pushChain = run.catch(() => {});
+    return run;
+  }
+  async doPush() {
+    await this.store.flush();
+    const cutoff = Date.now() - SyncClient.IN_FLIGHT_TTL_MS;
+    const pending = this.store.getPendingOps().filter((p) => {
+      const sentAt = this.inFlightOps.get(p.op.id);
+      return sentAt === undefined || sentAt <= cutoff;
+    });
+    if (pending.length === 0)
+      return;
+    const ops = pending.map((p) => p.op);
+    const chunks = [];
+    let current = [];
+    let i = 0;
+    while (i < ops.length) {
+      const op = ops[i];
+      if (op.batchId) {
+        let end = i + 1;
+        while (end < ops.length && ops[end].batchId === op.batchId)
+          end++;
+        const batchOps = ops.slice(i, end);
+        if (batchOps.length > MAX_BATCH_SIZE) {
+          if (current.length > 0) {
+            chunks.push(current);
+            current = [];
+          }
+          chunks.push(batchOps);
+        } else {
+          if (current.length + batchOps.length > MAX_BATCH_SIZE) {
+            chunks.push(current);
+            current = [];
+          }
+          current.push(...batchOps);
+        }
+        i = end;
+      } else {
+        if (current.length + 1 > MAX_BATCH_SIZE) {
+          chunks.push(current);
+          current = [];
+        }
+        current.push(op);
+        i++;
+      }
+    }
+    if (current.length > 0)
+      chunks.push(current);
+    for (const chunk of chunks) {
+      const chunkIds = chunk.map((op) => op.id);
+      const sentAt = Date.now();
+      for (const id of chunkIds)
+        this.inFlightOps.set(id, sentAt);
+      try {
+        await this.transport.send({
+          type: "ops",
+          ops: chunk,
+          token: this.config.token
+        });
+      } catch (err) {
+        for (const id of chunkIds)
+          this.inFlightOps.delete(id);
+        throw err;
+      }
+    }
+  }
+  clearInFlight() {
+    this.inFlightOps.clear();
+  }
+  async sendEphemeral(params) {
+    await this.transport.send({
+      type: "ephemeral",
+      ...params
+    });
+  }
+  subscribeEphemeral(key, listener) {
+    let listeners = this.ephemeralListeners.get(key);
+    if (!listeners) {
+      listeners = new Set;
+      this.ephemeralListeners.set(key, listeners);
+    }
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.ephemeralListeners.delete(key);
+      }
+    };
+  }
+  getRows(table, options) {
+    return this.store.getRows(table, options?.includeDeleted).map((r) => r.data);
+  }
+  getRow(table, rowId) {
+    const row = this.store.getRow(table, rowId);
+    return row?.data ?? null;
+  }
+  getPendingCount() {
+    return this.store.getPendingOps().length;
+  }
+  getStore() {
+    return this.store;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  subscribeTable(table, listener) {
+    let listeners = this.tableListeners.get(table);
+    if (!listeners) {
+      listeners = new Set;
+      this.tableListeners.set(table, listeners);
+    }
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.tableListeners.delete(table);
+      }
+    };
+  }
+  getVersion() {
+    return this.version;
+  }
+  getTableVersion(table) {
+    return this.tableVersions.get(table) ?? 0;
+  }
+  notify(tables) {
+    this.version++;
+    if (tables) {
+      for (const table of tables) {
+        this.tableVersions.set(table, (this.tableVersions.get(table) ?? 0) + 1);
+        const tableListeners = this.tableListeners.get(table);
+        if (tableListeners) {
+          for (const listener of [...tableListeners]) {
+            try {
+              listener();
+            } catch (err) {
+              console.error("[reflectdb] table listener threw:", err);
+            }
+          }
+        }
+      }
+    }
+    for (const listener of [...this.listeners]) {
+      try {
+        listener();
+      } catch (err) {
+        console.error("[reflectdb] listener threw:", err);
+      }
+    }
+  }
+  async clear(opts) {
+    if (opts?.tables && opts.tables.length > 0) {
+      for (const table of opts.tables) {
+        await this.store.clearTable(table);
+        this.syncedTables.delete(table);
+        this.syncOptions.delete(table);
+        this.syncParams.delete(table);
+        this.totalCounts.delete(table);
+      }
+      this.notify();
+      return;
+    }
+    await this.store.clear();
+    this.serverHlc = null;
+    this.syncedTables.clear();
+    this.syncOptions.clear();
+    this.syncParams.clear();
+    this.totalCounts.clear();
+    this.opCreator = createOpCreator(`client:${this.config.clientId}`);
+    this.clearInFlight();
+    this.state = "disconnected";
+    this.initialized = false;
+    this.notify();
+  }
+  handleMessage(message) {
+    switch (message.type) {
+      case "hello_ack":
+        if (!SUPPORTED_PROTOCOL_VERSIONS.includes(message.protocolVersion)) {
+          this.state = "disconnected";
+          this.connectReject?.(new Error(`Server negotiated unsupported version: ${message.protocolVersion}`));
+          this.connectResolve = null;
+          this.connectReject = null;
+          this.notify();
+          break;
+        }
+        this.negotiatedProtocolVersion = message.protocolVersion;
+        this.state = "connected";
+        this.connectResolve?.();
+        this.connectResolve = null;
+        this.connectReject = null;
+        this.notify();
+        break;
+      case "hello_reject":
+        this.state = "disconnected";
+        this.connectReject?.(new Error(message.reason));
+        this.connectResolve = null;
+        this.connectReject = null;
+        this.notify();
+        this.config.onError?.({ reason: "local:hello_rejected", message: message.reason });
+        break;
+      case "snapshot":
+        this.store.applySnapshot(message.table, message.rows, message.colClocks, message.append, message.pk);
+        if (message.totalCount != null) {
+          this.totalCounts.set(message.table, message.totalCount);
+        }
+        this.notify([message.table]);
+        this.config.onSync?.(message.table);
+        break;
+      case "bootstrap_complete":
+        this.serverHlc = message.serverHlc;
+        this.store.setTableMeta(message.tableMeta);
+        this.state = "synced";
+        this.mergeServerHlc(message.serverHlc);
+        this.persistMeta();
+        this.notify();
+        break;
+      case "resume_complete":
+        this.serverHlc = message.serverHlc;
+        this.state = "synced";
+        this.mergeServerHlc(message.serverHlc);
+        this.persistMeta();
+        this.notify();
+        break;
+      case "delta":
+        this.store.applyDelta(message.table, message.op, message.rowId, message.payload, message.hlc, message.colClocks);
+        this.notify([message.table]);
+        this.config.onSync?.(message.table);
+        break;
+      case "ack": {
+        const idSet = new Set(message.opIds);
+        const ackedTables = [
+          ...new Set(this.store.getPendingOps().filter((p) => idSet.has(p.op.id)).map((p) => p.op.table))
+        ];
+        for (const opId of message.opIds)
+          this.inFlightOps.delete(opId);
+        this.store.markSynced(message.opIds);
+        this.notify(ackedTables.length > 0 ? ackedTables : undefined);
+        break;
+      }
+      case "reject": {
+        const rejectedTables = [];
+        if (message.opId) {
+          this.inFlightOps.delete(message.opId);
+          const pending = this.store.getPendingOps().find((p) => p.op.id === message.opId);
+          if (pending)
+            rejectedTables.push(pending.op.table);
+          this.store.markRejected(message.opId, message.reason);
+          this.store.revertOp(message.opId, message.serverRow ?? null);
+        }
+        if (message.batchId) {
+          const batchOpIds = [];
+          for (const p of this.store.getPendingOps()) {
+            if (p.op.batchId === message.batchId) {
+              rejectedTables.push(p.op.table);
+              batchOpIds.push(p.op.id);
+            }
+          }
+          this.store.rejectBatch(message.batchId, message.reason);
+          for (const opId of batchOpIds) {
+            this.inFlightOps.delete(opId);
+            this.store.revertOp(opId, null);
+          }
+        }
+        const uniqueRejectedTables = [...new Set(rejectedTables)];
+        this.notify(uniqueRejectedTables.length > 0 ? uniqueRejectedTables : undefined);
+        this.config.onError?.({
+          opId: message.opId,
+          reason: message.reason
+        });
+        break;
+      }
+      case "resume_rejected":
+        this.serverHlc = null;
+        if (this.config.storage) {
+          this.config.storage.setMeta("serverHlc", "").catch((err) => {
+            console.error("[reflectdb] Failed to clear stale serverHlc:", err);
+          });
+        }
+        this.bootstrap();
+        break;
+      case "reauth":
+        this.handleReauth();
+        break;
+      case "disconnect":
+        this.state = "disconnected";
+        this.clearInFlight();
+        if (this.connectReject) {
+          this.connectReject(new Error(message.reason));
+          this.connectResolve = null;
+          this.connectReject = null;
+        }
+        this.notify();
+        this.config.onError?.({ reason: "local:disconnected", message: message.reason });
+        this.scheduleReconnect();
+        break;
+      case "shape_changed":
+        this.store.clearTable(message.table);
+        this.notify([message.table]);
+        this.config.onSync?.(message.table);
+        break;
+      case "count_changed":
+        this.totalCounts.set(message.table, message.totalCount);
+        this.notify([message.table]);
+        break;
+      case "ephemeral":
+        {
+          const listeners = this.ephemeralListeners.get(message.key);
+          if (listeners) {
+            for (const listener of listeners) {
+              listener(message);
+            }
+          }
+        }
+        break;
+    }
+  }
+  mergeServerHlc(packed) {
+    const remote = unpackHlc(packed);
+    const localHlc = this.opCreator.getHlc();
+    const merged = receiveHlc(localHlc, remote);
+    this.opCreator = createOpCreator(localHlc.nodeId, merged);
+  }
+  persistMeta() {
+    if (!this.config.storage)
+      return;
+    const storage = this.config.storage;
+    const hlcState = this.opCreator.getHlc();
+    storage.setMeta("serverHlc", this.serverHlc).catch((err) => {
+      console.error("[reflectdb] Failed to persist serverHlc:", err);
+    });
+    storage.setMeta("hlcState", JSON.stringify(hlcState)).catch((err) => {
+      console.error("[reflectdb] Failed to persist hlcState:", err);
+    });
+  }
+  persistSyncSubscriptions() {
+    if (!this.config.storage)
+      return;
+    const subs = Array.from(this.syncedTables).map((table) => ({
+      table,
+      params: this.syncParams.get(table),
+      options: this.syncOptions.get(table)
+    }));
+    this.config.storage.setMeta("syncSubscriptions", JSON.stringify(subs)).catch((err) => {
+      console.error("[reflectdb] Failed to persist sync subscriptions:", err);
+    });
+  }
+  handleReauth() {
+    if (!this.config.onReauth) {
+      this.config.onError?.({
+        reason: "local:reauth_failed",
+        message: "reauth requested but no onReauth handler configured"
+      });
+      return;
+    }
+    this.config.onReauth().then(async (token) => {
+      this.config.token = token;
+      try {
+        await this.transport.send({ type: "auth", token });
+      } catch (err) {
+        this.config.onError?.({
+          reason: "local:reauth_failed",
+          message: `auth send failed: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    }).catch((err) => {
+      this.config.onError?.({ reason: "local:reauth_failed", message: String(err) });
+    });
+  }
+  scheduleReconnect() {
+    if (this.closed || this.reconnectTimer)
+      return;
+    const cap = this.config.maxReconnectDelayMs ?? 30000;
+    const base = Math.min(1000 * 2 ** this.reconnectAttempts, cap);
+    const delay = Math.round(base * (0.5 + Math.random() * 0.5));
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      try {
+        await this.connect();
+        if (this.closed)
+          return;
+        if (this.closed)
+          return;
+        const syncResults = await Promise.allSettled([...this.syncedTables].map((table) => this.sync(table, this.syncParams.get(table), this.syncOptions.get(table))));
+        for (const r of syncResults) {
+          if (r.status === "rejected") {
+            console.error("[reflectdb] reconnect re-sync failed:", r.reason);
+          }
+        }
+        if (this.closed)
+          return;
+        await this.resume();
+        this.clearInFlight();
+        if (this.closed)
+          return;
+        await this.push();
+        this.reconnectAttempts = 0;
+      } catch (err) {
+        try {
+          this.config.onError?.({
+            reason: "local:reconnect_failed",
+            message: `attempt ${this.reconnectAttempts}: ${err instanceof Error ? err.message : String(err)}`
+          });
+        } catch {}
+        this.scheduleReconnect();
+      }
+    }, delay);
+  }
+}
+function pushSafely(client) {
+  return client.push().catch((err) => {
+    console.error("[reflectdb] push failed:", err);
+  });
+}
+// src/client/storage/memory.ts
+function createMemoryStorage() {
+  const rows = new Map;
+  let pendingOps = [];
+  const meta = new Map;
+  return {
+    async getRows(table) {
+      return Array.from(rows.get(table)?.values() ?? []);
+    },
+    async getAllRows() {
+      const all = [];
+      for (const tableRows of rows.values()) {
+        for (const row of tableRows.values()) {
+          all.push(row);
+        }
+      }
+      return all;
+    },
+    async putRow(table, rowId, row) {
+      let tableRows = rows.get(table);
+      if (!tableRows) {
+        tableRows = new Map;
+        rows.set(table, tableRows);
+      }
+      tableRows.set(rowId, row);
+    },
+    async deleteRow(table, rowId) {
+      rows.get(table)?.delete(rowId);
+    },
+    async clearTable(table) {
+      rows.delete(table);
+    },
+    async getPendingOps() {
+      return [...pendingOps];
+    },
+    async putPendingOps(ops) {
+      pendingOps = [...ops];
+    },
+    async appendPendingOps(ops) {
+      pendingOps.push(...ops);
+    },
+    async updatePendingOps(ops) {
+      const updateMap = new Map;
+      for (const op of ops) {
+        updateMap.set(op.op.id, op);
+      }
+      for (let i = 0;i < pendingOps.length; i++) {
+        const updated = updateMap.get(pendingOps[i].op.id);
+        if (updated) {
+          pendingOps[i] = updated;
+        }
+      }
+    },
+    async removePendingOps(opIds) {
+      const idSet = new Set(opIds);
+      pendingOps = pendingOps.filter((p) => !idSet.has(p.op.id));
+    },
+    async clearPendingOps() {
+      pendingOps = [];
+    },
+    async getMeta(key) {
+      return meta.get(key) ?? null;
+    },
+    async setMeta(key, value) {
+      meta.set(key, value);
+    },
+    async deleteMeta(key) {
+      meta.delete(key);
+    },
+    async clear() {
+      rows.clear();
+      pendingOps = [];
+      meta.clear();
+    }
+  };
+}
+// src/client/typed-client.ts
+function createSyncClient(config) {
+  const { queries, autoSync, ...clientConfig } = config;
+  const client = new SyncClient(clientConfig);
+  if (autoSync) {
+    const origConnect = client.connect.bind(client);
+    client.connect = async () => {
+      await origConnect();
+      await Promise.all(Object.keys(queries).filter((name) => !("params" in queries[name])).map((name) => client.sync(name)));
+    };
+  }
+  return client;
+}