or3-provider-sqlite 0.0.1 → 0.0.3

package/dist/runtime/server/sync/sqlite-sync-gateway-adapter.js

@@ -1,20 +1,138 @@
+import { canRunSyncHistoryGc } from "./history-gc-policy.js";
 import { createError } from "h3";
 import { randomUUID } from "node:crypto";
 import { getSqliteDb, getRawDb } from "../db/kysely.js";
 import { SYNCED_TABLE_MAP, ALLOWED_SYNC_TABLES } from "../db/schema.js";
+import { emitWebhookSystemHook } from "~~/server/utils/webhooks/runtime";
 const DEFAULT_PULL_LIMIT = 100;
 const MAX_PULL_LIMIT = 1e3;
+const MAX_SNAPSHOT_PAGE_SIZE = 1e3;
+const DEFAULT_CANONICAL_STORAGE_PAGE_SIZE = 100;
+const MAX_CANONICAL_STORAGE_PAGE_SIZE = 500;
+const SNAPSHOT_TTL_SECONDS = 60 * 60;
 const SESSION_CONTEXT_KEY_PREFIX = "__or3_session_context_";
+const MIN_SYNC_RETENTION_SECONDS = 60 * 60;
+const MAX_SYNC_RETENTION_SECONDS = 365 * 24 * 60 * 60;
 function uid() {
   return randomUUID();
 }
 function nowEpoch() {
   return Math.floor(Date.now() / 1e3);
 }
