lakesync 0.1.1 → 0.1.2

package/dist/client.js

@@ -6,7 +6,7 @@ import {
   decodeSyncResponse,
   encodeSyncPull,
   encodeSyncPush
-} from "./chunk-BNJOGBYK.js";
+} from "./chunk-X3UOVRV7.js";
 import {
   Err,
   HLC,
@@ -22,9 +22,12 @@ import {
   quoteIdentifier,
   toError,
   unwrapOrThrow
-} from "./chunk-ICNT7I3K.js";
+} from "./chunk-DKFUPHCU.js";
 import "./chunk-7D4SUZUM.js";
 
+// ../client/src/db/local-db.ts
+import initSqlJs from "sql.js";
+
 // ../client/src/db/idb-persistence.ts
 import { openDB } from "idb";
 var IDB_DB_NAME = "lakesync-snapshots";
@@ -57,9 +60,6 @@ async function deleteSnapshot(dbName) {
   await idb.delete(STORE_NAME, dbName);
 }
 
-// ../client/src/db/local-db.ts
-import initSqlJs from "sql.js";
-
 // ../client/src/db/types.ts
 var DbError = class extends LakeSyncError {
   constructor(message, cause) {
@@ -368,165 +368,88 @@ async function migrateSchema(db, oldSchema, newSchema) {
   });
 }
 