+function stableJson(value) {
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).sort().map(
+    (key) => `${JSON.stringify(key)}:${stableJson(record[key])}`
+  ).join(",")}}`;
+}
+function operationFingerprint(op) {
+  return stableJson({
+    tableName: op.tableName,
+    operation: op.operation,
+    pk: op.pk,
+    payload: op.payload,
+    clock: op.stamp.clock,
+    hlc: op.stamp.hlc,
+    deviceId: op.stamp.deviceId
+  });
+}
+function validatePushOperation(workspaceId, op) {
+  if (!ALLOWED_SYNC_TABLES.includes(op.tableName)) {
+    return `Invalid table: ${op.tableName}`;
+  }
+  if (op.payload !== void 0 && (typeof op.payload !== "object" || op.payload === null || Array.isArray(op.payload))) {
+    return `Invalid payload for ${op.tableName}: payload must be an object`;
+  }
+  const payload = op.payload;
+  if (!payload) return void 0;
+  try {
+    JSON.stringify(payload);
+  } catch {
+    return `Invalid payload for ${op.tableName}: payload is not serializable`;
+  }
+  if ("_id" in payload) return `Invalid payload for ${op.tableName}: '_id' is immutable`;
+  if ("workspace_id" in payload && payload.workspace_id !== workspaceId) {
+    return `Invalid payload for ${op.tableName}: 'workspace_id' is immutable`;
+  }
+  const pkField = op.tableName === "file_meta" ? "hash" : "id";
+  if (pkField in payload && payload[pkField] !== op.pk) {
+    return `Invalid payload for ${op.tableName}: '${pkField}' must match operation pk`;
+  }
+  return void 0;
+}
+function normalizeStorageHash(value) {
+  return value.replace(/^sha256:/i, "").replace(/^md5:/i, "").trim().toLowerCase();
+}
+function resolveCanonicalStorageLimit(limit) {
+  if (typeof limit !== "number" || !Number.isFinite(limit)) {
+    return DEFAULT_CANONICAL_STORAGE_PAGE_SIZE;
+  }
+  return Math.max(1, Math.min(Math.floor(limit), MAX_CANONICAL_STORAGE_PAGE_SIZE));
+}
+function encodeCanonicalStorageCursor(cursor) {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeCanonicalStorageCursor(input, kind, hash) {
+  if (!input) return [];
+  try {
+    if (input.length > 2048) throw new Error("oversized");
+    const parsed = JSON.parse(Buffer.from(input, "base64url").toString("utf8"));
+    if (parsed.version !== 1 || parsed.kind !== kind || parsed.hash !== hash || !Array.isArray(parsed.key) || !parsed.key.every((part) => typeof part === "string")) {
+      throw new Error("mismatch");
+    }
+    return parsed.key;
+  } catch {
+    throw createError({ statusCode: 400, statusMessage: "Invalid canonical storage cursor" });
+  }
+}
 function resolvePullLimit(limit) {
   if (typeof limit !== "number" || !Number.isFinite(limit)) return DEFAULT_PULL_LIMIT;
   return Math.max(1, Math.min(Math.floor(limit), MAX_PULL_LIMIT));
 }
+function resolveSnapshotPageSize(pageSize) {
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > MAX_SNAPSHOT_PAGE_SIZE) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: `pageSize must be an integer between 1 and ${MAX_SNAPSHOT_PAGE_SIZE}`
+    });
+  }
+  return pageSize;
+}
+function normalizeSnapshotTables(tables) {
+  const requested = tables?.length ? [...new Set(tables)] : [...ALLOWED_SYNC_TABLES];
+  for (const tableName of requested) {
+    if (!ALLOWED_SYNC_TABLES.includes(tableName)) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `Invalid snapshot table: ${tableName}`
+      });
+    }
+  }
+  return requested.sort();
+}
+function encodeSnapshotPageToken(token) {
+  return Buffer.from(JSON.stringify(token), "utf8").toString("base64url");
+}
+function decodeSnapshotPageToken(value) {
+  try {
+    const parsed = JSON.parse(
+      Buffer.from(value, "base64url").toString("utf8")
+    );
+    const after = parsed.after;
+    if (parsed.version !== 1 || typeof parsed.snapshotId !== "string" || !parsed.snapshotId || !after || typeof after.tableName !== "string" || typeof after.pk !== "string" || after.kind !== "row" && after.kind !== "tombstone") {
+      throw new Error("Invalid token payload");
+    }
+    return parsed;
+  } catch {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Invalid snapshot page token"
+    });
+  }
+}
 async function assertWorkspaceScopeAuthorized(event, workspaceId) {
   if (!workspaceId.trim()) {
     throw createError({
@@ -41,6 +159,126 @@ async function assertWorkspaceScopeAuthorized(event, workspaceId) {
     });
   }
 }
+function resolveSessionUserId(event) {
+  const context = event.context;
+  if (!context || typeof context !== "object") {
+    return void 0;
+  }
+  for (const [key, value] of Object.entries(context)) {
+    if (!key.startsWith(SESSION_CONTEXT_KEY_PREFIX)) continue;
+    const userId = value.user?.id;
+    if (typeof userId === "string" && userId.trim().length > 0) {
+      return userId;
+    }
+  }
+  return void 0;
+}
+function toWebhookEntityPayload(input) {
+  const base = input.op.payload && typeof input.op.payload === "object" ? { ...input.op.payload } : {};
+  if (typeof base.id !== "string" || base.id.length === 0) {
+    base.id = input.op.pk;
+  }
+  if (typeof base.workspace_id !== "string" || base.workspace_id.length === 0) {
+    base.workspace_id = input.workspaceId;
+  }
+  if (input.userId && (typeof base.user_id !== "string" || base.user_id.length === 0)) {
+    base.user_id = input.userId;
+  }
+  if (input.deleted) {
+    base.deleted = true;
+  }
+  if (typeof base.updated_at !== "number") {
+    base.updated_at = input.now;
+  }
+  return base;
+}
+function resolveHookEmission(input) {
+  if (!input.applied) {
+    return null;
+  }
+  const { op } = input;
+  if (op.tableName === "threads") {
+    if (op.operation === "delete") {
+      return {
+        hookName: "db.threads.delete:action:soft:after",
+        payload: toWebhookEntityPayload({
+          op,
+          workspaceId: input.workspaceId,
+          now: input.now,
+          userId: input.userId,
+          deleted: true
+        })
+      };
+    }
+    return {
+      hookName: input.wasExisting ? "db.threads.update:action:after" : "db.threads.create:action:after",
+      payload: toWebhookEntityPayload({
+        op,
+        workspaceId: input.workspaceId,
+        now: input.now,
+        userId: input.userId
+      })
+    };
+  }
+  if (op.tableName === "messages") {
+    if (op.operation === "delete") {
+      return {
+        hookName: "db.messages.delete:action:soft:after",
+        payload: toWebhookEntityPayload({
+          op,
+          workspaceId: input.workspaceId,
+          now: input.now,
+          userId: input.userId,
+          deleted: true
+        })
+      };
+    }
+    return {
+      hookName: input.wasExisting ? "db.messages.update:action:after" : "db.messages.create:action:after",
+      payload: toWebhookEntityPayload({
+        op,
+        workspaceId: input.workspaceId,
+        now: input.now,
+        userId: input.userId
+      })
+    };
+  }
+  if (op.tableName === "documents" || op.tableName === "posts") {
+    if (op.operation === "delete") {
+      return {
+        hookName: "db.documents.delete:action:soft:after",
+        payload: toWebhookEntityPayload({
+          op,
+          workspaceId: input.workspaceId,
+          now: input.now,
+          userId: input.userId,
+          deleted: true
+        })
+      };
+    }
+    return {
+      hookName: input.wasExisting ? "db.documents.update:action:after" : "db.documents.create:action:after",
+      payload: toWebhookEntityPayload({
+        op,
+        workspaceId: input.workspaceId,
+        now: input.now,
+        userId: input.userId
+      })
+    };
+  }
+  if (op.tableName === "notifications" && op.operation === "put") {
+    return {
+      hookName: "notify:action:push",
+      payload: toWebhookEntityPayload({
+        op,
+        workspaceId: input.workspaceId,
+        now: input.now,
+        userId: input.userId
+      })
+    };
+  }
+  return null;
+}
 function incomingWinsLww(inClock, inHlc, existingClock, existingHlc) {
   if (inClock > existingClock) return true;
   if (inClock === existingClock && inHlc > existingHlc) return true;
@@ -48,9 +286,270 @@ function incomingWinsLww(inClock, inHlc, existingClock, existingHlc) {
 }
 export class SqliteSyncGatewayAdapter {
   id = "sqlite";
+  capabilities = {
+    snapshotBootstrap: "snapshot-v1",
+    historyRetention: "snapshot-v1"
+  };
   get db() {
     return getSqliteDb();
   }
+  async reserveUploadIntent(event, input) {
+    await assertWorkspaceScopeAuthorized(event, input.workspaceId);
+    if (!input.intentId || !Number.isSafeInteger(input.sizeBytes) || input.sizeBytes < 1 || !Number.isSafeInteger(input.expiresAt) || input.expiresAt <= nowEpoch()) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid upload intent" });
+    }
+    if (input.workspaceQuotaBytes !== void 0 && (!Number.isSafeInteger(input.workspaceQuotaBytes) || input.workspaceQuotaBytes < 1)) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid workspace quota" });
+    }
+    const hash = normalizeStorageHash(input.hash);
+    const raw = getRawDb();
+    raw.transaction(() => {
+      const now = nowEpoch();
+      raw.prepare(`UPDATE upload_intents SET status = 'expired'
+                WHERE workspace_id = ? AND status = 'active' AND expires_at <= ?`).run(input.workspaceId, now);
+      const liveRows = raw.prepare(`SELECT id, data_json FROM s_file_meta
+                WHERE workspace_id = ? AND deleted = 0`).all(input.workspaceId);
+      let usedBytes = 0;
+      let alreadyStored = false;
+      for (const row of liveRows) {
+        const payload = JSON.parse(row.data_json);
+        const size = payload.size_bytes ?? payload.sizeBytes;
+        if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
+          throw createError({ statusCode: 500, statusMessage: "Invalid canonical file size" });
+        }
+        usedBytes += size;
+        if (normalizeStorageHash(row.id) === hash) alreadyStored = true;
+      }
+      const totals = raw.prepare(`SELECT
+                    COALESCE(SUM(reserved_bytes), 0) AS reserved_bytes,
+                    MAX(CASE WHEN hash = ? AND reserved_bytes > 0 THEN 1 ELSE 0 END) AS same_hash
+                FROM upload_intents WHERE workspace_id = ? AND status = 'active' AND expires_at > ?`).get(hash, input.workspaceId, now);
+      const reservedBytes = alreadyStored || totals.same_hash === 1 ? 0 : input.sizeBytes;
+      if (input.workspaceQuotaBytes !== void 0 && usedBytes + totals.reserved_bytes + reservedBytes > input.workspaceQuotaBytes) {
+        throw createError({ statusCode: 413, statusMessage: "Workspace storage quota exceeded" });
+      }
+      raw.prepare(`INSERT INTO upload_intents (
+                    id, workspace_id, hash, mime_type, size_bytes, reserved_bytes,
+                    expires_at, status, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, 'active', ?)`).run(
+        input.intentId,
+        input.workspaceId,
+        hash,
+        input.mimeType,
+        input.sizeBytes,
+        reservedBytes,
+        input.expiresAt,
+        now
+      );
+    })();
+  }
+  async consumeUploadIntent(event, input) {
+    await assertWorkspaceScopeAuthorized(event, input.workspaceId);
+    const raw = getRawDb();
+    const result = raw.prepare(`UPDATE upload_intents
+            SET status = 'consumed', storage_id = ?, consumed_at = ?
+            WHERE id = ? AND workspace_id = ? AND status = 'active' AND expires_at > ?
+              AND hash = ? AND mime_type = ? AND size_bytes = ?`).run(
+      input.storageId,
+      nowEpoch(),
+      input.intentId,
+      input.workspaceId,
+      nowEpoch(),
+      normalizeStorageHash(input.hash),
+      input.mimeType,
+      input.sizeBytes
+    );
+    if (result.changes !== 1) {
+      throw createError({ statusCode: 409, statusMessage: "Upload intent expired, mismatched, or already consumed" });
+    }
+  }
+  async cancelUploadIntent(event, input) {
+    await assertWorkspaceScopeAuthorized(event, input.workspaceId);
+    const result = getRawDb().prepare(`UPDATE upload_intents
+            SET status = 'cancelled', cancelled_at = ?
+            WHERE id = ? AND workspace_id = ? AND status = 'active'`).run(nowEpoch(), input.intentId, input.workspaceId);
+    if (result.changes !== 1) {
+      throw createError({ statusCode: 409, statusMessage: "Upload intent is not active" });
+    }
+  }
+  async queryCanonicalStorage(event, input) {
+    const workspaceId = input.scope.workspaceId;
+    await assertWorkspaceScopeAuthorized(event, workspaceId);
+    const limit = resolveCanonicalStorageLimit(input.limit);
+    const hash = input.hash === void 0 ? void 0 : normalizeStorageHash(input.hash);
+    if (input.hash !== void 0 && !hash) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid storage hash" });
+    }
+    const after = decodeCanonicalStorageCursor(input.cursor, input.kind, hash);
+    const raw = getRawDb();
+    if (input.kind === "active_reservations") {
+      if (after.length > 1) {
+        throw createError({ statusCode: 400, statusMessage: "Invalid canonical storage cursor" });
+      }
+      const now = input.now ?? nowEpoch();
+      const rows2 = raw.prepare(`SELECT id, hash, reserved_bytes, expires_at
+                FROM upload_intents
+                WHERE workspace_id = ? AND status = 'active' AND expires_at > ?
+                  AND id > ? AND reserved_bytes > 0 AND (? IS NULL OR hash = ?)
+                ORDER BY id ASC LIMIT ?`).all(workspaceId, now, after[0] ?? "", hash ?? null, hash ?? null, limit + 1);
+      const hasMore2 = rows2.length > limit;
+      const page2 = hasMore2 ? rows2.slice(0, limit) : rows2;
+      const last2 = page2[page2.length - 1];
+      return {
+        items: page2.map((row) => ({
+          kind: "reservation",
+          reservationId: row.id,
+          hash: row.hash,
+          sizeBytes: row.reserved_bytes,
+          expiresAt: row.expires_at
+        })),
+        hasMore: hasMore2,
+        ...hasMore2 && last2 ? { nextCursor: encodeCanonicalStorageCursor({
+          version: 1,
+          kind: input.kind,
+          hash,
+          key: [last2.id]
+        }) } : {}
+      };
+    }
+    if (input.kind === "live_metadata") {
+      if (after.length > 1) {
+        throw createError({ statusCode: 400, statusMessage: "Invalid canonical storage cursor" });
+      }
+      const rows2 = raw.prepare(`
+                SELECT id, data_json, updated_at
+                FROM s_file_meta
+                WHERE workspace_id = ?
+                  AND deleted = 0
+                  AND id > ?
+                  AND (? IS NULL OR lower(
+                    CASE
+                      WHEN instr(trim(id), ':') > 0
+                      THEN substr(trim(id), instr(trim(id), ':') + 1)
+                      ELSE trim(id)
+                    END
+                  ) = ?)
+                ORDER BY id ASC
+                LIMIT ?
+            `).all(workspaceId, after[0] ?? "", hash ?? null, hash ?? null, limit + 1);
+      const hasMore2 = rows2.length > limit;
+      const page2 = hasMore2 ? rows2.slice(0, limit) : rows2;
+      const items = page2.map((row) => {
+        let payload;
+        try {
+          payload = JSON.parse(row.data_json);
+        } catch {
+          throw createError({ statusCode: 500, statusMessage: "Invalid canonical file metadata" });
+        }
+        const size = payload.size_bytes ?? payload.sizeBytes;
+        if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
+          throw createError({ statusCode: 500, statusMessage: "Invalid canonical file size" });
+        }
+        const storageId = payload.storage_id ?? payload.storageId;
+        return {
+          kind: "metadata",
+          hash: normalizeStorageHash(row.id),
+          sizeBytes: size,
+          ...typeof storageId === "string" && storageId ? { storageId } : {},
+          updatedAt: row.updated_at
+        };
+      });
+      const last2 = page2[page2.length - 1];
+      return {
+        items,
+        hasMore: hasMore2,
+        ...hasMore2 && last2 ? {
+          nextCursor: encodeCanonicalStorageCursor({
+            version: 1,
+            kind: input.kind,
+            hash,
+            key: [last2.id]
+          })
+        } : {}
+      };
+    }
+    if (after.length !== 0 && after.length !== 3) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid canonical storage cursor" });
+    }
+    const [afterTable = "", afterId = "", afterHash = ""] = after;
+    const rows = raw.prepare(`
+            WITH reference_edges(source_table, source_id, raw_hash) AS (
+                SELECT 'messages', row.id, CAST(edge.value AS TEXT)
+                FROM s_messages AS row
+                JOIN json_each(
+                    CASE
+                      WHEN json_valid(json_extract(row.data_json, '$.file_hashes'))
+                      THEN json_extract(row.data_json, '$.file_hashes')
+                      ELSE '[]'
+                    END
+                ) AS edge
+                WHERE row.workspace_id = ? AND row.deleted = 0 AND edge.type = 'text'
+                UNION ALL
+                SELECT 'posts', row.id, CAST(edge.value AS TEXT)
+                FROM s_posts AS row
+                JOIN json_each(
+                    CASE
+                      WHEN json_valid(json_extract(row.data_json, '$.file_hashes'))
+                      THEN json_extract(row.data_json, '$.file_hashes')
+                      ELSE '[]'
+                    END
+                ) AS edge
+                WHERE row.workspace_id = ? AND row.deleted = 0 AND edge.type = 'text'
+            ), normalized_edges AS (
+                SELECT source_table, source_id, raw_hash, lower(
+                    CASE
+                      WHEN instr(trim(raw_hash), ':') > 0
+                      THEN substr(trim(raw_hash), instr(trim(raw_hash), ':') + 1)
+                      ELSE trim(raw_hash)
+                    END
+                ) AS normalized_hash
+                FROM reference_edges
+            )
+            SELECT source_table, source_id, raw_hash, normalized_hash
+            FROM normalized_edges
+            WHERE normalized_hash <> ''
+              AND (? IS NULL OR normalized_hash = ?)
+              AND (
+                source_table > ? OR
+                (source_table = ? AND source_id > ?) OR
+                (source_table = ? AND source_id = ? AND raw_hash > ?)
+              )
+            ORDER BY source_table ASC, source_id ASC, raw_hash ASC
+            LIMIT ?
+        `).all(
+      workspaceId,
+      workspaceId,
+      hash ?? null,
+      hash ?? null,
+      afterTable,
+      afterTable,
+      afterId,
+      afterTable,
+      afterId,
+      afterHash,
+      limit + 1
+    );
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const last = page[page.length - 1];
+    return {
+      items: page.map((row) => ({
+        kind: "reference",
+        hash: row.normalized_hash,
+        sourceTable: row.source_table,
+        sourceId: row.source_id
+      })),
+      hasMore,
+      ...hasMore && last ? {
+        nextCursor: encodeCanonicalStorageCursor({
+          version: 1,
+          kind: input.kind,
+          hash,
+          key: [last.source_table, last.source_id, last.raw_hash]
+        })
+      } : {}
+    };
+  }
   async push(event, input) {
     const { scope, ops } = input;
     const workspaceId = scope.workspaceId;
@@ -58,25 +557,49 @@ export class SqliteSyncGatewayAdapter {
     if (!ops.length) {
       return { results: [], serverVersion: 0 };
     }
-    for (const op of ops) {
-      if (!ALLOWED_SYNC_TABLES.includes(op.tableName)) {
-        return {
-          results: ops.map((o) => ({
-            opId: o.stamp.opId,
+    const resultSlots = new Array(ops.length);
+    const groups = /* @__PURE__ */ new Map();
+    ops.forEach((op, index) => {
+      const fingerprint = operationFingerprint(op);
+      const group = groups.get(op.stamp.opId);
+      if (!group) {
+        groups.set(op.stamp.opId, {
+          op,
+          fingerprint,
+          indices: [index],
+          conflicting: false
+        });
+        return;
+      }
+      group.indices.push(index);
+      if (group.fingerprint !== fingerprint) group.conflicting = true;
+    });
+    const uniqueOps = [];
+    const indicesByOpId = /* @__PURE__ */ new Map();
+    for (const group of groups.values()) {
+      const error = group.conflicting ? `Conflicting operations reuse op_id ${group.op.stamp.opId}` : validatePushOperation(workspaceId, group.op);
+      if (error) {
+        for (const index of group.indices) {
+          resultSlots[index] = {
+            opId: group.op.stamp.opId,
             success: false,
-            error: `Invalid table: ${o.tableName}`,
-            errorCode: "VALIDATION_ERROR"
-          })),
-          serverVersion: 0
-        };
+            error,
+            errorCode: group.conflicting ? "CONFLICT" : "VALIDATION_ERROR"
+          };
+        }
+        continue;
       }
+      uniqueOps.push(group.op);
+      indicesByOpId.set(group.op.stamp.opId, group.indices);
     }
     const raw = getRawDb();
     const now = nowEpoch();
-    const results = [];
+    const userId = resolveSessionUserId(event);
+    const uniqueResults = [];
     let finalServerVersion = 0;
+    const hookEmissions = [];
     const runTx = raw.transaction(() => {
-      const opIds = ops.map((o) => o.stamp.opId);
+      const opIds = uniqueOps.map((o) => o.stamp.opId);
       const existingOps = /* @__PURE__ */ new Map();
       const chunkSize = 500;
       for (let i = 0; i < opIds.length; i += chunkSize) {
@@ -90,7 +613,7 @@ export class SqliteSyncGatewayAdapter {
         }
       }
       const uniqueNewOpIds = /* @__PURE__ */ new Set();
-      for (const op of ops) {
+      for (const op of uniqueOps) {
         if (existingOps.has(op.stamp.opId)) continue;
         uniqueNewOpIds.add(op.stamp.opId);
       }
@@ -114,18 +637,18 @@ export class SqliteSyncGatewayAdapter {
             `);
       const assignedVersions = /* @__PURE__ */ new Map();
       let versionOffset = 0;