-// ../client/src/queue/idb-action-queue.ts
-import { openDB as openDB2 } from "idb";
-var DB_NAME = "lakesync-action-queue";
-var DB_VERSION = 1;
-var STORE_NAME2 = "entries";
-function serialiseAction(action) {
-  return { ...action, hlc: action.hlc.toString() };
-}
-function deserialiseAction(serialised) {
-  return { ...serialised, hlc: BigInt(serialised.hlc) };
-}
-function serialiseEntry(entry) {
-  return { ...entry, action: serialiseAction(entry.action) };
-}
-function deserialiseEntry(serialised) {
-  return { ...serialised, action: deserialiseAction(serialised.action) };
-}
-async function wrapIdbOp(operation, fn) {
-  try {
-    return Ok(await fn());
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return Err(new LakeSyncError(`Failed to ${operation}: ${message}`, "QUEUE_ERROR"));
-  }
-}
-var IDBActionQueue = class {
-  dbPromise;
+// ../client/src/queue/memory-queue.ts
+var MemoryQueue = class {
+  entries = /* @__PURE__ */ new Map();
   counter = 0;
-  /**
-   * Create a new IDB-backed action queue.
-   *
-   * @param dbName - Optional database name. Defaults to `'lakesync-action-queue'`.
-   */
-  constructor(dbName = DB_NAME) {
-    this.dbPromise = openDB2(dbName, DB_VERSION, {
-      upgrade(db) {
-        const store = db.createObjectStore(STORE_NAME2, { keyPath: "id" });
-        store.createIndex("status", "status");
-        store.createIndex("createdAt", "createdAt");
-      }
-    });
-  }
-  /** Add an action to the queue. */
-  async push(action) {
-    return wrapIdbOp("push to action queue", async () => {
-      const db = await this.dbPromise;
-      const entry = {
-        id: `idb-action-${Date.now()}-${++this.counter}`,
-        action,
-        status: "pending",
-        createdAt: Date.now(),
-        retryCount: 0
-      };
-      await db.put(STORE_NAME2, serialiseEntry(entry));
-      return entry;
-    });
+  /** Add a delta to the queue */
+  async push(delta) {
+    const entry = {
+      id: `mem-${++this.counter}`,
+      delta,
+      status: "pending",
+      createdAt: Date.now(),
+      retryCount: 0
+    };
+    this.entries.set(entry.id, entry);
+    return Ok(entry);
   }
-  /** Peek at pending entries (ordered by createdAt). */
+  /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter */
   async peek(limit) {
-    return wrapIdbOp("peek action queue", async () => {
-      const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME2, "readonly");
-      const index = tx.objectStore(STORE_NAME2).index("createdAt");
-      const results = [];
-      let cursor = await index.openCursor();
-      while (cursor && results.length < limit) {
-        const serialised = cursor.value;
-        if (serialised.status === "pending") {
-          const entry = deserialiseEntry(serialised);
-          if (entry.retryAfter === void 0 || entry.retryAfter <= Date.now()) {
-            results.push(entry);
-          }
-        }
-        cursor = await cursor.continue();
-      }
-      return results;
-    });
+    const now = Date.now();
+    const pending = [...this.entries.values()].filter((e) => e.status === "pending" && (e.retryAfter === void 0 || e.retryAfter <= now)).sort((a, b) => a.createdAt - b.createdAt).slice(0, limit);
+    return Ok(pending);
   }
-  /** Mark entries as currently being sent. */
+  /** Mark entries as currently being sent */
   async markSending(ids) {
-    return wrapIdbOp("mark sending", async () => {
-      const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME2, "readwrite");
-      const store = tx.objectStore(STORE_NAME2);
-      for (const id of ids) {
-        const serialised = await store.get(id);
-        if (serialised?.status === "pending") {
-          serialised.status = "sending";
-          await store.put(serialised);
-        }
+    for (const id of ids) {
+      const entry = this.entries.get(id);
+      if (entry?.status === "pending") {
+        entry.status = "sending";
       }
-      await tx.done;
-    });
+    }
+    return Ok(void 0);
   }
-  /** Acknowledge successful delivery (removes entries). */
+  /** Acknowledge successful delivery (removes entries) */
   async ack(ids) {
-    return wrapIdbOp("ack", async () => {
-      const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME2, "readwrite");
-      for (const id of ids) {
-        await tx.objectStore(STORE_NAME2).delete(id);
-      }
-      await tx.done;
-    });
+    for (const id of ids) {
+      this.entries.delete(id);
+    }
+    return Ok(void 0);
   }
-  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff. */
+  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff */
   async nack(ids) {
-    return wrapIdbOp("nack", async () => {
-      const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME2, "readwrite");
-      const store = tx.objectStore(STORE_NAME2);
-      for (const id of ids) {
-        const serialised = await store.get(id);
-        if (serialised) {
-          serialised.status = "pending";
-          serialised.retryCount++;
-          const backoffMs = Math.min(1e3 * 2 ** serialised.retryCount, 3e4);
-          serialised.retryAfter = Date.now() + backoffMs;
-          await store.put(serialised);
-        }
+    for (const id of ids) {
+      const entry = this.entries.get(id);
+      if (entry) {
+        entry.status = "pending";
+        entry.retryCount++;
+        const backoffMs = Math.min(1e3 * 2 ** entry.retryCount, 3e4);
+        entry.retryAfter = Date.now() + backoffMs;
       }
-      await tx.done;
-    });
+    }
+    return Ok(void 0);
   }
-  /** Get the number of pending + sending entries. */
+  /** Get the number of pending + sending entries */
   async depth() {
-    return wrapIdbOp("get depth", async () => {
-      const db = await this.dbPromise;
-      const all = await db.getAll(STORE_NAME2);
-      return all.filter((e) => e.status === "pending" || e.status === "sending").length;
-    });
+    const count = [...this.entries.values()].filter((e) => e.status !== "acked").length;
+    return Ok(count);
   }
-  /** Remove all entries. */
+  /** Remove all entries */
   async clear() {
-    return wrapIdbOp("clear action queue", async () => {
-      const db = await this.dbPromise;
-      await db.clear(STORE_NAME2);
-    });
+    this.entries.clear();
+    return Ok(void 0);
   }
 };
 
 // ../client/src/queue/idb-queue.ts
-import { openDB as openDB3 } from "idb";
-var DB_NAME2 = "lakesync-queue";
-var DB_VERSION2 = 1;
-var STORE_NAME3 = "entries";
+import { openDB as openDB2 } from "idb";
+var DB_NAME = "lakesync-queue";
+var DB_VERSION = 1;
+var STORE_NAME2 = "entries";
 function serialiseDelta(delta) {
   return { ...delta, hlc: delta.hlc.toString() };
 }
 function deserialiseDelta(serialised) {
   return { ...serialised, hlc: BigInt(serialised.hlc) };
 }