-      for (const op of ops) {
+      for (const op of uniqueOps) {
         if (existingOps.has(op.stamp.opId)) continue;
         if (assignedVersions.has(op.stamp.opId)) continue;
         versionOffset++;
         assignedVersions.set(op.stamp.opId, baseVersion + versionOffset);
       }
       const processedNew = /* @__PURE__ */ new Set();
-      for (const op of ops) {
+      for (const op of uniqueOps) {
         const opId = op.stamp.opId;
         const existingSv = existingOps.get(opId);
         if (existingSv !== void 0) {
-          results.push({
+          uniqueResults.push({
             opId,
             success: true,
             serverVersion: existingSv
@@ -137,7 +660,7 @@ export class SqliteSyncGatewayAdapter {
           throw new Error(`Missing server version allocation for op_id ${opId}`);
         }
         if (processedNew.has(opId)) {
-          results.push({
+          uniqueResults.push({
             opId,
             success: true,
             serverVersion
@@ -147,7 +670,7 @@ export class SqliteSyncGatewayAdapter {
         processedNew.add(opId);
         const materializedTable = SYNCED_TABLE_MAP[op.tableName];
         if (!materializedTable) {
-          results.push({
+          uniqueResults.push({
             opId,
             success: false,
             error: `Unknown table: ${op.tableName}`,
@@ -175,10 +698,11 @@ export class SqliteSyncGatewayAdapter {
           const existing = raw.prepare(
             `SELECT clock, hlc FROM ${materializedTable} WHERE id = ? AND workspace_id = ?`
           ).get(pkValue, workspaceId);
+          let applied = false;
           if (!existing) {
             raw.prepare(
-              `INSERT INTO ${materializedTable} (id, workspace_id, data_json, clock, hlc, device_id, deleted, created_at, updated_at)
-                             VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)`
+              `INSERT INTO ${materializedTable} (id, workspace_id, data_json, clock, hlc, device_id, op_id, deleted, created_at, updated_at)
+                             VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?)`
             ).run(
               pkValue,
               workspaceId,
@@ -186,9 +710,11 @@ export class SqliteSyncGatewayAdapter {
               op.stamp.clock,
               op.stamp.hlc,
               op.stamp.deviceId,
+              opId,
               now,
               now
             );
+            applied = true;
           } else if (incomingWinsLww(
             op.stamp.clock,
             op.stamp.hlc,
@@ -197,35 +723,51 @@ export class SqliteSyncGatewayAdapter {
           )) {
             raw.prepare(
               `UPDATE ${materializedTable}
-                             SET data_json = ?, clock = ?, hlc = ?, device_id = ?, deleted = 0, updated_at = ?
+                             SET data_json = ?, clock = ?, hlc = ?, device_id = ?, op_id = ?, deleted = 0, updated_at = ?
                              WHERE id = ? AND workspace_id = ?`
             ).run(
               payloadJson ?? "{}",
               op.stamp.clock,
               op.stamp.hlc,
               op.stamp.deviceId,
+              opId,
               now,
               pkValue,
               workspaceId
             );
+            applied = true;
+          }
+          const emission = resolveHookEmission({
+            op,
+            workspaceId,
+            now,
+            userId,
+            wasExisting: Boolean(existing),
+            applied
+          });
+          if (emission) {
+            hookEmissions.push(emission);
           }
         } else if (op.operation === "delete") {
           const existing = raw.prepare(
             `SELECT clock, hlc FROM ${materializedTable} WHERE id = ? AND workspace_id = ?`
           ).get(pkValue, workspaceId);
+          let applied = false;
           if (!existing) {
             raw.prepare(
-              `INSERT INTO ${materializedTable} (id, workspace_id, data_json, clock, hlc, device_id, deleted, created_at, updated_at)
-                             VALUES (?, ?, '{}', ?, ?, ?, 1, ?, ?)`
+              `INSERT INTO ${materializedTable} (id, workspace_id, data_json, clock, hlc, device_id, op_id, deleted, created_at, updated_at)
+                             VALUES (?, ?, '{}', ?, ?, ?, ?, 1, ?, ?)`
             ).run(
               pkValue,
               workspaceId,
               op.stamp.clock,
               op.stamp.hlc,
               op.stamp.deviceId,
+              opId,
               now,
               now
             );
+            applied = true;
           } else if (incomingWinsLww(
             op.stamp.clock,
             op.stamp.hlc,
@@ -234,23 +776,27 @@ export class SqliteSyncGatewayAdapter {
           )) {
             raw.prepare(
               `UPDATE ${materializedTable}
-                             SET deleted = 1, clock = ?, hlc = ?, device_id = ?, updated_at = ?
+                             SET deleted = 1, clock = ?, hlc = ?, device_id = ?, op_id = ?, updated_at = ?
                              WHERE id = ? AND workspace_id = ?`
             ).run(
               op.stamp.clock,
               op.stamp.hlc,
               op.stamp.deviceId,
+              opId,
               now,
               pkValue,
               workspaceId
             );
+            applied = true;
           }
           raw.prepare(
-            `INSERT INTO tombstones (id, workspace_id, table_name, pk, deleted_at, clock, server_version, created_at)
-                         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            `INSERT INTO tombstones (id, workspace_id, table_name, pk, deleted_at, clock, hlc, op_id, server_version, created_at)
+                         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                          ON CONFLICT(workspace_id, table_name, pk) DO UPDATE SET
                            deleted_at = excluded.deleted_at,
                            clock = excluded.clock,
+                           hlc = excluded.hlc,
+                           op_id = excluded.op_id,
                            server_version = excluded.server_version
                          WHERE excluded.clock > tombstones.clock
                             OR (
@@ -264,11 +810,24 @@ export class SqliteSyncGatewayAdapter {
             pkValue,
             now,
             op.stamp.clock,
+            op.stamp.hlc,
+            opId,
             serverVersion,
             now
           );
+          const emission = resolveHookEmission({
+            op,
+            workspaceId,
+            now,
+            userId,
+            wasExisting: Boolean(existing),
+            applied
+          });
+          if (emission) {
+            hookEmissions.push(emission);
+          }
         }
-        results.push({
+        uniqueResults.push({
           opId,
           success: true,
           serverVersion
@@ -276,7 +835,20 @@ export class SqliteSyncGatewayAdapter {
       }
     });
     runTx.immediate();
-    return { results, serverVersion: finalServerVersion };
+    for (const result of uniqueResults) {
+      for (const index of indicesByOpId.get(result.opId) ?? []) {
+        resultSlots[index] = result;
+      }
+    }
+    for (const emission of hookEmissions) {
+      await emitWebhookSystemHook(emission.hookName, emission.payload);
+    }
+    return {
+      results: resultSlots.filter(
+        (result) => Boolean(result)
+      ),
+      serverVersion: finalServerVersion
+    };
   }
   async pull(event, input) {
     const db = this.db;
@@ -307,58 +879,320 @@ export class SqliteSyncGatewayAdapter {
     const nextCursor = lastRow ? lastRow.server_version : cursor;
     return { changes, nextCursor, hasMore };
   }
+  async snapshot(event, input) {
+    const workspaceId = input.scope.workspaceId;
+    await assertWorkspaceScopeAuthorized(event, workspaceId);
+    const pageSize = resolveSnapshotPageSize(input.pageSize);
+    const raw = getRawDb();
+    const now = nowEpoch();
+    let header;
+    let after;
+    if (input.pageToken) {
+      if (input.pageToken.length > 4096) {
+        throw createError({
+          statusCode: 400,
+          statusMessage: "Invalid snapshot page token"
+        });
+      }
+      const token = decodeSnapshotPageToken(input.pageToken);
+      const existing = raw.prepare(`
+                    SELECT id, workspace_id, high_watermark, tables_json, expires_at
+                    FROM sync_snapshots
+                    WHERE id = ?
+                `).get(token.snapshotId);
+      if (!existing || existing.expires_at <= now) {
+        if (existing) {
+          raw.prepare("DELETE FROM sync_snapshots WHERE id = ?").run(existing.id);
+        }
+        throw createError({
+          statusCode: 410,
+          statusMessage: "Snapshot expired or unavailable"
+        });
+      }
+      if (existing.workspace_id !== workspaceId) {
+        throw createError({
+          statusCode: 403,
+          statusMessage: "Forbidden"
+        });
+      }
+      if (input.tables && existing.tables_json !== JSON.stringify(normalizeSnapshotTables(input.tables))) {
+        throw createError({
+          statusCode: 400,
+          statusMessage: "Snapshot table filter cannot change between pages"
+        });
+      }
+      header = existing;
+      after = token.after;
+    } else {
+      const tables = normalizeSnapshotTables(input.tables);
+      const snapshotId = uid();
+      const expiresAt = now + SNAPSHOT_TTL_SECONDS;
+      const capture = raw.transaction(() => {
+        raw.prepare("DELETE FROM sync_snapshots WHERE expires_at <= ?").run(now);
+        const counter = raw.prepare(
+          "SELECT value FROM server_version_counter WHERE workspace_id = ?"
+        ).get(workspaceId);
+        const highWatermark = counter?.value ?? 0;
+        const tablesJson = JSON.stringify(tables);
+        raw.prepare(`
+                    INSERT INTO sync_snapshots (
+                        id, workspace_id, high_watermark, tables_json, created_at, expires_at
+                    ) VALUES (?, ?, ?, ?, ?, ?)
+                `).run(
+          snapshotId,
+          workspaceId,
+          highWatermark,
+          tablesJson,
+          now,
+          expiresAt
+        );
+        for (const tableName of tables) {
+          const materializedTable = SYNCED_TABLE_MAP[tableName];
+          if (!materializedTable) {
+            throw new Error(`Missing materialized table for ${tableName}`);
+          }
+          raw.prepare(`
+                        INSERT INTO sync_snapshot_items (
+                            snapshot_id, table_name, pk, kind, payload_json,
+                            clock, hlc, op_id, server_deleted_at
+                        )
+                        SELECT
+                            ?, ?, id, 'row', data_json,
+                            clock,
+                            CASE WHEN hlc <> '' THEN hlc ELSE 'legacy:0' END,
+                            CASE
+                                WHEN op_id <> '' THEN op_id
+                                ELSE 'legacy:${tableName}:' || id || ':' || clock || ':' || hlc
+                            END,
+                            NULL
+                        FROM "${materializedTable}"
+                        WHERE workspace_id = ? AND deleted = 0
+                    `).run(snapshotId, tableName, workspaceId);
+          raw.prepare(`
+                        INSERT INTO sync_snapshot_items (
+                            snapshot_id, table_name, pk, kind, payload_json,
+                            clock, hlc, op_id, server_deleted_at
+                        )
+                        SELECT
+                            ?, ?, materialized.id, 'tombstone', NULL,
+                            materialized.clock,
+                            CASE
+                                WHEN materialized.hlc <> '' THEN materialized.hlc
+                                ELSE 'legacy:0'
+                            END,
+                            CASE
+                                WHEN materialized.op_id <> '' THEN materialized.op_id
+                                ELSE 'legacy:tombstone:${tableName}:' || materialized.id || ':' || materialized.clock
+                            END,
+                            MAX(0, COALESCE(
+                                (
+                                    SELECT tombstone.deleted_at
+                                    FROM tombstones AS tombstone
+                                    WHERE tombstone.workspace_id = materialized.workspace_id
+                                      AND tombstone.table_name = ?
+                                      AND tombstone.pk = materialized.id
+                                    LIMIT 1
+                                ),
+                                materialized.updated_at,
+                                materialized.created_at,
+                                0
+                            ))
+                        FROM "${materializedTable}" AS materialized
+                        WHERE materialized.workspace_id = ? AND materialized.deleted <> 0
+                    `).run(snapshotId, tableName, tableName, workspaceId);
+          raw.prepare(`
+                        INSERT INTO sync_snapshot_items (
+                            snapshot_id, table_name, pk, kind, payload_json,
+                            clock, hlc, op_id, server_deleted_at
+                        )
+                        SELECT
+                            ?, ?, tombstone.pk, 'tombstone', NULL,
+                            tombstone.clock,
+                            CASE WHEN tombstone.hlc <> '' THEN tombstone.hlc ELSE 'legacy:0' END,
+                            CASE
+                                WHEN tombstone.op_id <> '' THEN tombstone.op_id
+                                ELSE 'legacy:tombstone:${tableName}:' || tombstone.pk || ':' || tombstone.clock
+                            END,
+                            MAX(0, tombstone.deleted_at)
+                        FROM tombstones AS tombstone
+                        WHERE tombstone.workspace_id = ?
+                          AND tombstone.table_name = ?
+                          AND NOT EXISTS (
+                              SELECT 1
+                              FROM "${materializedTable}" AS materialized
+                              WHERE materialized.workspace_id = tombstone.workspace_id
+                                AND materialized.id = tombstone.pk
+                          )
+                    `).run(snapshotId, tableName, workspaceId, tableName);
+        }
+        return {
+          id: snapshotId,
+          workspace_id: workspaceId,
+          high_watermark: highWatermark,
+          tables_json: tablesJson,
+          expires_at: expiresAt
+        };
+      });
+      header = capture.immediate();
+    }
+    const rows = after ? raw.prepare(`
+                SELECT
+                    table_name, pk, kind, payload_json, clock, hlc, op_id,
+                    server_deleted_at
+                FROM sync_snapshot_items
+                WHERE snapshot_id = ?
+                  AND (
+                      table_name > ?
+                      OR (table_name = ? AND pk > ?)
+                      OR (table_name = ? AND pk = ? AND kind > ?)
+                  )
+                ORDER BY table_name ASC, pk ASC, kind ASC
+                LIMIT ?
+            `).all(
+      header.id,
+      after.tableName,
+      after.tableName,
+      after.pk,
+      after.tableName,
+      after.pk,
+      after.kind,
+      pageSize + 1
+    ) : raw.prepare(`
+                SELECT
+                    table_name, pk, kind, payload_json, clock, hlc, op_id,
+                    server_deleted_at
+                FROM sync_snapshot_items
+                WHERE snapshot_id = ?
+                ORDER BY table_name ASC, pk ASC, kind ASC
+                LIMIT ?
+            `).all(header.id, pageSize + 1);
+    const hasMore = rows.length > pageSize;
+    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+    const items = pageRows.map((row) => {
+      const revision = {
+        clock: row.clock,
+        hlc: row.hlc,
+        opId: row.op_id
+      };
+      if (row.kind === "row") {
+        return {
+          kind: "row",
+          tableName: row.table_name,
+          pk: row.pk,
+          payload: JSON.parse(row.payload_json ?? "null"),
+          revision
+        };
+      }
+      return {
+        kind: "tombstone",
+        tableName: row.table_name,
+        pk: row.pk,
+        revision,
+        serverDeletedAt: row.server_deleted_at ?? 0
+      };
+    });
+    const lastRow = pageRows.at(-1);
+    const nextPageToken = hasMore && lastRow ? encodeSnapshotPageToken({
+      version: 1,
+      snapshotId: header.id,
+      after: {
+        tableName: lastRow.table_name,
+        pk: lastRow.pk,
+        kind: lastRow.kind
+      }
+    }) : null;
+    return {
+      workspaceId: header.workspace_id,
+      snapshotId: header.id,
+      highWatermark: header.high_watermark,
+      items,
+      nextPageToken
+    };
+  }
   async updateCursor(event, input) {
     await assertWorkspaceScopeAuthorized(event, input.scope.workspaceId);
     const raw = getRawDb();
     const now = nowEpoch();
-    raw.prepare(
-      `INSERT INTO device_cursors (id, workspace_id, device_id, last_seen_version, updated_at)
-             VALUES (?, ?, ?, ?, ?)
-             ON CONFLICT(workspace_id, device_id) DO UPDATE SET
-               last_seen_version = MAX(device_cursors.last_seen_version, excluded.last_seen_version),
-               updated_at = excluded.updated_at`
-    ).run(uid(), input.scope.workspaceId, input.deviceId, input.version, now);
+    const deviceId = input.deviceId.trim();
+    if (!deviceId || deviceId.length > 256) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid device cursor" });
+    }
+    if (!Number.isSafeInteger(input.version) || input.version < 0) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid device cursor" });
+    }
+    const ownerUserId = resolveSessionUserId(event);
+    if (!ownerUserId) {
+      throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+    }
+    const update = raw.transaction(() => {
+      const counter = raw.prepare(
+        "SELECT value FROM server_version_counter WHERE workspace_id = ?"
+      ).get(input.scope.workspaceId);
+      const maximum = counter?.value ?? 0;
+      if (input.version > maximum) {
+        throw createError({ statusCode: 400, statusMessage: "Cursor exceeds workspace version" });
+      }
+      const existing = raw.prepare(
+        `SELECT owner_user_id, last_seen_version
+                 FROM device_cursors WHERE workspace_id = ? AND device_id = ?`
+      ).get(input.scope.workspaceId, deviceId);
+      if (existing?.owner_user_id && existing.owner_user_id !== ownerUserId) {
+        throw createError({ statusCode: 403, statusMessage: "Device cursor belongs to another user" });
+      }
+      if (existing && input.version < existing.last_seen_version) {
+        throw createError({ statusCode: 409, statusMessage: "Device cursor cannot regress" });
+      }
+      raw.prepare(
+        `INSERT INTO device_cursors (
+                    id, workspace_id, device_id, owner_user_id, last_seen_version, updated_at
+                 ) VALUES (?, ?, ?, ?, ?, ?)
+                 ON CONFLICT(workspace_id, device_id) DO UPDATE SET
+                   owner_user_id = COALESCE(device_cursors.owner_user_id, excluded.owner_user_id),
+                   last_seen_version = excluded.last_seen_version,
+                   updated_at = excluded.updated_at`
+      ).run(uid(), input.scope.workspaceId, deviceId, ownerUserId, input.version, now);
+    });
+    update();
   }
   async gcTombstones(event, input) {
     await assertWorkspaceScopeAuthorized(event, input.scope.workspaceId);
-    const raw = getRawDb();
-    const workspaceId = input.scope.workspaceId;
-    const minCursorRow = raw.prepare(
-      "SELECT MIN(last_seen_version) as min_version FROM device_cursors WHERE workspace_id = ?"
-    ).get(workspaceId);
-    const minCursor = minCursorRow?.min_version ?? 0;
+    if (!Number.isSafeInteger(input.retentionSeconds) || input.retentionSeconds < MIN_SYNC_RETENTION_SECONDS || input.retentionSeconds > MAX_SYNC_RETENTION_SECONDS) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid sync retention window" });
+    }
+    if (!canRunSyncHistoryGc()) return;
     const cutoff = nowEpoch() - input.retentionSeconds;
-    raw.prepare(
-      `DELETE FROM tombstones
-             WHERE workspace_id = ?
-               AND server_version < ?
-               AND created_at < ?`
-    ).run(workspaceId, minCursor, cutoff);
+    const raw = getRawDb();
+    raw.transaction(() => {
+      const cursor = raw.prepare(
+        `SELECT MIN(last_seen_version) AS min_version
+                 FROM device_cursors WHERE workspace_id = ?`
+      ).get(input.scope.workspaceId);
+      if (cursor.min_version === null) return;
+      raw.prepare(
+        `DELETE FROM tombstones
+                 WHERE workspace_id = ? AND created_at < ? AND server_version <= ?`
+      ).run(input.scope.workspaceId, cutoff, cursor.min_version);
+    })();
   }
   async gcChangeLog(event, input) {
     await assertWorkspaceScopeAuthorized(event, input.scope.workspaceId);
-    const raw = getRawDb();
-    const workspaceId = input.scope.workspaceId;
-    const minCursorRow = raw.prepare(
-      "SELECT MIN(last_seen_version) as min_version FROM device_cursors WHERE workspace_id = ?"
-    ).get(workspaceId);
-    const minCursor = minCursorRow?.min_version ?? 0;
+    if (!Number.isSafeInteger(input.retentionSeconds) || input.retentionSeconds < MIN_SYNC_RETENTION_SECONDS || input.retentionSeconds > MAX_SYNC_RETENTION_SECONDS) {
+      throw createError({ statusCode: 400, statusMessage: "Invalid sync retention window" });
+    }
+    if (!canRunSyncHistoryGc()) return;
     const cutoff = nowEpoch() - input.retentionSeconds;
-    const BATCH_SIZE = 1e3;
-    let deleted;
-    do {
-      const result = raw.prepare(
+    const raw = getRawDb();
+    raw.transaction(() => {
+      const cursor = raw.prepare(
+        `SELECT MIN(last_seen_version) AS min_version
+                 FROM device_cursors WHERE workspace_id = ?`
+      ).get(input.scope.workspaceId);
+      if (cursor.min_version === null) return;
+      raw.prepare(
         `DELETE FROM change_log
-                     WHERE rowid IN (
-                       SELECT rowid FROM change_log
-                       WHERE workspace_id = ?
-                         AND server_version < ?
-                         AND created_at < ?
-                       LIMIT ?
-                     )`
-      ).run(workspaceId, minCursor, cutoff, BATCH_SIZE);
-      deleted = result.changes;
-    } while (deleted >= BATCH_SIZE);
+                 WHERE workspace_id = ? AND created_at < ? AND server_version <= ?`
+      ).run(input.scope.workspaceId, cutoff, cursor.min_version);
+    })();
   }
 }
 export function createSqliteSyncGatewayAdapter() {