-function serialiseEntry2(entry) {
+function serialiseEntry(entry) {
   return { ...entry, delta: serialiseDelta(entry.delta) };
 }
-function deserialiseEntry2(serialised) {
+function deserialiseEntry(serialised) {
   return { ...serialised, delta: deserialiseDelta(serialised.delta) };
 }
-async function wrapIdbOp2(operation, fn) {
+async function wrapIdbOp(operation, fn) {
   try {
     return Ok(await fn());
   } catch (error) {
@@ -543,10 +466,10 @@ var IDBQueue = class {
    * @param dbName - Optional database name. Defaults to `'lakesync-queue'`.
    *                 Useful for tests or running multiple independent queues.
    */
-  constructor(dbName = DB_NAME2) {
-    this.dbPromise = openDB3(dbName, DB_VERSION2, {
+  constructor(dbName = DB_NAME) {
+    this.dbPromise = openDB2(dbName, DB_VERSION, {
       upgrade(db) {
-        const store = db.createObjectStore(STORE_NAME3, { keyPath: "id" });
+        const store = db.createObjectStore(STORE_NAME2, { keyPath: "id" });
         store.createIndex("status", "status");
         store.createIndex("createdAt", "createdAt");
       }
@@ -554,7 +477,7 @@ var IDBQueue = class {
   }
   /** Add a delta to the queue */
   async push(delta) {
-    return wrapIdbOp2("push to queue", async () => {
+    return wrapIdbOp("push to queue", async () => {
       const db = await this.dbPromise;
       const entry = {
         id: `idb-${Date.now()}-${++this.counter}`,
@@ -563,22 +486,22 @@ var IDBQueue = class {
         createdAt: Date.now(),
         retryCount: 0
       };
-      await db.put(STORE_NAME3, serialiseEntry2(entry));
+      await db.put(STORE_NAME2, serialiseEntry(entry));
       return entry;
     });
   }
   /** Peek at pending entries (ordered by createdAt) */
   async peek(limit) {
-    return wrapIdbOp2("peek queue", async () => {
+    return wrapIdbOp("peek queue", async () => {
       const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME3, "readonly");
-      const index = tx.objectStore(STORE_NAME3).index("createdAt");
+      const tx = db.transaction(STORE_NAME2, "readonly");
+      const index = tx.objectStore(STORE_NAME2).index("createdAt");
       const results = [];
       let cursor = await index.openCursor();
       while (cursor && results.length < limit) {
         const serialised = cursor.value;
         if (serialised.status === "pending") {
-          const entry = deserialiseEntry2(serialised);
+          const entry = deserialiseEntry(serialised);
           if (entry.retryAfter === void 0 || entry.retryAfter <= Date.now()) {
             results.push(entry);
           }
@@ -590,10 +513,10 @@ var IDBQueue = class {
   }
   /** Mark entries as currently being sent */
   async markSending(ids) {
-    return wrapIdbOp2("mark sending", async () => {
+    return wrapIdbOp("mark sending", async () => {
       const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME3, "readwrite");
-      const store = tx.objectStore(STORE_NAME3);
+      const tx = db.transaction(STORE_NAME2, "readwrite");
+      const store = tx.objectStore(STORE_NAME2);
       for (const id of ids) {
         const serialised = await store.get(id);
         if (serialised?.status === "pending") {
@@ -606,21 +529,21 @@ var IDBQueue = class {
   }
   /** Acknowledge successful delivery (removes entries) */
   async ack(ids) {
-    return wrapIdbOp2("ack", async () => {
+    return wrapIdbOp("ack", async () => {
       const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME3, "readwrite");
+      const tx = db.transaction(STORE_NAME2, "readwrite");
       for (const id of ids) {
-        await tx.objectStore(STORE_NAME3).delete(id);
+        await tx.objectStore(STORE_NAME2).delete(id);
       }
       await tx.done;
     });
   }
   /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff */
   async nack(ids) {
-    return wrapIdbOp2("nack", async () => {
+    return wrapIdbOp("nack", async () => {
       const db = await this.dbPromise;
-      const tx = db.transaction(STORE_NAME3, "readwrite");
-      const store = tx.objectStore(STORE_NAME3);
+      const tx = db.transaction(STORE_NAME2, "readwrite");
+      const store = tx.objectStore(STORE_NAME2);
       for (const id of ids) {
         const serialised = await store.get(id);
         if (serialised) {
@@ -636,155 +559,25 @@ var IDBQueue = class {
   }
   /** Get the number of pending + sending entries */
   async depth() {
-    return wrapIdbOp2("get depth", async () => {
+    return wrapIdbOp("get depth", async () => {
       const db = await this.dbPromise;
-      const all = await db.getAll(STORE_NAME3);
+      const all = await db.getAll(STORE_NAME2);
       return all.filter((e) => e.status !== "acked").length;
     });
   }
   /** Remove all entries */
   async clear() {
-    return wrapIdbOp2("clear queue", async () => {
+    return wrapIdbOp("clear queue", async () => {
       const db = await this.dbPromise;
-      await db.clear(STORE_NAME3);
+      await db.clear(STORE_NAME2);
     });
   }
 };
 
-// ../client/src/queue/memory-action-queue.ts
-var MemoryActionQueue = class {
-  entries = /* @__PURE__ */ new Map();
-  counter = 0;
-  /** Add an action to the queue. */
-  async push(action) {
-    const entry = {
-      id: `mem-action-${++this.counter}`,
-      action,
-      status: "pending",
-      createdAt: Date.now(),
-      retryCount: 0
-    };
-    this.entries.set(entry.id, entry);
-    return Ok(entry);
-  }
-  /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter. */
-  async peek(limit) {
-    const now = Date.now();
-    const pending = [...this.entries.values()].filter((e) => e.status === "pending" && (e.retryAfter === void 0 || e.retryAfter <= now)).sort((a, b) => a.createdAt - b.createdAt).slice(0, limit);
-    return Ok(pending);
-  }
-  /** Mark entries as currently being sent. */
-  async markSending(ids) {
-    for (const id of ids) {
-      const entry = this.entries.get(id);
-      if (entry?.status === "pending") {
-        entry.status = "sending";
-      }
-    }
-    return Ok(void 0);
-  }
-  /** Acknowledge successful delivery (removes entries). */
-  async ack(ids) {
-    for (const id of ids) {
-      this.entries.delete(id);
-    }
-    return Ok(void 0);
-  }
-  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff. */
-  async nack(ids) {
-    for (const id of ids) {
-      const entry = this.entries.get(id);
-      if (entry) {
-        entry.status = "pending";
-        entry.retryCount++;
-        const backoffMs = Math.min(1e3 * 2 ** entry.retryCount, 3e4);
-        entry.retryAfter = Date.now() + backoffMs;
-      }
-    }
-    return Ok(void 0);
-  }
-  /** Get the number of pending + sending entries. */
-  async depth() {
-    const count = [...this.entries.values()].filter(
-      (e) => e.status === "pending" || e.status === "sending"
-    ).length;
-    return Ok(count);
-  }
-  /** Remove all entries. */
-  async clear() {
-    this.entries.clear();
-    return Ok(void 0);
-  }
-};
-
-// ../client/src/queue/memory-queue.ts
-var MemoryQueue = class {
-  entries = /* @__PURE__ */ new Map();
-  counter = 0;
-  /** Add a delta to the queue */
-  async push(delta) {
-    const entry = {
-      id: `mem-${++this.counter}`,
-      delta,
-      status: "pending",
-      createdAt: Date.now(),
-      retryCount: 0
-    };
-    this.entries.set(entry.id, entry);
-    return Ok(entry);
-  }
-  /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter */
-  async peek(limit) {
-    const now = Date.now();
-    const pending = [...this.entries.values()].filter((e) => e.status === "pending" && (e.retryAfter === void 0 || e.retryAfter <= now)).sort((a, b) => a.createdAt - b.createdAt).slice(0, limit);
-    return Ok(pending);
-  }
-  /** Mark entries as currently being sent */
-  async markSending(ids) {
-    for (const id of ids) {
-      const entry = this.entries.get(id);
-      if (entry?.status === "pending") {
-        entry.status = "sending";
-      }
-    }
-    return Ok(void 0);
-  }
-  /** Acknowledge successful delivery (removes entries) */
-  async ack(ids) {
-    for (const id of ids) {
-      this.entries.delete(id);
-    }
-    return Ok(void 0);
-  }
-  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff */
-  async nack(ids) {
-    for (const id of ids) {
-      const entry = this.entries.get(id);
-      if (entry) {
-        entry.status = "pending";
-        entry.retryCount++;
-        const backoffMs = Math.min(1e3 * 2 ** entry.retryCount, 3e4);
-        entry.retryAfter = Date.now() + backoffMs;
-      }
-    }
-    return Ok(void 0);
-  }
-  /** Get the number of pending + sending entries */
-  async depth() {
-    const count = [...this.entries.values()].filter((e) => e.status !== "acked").length;
-    return Ok(count);
-  }
-  /** Remove all entries */
-  async clear() {
-    this.entries.clear();
-    return Ok(void 0);
-  }
-};
-
-// ../client/src/sync/applier.ts
-async function applyRemoteDeltas(db, deltas, resolver, pendingQueue) {
-  if (deltas.length === 0) {
-    return Ok(0);
+// ../client/src/sync/applier.ts
+async function applyRemoteDeltas(db, deltas, resolver, pendingQueue) {
+  if (deltas.length === 0) {
+    return Ok(0);
   }
   const cursorTableResult = await db.exec(`
 		CREATE TABLE IF NOT EXISTS _sync_cursor (
@@ -1415,7 +1208,7 @@ var SyncCoordinator = class {
       return;
     }
     const hlc = this.hlc.now();
-    const { generateActionId } = await import("./src-WYBF5LOI.js");
+    const { generateActionId } = await import("./src-3CWNXNX6.js");
     const actionId = await generateActionId({
       clientId: this._clientId,
       hlc,
@@ -1517,80 +1310,6 @@ var SyncCoordinator = class {
   }
 };
 
-// ../client/src/sync/schema-sync.ts
-var SchemaSynchroniser = class {
-  constructor(db) {
-    this.db = db;
-  }
-  /**
-   * Compare local schema version with server and apply migrations if behind.
-   *
-   * If the local version is already equal to or ahead of the server version,
-   * this is a no-op. Otherwise, the local schema is migrated to match the
-   * server schema via `migrateSchema()`, which runs ALTER TABLE ... ADD COLUMN
-   * for each new column.
-   *
-   * @param table - The table name to synchronise
-   * @param serverSchema - The server's current TableSchema
-   * @param serverVersion - The server's schema version number
-   * @returns Ok on success, or Err with a LakeSyncError on failure
-   */
-  async synchronise(table, serverSchema, serverVersion) {
-    const localSchemaResult = await getSchema(this.db, table);
-    if (!localSchemaResult.ok) return localSchemaResult;
-    const localSchema = localSchemaResult.value;
-    if (!localSchema) {
-      return Err(
-        new SchemaError(
-          `Cannot synchronise schema for table "${table}": no local schema registered`
-        )
-      );
-    }
-    const localVersionResult = await this.getLocalVersion(table);
-    if (!localVersionResult.ok) return localVersionResult;
-    const localVersion = localVersionResult.value;
-    if (localVersion >= serverVersion) {
-      return Ok(void 0);
-    }
-    const migrateResult = await migrateSchema(this.db, localSchema, serverSchema);
-    if (!migrateResult.ok) return migrateResult;
-    const updateResult = await this.setLocalVersion(table, serverVersion);
-    if (!updateResult.ok) return updateResult;
-    return Ok(void 0);
-  }
-  /**
-   * Retrieve the local schema version for a given table from `_lakesync_meta`.
-   *
-   * @param table - The table name to look up
-   * @returns The schema version number, or 0 if the table is not registered
-   */
-  async getLocalVersion(table) {
-    const result = await this.db.query(
-      "SELECT schema_version FROM _lakesync_meta WHERE table_name = ?",
-      [table]
-    );
-    if (!result.ok) return result;
-    const rows = result.value;
-    if (rows.length === 0 || !rows[0]) {
-      return Ok(0);
-    }
-    return Ok(rows[0].schema_version);
-  }
-  /**
-   * Set the local schema version for a given table in `_lakesync_meta`.
-   *
-   * @param table - The table name to update
-   * @param version - The version number to set
-   * @returns Ok on success, or Err with a DbError on failure
-   */
-  async setLocalVersion(table, version) {
-    return this.db.exec("UPDATE _lakesync_meta SET schema_version = ? WHERE table_name = ?", [
-      version,
-      table
-    ]);
-  }
-};
-
 // ../client/src/sync/transport-http.ts
 var HttpTransport = class {
   baseUrl;
@@ -1784,6 +1503,324 @@ async function readStreamingCheckpointDeltas(response) {
   return allDeltas;
 }
 
+// ../client/src/create-client.ts
+async function createClient(config) {
+  const dbResult = await LocalDB.open({
+    name: config.name,
+    backend: config.backend
+  });
+  const db = unwrapOrThrow(dbResult);
+  for (const schema of config.schemas) {
+    unwrapOrThrow(await registerSchema(db, schema));
+  }
+  const transport = new HttpTransport({
+    baseUrl: config.gateway.url,
+    gatewayId: config.gateway.gatewayId,
+    token: config.gateway.token ?? ""
+  });
+  const queue = config.queue ?? new MemoryQueue();
+  const autoSyncMs = config.autoSyncMs ?? 1e4;
+  const coordinator = new SyncCoordinator(db, transport, {
+    ...config.coordinatorConfig,
+    queue,
+    clientId: config.clientId,
+    autoSyncIntervalMs: autoSyncMs
+  });
+  if (autoSyncMs > 0) {
+    coordinator.startAutoSync();
+  }
+  return {
+    coordinator,
+    db,
+    transport,
+    destroy: async () => {
+      coordinator.stopAutoSync();
+      await db.close();
+    }
+  };
+}
+
+// ../client/src/queue/idb-action-queue.ts
+import { openDB as openDB3 } from "idb";
+var DB_NAME2 = "lakesync-action-queue";
+var DB_VERSION2 = 1;
+var STORE_NAME3 = "entries";
+function serialiseAction(action) {
+  return { ...action, hlc: action.hlc.toString() };
+}
+function deserialiseAction(serialised) {
+  return { ...serialised, hlc: BigInt(serialised.hlc) };
+}
+function serialiseEntry2(entry) {
+  return { ...entry, action: serialiseAction(entry.action) };
+}
+function deserialiseEntry2(serialised) {
+  return { ...serialised, action: deserialiseAction(serialised.action) };
+}
+async function wrapIdbOp2(operation, fn) {
+  try {
+    return Ok(await fn());
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Err(new LakeSyncError(`Failed to ${operation}: ${message}`, "QUEUE_ERROR"));
+  }
+}
+var IDBActionQueue = class {
+  dbPromise;
+  counter = 0;
+  /**
+   * Create a new IDB-backed action queue.
+   *
+   * @param dbName - Optional database name. Defaults to `'lakesync-action-queue'`.
+   */
+  constructor(dbName = DB_NAME2) {
+    this.dbPromise = openDB3(dbName, DB_VERSION2, {
+      upgrade(db) {
+        const store = db.createObjectStore(STORE_NAME3, { keyPath: "id" });
+        store.createIndex("status", "status");
+        store.createIndex("createdAt", "createdAt");
+      }
+    });
+  }
+  /** Add an action to the queue. */
+  async push(action) {
+    return wrapIdbOp2("push to action queue", async () => {
+      const db = await this.dbPromise;
+      const entry = {
+        id: `idb-action-${Date.now()}-${++this.counter}`,
+        action,
+        status: "pending",
+        createdAt: Date.now(),
+        retryCount: 0
+      };
+      await db.put(STORE_NAME3, serialiseEntry2(entry));
+      return entry;
+    });
+  }
+  /** Peek at pending entries (ordered by createdAt). */
+  async peek(limit) {
+    return wrapIdbOp2("peek action queue", async () => {
+      const db = await this.dbPromise;
+      const tx = db.transaction(STORE_NAME3, "readonly");
+      const index = tx.objectStore(STORE_NAME3).index("createdAt");
+      const results = [];
+      let cursor = await index.openCursor();
+      while (cursor && results.length < limit) {
+        const serialised = cursor.value;
+        if (serialised.status === "pending") {
+          const entry = deserialiseEntry2(serialised);
+          if (entry.retryAfter === void 0 || entry.retryAfter <= Date.now()) {
+            results.push(entry);
+          }
+        }
+        cursor = await cursor.continue();
+      }
+      return results;
+    });
+  }
+  /** Mark entries as currently being sent. */
+  async markSending(ids) {
+    return wrapIdbOp2("mark sending", async () => {
+      const db = await this.dbPromise;
+      const tx = db.transaction(STORE_NAME3, "readwrite");
+      const store = tx.objectStore(STORE_NAME3);
+      for (const id of ids) {
+        const serialised = await store.get(id);
+        if (serialised?.status === "pending") {
+          serialised.status = "sending";
+          await store.put(serialised);
+        }
+      }
+      await tx.done;
+    });
+  }
+  /** Acknowledge successful delivery (removes entries). */
+  async ack(ids) {
+    return wrapIdbOp2("ack", async () => {
+      const db = await this.dbPromise;
+      const tx = db.transaction(STORE_NAME3, "readwrite");
+      for (const id of ids) {
+        await tx.objectStore(STORE_NAME3).delete(id);
+      }
+      await tx.done;
+    });
+  }
+  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff. */
+  async nack(ids) {
+    return wrapIdbOp2("nack", async () => {
+      const db = await this.dbPromise;
+      const tx = db.transaction(STORE_NAME3, "readwrite");
+      const store = tx.objectStore(STORE_NAME3);
+      for (const id of ids) {
+        const serialised = await store.get(id);
+        if (serialised) {
+          serialised.status = "pending";
+          serialised.retryCount++;
+          const backoffMs = Math.min(1e3 * 2 ** serialised.retryCount, 3e4);
+          serialised.retryAfter = Date.now() + backoffMs;
+          await store.put(serialised);
+        }
+      }
+      await tx.done;
+    });
+  }
+  /** Get the number of pending + sending entries. */
+  async depth() {
+    return wrapIdbOp2("get depth", async () => {
+      const db = await this.dbPromise;
+      const all = await db.getAll(STORE_NAME3);
+      return all.filter((e) => e.status === "pending" || e.status === "sending").length;
+    });
+  }
+  /** Remove all entries. */
+  async clear() {
+    return wrapIdbOp2("clear action queue", async () => {
+      const db = await this.dbPromise;
+      await db.clear(STORE_NAME3);
+    });
+  }
+};
+
+// ../client/src/queue/memory-action-queue.ts
+var MemoryActionQueue = class {
+  entries = /* @__PURE__ */ new Map();
+  counter = 0;
+  /** Add an action to the queue. */
+  async push(action) {
+    const entry = {
+      id: `mem-action-${++this.counter}`,
+      action,
+      status: "pending",
+      createdAt: Date.now(),
+      retryCount: 0
+    };
+    this.entries.set(entry.id, entry);
+    return Ok(entry);
+  }
+  /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter. */
+  async peek(limit) {
+    const now = Date.now();
+    const pending = [...this.entries.values()].filter((e) => e.status === "pending" && (e.retryAfter === void 0 || e.retryAfter <= now)).sort((a, b) => a.createdAt - b.createdAt).slice(0, limit);
+    return Ok(pending);
+  }
+  /** Mark entries as currently being sent. */
+  async markSending(ids) {
+    for (const id of ids) {
+      const entry = this.entries.get(id);
+      if (entry?.status === "pending") {
+        entry.status = "sending";
+      }
+    }
+    return Ok(void 0);
+  }
+  /** Acknowledge successful delivery (removes entries). */
+  async ack(ids) {
+    for (const id of ids) {
+      this.entries.delete(id);
+    }
+    return Ok(void 0);
+  }
+  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff. */
+  async nack(ids) {
+    for (const id of ids) {
+      const entry = this.entries.get(id);
+      if (entry) {
+        entry.status = "pending";
+        entry.retryCount++;
+        const backoffMs = Math.min(1e3 * 2 ** entry.retryCount, 3e4);
+        entry.retryAfter = Date.now() + backoffMs;
+      }
+    }
+    return Ok(void 0);
+  }
+  /** Get the number of pending + sending entries. */
+  async depth() {
+    const count = [...this.entries.values()].filter(
+      (e) => e.status === "pending" || e.status === "sending"
+    ).length;
+    return Ok(count);
+  }
+  /** Remove all entries. */
+  async clear() {
+    this.entries.clear();
+    return Ok(void 0);
+  }
+};
+
+// ../client/src/sync/schema-sync.ts
+var SchemaSynchroniser = class {
+  constructor(db) {
+    this.db = db;
+  }
+  /**
+   * Compare local schema version with server and apply migrations if behind.
+   *
+   * If the local version is already equal to or ahead of the server version,
+   * this is a no-op. Otherwise, the local schema is migrated to match the
+   * server schema via `migrateSchema()`, which runs ALTER TABLE ... ADD COLUMN
+   * for each new column.
+   *
+   * @param table - The table name to synchronise
+   * @param serverSchema - The server's current TableSchema
+   * @param serverVersion - The server's schema version number
+   * @returns Ok on success, or Err with a LakeSyncError on failure
+   */
+  async synchronise(table, serverSchema, serverVersion) {
+    const localSchemaResult = await getSchema(this.db, table);
+    if (!localSchemaResult.ok) return localSchemaResult;
+    const localSchema = localSchemaResult.value;
+    if (!localSchema) {
+      return Err(
+        new SchemaError(
+          `Cannot synchronise schema for table "${table}": no local schema registered`
+        )
+      );
+    }
+    const localVersionResult = await this.getLocalVersion(table);
+    if (!localVersionResult.ok) return localVersionResult;
+    const localVersion = localVersionResult.value;
+    if (localVersion >= serverVersion) {
+      return Ok(void 0);
+    }
+    const migrateResult = await migrateSchema(this.db, localSchema, serverSchema);
+    if (!migrateResult.ok) return migrateResult;
+    const updateResult = await this.setLocalVersion(table, serverVersion);
+    if (!updateResult.ok) return updateResult;
+    return Ok(void 0);
+  }
+  /**
+   * Retrieve the local schema version for a given table from `_lakesync_meta`.
+   *
+   * @param table - The table name to look up
+   * @returns The schema version number, or 0 if the table is not registered
+   */
+  async getLocalVersion(table) {
+    const result = await this.db.query(
+      "SELECT schema_version FROM _lakesync_meta WHERE table_name = ?",
+      [table]
+    );
+    if (!result.ok) return result;
+    const rows = result.value;
+    if (rows.length === 0 || !rows[0]) {
+      return Ok(0);
+    }
+    return Ok(rows[0].schema_version);
+  }
+  /**
+   * Set the local schema version for a given table in `_lakesync_meta`.
+   *
+   * @param table - The table name to update
+   * @param version - The version number to set
+   * @returns Ok on success, or Err with a DbError on failure
+   */
+  async setLocalVersion(table, version) {
+    return this.db.exec("UPDATE _lakesync_meta SET schema_version = ? WHERE table_name = ?", [
+      version,
+      table
+    ]);
+  }
+};
+
 // ../client/src/sync/transport-local.ts
 var LocalTransport = class {
   constructor(gateway) {
@@ -2037,6 +2074,7 @@ export {
   SyncTracker,
   WebSocketTransport,
   applyRemoteDeltas,
+  createClient,
   deleteSnapshot,
   getSchema,
   loadSnapshot,