@delali/sirannon-db 0.1.7 → 0.2.0

package/dist/server/index.mjs

@@ -1,9 +1,15 @@
-import { ChangeTracker, SubscriptionManager, changeMatchesFilter, isBulkLoadDurability } from '../chunk-HHRMRFFR.mjs';
-import '../chunk-CJLYFDP5.mjs';
-import { encodeTaggedValues, decodeTaggedValues, META_TABLE } from '../chunk-GEZUUIKV.mjs';
-import { SirannonError, CDCError, WriteOverloadError } from '../chunk-YPYVQJ4C.mjs';
+import { dumpSchema, tablesInFkOrder, dumpTablePages } from '../chunk-OQVZBEBY.mjs';
+import { ChangeTracker, SubscriptionManager, ensureCdcEpoch, migrationChecksum, needsResync, filteredChange, TransactionGrouper, isBulkLoadDurability, PrimedSubscription } from '../chunk-H6PIVVDN.mjs';
+import { SEQ_STRING_RE, highestMigrationVersion, selectCountTableRows, selectTableExists, selectAppliedMigrations, PkResolver, ensureDeviceCursorsTable, upsertDeviceCursor, selectMaxChangeSeq, canonicaliseForChecksum, selectDeviceCursors, selectMinForeignChangeSeqSql, IDENTIFIER_RE, deleteDeviceCursorsUpdatedBefore } from '../chunk-NVQS53NT.mjs';
+import '../chunk-5NOIGN5Y.mjs';
+import { encodeTaggedValues, MIGRATIONS_TABLE, decodeTaggedValues, encodeWireRowsInPlace, CHANGES_TABLE, DEVICE_CURSORS_TABLE, INTERNAL_TABLE_PREFIX } from '../chunk-D7LAYTKN.mjs';
+import { createOperationSource, operationRegistryDigest, findRead, isRefusal, resolveArguments, findWrite } from '../chunk-TUD5CJ76.mjs';
+import '../chunk-GVCNMPOS.mjs';
+import '../chunk-LFZ37BSX.mjs';
+import { SQLITE_USER_VERSION_MAX } from '../chunk-67M7KAH6.mjs';
+import { SirannonError, WriteOverloadError } from '../chunk-UC3SCMIN.mjs';
 import uWS from 'uWebSockets.js';
-import { randomBytes } from 'crypto';
+import { createHash } from 'crypto';
 
 // src/server/protocol.ts
 function toExecuteResponse(result) {
@@ -124,102 +130,8 @@ function paramsBatchValidationError(value) {
   return null;
 }
 
-// src/server/cors.ts
-function resolveCors(cors) {
-  if (!cors) return null;
-  if (cors === true) {
-    return {
-      origin: "*",
-      methods: "GET, POST, OPTIONS",
-      headers: "Content-Type, Authorization"
-    };
-  }
-  return {
-    origin: cors.origin ?? "*",
-    methods: cors.methods?.join(", ") ?? "GET, POST, OPTIONS",
-    headers: cors.headers?.join(", ") ?? "Content-Type, Authorization"
-  };
-}
-function matchOrigin(cors, requestOrigin) {
-  if (typeof cors.origin === "string") return cors.origin;
-  if (cors.origin.includes(requestOrigin)) return requestOrigin;
-  return null;
-}
-function writeCorsOrigin(res, cors, requestOrigin) {
-  const allowed = matchOrigin(cors, requestOrigin);
-  if (!allowed) return;
-  res.writeHeader("Access-Control-Allow-Origin", allowed);
-  if (allowed !== "*") {
-    res.writeHeader("Vary", "Origin");
-  }
-}
-
-// src/server/health.ts
-function handleLiveness() {
-  const payload = JSON.stringify({ status: "ok" });
-  return (res) => {
-    res.cork(() => {
-      res.writeStatus("200 OK").writeHeader("Content-Type", "application/json").end(payload);
-    });
-  };
-}
-function handleReadiness(sirannon, getReplicationStatus) {
-  return (res) => {
-    const dbs = sirannon.databases();
-    const databases = [];
-    let degraded = false;
-    for (const [id, db] of dbs) {
-      const entry = {
-        id,
-        readOnly: db.readOnly,
-        closed: db.closed
-      };
-      databases.push(entry);
-      if (db.closed) degraded = true;
-    }
-    const body = {
-      status: degraded ? "degraded" : "ok",
-      databases
-    };
-    if (getReplicationStatus) {
-      const replStatus = getReplicationStatus();
-      if (replStatus) {
-        body.replication = {
-          role: replStatus.role,
-          writeForwarding: replStatus.writeForwarding,
-          peers: replStatus.peers,
-          localSeq: replStatus.localSeq.toString(),
-          replicationGroupId: replStatus.replicationGroupId,
-          primaryTerm: replStatus.primaryTerm?.toString(),
-          currentPrimary: replStatus.currentPrimary,
-          coordinator: replStatus.coordinator,
-          controller: replStatus.controller,
-          inSyncReplicas: replStatus.inSyncReplicas,
-          laggingReplicas: replStatus.laggingReplicas,
-          syncState: replStatus.syncState,
-          readAvailability: replStatus.readAvailability,
-          writeAvailability: replStatus.writeAvailability
-        };
-        body.status = readinessStatusForReplication(replStatus, body.status);
-      }
-    }
-    const payload = JSON.stringify(body);
-    res.cork(() => {
-      res.writeStatus("200 OK").writeHeader("Content-Type", "application/json").end(payload);
-    });
-  };
-}
-function readinessStatusForReplication(replication, current) {
-  if (replication.syncState === "syncing" || replication.syncState === "catching-up") return "syncing";
-  if (replication.controller?.state === "active" && replication.writeAvailability === "unavailable")
-    return "failing_over";
-  if (replication.readAvailability === "unavailable" && replication.writeAvailability === "unavailable")
-    return "unavailable";
-  if ((replication.laggingReplicas?.length ?? 0) > 0) return "degraded";
-  return current;
-}
-
 // src/server/http-common.ts
+var SQL_NOT_ACCEPTED_MESSAGE = "This server does not accept SQL statements over the wire; call a registered operation by name";
 function initAbortHandler(res) {
   const listeners = [];
   let aborted = false;
@@ -312,6 +224,8 @@ function sendError(res, status, code, message, details, headers) {
   });
 }
 function httpStatusForError(err) {
+  const explicit = err.status;
+  if (typeof explicit === "number") return explicit;
   switch (err.code) {
     case "DATABASE_NOT_FOUND":
       return 404;
@@ -322,6 +236,7 @@ function httpStatusForError(err) {
     case "TRANSACTION_ERROR":
     case "INVALID_DURABILITY":
     case "INVALID_SYNCHRONOUS":
+    case "BATCH_VALIDATION_ERROR":
       return 400;
     case "STALE_PRIMARY":
     case "PROTOCOL_VERSION_MISMATCH":
@@ -393,6 +308,251 @@ function parseWriteConcern(res, value) {
   return validation;
 }
 
+// src/server/capabilities.ts
+var REQUIRED_DEVICE_SYNC_CAPABILITIES = [
+  "sync.push",
+  "sync.echo-suppression",
+  "sync.ack",
+  "sync.resume",
+  "sync.snapshot",
+  "sync.migrations",
+  "sync.schema-gate",
+  "sync.stream-apply"
+];
+var STAGED_STREAM_CAPABILITY = "sync.staged-stream";
+var SERVER_CAPABILITIES = [...REQUIRED_DEVICE_SYNC_CAPABILITIES, STAGED_STREAM_CAPABILITY];
+var NAMED_QUERY_CAPABILITY = "query.named";
+var SQL_QUERY_CAPABILITY = "query.sql";
+function buildCapabilitiesResponse(options) {
+  const capabilities = [...SERVER_CAPABILITIES];
+  if (options?.registryDigest !== void 0) capabilities.push(NAMED_QUERY_CAPABILITY);
+  if (options?.acceptSql !== false) capabilities.push(SQL_QUERY_CAPABILITY);
+  const response = { capabilities };
+  if (options?.registryDigest !== void 0) response.registry = { digest: options.registryDigest };
+  return response;
+}
+function handleCapabilities(options) {
+  const response = buildCapabilitiesResponse(options);
+  return (res) => {
+    sendJson(res, response);
+  };
+}
+
+// src/server/cors.ts
+function resolveCors(cors) {
+  if (!cors) return null;
+  if (cors === true) {
+    return {
+      origin: "*",
+      methods: "GET, POST, OPTIONS",
+      headers: "Content-Type, Authorization"
+    };
+  }
+  return {
+    origin: cors.origin ?? "*",
+    methods: cors.methods?.join(", ") ?? "GET, POST, OPTIONS",
+    headers: cors.headers?.join(", ") ?? "Content-Type, Authorization"
+  };
+}
+function matchOrigin(cors, requestOrigin) {
+  if (typeof cors.origin === "string") return cors.origin;
+  if (cors.origin.includes(requestOrigin)) return requestOrigin;
+  return null;
+}
+function writeCorsOrigin(res, cors, requestOrigin) {
+  const allowed = matchOrigin(cors, requestOrigin);
+  if (!allowed) return;
+  res.writeHeader("Access-Control-Allow-Origin", allowed);
+  if (allowed !== "*") {
+    res.writeHeader("Vary", "Origin");
+  }
+}
+
+// src/server/health.ts
+function handleLiveness() {
+  const payload = JSON.stringify({ status: "ok" });
+  return (res) => {
+    res.cork(() => {
+      res.writeStatus("200 OK").writeHeader("Content-Type", "application/json").end(payload);
+    });
+  };
+}
+function handleReadiness(sirannon, getReplicationStatus) {
+  return (res) => {
+    const dbs = sirannon.databases();
+    const databases = [];
+    let degraded = false;
+    for (const [id, db] of dbs) {
+      const entry = {
+        id,
+        readOnly: db.readOnly,
+        closed: db.closed
+      };
+      databases.push(entry);
+      if (db.closed) degraded = true;
+    }
+    const body = {
+      status: degraded ? "degraded" : "ok",
+      databases
+    };
+    if (getReplicationStatus) {
+      const replStatus = getReplicationStatus();
+      if (replStatus) {
+        body.replication = {
+          role: replStatus.role,
+          writeForwarding: replStatus.writeForwarding,
+          peers: replStatus.peers,
+          localSeq: replStatus.localSeq.toString(),
+          replicationGroupId: replStatus.replicationGroupId,
+          primaryTerm: replStatus.primaryTerm?.toString(),
+          currentPrimary: replStatus.currentPrimary,
+          coordinator: replStatus.coordinator,
+          controller: replStatus.controller,
+          inSyncReplicas: replStatus.inSyncReplicas,
+          laggingReplicas: replStatus.laggingReplicas,
+          syncState: replStatus.syncState,
+          healthReason: replStatus.health.reason,
+          readAvailability: replStatus.health.canRead ? "available" : "unavailable",
+          writeAvailability: replStatus.health.canWrite ? "available" : "unavailable"
+        };
+        body.status = readinessStatusForReplication(replStatus, body.status);
+      }
+    }
+    const payload = JSON.stringify(body);
+    res.cork(() => {
+      res.writeStatus("200 OK").writeHeader("Content-Type", "application/json").end(payload);
+    });
+  };
+}
+function readinessStatusForReplication(replication, current) {
+  if (replication.health.state !== "healthy") return replication.health.state;
+  return current;
+}
+
+// src/server/sync-protocol.ts
+var MAX_SYNC_BATCH_CHANGES = 1e3;
+var NODE_ID_RE = /^[0-9a-f]{32}$/;
+var TABLE_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var OPERATIONS = /* @__PURE__ */ new Set(["insert", "update", "delete"]);
+function isValidDeviceId(candidate) {
+  return typeof candidate === "string" && NODE_ID_RE.test(candidate);
+}
+function isValidSchemaVersion(candidate) {
+  return typeof candidate === "number" && Number.isSafeInteger(candidate) && candidate >= 0 && candidate <= SQLITE_USER_VERSION_MAX;
+}
+function schemaVersionValidationError(candidate) {
+  if (candidate === void 0) return null;
+  if (!isValidSchemaVersion(candidate)) {
+    return `"schemaVersion" must be an integer from 0 to ${SQLITE_USER_VERSION_MAX}`;
+  }
+  return null;
+}
+function schemaVersionGateRefusal(deviceVersion, serverVersion) {
+  if (deviceVersion < serverVersion) {
+    return {
+      code: "MIGRATION_REQUIRED",
+      message: `Device schema version ${deviceVersion} is behind server version ${serverVersion}; apply the missing migrations before syncing`
+    };
+  }
+  if (deviceVersion > serverVersion) {
+    return {
+      code: "SCHEMA_AHEAD",
+      message: `Device schema version ${deviceVersion} is ahead of server version ${serverVersion}; the server must be migrated before this device can sync`
+    };
+  }
+  return null;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function changeValidationError(change, index) {
+  if (!isPlainObject(change)) return `changes[${index}] must be an object`;
+  if (typeof change.table !== "string" || !TABLE_RE.test(change.table)) {
+    return `changes[${index}].table must be a valid table name`;
+  }
+  if (typeof change.operation !== "string" || !OPERATIONS.has(change.operation)) {
+    return `changes[${index}].operation must be one of insert, update, delete`;
+  }
+  if (typeof change.rowId !== "string" || change.rowId.length === 0) {
+    return `changes[${index}].rowId must be a non-empty string`;
+  }
+  if (!isPlainObject(change.primaryKey)) return `changes[${index}].primaryKey must be an object`;
+  if (typeof change.hlc !== "string" || change.hlc.length === 0) {
+    return `changes[${index}].hlc must be a non-empty string`;
+  }
+  if (typeof change.txId !== "string" || change.txId.length === 0) {
+    return `changes[${index}].txId must be a non-empty string`;
+  }
+  if (!isValidDeviceId(change.nodeId)) return `changes[${index}].nodeId must be a 32-hex node id`;
+  if (change.newData !== null && !isPlainObject(change.newData)) {
+    return `changes[${index}].newData must be an object or null`;
+  }
+  if (change.oldData !== null && !isPlainObject(change.oldData)) {
+    return `changes[${index}].oldData must be an object or null`;
+  }
+  return null;
+}
+function syncBatchValidationError(raw) {
+  if (!isPlainObject(raw)) return 'Field "batch" is required and must be an object';
+  if (!isValidDeviceId(raw.sourceNodeId)) return '"batch.sourceNodeId" must be a 32-hex node id';
+  if (typeof raw.batchId !== "string" || raw.batchId.length === 0 || raw.batchId.length > 128) {
+    return '"batch.batchId" must be a non-empty string of at most 128 characters';
+  }
+  if (typeof raw.fromSeq !== "string" || !SEQ_STRING_RE.test(raw.fromSeq)) {
+    return '"batch.fromSeq" must be a positive integer string';
+  }
+  if (typeof raw.toSeq !== "string" || !SEQ_STRING_RE.test(raw.toSeq)) {
+    return '"batch.toSeq" must be a positive integer string';
+  }
+  if (BigInt(raw.fromSeq) > BigInt(raw.toSeq)) return '"batch.fromSeq" must not exceed "batch.toSeq"';
+  if (!isPlainObject(raw.hlcRange) || typeof raw.hlcRange.min !== "string" || typeof raw.hlcRange.max !== "string") {
+    return '"batch.hlcRange" must carry string "min" and "max" fields';
+  }
+  if (!Array.isArray(raw.changes) || raw.changes.length === 0) {
+    return '"batch.changes" must be a non-empty array';
+  }
+  if (raw.changes.length > MAX_SYNC_BATCH_CHANGES) {
+    return `"batch.changes" must not exceed ${MAX_SYNC_BATCH_CHANGES} changes`;
+  }
+  if (typeof raw.checksum !== "string" || raw.checksum.length === 0) {
+    return '"batch.checksum" must be a non-empty string';
+  }
+  for (let i = 0; i < raw.changes.length; i++) {
+    const changeError = changeValidationError(raw.changes[i], i);
+    if (changeError !== null) return changeError;
+    const change = raw.changes[i];
+    if (change.nodeId !== raw.sourceNodeId) {
+      return `changes[${i}].nodeId must match "batch.sourceNodeId"`;
+    }
+  }
+  return null;
+}
+function decodeSyncBatch(body) {
+  const changes = body.changes.map((change) => ({
+    table: change.table,
+    operation: change.operation,
+    rowId: change.rowId,
+    primaryKey: decodeTaggedValues(change.primaryKey),
+    hlc: change.hlc,
+    txId: change.txId,
+    nodeId: change.nodeId,
+    newData: change.newData === null ? null : decodeTaggedValues(change.newData),
+    oldData: change.oldData === null ? null : decodeTaggedValues(change.oldData)
+  }));
+  return {
+    sourceNodeId: body.sourceNodeId,
+    batchId: body.batchId,
+    fromSeq: BigInt(body.fromSeq),
+    toSeq: BigInt(body.toSeq),
+    hlcRange: { min: body.hlcRange.min, max: body.hlcRange.max },
+    changes,
+    checksum: body.checksum
+  };
+}
+function toChangesResponse(result) {
+  return { applied: result.applied, skipped: result.skipped, conflicts: result.conflicts };
+}
+
 // src/server/wire-rows.ts
 async function queryWireRows(target, sql, params, options) {
   if (target.queryForWire) {
@@ -589,10 +749,76 @@ function handleLoad(sirannon, resolveTarget) {
     }
   };
 }
-function handleClusterStatus(getClusterStatus) {
-  return (res, dbId) => {
-    if (!getClusterStatus) {
-      sendError(res, 404, "NOT_FOUND", "Cluster status is not configured");
+function handleChanges(sirannon, resolveTarget) {
+  return async (res, dbId, rawBody, abort) => {
+    const body = parseBody(res, rawBody);
+    if (!body) return;
+    const batchError = syncBatchValidationError(body.batch);
+    if (batchError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", batchError);
+      return;
+    }
+    const schemaVersionError = schemaVersionValidationError(body.schemaVersion);
+    if (schemaVersionError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", schemaVersionError);
+      return;
+    }
+    const target = await resolveExecutionTarget(res, abort, sirannon, dbId, resolveTarget);
+    if (!target) return;
+    const appliedMigrations = target.appliedMigrations;
+    if (typeof appliedMigrations === "function") {
+      try {
+        const serverVersion = highestMigrationVersion(await appliedMigrations.call(target));
+        const refusal = schemaVersionGateRefusal(body.schemaVersion ?? 0, serverVersion);
+        if (refusal !== null) {
+          if (abort.aborted) return;
+          sendError(res, 409, refusal.code, refusal.message, { serverVersion });
+          return;
+        }
+      } catch (err) {
+        sendCaughtError(res, abort, err);
+        return;
+      }
+    }
+    const applyChanges = target.applyChanges;
+    if (typeof applyChanges !== "function") {
+      sendError(
+        res,
+        501,
+        "SYNC_UNSUPPORTED",
+        "The execution target for this database does not support applying sync changes"
+      );
+      return;
+    }
+    try {
+      const result = await applyChanges.call(target, decodeSyncBatch(body.batch));
+      if (abort.aborted) return;
+      sendJson(res, toChangesResponse(result));
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+    }
+  };
+}
+function sendClusterUnavailable(res, dbId) {
+  sendError(res, 404, "NOT_FOUND", `Cluster status is not available for database '${dbId}'`);
+}
+function handleClusterStatus(getClusterStatus, authorizeClusterStatus) {
+  return async (res, dbId, ctx, abort) => {
+    if (!getClusterStatus || !authorizeClusterStatus) {
+      sendClusterUnavailable(res, dbId);
+      return;
+    }
+    let allowed;
+    try {
+      allowed = await authorizeClusterStatus(ctx);
+    } catch {
+      if (abort.aborted) return;
+      sendError(res, 500, "HOOK_ERROR", "authorizeClusterStatus threw an error");
+      return;
+    }
+    if (abort.aborted) return;
+    if (!allowed) {
+      sendClusterUnavailable(res, dbId);
       return;
     }
     const status = getClusterStatus(dbId);
@@ -615,38 +841,514 @@ function toClusterStatusResponse(status) {
   };
 }
 
-// src/server/request-hook.ts
-function decodeRemoteAddress(res) {
-  return Buffer.from(res.getRemoteAddressAsText()).toString();
-}
-function isRequestDenial(value) {
-  return typeof value === "object" && value !== null && "status" in value;
-}
-async function runOnRequest(res, abort, ctx, hook) {
+// src/server/http-migrations.ts
+function handleMigrationList(sirannon) {
+  return async (res, dbId, rawBody, abort) => {
+    const body = parseBody(res, rawBody);
+    if (!body) return;
+    const afterError = schemaVersionValidationError(body.after);
+    if (afterError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", afterError.replace('"schemaVersion"', '"after"'));
+      return;
+    }
+    const after = body.after ?? 0;
+    let database;
+    try {
+      database = await sirannon.resolve(dbId);
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+      return;
+    }
+    if (abort.aborted) return;
+    if (!database) {
+      sendError(res, 404, "DATABASE_NOT_FOUND", `Database '${dbId}' not found`);
+      return;
+    }
+    try {
+      const applied = await database.appliedMigrations();
+      const registry = new Map((await sirannon.registryMigrations()).map((migration) => [migration.version, migration]));
+      const migrations = applied.map((row) => {
+        const entry = { version: row.version, name: row.name, checksum: row.checksum };
+        if (row.version > after && row.checksum !== null) {
+          const source = registry.get(row.version);
+          if (source !== void 0 && typeof source.up === "string" && migrationChecksum(source.up) === row.checksum) {
+            entry.up = source.up;
+          }
+        }
+        return entry;
+      });
+      if (abort.aborted) return;
+      const response = { serverVersion: highestMigrationVersion(applied), migrations };
+      sendJson(res, response);
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+    }
+  };
+}
+
+// src/server/http-operations.ts
+function parseOperationBody(res, rawBody) {
+  if (rawBody.length === 0) return {};
+  return parseBody(res, rawBody);
+}
+function decodeArguments(res, raw) {
+  if (raw === void 0) return {};
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    sendError(res, 400, "INVALID_REQUEST", 'Field "args" must be an object');
+    return null;
+  }
+  const decoded = decodeBoundParams(raw, "args");
+  if (!decoded.ok) {
+    sendError(res, 400, "INVALID_REQUEST", decoded.message);
+    return null;
+  }
+  return decoded.value ?? {};
+}
+function handleOperationQuery(sirannon, registry, resolveTarget) {
+  return async (res, dbId, name, identity, rawBody, abort) => {
+    const operation = findRead(registry, dbId, name);
+    if (isRefusal(operation)) {
+      sendError(res, operation.status, operation.code, operation.message);
+      return;
+    }
+    const body = parseOperationBody(res, rawBody);
+    if (!body) return;
+    const readConcern = parseReadConcern(res, body.readConcern);
+    if (!readConcern.ok) return;
+    const supplied = decodeArguments(res, body.args);
+    if (!supplied) return;
+    const args = resolveArguments(operation, supplied, identity);
+    if (!args.ok) {
+      sendError(res, args.refusal.status, args.refusal.code, args.refusal.message);
+      return;
+    }
+    let statement;
+    try {
+      statement = operation.statement(args.value);
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+      return;
+    }
+    const target = await resolveExecutionTarget(res, abort, sirannon, dbId, resolveTarget);
+    if (!target) return;
+    try {
+      const rows = await queryWireRows(
+        target,
+        statement.sql,
+        statement.params,
+        readConcern.value ? { readConcern: readConcern.value } : void 0
+      );
+      if (abort.aborted) return;
+      sendJson(res, { rows });
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+    }
+  };
+}
+function handleOperationExecute(sirannon, registry, resolveTarget) {
+  return async (res, dbId, name, identity, rawBody, abort) => {
+    const operation = findWrite(registry, dbId, name);
+    if (isRefusal(operation)) {
+      sendError(res, operation.status, operation.code, operation.message);
+      return;
+    }
+    const body = parseOperationBody(res, rawBody);
+    if (!body) return;
+    const writeConcern = parseWriteConcern(res, body.writeConcern);
+    if (!writeConcern.ok) return;
+    const supplied = decodeArguments(res, body.args);
+    if (!supplied) return;
+    const args = resolveArguments(operation, supplied, identity);
+    if (!args.ok) {
+      sendError(res, args.refusal.status, args.refusal.code, args.refusal.message);
+      return;
+    }
+    let statements;
+    try {
+      const produced = operation.statements(args.value);
+      statements = Array.isArray(produced) ? produced : [produced];
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+      return;
+    }
+    if (statements.length === 0) {
+      sendError(res, 500, "INTERNAL_ERROR", `Operation '${name}' produced no statements`);
+      return;
+    }
+    const target = await resolveExecutionTarget(res, abort, sirannon, dbId, resolveTarget);
+    if (!target) return;
+    const txOptions = writeConcern.value ? { writeConcern: writeConcern.value } : void 0;
+    try {
+      const results = target.executeTransaction ? await target.executeTransaction(statements, txOptions) : await target.transaction(async (tx) => {
+        const txResults = [];
+        for (const statement of statements) {
+          txResults.push(await tx.execute(statement.sql, statement.params));
+        }
+        return txResults;
+      }, txOptions);
+      if (abort.aborted) return;
+      sendJson(res, { results: results.map(toExecuteResponse) });
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+    }
+  };
+}
+
+// src/server/snapshot-protocol.ts
+var SNAPSHOT_MAX_PAGE_ROWS = 1e3;
+var SNAPSHOT_DEFAULT_PAGE_ROWS = 500;
+var SNAPSHOT_PAGE_BYTE_CAP = 8 * 1024 * 1024;
+function isDumpableTableName(candidate) {
+  return typeof candidate === "string" && IDENTIFIER_RE.test(candidate) && !candidate.startsWith(INTERNAL_TABLE_PREFIX) && !candidate.toLowerCase().startsWith("sqlite_");
+}
+function snapshotPageValidationError(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return "Request body must be an object";
+  }
+  const record = raw;
+  if (!isDumpableTableName(record.table)) {
+    return 'Field "table" is required and must be a dumpable table name';
+  }
+  if (record.afterKey !== void 0) {
+    if (!Array.isArray(record.afterKey) || record.afterKey.length === 0 || record.afterKey.length > 16) {
+      return '"afterKey" must be a non-empty array of at most 16 key values';
+    }
+  }
+  if (record.limit !== void 0) {
+    if (typeof record.limit !== "number" || !Number.isInteger(record.limit) || record.limit < 1) {
+      return '"limit" must be a positive integer';
+    }
+    if (record.limit > SNAPSHOT_MAX_PAGE_ROWS) {
+      return `"limit" must not exceed ${SNAPSHOT_MAX_PAGE_ROWS}`;
+    }
+  }
+  return null;
+}
+
+// src/server/http-snapshot.ts
+async function resolveSnapshotDatabase(res, abort, sirannon, dbId) {
+  let database;
   try {
-    const result = await hook(ctx);
-    if (isRequestDenial(result)) {
-      if (abort.claim()) sendError(res, result.status, result.code, result.message);
-      return false;
+    database = await sirannon.resolve(dbId);
+  } catch (err) {
+    if (abort.aborted) return null;
+    sendCaughtError(res, abort, err);
+    return null;
+  }
+  if (abort.aborted) return null;
+  if (!database) {
+    sendError(res, 404, "DATABASE_NOT_FOUND", `Database '${dbId}' not found`);
+    return null;
+  }
+  if (database.path === ":memory:") {
+    sendError(res, 400, "SNAPSHOT_UNSUPPORTED", "Snapshots require file-based databases");
+    return null;
+  }
+  return database;
+}
+async function changeLogStartSeq(conn) {
+  if (!await selectTableExists(conn, CHANGES_TABLE)) return 0n;
+  return selectMaxChangeSeq(conn);
+}
+function handleSnapshotManifest(sirannon) {
+  return async (res, dbId, _rawBody, abort) => {
+    const database = await resolveSnapshotDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
+    try {
+      let epoch = "";
+      await database.runCdcMaintenance(async (writer) => {
+        epoch = await ensureCdcEpoch(writer);
+      });
+      const conn = await sirannon.driver.open(database.path, { walMode: true });
+      try {
+        const startSeq = await changeLogStartSeq(conn);
+        const schema = await dumpSchema(conn);
+        const tableNames = await tablesInFkOrder(conn);
+        const tables = [];
+        for (const name of tableNames) {
+          tables.push({ name, rowCount: await selectCountTableRows(conn, name) });
+        }
+        const migrations = await selectTableExists(conn, MIGRATIONS_TABLE) ? await selectAppliedMigrations(conn) : [];
+        if (abort.aborted) return;
+        const manifest = {
+          databaseId: dbId,
+          startSeq: startSeq.toString(),
+          epoch,
+          schema,
+          tables,
+          migrations
+        };
+        sendJson(res, manifest);
+      } finally {
+        await conn.close();
+      }
+    } catch (err) {
+      sendCaughtError(res, abort, err);
     }
-    return true;
+  };
+}
+function trimPageToByteCap(rows, checksum, isLast) {
+  let kept = rows;
+  let keptChecksum = checksum;
+  let keptIsLast = isLast;
+  let canonical = canonicaliseForChecksum(kept);
+  while (canonical.length > SNAPSHOT_PAGE_BYTE_CAP && kept.length > 1) {
+    kept = kept.slice(0, Math.ceil(kept.length / 2));
+    canonical = canonicaliseForChecksum(kept);
+    keptChecksum = createHash("sha256").update(canonical).digest("hex");
+    keptIsLast = false;
+  }
+  return { rows: kept, checksum: keptChecksum, isLast: keptIsLast };
+}
+function handleSnapshotPage(sirannon) {
+  return async (res, dbId, rawBody, abort) => {
+    const body = parseBody(res, rawBody);
+    if (!body) return;
+    const validationError = snapshotPageValidationError(body);
+    if (validationError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", validationError);
+      return;
+    }
+    const database = await resolveSnapshotDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
+    try {
+      const conn = await sirannon.driver.open(database.path, { walMode: true });
+      try {
+        if (!await selectTableExists(conn, body.table)) {
+          sendError(res, 404, "TABLE_NOT_FOUND", `Table '${body.table}' not found`);
+          return;
+        }
+        const pkResolver = new PkResolver(conn);
+        const pkColumns = await pkResolver.forTableOnConnection(conn, body.table);
+        let startAfter;
+        if (body.afterKey !== void 0) {
+          if (body.afterKey.length !== pkColumns.length) {
+            sendError(
+              res,
+              400,
+              "INVALID_REQUEST",
+              `"afterKey" must carry ${pkColumns.length} value(s) for table '${body.table}'`
+            );
+            return;
+          }
+          startAfter = decodeTaggedValues(body.afterKey);
+        }
+        const limit = body.limit ?? SNAPSHOT_DEFAULT_PAGE_ROWS;
+        const pages = dumpTablePages(conn, pkResolver, body.table, limit, startAfter);
+        const first = await pages.next();
+        await pages.return(void 0);
+        if (abort.aborted) return;
+        if (first.done || first.value === void 0) {
+          const empty = { rows: [], checksum: "", done: true, nextKey: null };
+          sendJson(res, empty);
+          return;
+        }
+        const page = trimPageToByteCap(first.value.rows, first.value.checksum, first.value.isLast);
+        let nextKey = null;
+        if (!page.isLast && page.rows.length > 0) {
+          const lastRow = page.rows[page.rows.length - 1];
+          nextKey = encodeTaggedValues(pkColumns.map((column) => lastRow[column]));
+        }
+        const response = {
+          rows: encodeWireRowsInPlace(page.rows),
+          checksum: page.checksum,
+          done: page.isLast,
+          nextKey
+        };
+        sendJson(res, response);
+      } finally {
+        await conn.close();
+      }
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+    }
+  };
+}
+
+// src/core/ws-handshake.ts
+var SIRANNON_WS_SUBPROTOCOL = "sirannon.v1";
+var WS_CLOSE_UNAUTHENTICATED = 4401;
+var WS_CLOSE_FORBIDDEN = 4403;
+function selectSubprotocol(header) {
+  const offered = header.split(",").map((value) => value.trim()).filter((value) => value.length > 0);
+  if (offered.length === 0) return { ok: true, protocol: "" };
+  if (offered.includes(SIRANNON_WS_SUBPROTOCOL)) return { ok: true, protocol: SIRANNON_WS_SUBPROTOCOL };
+  return { ok: false };
+}
+
+// src/server/request-hook.ts
+function decodeRemoteAddress(res) {
+  return Buffer.from(res.getRemoteAddressAsText()).toString();
+}
+var CLOSE_REASON_MAX_BYTES = 123;
+var RETURNED_REFUSAL_MESSAGE = "The authenticate hook returned a refusal object rather than an identity. A hook refuses a request by throwing a SirannonError; every value it returns becomes the caller identity.";
+function looksLikeRefusal(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.status === "number" && typeof candidate.code === "string" && typeof candidate.message === "string";
+}
+async function invokeAuthenticate(ctx, hook) {
+  try {
+    const identity = await hook(ctx);
+    if (looksLikeRefusal(identity)) return { status: "returned-refusal" };
+    return { status: "identity", identity };
+  } catch (error) {
+    return { status: "threw", error };
+  }
+}
+function sendRefusal(res, abort, outcome) {
+  if (!abort.claim()) return;
+  if (outcome.status === "returned-refusal") {
+    sendError(res, 500, "HOOK_ERROR", RETURNED_REFUSAL_MESSAGE);
+    return;
+  }
+  if (outcome.status === "threw" && outcome.error instanceof SirannonError) {
+    sendCaughtError(res, abort, outcome.error);
+    return;
+  }
+  sendError(res, 500, "HOOK_ERROR", "authenticate hook threw an error");
+}
+function truncateCloseReason(reason) {
+  if (Buffer.byteLength(reason, "utf-8") <= CLOSE_REASON_MAX_BYTES) return reason;
+  let truncated = reason.slice(0, CLOSE_REASON_MAX_BYTES);
+  while (truncated.length > 0 && Buffer.byteLength(truncated, "utf-8") > CLOSE_REASON_MAX_BYTES) {
+    truncated = truncated.slice(0, -1);
+  }
+  return truncated;
+}
+function upgradeRefusalFor(error) {
+  if (!(error instanceof SirannonError)) return void 0;
+  const status = httpStatusForError(error);
+  if (status !== 401 && status !== 403) return void 0;
+  return {
+    code: status === 403 ? WS_CLOSE_FORBIDDEN : WS_CLOSE_UNAUTHENTICATED,
+    reason: truncateCloseReason(`${error.code}: ${error.message}`)
+  };
+}
+async function runAuthenticate(res, abort, ctx, hook) {
+  const outcome = await invokeAuthenticate(ctx, hook);
+  if (outcome.status === "identity") return { ok: true, identity: outcome.identity };
+  sendRefusal(res, abort, outcome);
+  return { ok: false };
+}
+async function authenticateUpgrade(res, abort, ctx, hook) {
+  const outcome = await invokeAuthenticate(ctx, hook);
+  if (outcome.status === "identity") return { ok: true, identity: outcome.identity };
+  if (outcome.status === "threw") {
+    const refusal = upgradeRefusalFor(outcome.error);
+    if (refusal) return { ok: false, refusal };
+  }
+  sendRefusal(res, abort, outcome);
+  return { ok: false, refusal: void 0 };
+}
+
+// src/server/operation-route.ts
+function decodePathSegment(value) {
+  try {
+    return decodeURIComponent(value);
   } catch {
-    if (abort.claim()) sendError(res, 500, "HOOK_ERROR", "onRequest hook threw an error");
-    return false;
+    return null;
   }
 }
-var EPOCH_KEY = "cdc_epoch";
-async function ensureCdcEpoch(conn) {
-  await conn.exec(`CREATE TABLE IF NOT EXISTS "${META_TABLE}" (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
-  const insert = await conn.prepare(`INSERT OR IGNORE INTO "${META_TABLE}" (key, value) VALUES (?, ?)`);
-  await insert.run(EPOCH_KEY, randomBytes(16).toString("hex"));
-  const select = await conn.prepare(`SELECT value FROM "${META_TABLE}" WHERE key = ?`);
-  const row = await select.get(EPOCH_KEY);
-  const value = row?.value;
-  if (typeof value !== "string" || value.length === 0) {
-    throw new CDCError("Failed to read the CDC epoch identifier");
+function wrapOperationRoute(deps, handler) {
+  return (res, req) => {
+    const dbId = req.getParameter(0) ?? "";
+    const rawName = req.getParameter(1) ?? "";
+    const method = req.getMethod();
+    const path = req.getUrl();
+    if (deps.cors) writeCorsOrigin(res, deps.cors, req.getHeader("origin"));
+    const name = decodePathSegment(rawName);
+    if (name === null) {
+      sendError(res, 400, "INVALID_REQUEST", `Operation name '${rawName}' is not valid percent-encoding`);
+      return;
+    }
+    const headers = {};
+    req.forEach((key, value) => {
+      headers[key] = value;
+    });
+    const abort = initAbortHandler(res);
+    const bodyPromise = readBody(res, deps.maxBodyBytes, abort);
+    const ctx = {
+      headers,
+      method,
+      path,
+      databaseId: dbId,
+      remoteAddress: decodeRemoteAddress(res)
+    };
+    const run = async () => {
+      const rawBody = await bodyPromise;
+      let identity;
+      if (deps.authenticateHook) {
+        const authenticated = await runAuthenticate(res, abort, ctx, deps.authenticateHook);
+        if (!authenticated.ok) return;
+        identity = authenticated.identity;
+      }
+      if (!abort.claim()) return;
+      try {
+        await handler(res, dbId, name, identity, rawBody, abort);
+      } catch {
+        if (!abort.aborted) {
+          sendError(res, 500, "INTERNAL_ERROR", "An unexpected error occurred");
+        }
+      }
+    };
+    run().catch(() => {
+    });
+  };
+}
+
+// src/server/device-cursors.ts
+var DEFAULT_DEVICE_CURSOR_RETENTION_MS = 30 * 24 * 36e5;
+async function upsertDeviceAck(conn, deviceId, seq) {
+  await ensureDeviceCursorsTable(conn);
+  await upsertDeviceCursor(conn, deviceId, seq, Date.now() / 1e3);
+}
+function evictStaleDeviceCursors(conn, retentionMs) {
+  return deleteDeviceCursorsUpdatedBefore(conn, Date.now() / 1e3 - retentionMs / 1e3);
+}
+async function effectiveMinDeviceCursor(conn, retentionMs, changesTable = CHANGES_TABLE) {
+  if (!await selectTableExists(conn, DEVICE_CURSORS_TABLE)) return null;
+  await evictStaleDeviceCursors(conn, retentionMs);
+  const cursors = await selectDeviceCursors(conn);
+  if (cursors.length === 0) return null;
+  const nextForeignStmt = await conn.prepare(selectMinForeignChangeSeqSql(changesTable));
+  const maxSeq = await selectMaxChangeSeq(conn, changesTable);
+  let min = null;
+  for (const cursor of cursors) {
+    const acked = cursor.ackedSeq;
+    const foreignRow = await nextForeignStmt.get(acked.toString(), cursor.deviceId);
+    const nextForeign = foreignRow?.seq === null || foreignRow?.seq === void 0 ? null : BigInt(foreignRow.seq);
+    const effective = nextForeign === null ? maxSeq : nextForeign - 1n;
+    if (min === null || effective < min) {
+      min = effective;
+    }
+  }
+  return min;
+}
+
+// src/server/ws-ack.ts
+async function handleAckMessage(deps, conn, state, msg, id) {
+  if (!isValidDeviceId(msg.deviceId)) {
+    deps.sendError(conn, id, "INVALID_MESSAGE", '"deviceId" must be a 32-hex device id');
+    return;
+  }
+  if (typeof msg.seq !== "string" || !SEQ_STRING_RE.test(msg.seq)) {
+    deps.sendError(conn, id, "INVALID_MESSAGE", '"seq" must be a non-negative integer string');
+    return;
+  }
+  const deviceId = msg.deviceId;
+  const seq = BigInt(msg.seq);
+  try {
+    await state.database.runCdcMaintenance((writer) => upsertDeviceAck(writer, deviceId, seq));
+    for (const stream of state.deviceStreams.values()) {
+      if (stream.deviceId === deviceId) {
+        stream.onAck(seq);
+      }
+    }
+    deps.sendResult(conn, id, { acked: true, seq: seq.toString() });
+  } catch (err) {
+    deps.sendSirannonError(conn, id, err);
   }
-  return value;
 }
 
 // src/server/ws-cdc.ts
@@ -655,12 +1357,14 @@ var CLEANUP_INTERVAL_TICKS = 100;
 var CdcContextRegistry = class {
   sirannon;
   retentionMs;
+  deviceCursorRetentionMs;
   contexts = /* @__PURE__ */ new Map();
   pending = /* @__PURE__ */ new Map();
   closed = false;
-  constructor(sirannon, retentionMs) {
+  constructor(sirannon, retentionMs, deviceCursorRetentionMs) {
     this.sirannon = sirannon;
     this.retentionMs = retentionMs;
+    this.deviceCursorRetentionMs = deviceCursorRetentionMs ?? DEFAULT_DEVICE_CURSOR_RETENTION_MS;
   }
   async ensure(databaseId, database) {
     const existing = this.contexts.get(databaseId);
@@ -742,11 +1446,20 @@ var CdcContextRegistry = class {
         if (events.length > 0) {
           manager.dispatch(events);
         }
+        manager.endBatch(tracker.pollEndedAtTxBoundary);
         consecutiveErrors = 0;
         tickCount++;
         if (tickCount >= CLEANUP_INTERVAL_TICKS) {
           tickCount = 0;
-          await database.runCdcMaintenance((writer) => tracker.cleanup(writer)).catch(() => {
+          await database.runCdcMaintenance(async (writer) => {
+            const minCursor = await effectiveMinDeviceCursor(writer, this.deviceCursorRetentionMs);
+            if (minCursor === null) {
+              tracker.clearPruneBoundary();
+            } else {
+              tracker.setPruneBoundary(minCursor);
+            }
+            await tracker.cleanup(writer);
+          }).catch(() => {
           });
         }
       } catch {
@@ -764,273 +1477,965 @@ var CdcContextRegistry = class {
   }
 };
 
-// src/server/ws-cdc-resume.ts
-var REPLAY_BATCH_SIZE = 1e3;
-var DEFAULT_PRIME_BUFFER_LIMIT = 1e4;
-var DEFAULT_PRIME_BUFFER_BYTES = 16 * 1048576;
-function approxEventBytes(event) {
-  let bytes = 0;
-  if (event.row) bytes += JSON.stringify(encodeTaggedValues(event.row)).length;
-  if (event.oldRow) bytes += JSON.stringify(encodeTaggedValues(event.oldRow)).length;
-  return bytes;
-}
-function needsResync(sinceSeq, minSeq, boundary) {
-  if (sinceSeq >= boundary) return false;
-  if (minSeq === null) return true;
-  return minSeq > sinceSeq + 1n;
-}
-var PrimedSubscription = class {
-  constructor(sinceSeq, deliver, onOverload, bufferLimit = DEFAULT_PRIME_BUFFER_LIMIT, bufferByteLimit = DEFAULT_PRIME_BUFFER_BYTES) {
-    this.sinceSeq = sinceSeq;
-    this.deliver = deliver;
-    this.onOverload = onOverload;
-    this.bufferLimit = bufferLimit;
-    this.bufferByteLimit = bufferByteLimit;
-  }
-  mode = "priming";
-  buffer = [];
-  bufferBytes = 0;
-  bufferLimit;
-  bufferByteLimit;
-  onLiveEvent(event) {
-    if (this.mode === "stopped") return;
-    if (this.mode === "live") {
-      this.emit(event);
-      return;
+// src/server/ws-connection.ts
+var WS_CLOSE_OVERLOADED = 4290;
+
+// src/server/ws-device-frames.ts
+var DEVICE_FRAME_TARGET_BYTES = 65536;
+function wireChangeEvent(event) {
+  return {
+    type: event.type,
+    table: event.table,
+    row: encodeTaggedValues(event.row),
+    oldRow: event.oldRow === void 0 ? void 0 : encodeTaggedValues(event.oldRow),
+    seq: event.seq.toString(),
+    timestamp: event.timestamp,
+    ...event.hlc !== void 0 ? { hlc: event.hlc } : {},
+    ...event.origin !== void 0 ? { origin: event.origin } : {},
+    ...event.rowId !== void 0 ? { rowId: event.rowId } : {},
+    ...event.txId !== void 0 ? { txId: event.txId } : {},
+    ...event.txEnd === true ? { txEnd: true } : {}
+  };
+}
+var DeviceFramePacker = class {
+  constructor(subscriptionId, sendText, targetBytes = DEVICE_FRAME_TARGET_BYTES) {
+    this.subscriptionId = subscriptionId;
+    this.sendText = sendText;
+    this.targetBytes = targetBytes;
+  }
+  parts = [];
+  bytes = 0;
+  append(event) {
+    let encoded;
+    try {
+      encoded = JSON.stringify(wireChangeEvent(event));
+    } catch {
+      return "dropped";
     }
-    const nextBytes = this.bufferBytes + approxEventBytes(event);
-    if (this.buffer.length >= this.bufferLimit || nextBytes > this.bufferByteLimit) {
-      this.stop();
-      this.onOverload();
-      return;
+    let outcome = "queued";
+    if (this.parts.length > 0 && this.bytes + encoded.length > this.targetBytes) {
+      outcome = this.flush();
+      if (outcome === "dropped") return outcome;
     }
-    this.buffer.push(event);
-    this.bufferBytes = nextBytes;
-  }
-  async replay(tracker, conn, table, filter, boundary) {
-    let cursor = this.sinceSeq;
-    while (this.mode === "priming" && cursor < boundary) {
-      const events = await tracker.readSince(conn, table, cursor, boundary, REPLAY_BATCH_SIZE);
-      if (events.length === 0) break;
-      for (const event of events) {
-        if (filter && !changeMatchesFilter(event, filter)) continue;
-        if (!this.emit(event)) return;
-      }
-      const lastEvent = events[events.length - 1];
-      if (lastEvent === void 0) break;
-      cursor = lastEvent.seq;
-      if (events.length < REPLAY_BATCH_SIZE) break;
+    this.parts.push(encoded);
+    this.bytes += encoded.length;
+    if (this.bytes >= this.targetBytes) {
+      outcome = worstOutcome(outcome, this.flush());
     }
+    return outcome;
   }
-  goLive() {
-    if (this.mode !== "priming") return;
-    const pending = this.buffer;
-    this.buffer = [];
-    for (const event of pending) {
-      if (!this.emit(event)) return;
-    }
-    if (this.mode === "priming") {
-      this.mode = "live";
+  flush() {
+    if (this.parts.length === 0) return "queued";
+    const frame = `{"type":"changes","id":${JSON.stringify(this.subscriptionId)},"events":[${this.parts.join(",")}]}`;
+    this.parts = [];
+    this.bytes = 0;
+    return this.sendText(frame);
+  }
+  clear() {
+    this.parts = [];
+    this.bytes = 0;
+  }
+  get pendingEvents() {
+    return this.parts.length;
+  }
+};
+var OUTCOME_SEVERITY = {
+  queued: 0,
+  sent: 1,
+  buffered: 2,
+  dropped: 3
+};
+function worstOutcome(a, b) {
+  return OUTCOME_SEVERITY[a] >= OUTCOME_SEVERITY[b] ? a : b;
+}
+
+// src/server/ws-device-stream.ts
+var DEFAULT_MAX_UNACKNOWLEDGED_CHANGES = 1e3;
+var CATCHUP_READ_BATCH = 1e3;
+var DeviceChangeStream = class {
+  constructor(deps, baselineSeq, startMode) {
+    this.deps = deps;
+    this.mode = startMode;
+    this.catchupFrom = baselineSeq;
+    this.highestQueuedSeq = baselineSeq;
+    this.processedSeq = baselineSeq;
+    this.ackedSeq = baselineSeq;
+  }
+  mode;
+  grouper = null;
+  catchupFrom;
+  highestQueuedSeq;
+  processedSeq;
+  heldSeq = null;
+  ackedSeq;
+  lastQueuedTxId;
+  midTransaction = false;
+  draining = false;
+  socketWait = false;
+  halted = false;
+  get deviceId() {
+    return this.deps.deviceId;
+  }
+  get stopped() {
+    return this.halted;
+  }
+  get catchingUp() {
+    return this.mode === "catchup";
+  }
+  start() {
+    if (this.mode === "catchup") {
+      void this.drain();
+    }
+  }
+  receiveLive(event) {
+    if (this.halted || this.mode !== "live") return;
+    this.ensureGrouper().receive(event);
+  }
+  onBatchEnd(atTxBoundary) {
+    if (this.halted || this.mode !== "live") return;
+    if (this.grouper !== null && !this.grouper.flush(atTxBoundary)) return;
+    this.settleFrame(this.deps.packer?.flush() ?? "queued");
+  }
+  onAck(seq) {
+    if (this.halted) return;
+    if (seq > this.ackedSeq) {
+      this.ackedSeq = seq;
+    }
+    if (this.mode === "catchup") {
+      void this.drain();
+    }
+  }
+  onSocketDrain() {
+    if (this.halted) return;
+    this.socketWait = false;
+    if (this.mode === "catchup") {
+      void this.drain();
     }
   }
-  emit(event) {
-    if (this.mode === "stopped") return false;
-    if (event.seq <= this.sinceSeq) return true;
-    const outcome = this.deliver(event);
+  stop() {
+    this.halted = true;
+    this.grouper = null;
+    this.deps.packer?.clear();
+  }
+  ensureGrouper() {
+    this.grouper ??= new TransactionGrouper((event) => this.deliver(event));
+    return this.grouper;
+  }
+  windowClosed() {
+    return this.highestQueuedSeq - this.ackedSeq > BigInt(this.deps.maxUnacknowledgedChanges);
+  }
+  deliver(event) {
+    if (this.halted) return false;
+    const startsTransaction = event.txId === void 0 || event.txId !== this.lastQueuedTxId;
+    if (this.windowClosed() && (this.deps.pacing === "perEvent" || startsTransaction)) {
+      this.enterCatchup();
+      return false;
+    }
+    const outcome = this.deps.packer === null ? this.deps.sendEvent(event) : this.deps.packer.append(event);
     if (outcome === "dropped") {
       this.stop();
+      this.deps.onOverload();
+      return false;
+    }
+    this.lastQueuedTxId = event.txId;
+    if (event.seq > this.highestQueuedSeq) {
+      this.highestQueuedSeq = event.seq;
+    }
+    if (event.seq > this.processedSeq) {
+      this.processedSeq = event.seq;
+    }
+    this.midTransaction = event.txEnd !== true && event.txId !== void 0;
+    if (outcome === "buffered") {
+      this.socketWait = true;
+      this.enterCatchup();
       return false;
     }
     return true;
   }
-  stop() {
-    this.mode = "stopped";
-    this.buffer = [];
-    this.bufferBytes = 0;
+  /**
+   * Abandons the in-flight stream state and falls back to the change log.
+   * The grouper's held event was never queued and its seq is above both
+   * watermarks, so dropping it loses nothing. The catch-up read resumes
+   * after the last position fully settled: `highestQueuedSeq` is the last
+   * event that reached the socket, and `processedSeq` may run further ahead
+   * of it over a span whose every event was suppressed, so a long run of
+   * the device's own echoes is not re-read on every pause.
+   */
+  enterCatchup() {
+    const flushed = this.deps.packer?.flush() ?? "queued";
+    if (flushed === "dropped") {
+      this.stop();
+      this.deps.onOverload();
+      return;
+    }
+    if (flushed === "buffered") {
+      this.socketWait = true;
+    }
+    this.mode = "catchup";
+    this.grouper = null;
+    this.heldSeq = null;
+    this.catchupFrom = this.processedSeq > this.highestQueuedSeq ? this.processedSeq : this.highestQueuedSeq;
   }
-};
-
-// src/server/ws-connection.ts
-var WS_CLOSE_OVERLOADED = 4290;
-
-// src/server/ws-operations.ts
-function isValidParams(params) {
-  if (params === void 0 || params === null) return true;
-  return typeof params === "object";
-}
-function decodeBatchParams2(ctx, id, raw) {
-  const decoded = [];
-  for (const entry of raw) {
-    const result = decodeBoundParams(entry, "paramsBatch");
-    if (!result.ok) {
-      ctx.sendError(id, "INVALID_MESSAGE", result.message);
-      return null;
+  /**
+   * A closed window stops the catch-up read only where the window may pace
+   * the stream: anywhere under `perEvent` pacing, and at a transaction
+   * boundary under `perTransaction` pacing. Mid-transaction the read keeps
+   * going, because a `perTransaction` device acknowledges only applied
+   * whole transactions, and holding the rest of an open transaction back
+   * would wait for an acknowledgement that can never arrive.
+   */
+  readGateClosed() {
+    if (!this.windowClosed()) return false;
+    return this.deps.pacing === "perEvent" || !this.midTransaction;
+  }
+  async drain() {
+    if (this.draining || this.halted) return;
+    this.draining = true;
+    try {
+      while (!this.halted && this.mode === "catchup") {
+        if (this.socketWait || this.readGateClosed()) return;
+        const upTo = this.deps.logCursor();
+        if (this.catchupFrom >= upTo) {
+          this.goLive();
+          return;
+        }
+        let events;
+        try {
+          events = await this.deps.readLog(this.catchupFrom, upTo, CATCHUP_READ_BATCH);
+        } catch (err) {
+          this.halted = true;
+          this.deps.onFault(err);
+          return;
+        }
+        if (this.halted || this.mode !== "catchup") return;
+        if (events.length === 0) {
+          this.catchupFrom = upTo;
+          this.goLive();
+          return;
+        }
+        const grouper = this.ensureGrouper();
+        for (const event of events) {
+          this.catchupFrom = event.seq;
+          const delivered = this.deps.transform(event);
+          if (delivered === null) {
+            if (this.heldSeq === null && event.seq > this.processedSeq) {
+              this.processedSeq = event.seq;
+            }
+            continue;
+          }
+          if (!grouper.receive(delivered)) return;
+          const settledBefore = event.seq - 1n;
+          if (settledBefore > this.processedSeq) {
+            this.processedSeq = settledBefore;
+          }
+          this.heldSeq = delivered.txId === void 0 ? null : event.seq;
+        }
+      }
+    } finally {
+      this.draining = false;
+    }
+  }
+  /**
+   * Rejoins the live feed. Runs synchronously right after a log read, so no
+   * poller tick can dispatch between the caught-up check and the mode flip.
+   * The grouper survives the transition: the event it holds is released by
+   * the boundary flush when the poller stopped at a transaction boundary,
+   * exactly as a resuming ordinary subscription does.
+   */
+  goLive() {
+    this.mode = "live";
+    const grouper = this.ensureGrouper();
+    const atBoundary = this.deps.logCursorAtTxBoundary();
+    if (!grouper.flush(atBoundary)) return;
+    if (atBoundary) {
+      this.heldSeq = null;
+    }
+    this.settleFrame(this.deps.packer?.flush() ?? "queued");
+  }
+  settleFrame(outcome) {
+    if (this.halted) return;
+    if (outcome === "dropped") {
+      this.stop();
+      this.deps.onOverload();
+      return;
+    }
+    if (outcome === "buffered") {
+      this.socketWait = true;
+      if (this.mode === "live") {
+        this.enterCatchup();
+      }
+    }
+  }
+};
+
+// src/server/ws-operations.ts
+function isValidParams(params) {
+  if (params === void 0 || params === null) return true;
+  return typeof params === "object";
+}
+function decodeBatchParams2(ctx, id, raw) {
+  const decoded = [];
+  for (const entry of raw) {
+    const result = decodeBoundParams(entry, "paramsBatch");
+    if (!result.ok) {
+      ctx.sendError(id, "INVALID_MESSAGE", result.message);
+      return null;
+    }
+    decoded.push(result.value);
+  }
+  return decoded;
+}
+async function handleQueryMessage(ctx, msg, id) {
+  if (typeof msg.sql !== "string") {
+    ctx.sendError(id, "INVALID_MESSAGE", 'Query message requires a "sql" string field');
+    return;
+  }
+  if (!isValidParams(msg.params)) {
+    ctx.sendError(id, "INVALID_MESSAGE", '"params" must be an object or array');
+    return;
+  }
+  const params = decodeBoundParams(msg.params, "params");
+  if (!params.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", params.message);
+    return;
+  }
+  const readConcern = validateReadConcern(msg.readConcern);
+  if (!readConcern.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", readConcern.message);
+    return;
+  }
+  try {
+    const rows = await queryWireRows(ctx.target, msg.sql, params.value, toReadOptions(readConcern.value));
+    ctx.sendResult(id, { rows });
+  } catch (err) {
+    ctx.sendCaughtError(id, err);
+  }
+}
+function toReadOptions(readConcern) {
+  return readConcern ? { readConcern } : void 0;
+}
+async function handleExecuteMessage(ctx, msg, id) {
+  if (typeof msg.sql !== "string") {
+    ctx.sendError(id, "INVALID_MESSAGE", 'Execute message requires a "sql" string field');
+    return;
+  }
+  if (!isValidParams(msg.params)) {
+    ctx.sendError(id, "INVALID_MESSAGE", '"params" must be an object or array');
+    return;
+  }
+  const params = decodeBoundParams(msg.params, "params");
+  if (!params.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", params.message);
+    return;
+  }
+  try {
+    const result = await ctx.target.execute(msg.sql, params.value);
+    ctx.sendResult(id, toExecuteResponse(result));
+  } catch (err) {
+    ctx.sendCaughtError(id, err);
+  }
+}
+async function handleTransactionMessage(ctx, msg, id) {
+  const statementsError = transactionStatementsValidationError(msg.statements);
+  if (statementsError !== null) {
+    ctx.sendError(id, "INVALID_MESSAGE", statementsError);
+    return;
+  }
+  const writeConcern = validateWriteConcern(msg.writeConcern);
+  if (!writeConcern.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", writeConcern.message);
+    return;
+  }
+  const validStatements = msg.statements;
+  const statements = [];
+  for (const stmt of validStatements) {
+    const params = decodeBoundParams(stmt.params, "params");
+    if (!params.ok) {
+      ctx.sendError(id, "INVALID_MESSAGE", params.message);
+      return;
+    }
+    statements.push({ sql: stmt.sql, params: params.value });
+  }
+  const txOptions = writeConcern.value ? { writeConcern: writeConcern.value } : void 0;
+  try {
+    const results = ctx.target.executeTransaction ? await ctx.target.executeTransaction(statements, txOptions) : await ctx.target.transaction(async (tx) => {
+      const txResults = [];
+      for (const stmt of statements) {
+        txResults.push(await tx.execute(stmt.sql, stmt.params));
+      }
+      return txResults;
+    }, txOptions);
+    ctx.sendResult(id, { results: results.map(toExecuteResponse) });
+  } catch (err) {
+    ctx.sendCaughtError(id, err);
+  }
+}
+async function handleBatchMessage(ctx, msg, id) {
+  if (typeof msg.sql !== "string") {
+    ctx.sendError(id, "INVALID_MESSAGE", 'Batch message requires a "sql" string field');
+    return;
+  }
+  const paramsBatchError = paramsBatchValidationError(msg.paramsBatch);
+  if (paramsBatchError !== null) {
+    ctx.sendError(id, "INVALID_MESSAGE", paramsBatchError);
+    return;
+  }
+  const writeConcern = validateWriteConcern(msg.writeConcern);
+  if (!writeConcern.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", writeConcern.message);
+    return;
+  }
+  const sql = msg.sql;
+  const paramsBatch = decodeBatchParams2(ctx, id, msg.paramsBatch);
+  if (paramsBatch === null) return;
+  try {
+    const results = await ctx.target.transaction(
+      async (tx) => tx.executeBatch(sql, paramsBatch),
+      writeConcern.value ? { writeConcern: writeConcern.value } : void 0
+    );
+    ctx.sendResult(id, { results: results.map(toExecuteResponse) });
+  } catch (err) {
+    ctx.sendCaughtError(id, err);
+  }
+}
+async function handleLoadMessage(ctx, msg, id) {
+  if (typeof msg.sql !== "string") {
+    ctx.sendError(id, "INVALID_MESSAGE", 'Load message requires a "sql" string field');
+    return;
+  }
+  const paramsBatchError = paramsBatchValidationError(msg.paramsBatch);
+  if (paramsBatchError !== null) {
+    ctx.sendError(id, "INVALID_MESSAGE", paramsBatchError);
+    return;
+  }
+  const durabilityError = loadDurabilityValidationError(msg.durability);
+  if (durabilityError !== null) {
+    ctx.sendError(id, "INVALID_MESSAGE", durabilityError);
+    return;
+  }
+  const checkpointError = loadCheckpointValidationError(msg.checkpoint);
+  if (checkpointError !== null) {
+    ctx.sendError(id, "INVALID_MESSAGE", checkpointError);
+    return;
+  }
+  const bulkLoad = ctx.target.bulkLoad;
+  if (typeof bulkLoad !== "function") {
+    ctx.sendError(id, "BULK_LOAD_UNSUPPORTED", "The execution target for this database does not support bulk load");
+    return;
+  }
+  const sql = msg.sql;
+  const paramsBatch = decodeBatchParams2(ctx, id, msg.paramsBatch);
+  if (paramsBatch === null) return;
+  const options = toBulkLoadOptions({
+    durability: msg.durability,
+    checkpoint: msg.checkpoint
+  });
+  try {
+    const summary = await bulkLoad.call(ctx.target, sql, paramsBatch, options);
+    ctx.sendResult(id, summary);
+  } catch (err) {
+    ctx.sendCaughtError(id, err);
+  }
+}
+
+// src/server/ws-named.ts
+function readArguments(raw) {
+  if (raw === void 0) return { ok: true, value: {} };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, message: '"args" must be an object' };
+  }
+  const decoded = decodeBoundParams(raw, "args");
+  if (!decoded.ok) return { ok: false, message: decoded.message };
+  return { ok: true, value: decoded.value ?? {} };
+}
+async function handleNamedQueryMessage(ctx, msg, id, name) {
+  const args = readArguments(msg.args);
+  if (!args.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", args.message);
+    return;
+  }
+  const readConcern = validateReadConcern(msg.readConcern);
+  if (!readConcern.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", readConcern.message);
+    return;
+  }
+  try {
+    const resolved = ctx.operations.resolve("read", ctx.databaseId, name, args.value, ctx.identity);
+    if (!resolved.ok) {
+      ctx.sendError(id, resolved.refusal.code, resolved.refusal.message);
+      return;
+    }
+    const statement = resolved.statements[0];
+    const rows = await queryWireRows(ctx.target, statement.sql, statement.params, toReadOptions(readConcern.value));
+    ctx.sendResult(id, { rows });
+  } catch (err) {
+    ctx.sendCaughtError(id, err);
+  }
+}
+async function handleNamedExecuteMessage(ctx, msg, id, name) {
+  const args = readArguments(msg.args);
+  if (!args.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", args.message);
+    return;
+  }
+  const writeConcern = validateWriteConcern(msg.writeConcern);
+  if (!writeConcern.ok) {
+    ctx.sendError(id, "INVALID_MESSAGE", writeConcern.message);
+    return;
+  }
+  try {
+    const resolved = ctx.operations.resolve("write", ctx.databaseId, name, args.value, ctx.identity);
+    if (!resolved.ok) {
+      ctx.sendError(id, resolved.refusal.code, resolved.refusal.message);
+      return;
+    }
+    const statements = resolved.statements;
+    const options = writeConcern.value ? { writeConcern: writeConcern.value } : void 0;
+    const results = ctx.target.executeTransaction ? await ctx.target.executeTransaction(statements, options) : await ctx.target.transaction(async (tx) => {
+      const collected = [];
+      for (const statement of statements) {
+        collected.push(await tx.execute(statement.sql, statement.params));
+      }
+      return collected;
+    }, options);
+    ctx.sendResult(id, { results: results.map(toExecuteResponse) });
+  } catch (err) {
+    ctx.sendCaughtError(id, err);
+  }
+}
+
+// src/server/ws-live.ts
+var LIVE_ONLY_FIELDS = ["table", "tables", "filter", "sinceSeq", "epoch", "deviceId", "schemaVersion"];
+async function handleLiveSubscribeMessage(deps, conn, state, msg, id, name) {
+  const rejected = LIVE_ONLY_FIELDS.find((field) => msg[field] !== void 0);
+  if (rejected !== void 0) {
+    deps.sendError(
+      conn,
+      id,
+      "INVALID_MESSAGE",
+      `A subscription naming a registered read carries no "${rejected}"; the server holds the result`
+    );
+    return;
+  }
+  if (state.subscriptions.has(id)) {
+    deps.sendError(conn, id, "DUPLICATE_SUBSCRIPTION", `Subscription '${id}' already exists on this connection`);
+    return;
+  }
+  if (state.database.readOnly) {
+    deps.sendError(conn, id, "READ_ONLY", "Live queries are not available on read-only databases");
+    return;
+  }
+  if (state.database.path === ":memory:") {
+    deps.sendError(conn, id, "CDC_UNSUPPORTED", "Live queries require file-based databases");
+    return;
+  }
+  if (msg.registryDigest !== void 0) {
+    if (typeof msg.registryDigest !== "string") {
+      deps.sendError(conn, id, "INVALID_MESSAGE", '"registryDigest" must be a string');
+      return;
+    }
+    if (msg.registryDigest !== deps.operations.digest) {
+      deps.sendError(
+        conn,
+        id,
+        "REGISTRY_MISMATCH",
+        "This server runs a different operation registry than the one the client generated against; re-read GET /capabilities"
+      );
+      return;
+    }
+  }
+  const args = readArguments(msg.args);
+  if (!args.ok) {
+    deps.sendError(conn, id, "INVALID_MESSAGE", args.message);
+    return;
+  }
+  let sql;
+  let params;
+  try {
+    const resolved = deps.operations.resolve("read", state.databaseId, name, args.value, state.identity);
+    if (!resolved.ok) {
+      deps.sendError(conn, id, resolved.refusal.code, resolved.refusal.message);
+      return;
+    }
+    sql = resolved.statements[0].sql;
+    params = resolved.statements[0].params;
+  } catch (err) {
+    deps.sendSirannonError(conn, id, err);
+    return;
+  }
+  let cancelled = false;
+  state.subscriptions.set(id, {
+    unsubscribe: () => {
+      cancelled = true;
+    }
+  });
+  let query;
+  try {
+    query = await state.database.live(sql, params);
+  } catch (err) {
+    state.subscriptions.delete(id);
+    if (!cancelled) deps.sendSirannonError(conn, id, err);
+    return;
+  }
+  if (cancelled) {
+    await query.close().catch(() => {
+    });
+    return;
+  }
+  let stop = null;
+  const teardown = () => {
+    state.subscriptions.delete(id);
+    stop?.();
+    stop = null;
+    query.close().catch(() => {
+    });
+  };
+  stop = query.subscribe((update) => {
+    deliver(deps, conn, id, query, update, teardown);
+  });
+  state.subscriptions.set(id, { unsubscribe: teardown });
+  const opened = query.getState();
+  if (opened.status !== "ready") {
+    teardown();
+    deps.sendError(conn, id, "INTERNAL_ERROR", "The live query produced no first result");
+    return;
+  }
+  deps.sendSubscribedRows(conn, id, encodeRows(opened.rows));
+}
+function deliver(deps, conn, id, query, update, teardown) {
+  if (update.kind === "ops") {
+    deps.sendLive(conn, { type: "live", id, ops: update.ops.map(encodeOp) });
+    return;
+  }
+  if (update.kind === "revalidating") {
+    deps.sendLive(conn, { type: "live", id, revalidating: true });
+    return;
+  }
+  const state = query.getState();
+  if (state.status === "ready") {
+    deps.sendLive(conn, { type: "live", id, rows: encodeRows(state.rows) });
+    return;
+  }
+  if (state.status === "error") {
+    teardown();
+    deps.sendError(conn, id, "CDC_ERROR", state.error.message);
+  }
+}
+function encodeRows(rows) {
+  return rows.map((row) => encodeTaggedValues(row));
+}
+function encodeOp(op) {
+  if (op.op === "delete") return { op: "delete", index: op.index };
+  return {
+    op: op.op === "insert" ? "insert" : "update",
+    index: op.index,
+    row: encodeTaggedValues(op.row)
+  };
+}
+
+// src/server/ws-cdc-resume.ts
+var PrimedSubscription2 = class extends PrimedSubscription {
+  constructor(sinceSeq, deliver2, onOverload, bufferLimit, bufferByteLimit) {
+    super(sinceSeq, (event) => deliver2(event) !== "dropped", onOverload, bufferLimit, bufferByteLimit);
+  }
+};
+
+// src/server/ws-device-subscribe.ts
+async function subscribeDevice(deps, conn, state, request) {
+  const { id, tables, filter, sinceSeq, clientEpoch, deviceId, stagedStream } = request;
+  let stream;
+  let boundary;
+  let resync;
+  let epoch;
+  try {
+    const ctx = await deps.cdc.ensure(state.databaseId, state.database);
+    for (const table of tables) {
+      await ctx.tracker.watch(ctx.cdcConn, table);
+    }
+    await state.database.ensureChangeStamping();
+    epoch = ctx.epoch;
+    boundary = ctx.tracker.cursor;
+    if (sinceSeq === void 0) {
+      resync = false;
+    } else {
+      const minSeq = await ctx.tracker.getMinSeq(ctx.cdcConn);
+      const foreignEpoch = clientEpoch !== void 0 && clientEpoch !== ctx.epoch;
+      resync = foreignEpoch || needsResync(sinceSeq, minSeq, boundary);
     }
-    decoded.push(result.value);
+    const suppress = (event) => event.origin === deviceId || event.origin === void 0;
+    const resumeFrom = resync || sinceSeq === void 0 ? boundary : sinceSeq;
+    stream = new DeviceChangeStream(
+      {
+        deviceId,
+        maxUnacknowledgedChanges: deps.maxUnacknowledgedChanges,
+        pacing: stagedStream ? "perEvent" : "perTransaction",
+        packer: stagedStream ? new DeviceFramePacker(id, (data) => deps.sendText(conn, data)) : null,
+        sendEvent: (event) => deps.sendChange(conn, id, event),
+        onOverload: () => deps.handleOverload(conn),
+        onFault: () => deps.closeFaulted(conn),
+        readLog: (afterSeq, upToSeq, limit) => ctx.tracker.readSinceTables(ctx.cdcConn, tables, afterSeq, upToSeq, limit),
+        logCursor: () => ctx.tracker.cursor,
+        logCursorAtTxBoundary: () => ctx.tracker.pollEndedAtTxBoundary,
+        transform: (event) => {
+          if (suppress(event)) return null;
+          return filter === void 0 ? event : filteredChange(event, filter);
+        }
+      },
+      resumeFrom,
+      resumeFrom < boundary ? "catchup" : "live"
+    );
+    const subscriptions = tables.map(
+      (table) => ctx.manager.subscribe(table, filter, (event) => {
+        if (suppress(event)) return;
+        stream.receiveLive(event);
+      })
+    );
+    const removeBatchEnd = ctx.manager.addBatchEndListener((atTxBoundary) => stream.onBatchEnd(atTxBoundary));
+    state.subscriptions.set(id, {
+      unsubscribe: () => {
+        removeBatchEnd();
+        stream.stop();
+        state.deviceStreams.delete(id);
+        for (const subscription of subscriptions) {
+          subscription.unsubscribe();
+        }
+      }
+    });
+    state.deviceStreams.set(id, stream);
+  } catch (err) {
+    deps.cdc.maybeCleanup(state.databaseId);
+    deps.sendSirannonError(conn, id, err);
+    return;
   }
-  return decoded;
+  deps.sendSubscribed(conn, id, boundary.toString(), epoch, resync, deps.maxUnacknowledgedChanges);
+  stream.start();
 }
-async function handleQueryMessage(ctx, msg, id) {
-  if (typeof msg.sql !== "string") {
-    ctx.sendError(id, "INVALID_MESSAGE", 'Query message requires a "sql" string field');
+
+// src/server/ws-subscribe.ts
+var MAX_SUBSCRIBED_TABLES = 500;
+async function handleSubscribeMessage(deps, conn, state, msg, id) {
+  const tables = readTableSet(msg);
+  if (typeof tables === "string") {
+    deps.sendError(conn, id, "INVALID_MESSAGE", tables);
     return;
   }
-  if (!isValidParams(msg.params)) {
-    ctx.sendError(id, "INVALID_MESSAGE", '"params" must be an object or array');
+  if (state.subscriptions.has(id)) {
+    deps.sendError(conn, id, "DUPLICATE_SUBSCRIPTION", `Subscription '${id}' already exists on this connection`);
     return;
   }
-  const params = decodeBoundParams(msg.params, "params");
-  if (!params.ok) {
-    ctx.sendError(id, "INVALID_MESSAGE", params.message);
+  if (state.database.readOnly) {
+    deps.sendError(conn, id, "READ_ONLY", "Subscriptions are not available on read-only databases");
     return;
   }
-  try {
-    const rows = await queryWireRows(ctx.target, msg.sql, params.value);
-    ctx.sendResult(id, { rows });
-  } catch (err) {
-    ctx.sendCaughtError(id, err);
-  }
-}
-async function handleExecuteMessage(ctx, msg, id) {
-  if (typeof msg.sql !== "string") {
-    ctx.sendError(id, "INVALID_MESSAGE", 'Execute message requires a "sql" string field');
+  if (state.database.path === ":memory:") {
+    deps.sendError(conn, id, "CDC_UNSUPPORTED", "CDC subscriptions require file-based databases");
     return;
   }
-  if (!isValidParams(msg.params)) {
-    ctx.sendError(id, "INVALID_MESSAGE", '"params" must be an object or array');
+  if (msg.filter !== void 0 && msg.filter !== null && (typeof msg.filter !== "object" || Array.isArray(msg.filter))) {
+    deps.sendError(conn, id, "INVALID_MESSAGE", '"filter" must be a plain object');
     return;
   }
-  const params = decodeBoundParams(msg.params, "params");
-  if (!params.ok) {
-    ctx.sendError(id, "INVALID_MESSAGE", params.message);
+  const decodedFilter = decodeBoundParams(msg.filter, "filter");
+  if (!decodedFilter.ok) {
+    deps.sendError(conn, id, "INVALID_MESSAGE", decodedFilter.message);
     return;
   }
-  try {
-    const result = await ctx.target.execute(msg.sql, params.value);
-    ctx.sendResult(id, toExecuteResponse(result));
-  } catch (err) {
-    ctx.sendCaughtError(id, err);
-  }
-}
-async function handleTransactionMessage(ctx, msg, id) {
-  const statementsError = transactionStatementsValidationError(msg.statements);
-  if (statementsError !== null) {
-    ctx.sendError(id, "INVALID_MESSAGE", statementsError);
-    return;
+  const filter = decodedFilter.value;
+  let sinceSeq;
+  if (msg.sinceSeq !== void 0) {
+    if (typeof msg.sinceSeq !== "string" || !/^\d+$/.test(msg.sinceSeq)) {
+      deps.sendError(conn, id, "INVALID_MESSAGE", '"sinceSeq" must be a non-negative integer string');
+      return;
+    }
+    sinceSeq = BigInt(msg.sinceSeq);
   }
-  const writeConcern = validateWriteConcern(msg.writeConcern);
-  if (!writeConcern.ok) {
-    ctx.sendError(id, "INVALID_MESSAGE", writeConcern.message);
-    return;
+  let clientEpoch;
+  if (msg.epoch !== void 0) {
+    if (typeof msg.epoch !== "string") {
+      deps.sendError(conn, id, "INVALID_MESSAGE", '"epoch" must be a string');
+      return;
+    }
+    clientEpoch = msg.epoch;
   }
-  const validStatements = msg.statements;
-  const statements = [];
-  for (const stmt of validStatements) {
-    const params = decodeBoundParams(stmt.params, "params");
-    if (!params.ok) {
-      ctx.sendError(id, "INVALID_MESSAGE", params.message);
+  let deviceId;
+  if (msg.deviceId !== void 0) {
+    if (!isValidDeviceId(msg.deviceId)) {
+      deps.sendError(conn, id, "INVALID_MESSAGE", '"deviceId" must be a 32-hex device id');
       return;
     }
-    statements.push({ sql: stmt.sql, params: params.value });
+    deviceId = msg.deviceId;
   }
-  const txOptions = writeConcern.value ? { writeConcern: writeConcern.value } : void 0;
-  try {
-    const results = ctx.target.executeTransaction ? await ctx.target.executeTransaction(statements, txOptions) : await ctx.target.transaction(async (tx) => {
-      const txResults = [];
-      for (const stmt of statements) {
-        txResults.push(await tx.execute(stmt.sql, stmt.params));
-      }
-      return txResults;
-    }, txOptions);
-    ctx.sendResult(id, { results: results.map(toExecuteResponse) });
-  } catch (err) {
-    ctx.sendCaughtError(id, err);
+  if (deviceId !== void 0) {
+    if (msg.schemaVersion !== void 0 && !isValidSchemaVersion(msg.schemaVersion)) {
+      deps.sendError(conn, id, "INVALID_MESSAGE", '"schemaVersion" must be a non-negative integer');
+      return;
+    }
+    let refusal;
+    try {
+      const serverVersion = highestMigrationVersion(await state.database.appliedMigrations());
+      refusal = schemaVersionGateRefusal(msg.schemaVersion ?? 0, serverVersion);
+    } catch (err) {
+      deps.sendSirannonError(conn, id, err);
+      return;
+    }
+    if (refusal !== null) {
+      deps.sendError(conn, id, refusal.code, refusal.message);
+      return;
+    }
   }
-}
-async function handleBatchMessage(ctx, msg, id) {
-  if (typeof msg.sql !== "string") {
-    ctx.sendError(id, "INVALID_MESSAGE", 'Batch message requires a "sql" string field');
+  if (msg.stagedStream !== void 0 && typeof msg.stagedStream !== "boolean") {
+    deps.sendError(conn, id, "INVALID_MESSAGE", '"stagedStream" must be a boolean');
     return;
   }
-  const paramsBatchError = paramsBatchValidationError(msg.paramsBatch);
-  if (paramsBatchError !== null) {
-    ctx.sendError(id, "INVALID_MESSAGE", paramsBatchError);
+  if (deviceId !== void 0) {
+    await subscribeDevice(deps, conn, state, {
+      id,
+      tables,
+      filter,
+      sinceSeq,
+      clientEpoch,
+      deviceId,
+      stagedStream: msg.stagedStream === true
+    });
     return;
   }
-  const writeConcern = validateWriteConcern(msg.writeConcern);
-  if (!writeConcern.ok) {
-    ctx.sendError(id, "INVALID_MESSAGE", writeConcern.message);
+  if (msg.stagedStream !== void 0) {
+    deps.sendError(conn, id, "INVALID_MESSAGE", '"stagedStream" requires a "deviceId"');
     return;
   }
-  const sql = msg.sql;
-  const paramsBatch = decodeBatchParams2(ctx, id, msg.paramsBatch);
-  if (paramsBatch === null) return;
-  try {
-    const results = await ctx.target.transaction(
-      async (tx) => tx.executeBatch(sql, paramsBatch),
-      writeConcern.value ? { writeConcern: writeConcern.value } : void 0
-    );
-    ctx.sendResult(id, { results: results.map(toExecuteResponse) });
-  } catch (err) {
-    ctx.sendCaughtError(id, err);
-  }
-}
-async function handleLoadMessage(ctx, msg, id) {
-  if (typeof msg.sql !== "string") {
-    ctx.sendError(id, "INVALID_MESSAGE", 'Load message requires a "sql" string field');
+  if (tables.length > 1) {
+    deps.sendError(conn, id, "INVALID_MESSAGE", '"tables" requires a "deviceId"');
     return;
   }
-  const paramsBatchError = paramsBatchValidationError(msg.paramsBatch);
-  if (paramsBatchError !== null) {
-    ctx.sendError(id, "INVALID_MESSAGE", paramsBatchError);
+  const table = tables[0];
+  if (sinceSeq === void 0) {
+    await subscribeLive(deps, conn, state, id, table, filter);
     return;
   }
-  const durabilityError = loadDurabilityValidationError(msg.durability);
-  if (durabilityError !== null) {
-    ctx.sendError(id, "INVALID_MESSAGE", durabilityError);
-    return;
+  await subscribeResuming(deps, conn, state, id, table, filter, sinceSeq, clientEpoch);
+}
+function readTableSet(msg) {
+  if (msg.tables !== void 0) {
+    if (!Array.isArray(msg.tables) || msg.tables.length === 0) {
+      return '"tables" must be a non-empty array of table names';
+    }
+    if (msg.tables.length > MAX_SUBSCRIBED_TABLES) {
+      return `"tables" must hold at most ${MAX_SUBSCRIBED_TABLES} table names`;
+    }
+    for (const table of msg.tables) {
+      if (typeof table !== "string" || table.length === 0) {
+        return '"tables" must hold non-empty table names';
+      }
+    }
+    return msg.tables;
   }
-  const checkpointError = loadCheckpointValidationError(msg.checkpoint);
-  if (checkpointError !== null) {
-    ctx.sendError(id, "INVALID_MESSAGE", checkpointError);
-    return;
+  if (typeof msg.table !== "string") {
+    return 'Subscribe message requires a "table" string field';
   }
-  const bulkLoad = ctx.target.bulkLoad;
-  if (typeof bulkLoad !== "function") {
-    ctx.sendError(id, "BULK_LOAD_UNSUPPORTED", "The execution target for this database does not support bulk load");
-    return;
+  return [msg.table];
+}
+async function subscribeLive(deps, conn, state, id, table, filter) {
+  try {
+    const ctx = await deps.cdc.ensure(state.databaseId, state.database);
+    await ctx.tracker.watch(ctx.cdcConn, table);
+    await state.database.ensureChangeStamping();
+    const grouper = new TransactionGrouper((event) => deps.sendChange(conn, id, event) !== "dropped");
+    const boundary = ctx.tracker.cursor;
+    const sub = ctx.manager.subscribe(table, filter, (event) => {
+      grouper.receive(event);
+    });
+    const removeBatchEnd = ctx.manager.addBatchEndListener((atTxBoundary) => {
+      grouper.flush(atTxBoundary);
+    });
+    state.subscriptions.set(id, {
+      unsubscribe: () => {
+        removeBatchEnd();
+        sub.unsubscribe();
+      }
+    });
+    deps.sendSubscribed(conn, id, boundary.toString(), ctx.epoch, false);
+  } catch (err) {
+    deps.cdc.maybeCleanup(state.databaseId);
+    deps.sendSirannonError(conn, id, err);
   }
-  const sql = msg.sql;
-  const paramsBatch = decodeBatchParams2(ctx, id, msg.paramsBatch);
-  if (paramsBatch === null) return;
-  const options = toBulkLoadOptions({
-    durability: msg.durability,
-    checkpoint: msg.checkpoint
-  });
+}
+async function subscribeResuming(deps, conn, state, id, table, filter, sinceSeq, clientEpoch) {
+  let ctx;
+  let primed;
+  let boundary;
+  let resync;
+  let goLive;
   try {
-    const summary = await bulkLoad.call(ctx.target, sql, paramsBatch, options);
-    ctx.sendResult(id, summary);
+    ctx = await deps.cdc.ensure(state.databaseId, state.database);
+    await ctx.tracker.watch(ctx.cdcConn, table);
+    await state.database.ensureChangeStamping();
+    const grouper = new TransactionGrouper((event) => deps.sendChange(conn, id, event) !== "dropped");
+    const deliver2 = (event) => grouper.receive(event) ? "sent" : "dropped";
+    boundary = ctx.tracker.cursor;
+    const boundaryEndsTransaction = ctx.tracker.pollEndedAtTxBoundary;
+    primed = new PrimedSubscription2(sinceSeq, deliver2, () => deps.handleOverload(conn));
+    const sub = ctx.manager.subscribe(table, filter, (event) => primed.onLiveEvent(event));
+    let removeBatchEnd = () => {
+    };
+    let cancelled = false;
+    goLive = () => {
+      if (cancelled) return;
+      grouper.flush(boundaryEndsTransaction);
+      primed.goLive();
+      removeBatchEnd = ctx.manager.addBatchEndListener((atTxBoundary) => {
+        grouper.flush(atTxBoundary);
+      });
+    };
+    state.subscriptions.set(id, {
+      unsubscribe: () => {
+        cancelled = true;
+        removeBatchEnd();
+        sub.unsubscribe();
+      }
+    });
+    const minSeq = await ctx.tracker.getMinSeq(ctx.cdcConn);
+    const foreignEpoch = clientEpoch !== void 0 && clientEpoch !== ctx.epoch;
+    resync = foreignEpoch || needsResync(sinceSeq, minSeq, boundary);
+    deps.sendSubscribed(conn, id, boundary.toString(), ctx.epoch, resync);
   } catch (err) {
-    ctx.sendCaughtError(id, err);
+    deps.cdc.maybeCleanup(state.databaseId);
+    deps.sendSirannonError(conn, id, err);
+    return;
+  }
+  if (!resync) {
+    try {
+      await primed.replay(ctx.tracker, ctx.cdcConn, table, filter, boundary);
+    } catch {
+      deps.sendSubscribed(conn, id, boundary.toString(), ctx.epoch, true);
+    }
   }
+  goLive();
 }
 
 // src/server/ws-handler.ts
 var DEFAULT_MAX_PAYLOAD_LENGTH = 1048576;
+var SQL_MESSAGE_TYPES = /* @__PURE__ */ new Set(["query", "execute", "transaction", "batch", "load"]);
+var NAMED_MESSAGE_TYPES = /* @__PURE__ */ new Set(["query", "execute", "subscribe"]);
 var WSHandler = class {
   sirannon;
   maxPayloadLength;
   resolveExecutionTarget;
   connections = /* @__PURE__ */ new Map();
   cdc;
+  maxUnacknowledgedChanges;
+  acceptSql;
+  operations;
   closed = false;
   constructor(sirannon, options) {
     this.sirannon = sirannon;
+    this.acceptSql = options?.acceptSql === true;
+    this.operations = createOperationSource(options?.operations);
     this.maxPayloadLength = options?.maxPayloadLength ?? DEFAULT_MAX_PAYLOAD_LENGTH;
+    this.maxUnacknowledgedChanges = options?.maxUnacknowledgedChanges ?? DEFAULT_MAX_UNACKNOWLEDGED_CHANGES;
     this.resolveExecutionTarget = options?.resolveExecutionTarget;
-    this.cdc = new CdcContextRegistry(sirannon, options?.cdcRetentionMs);
+    this.cdc = new CdcContextRegistry(sirannon, options?.cdcRetentionMs, options?.deviceCursorRetentionMs);
   }
-  async handleOpen(conn, databaseId) {
+  async handleOpen(conn, databaseId, identity) {
     if (this.closed) {
       this.sendError(conn, "", "HANDLER_CLOSED", "WebSocket handler is shut down");
       conn.close(1013, "Handler shutting down");
@@ -1064,7 +2469,9 @@ var WSHandler = class {
       databaseId,
       database,
       executionTarget,
+      identity,
       subscriptions: /* @__PURE__ */ new Map(),
+      deviceStreams: /* @__PURE__ */ new Map(),
       overloaded: false
     });
   }
@@ -1107,12 +2514,23 @@ var WSHandler = class {
       return;
     }
     const id = msg.id;
+    const name = typeof msg.name === "string" ? msg.name : null;
+    if (name !== null && !NAMED_MESSAGE_TYPES.has(msg.type)) {
+      this.sendError(conn, id, "INVALID_MESSAGE", `A "${msg.type}" message names no registered operation`);
+      return;
+    }
+    if (!this.acceptSql && SQL_MESSAGE_TYPES.has(msg.type) && name === null) {
+      this.sendError(conn, id, "SQL_NOT_ACCEPTED", SQL_NOT_ACCEPTED_MESSAGE);
+      return;
+    }
     switch (msg.type) {
       case "query":
-        handleQueryMessage(this.operationContext(conn, state), msg, id);
+        if (name !== null) handleNamedQueryMessage(this.namedContext(conn, state), msg, id, name);
+        else handleQueryMessage(this.operationContext(conn, state), msg, id);
         break;
       case "execute":
-        handleExecuteMessage(this.operationContext(conn, state), msg, id);
+        if (name !== null) handleNamedExecuteMessage(this.namedContext(conn, state), msg, id, name);
+        else handleExecuteMessage(this.operationContext(conn, state), msg, id);
         break;
       case "transaction":
         handleTransactionMessage(this.operationContext(conn, state), msg, id);
@@ -1124,15 +2542,26 @@ var WSHandler = class {
         handleLoadMessage(this.operationContext(conn, state), msg, id);
         break;
       case "subscribe":
-        this.handleSubscribe(conn, state, msg, id);
+        if (name !== null) handleLiveSubscribeMessage(this.liveDeps(), conn, state, msg, id, name);
+        else handleSubscribeMessage(this.subscribeDeps(), conn, state, msg, id);
         break;
       case "unsubscribe":
         this.handleUnsubscribe(conn, state, id);
         break;
+      case "ack":
+        handleAckMessage(this.subscribeDeps(), conn, state, msg, id);
+        break;
       default:
         this.sendError(conn, id, "UNKNOWN_TYPE", `Unknown message type: '${msg.type}'`);
     }
   }
+  handleSocketDrain(conn) {
+    const state = this.connections.get(conn);
+    if (!state) return;
+    for (const stream of state.deviceStreams.values()) {
+      stream.onSocketDrain();
+    }
+  }
   handleClose(conn) {
     const state = this.connections.get(conn);
     if (!state) return;
@@ -1167,109 +2596,43 @@ var WSHandler = class {
       sendCaughtError: (id, err) => this.sendSirannonError(conn, id, err)
     };
   }
-  async handleSubscribe(conn, state, msg, id) {
-    if (typeof msg.table !== "string") {
-      this.sendError(conn, id, "INVALID_MESSAGE", 'Subscribe message requires a "table" string field');
-      return;
-    }
-    if (state.subscriptions.has(id)) {
-      this.sendError(conn, id, "DUPLICATE_SUBSCRIPTION", `Subscription '${id}' already exists on this connection`);
-      return;
-    }
-    if (state.database.readOnly) {
-      this.sendError(conn, id, "READ_ONLY", "Subscriptions are not available on read-only databases");
-      return;
-    }
-    if (state.database.path === ":memory:") {
-      this.sendError(conn, id, "CDC_UNSUPPORTED", "CDC subscriptions require file-based databases");
-      return;
-    }
-    if (msg.filter !== void 0 && msg.filter !== null && (typeof msg.filter !== "object" || Array.isArray(msg.filter))) {
-      this.sendError(conn, id, "INVALID_MESSAGE", '"filter" must be a plain object');
-      return;
-    }
-    const decodedFilter = decodeBoundParams(msg.filter, "filter");
-    if (!decodedFilter.ok) {
-      this.sendError(conn, id, "INVALID_MESSAGE", decodedFilter.message);
-      return;
-    }
-    const filter = decodedFilter.value;
-    let sinceSeq;
-    if (msg.sinceSeq !== void 0) {
-      if (typeof msg.sinceSeq !== "string" || !/^\d+$/.test(msg.sinceSeq)) {
-        this.sendError(conn, id, "INVALID_MESSAGE", '"sinceSeq" must be a non-negative integer string');
-        return;
-      }
-      sinceSeq = BigInt(msg.sinceSeq);
-    }
-    let clientEpoch;
-    if (msg.epoch !== void 0) {
-      if (typeof msg.epoch !== "string") {
-        this.sendError(conn, id, "INVALID_MESSAGE", '"epoch" must be a string');
-        return;
-      }
-      clientEpoch = msg.epoch;
-    }
-    if (sinceSeq === void 0) {
-      await this.subscribeLive(conn, state, id, msg.table, filter);
-      return;
-    }
-    await this.subscribeResuming(conn, state, id, msg.table, filter, sinceSeq, clientEpoch);
+  namedContext(conn, state) {
+    return {
+      ...this.operationContext(conn, state),
+      databaseId: state.databaseId,
+      identity: state.identity,
+      operations: this.operations
+    };
   }
-  async subscribeLive(conn, state, id, table, filter) {
-    try {
-      const ctx = await this.cdc.ensure(state.databaseId, state.database);
-      await ctx.tracker.watch(ctx.cdcConn, table);
-      const boundary = ctx.tracker.cursor;
-      const sub = ctx.manager.subscribe(table, filter, (event) => {
-        this.sendChange(conn, id, event);
-      });
-      state.subscriptions.set(id, sub);
-      this.send(conn, { type: "subscribed", id, seq: boundary.toString(), epoch: ctx.epoch });
-    } catch (err) {
-      this.cdc.maybeCleanup(state.databaseId);
-      this.sendSirannonError(conn, id, err);
-    }
+  liveDeps() {
+    return {
+      operations: this.operations,
+      sendSubscribedRows: (conn, id, rows) => this.send(conn, { type: "subscribed", id, rows }),
+      sendLive: (conn, message) => this.send(conn, message),
+      sendError: (conn, id, code, message) => this.sendError(conn, id, code, message),
+      sendSirannonError: (conn, id, err) => this.sendSirannonError(conn, id, err)
+    };
   }
-  async subscribeResuming(conn, state, id, table, filter, sinceSeq, clientEpoch) {
-    let ctx;
-    let primed;
-    let boundary;
-    let resync;
-    try {
-      ctx = await this.cdc.ensure(state.databaseId, state.database);
-      await ctx.tracker.watch(ctx.cdcConn, table);
-      boundary = ctx.tracker.cursor;
-      primed = new PrimedSubscription(
-        sinceSeq,
-        (event) => this.sendChange(conn, id, event),
-        () => this.handleOverload(conn)
-      );
-      const sub = ctx.manager.subscribe(table, filter, (event) => primed.onLiveEvent(event));
-      state.subscriptions.set(id, sub);
-      const minSeq = await ctx.tracker.getMinSeq(ctx.cdcConn);
-      const foreignEpoch = clientEpoch !== void 0 && clientEpoch !== ctx.epoch;
-      resync = foreignEpoch || needsResync(sinceSeq, minSeq, boundary);
-      this.send(conn, {
+  subscribeDeps() {
+    return {
+      cdc: this.cdc,
+      maxUnacknowledgedChanges: this.maxUnacknowledgedChanges,
+      sendSubscribed: (conn, id, seq, epoch, resync, maxUnacknowledgedChanges) => this.send(conn, {
         type: "subscribed",
         id,
-        seq: boundary.toString(),
-        epoch: ctx.epoch,
-        ...resync ? { resync: true } : {}
-      });
-    } catch (err) {
-      this.cdc.maybeCleanup(state.databaseId);
-      this.sendSirannonError(conn, id, err);
-      return;
-    }
-    if (!resync) {
-      try {
-        await primed.replay(ctx.tracker, ctx.cdcConn, table, filter, boundary);
-      } catch {
-        this.send(conn, { type: "subscribed", id, seq: boundary.toString(), epoch: ctx.epoch, resync: true });
-      }
-    }
-    primed.goLive();
+        seq,
+        epoch,
+        ...resync ? { resync: true } : {},
+        ...maxUnacknowledgedChanges !== void 0 ? { maxUnacknowledgedChanges } : {}
+      }),
+      sendResult: (conn, id, data) => this.send(conn, { type: "result", id, data }),
+      sendError: (conn, id, code, message) => this.sendError(conn, id, code, message),
+      sendSirannonError: (conn, id, err) => this.sendSirannonError(conn, id, err),
+      sendChange: (conn, id, event) => this.sendChange(conn, id, event),
+      sendText: (conn, data) => this.sendText(conn, data),
+      closeFaulted: (conn) => conn.close(1011, "Device stream failed"),
+      handleOverload: (conn) => this.handleOverload(conn)
+    };
   }
   handleUnsubscribe(conn, state, id) {
     const sub = state.subscriptions.get(id);
@@ -1311,18 +2674,14 @@ var WSHandler = class {
     this.sendError(conn, id, code, message);
   }
   sendChange(conn, subscriptionId, event) {
-    return this.send(conn, {
-      type: "change",
-      id: subscriptionId,
-      event: {
-        type: event.type,
-        table: event.table,
-        row: encodeTaggedValues(event.row),
-        oldRow: event.oldRow === void 0 ? void 0 : encodeTaggedValues(event.oldRow),
-        seq: event.seq.toString(),
-        timestamp: event.timestamp
-      }
-    });
+    return this.send(conn, { type: "change", id: subscriptionId, event: wireChangeEvent(event) });
+  }
+  sendText(conn, data) {
+    const outcome = conn.send(data);
+    if (outcome === "dropped") {
+      this.handleOverload(conn);
+    }
+    return outcome;
   }
 };
 function createWSHandler(sirannon, options) {
@@ -1330,17 +2689,14 @@ function createWSHandler(sirannon, options) {
 }
 
 // src/server/ws-route.ts
+var UNSUPPORTED_SUBPROTOCOL_MESSAGE = `The upgrade offered no subprotocol this server supports. Offer '${SIRANNON_WS_SUBPROTOCOL}' alongside any credential-bearing value, or offer none at all.`;
 function toSendOutcome(result) {
   if (result === 2) return "dropped";
   if (result === 0) return "buffered";
   return "sent";
 }
-function selectWebSocketProtocol(header) {
-  const [firstProtocol] = header.split(",");
-  return firstProtocol?.trim() ?? "";
-}
 function registerWebSocketRoute(options) {
-  const { app, wsHandler, onRequestHook } = options;
+  const { app, wsHandler, authenticateHook } = options;
   app.ws("/db/:id", {
     maxPayloadLength: options.maxBodyBytes,
     maxBackpressure: options.maxBackpressureBytes,
@@ -1352,7 +2708,7 @@ function registerWebSocketRoute(options) {
       const method = req.getMethod();
       const secWebSocketKey = req.getHeader("sec-websocket-key");
       const secWebSocketProtocol = req.getHeader("sec-websocket-protocol");
-      const selectedWebSocketProtocol = selectWebSocketProtocol(secWebSocketProtocol);
+      const negotiated = selectSubprotocol(secWebSocketProtocol);
       const secWebSocketExtensions = req.getHeader("sec-websocket-extensions");
       const headers = {};
       req.forEach((key, value) => {
@@ -1360,7 +2716,14 @@ function registerWebSocketRoute(options) {
       });
       const remoteAddress = decodeRemoteAddress(res);
       const abort = initAbortHandler(res);
-      if (!onRequestHook) {
+      if (!negotiated.ok) {
+        if (abort.claim()) {
+          sendError(res, 400, "UNSUPPORTED_SUBPROTOCOL", UNSUPPORTED_SUBPROTOCOL_MESSAGE);
+        }
+        return;
+      }
+      const selectedWebSocketProtocol = negotiated.protocol;
+      if (!authenticateHook) {
         if (abort.claim()) {
           res.upgrade(
             { databaseId: dbId },
@@ -1379,20 +2742,24 @@ function registerWebSocketRoute(options) {
         databaseId: dbId,
         remoteAddress
       };
-      runOnRequest(res, abort, ctx, onRequestHook).then((allowed) => {
-        if (!allowed || !abort.claim()) return;
-        res.upgrade(
-          { databaseId: dbId },
-          secWebSocketKey,
-          selectedWebSocketProtocol,
-          secWebSocketExtensions,
-          context
-        );
+      authenticateUpgrade(res, abort, ctx, authenticateHook).then((authenticated) => {
+        if (!authenticated.ok && !authenticated.refusal) return;
+        if (!abort.claim()) return;
+        const userData = authenticated.ok ? { databaseId: dbId, identity: authenticated.identity } : { databaseId: dbId, refusal: authenticated.refusal };
+        res.upgrade(userData, secWebSocketKey, selectedWebSocketProtocol, secWebSocketExtensions, context);
       }).catch(() => {
       });
     },
     open: (ws) => {
       const userData = ws.getUserData();
+      const refusal = userData.refusal;
+      if (refusal) {
+        try {
+          ws.end(refusal.code, refusal.reason);
+        } catch {
+        }
+        return;
+      }
       const conn = {
         send(data) {
           try {
@@ -1409,7 +2776,7 @@ function registerWebSocketRoute(options) {
         }
       };
       userData.conn = conn;
-      wsHandler.handleOpen(conn, userData.databaseId).catch(() => {
+      wsHandler.handleOpen(conn, userData.databaseId, userData.identity).catch(() => {
       });
     },
     message: (ws, message) => {
@@ -1424,6 +2791,12 @@ function registerWebSocketRoute(options) {
         wsHandler.handleOverload(userData.conn);
       }
     },
+    drain: (ws) => {
+      const userData = ws.getUserData();
+      if (userData.conn) {
+        wsHandler.handleSocketDrain(userData.conn);
+      }
+    },
     close: (ws) => {
       const userData = ws.getUserData();
       if (!userData.conn) return;
@@ -1434,6 +2807,10 @@ function registerWebSocketRoute(options) {
 }
 
 // src/server/server.ts
+var SQL_ROUTES = ["/db/:id/query", "/db/:id/execute", "/db/:id/transaction", "/db/:id/batch", "/db/:id/load"];
+function refuseSql(res) {
+  sendError(res, 403, "SQL_NOT_ACCEPTED", SQL_NOT_ACCEPTED_MESSAGE);
+}
 var DEFAULT_MAX_BODY_BYTES = 1048576;
 var DEFAULT_WS_BACKPRESSURE_BYTES = 16 * 1048576;
 var UWS_MAX_LIMIT_BYTES = 4294967295;
@@ -1481,10 +2858,14 @@ var SirannonServer = class {
   host;
   port;
   cors;
-  onRequestHook;
+  authenticateHook;
+  acceptSql;
+  operations;
+  registryDigest;
   resolveExecutionTarget;
   getReplicationStatus;
   getClusterStatus;
+  authorizeClusterStatus;
   sirannon;
   wsHandler;
   maxBodyBytes;
@@ -1494,16 +2875,24 @@ var SirannonServer = class {
     this.host = options?.host ?? "127.0.0.1";
     this.port = options?.port ?? 9876;
     this.cors = resolveCors(options?.cors);
-    this.onRequestHook = options?.onRequest;
+    this.authenticateHook = options?.authenticate;
+    this.acceptSql = options?.acceptSql === true;
+    this.operations = options?.operations;
+    this.registryDigest = operationRegistryDigest(options?.operations);
     this.resolveExecutionTarget = options?.resolveExecutionTarget;
     this.getReplicationStatus = options?.getReplicationStatus;
     this.getClusterStatus = options?.getClusterStatus;
+    this.authorizeClusterStatus = options?.authorizeClusterStatus;
     this.maxBodyBytes = resolveMaxBodyBytes(options?.maxBodyBytes);
     this.maxWsBackpressureBytes = resolveWsBackpressure(options?.maxWebSocketBackpressureBytes, this.maxBodyBytes);
     this.wsHandler = new WSHandler(sirannon, {
       resolveExecutionTarget: this.resolveExecutionTarget,
       maxPayloadLength: this.maxBodyBytes,
-      cdcRetentionMs: options?.cdcRetentionMs
+      cdcRetentionMs: options?.cdcRetentionMs,
+      deviceCursorRetentionMs: options?.deviceCursorRetentionMs,
+      maxUnacknowledgedChanges: options?.maxUnacknowledgedChanges,
+      acceptSql: this.acceptSql,
+      operations: options?.operations
     });
     this.app = uWS.App();
     this.registerRoutes();
@@ -1546,17 +2935,42 @@ var SirannonServer = class {
         });
       });
     }
+    this.app.get(
+      "/capabilities",
+      this.withCors(handleCapabilities({ registryDigest: this.registryDigest, acceptSql: this.acceptSql }))
+    );
     this.app.get("/health", this.withCors(handleLiveness()));
     this.app.get("/health/ready", this.withCors(handleReadiness(this.sirannon, this.getReplicationStatus)));
-    this.app.get("/db/:id/cluster", this.wrapDbGetRoute(handleClusterStatus(this.getClusterStatus)));
-    this.app.post("/db/:id/query", this.wrapDbRoute(handleQuery(this.sirannon, this.resolveExecutionTarget)));
-    this.app.post("/db/:id/execute", this.wrapDbRoute(handleExecute(this.sirannon, this.resolveExecutionTarget)));
+    this.app.get(
+      "/db/:id/cluster",
+      this.wrapDbGetRoute(handleClusterStatus(this.getClusterStatus, this.authorizeClusterStatus))
+    );
+    if (this.acceptSql) {
+      this.app.post("/db/:id/query", this.wrapDbRoute(handleQuery(this.sirannon, this.resolveExecutionTarget)));
+      this.app.post("/db/:id/execute", this.wrapDbRoute(handleExecute(this.sirannon, this.resolveExecutionTarget)));
+      this.app.post(
+        "/db/:id/transaction",
+        this.wrapDbRoute(handleTransaction(this.sirannon, this.resolveExecutionTarget))
+      );
+      this.app.post("/db/:id/batch", this.wrapDbRoute(handleBatch(this.sirannon, this.resolveExecutionTarget)));
+      this.app.post("/db/:id/load", this.wrapDbRoute(handleLoad(this.sirannon, this.resolveExecutionTarget)));
+    } else {
+      for (const route of SQL_ROUTES) {
+        this.app.post(route, this.withCors(refuseSql));
+      }
+    }
+    this.app.post(
+      "/db/:id/query/:name",
+      this.wrapOperationRoute(handleOperationQuery(this.sirannon, this.operations, this.resolveExecutionTarget))
+    );
     this.app.post(
-      "/db/:id/transaction",
-      this.wrapDbRoute(handleTransaction(this.sirannon, this.resolveExecutionTarget))
+      "/db/:id/execute/:name",
+      this.wrapOperationRoute(handleOperationExecute(this.sirannon, this.operations, this.resolveExecutionTarget))
     );
-    this.app.post("/db/:id/batch", this.wrapDbRoute(handleBatch(this.sirannon, this.resolveExecutionTarget)));
-    this.app.post("/db/:id/load", this.wrapDbRoute(handleLoad(this.sirannon, this.resolveExecutionTarget)));
+    this.app.post("/db/:id/changes", this.wrapDbRoute(handleChanges(this.sirannon, this.resolveExecutionTarget)));
+    this.app.post("/db/:id/migrations", this.wrapDbRoute(handleMigrationList(this.sirannon)));
+    this.app.post("/db/:id/snapshot", this.wrapDbRoute(handleSnapshotManifest(this.sirannon)));
+    this.app.post("/db/:id/snapshot/page", this.wrapDbRoute(handleSnapshotPage(this.sirannon)));
     this.registerWebSocketRoute();
     this.app.any("/*", (res) => {
       sendError(res, 404, "NOT_FOUND", "Route not found");
@@ -1566,7 +2980,7 @@ var SirannonServer = class {
     registerWebSocketRoute({
       app: this.app,
       wsHandler: this.wsHandler,
-      onRequestHook: this.onRequestHook,
+      authenticateHook: this.authenticateHook,
       maxBodyBytes: this.maxBodyBytes,
       maxBackpressureBytes: this.maxWsBackpressureBytes
     });
@@ -1580,7 +2994,7 @@ var SirannonServer = class {
     };
   }
   wrapDbRoute(handler) {
-    const onRequestHook = this.onRequestHook;
+    const authenticateHook = this.authenticateHook;
     const corsHeaders = this.cors;
     const maxBody = this.maxBodyBytes;
     return (res, req) => {
@@ -1592,7 +3006,7 @@ var SirannonServer = class {
       }
       const abort = initAbortHandler(res);
       const bodyPromise = readBody(res, maxBody, abort);
-      if (!onRequestHook) {
+      if (!authenticateHook) {
         bodyPromise.then(async (rawBody) => {
           if (!abort.claim()) return;
           try {
@@ -1618,9 +3032,9 @@ var SirannonServer = class {
         databaseId: dbId,
         remoteAddress
       };
-      const hookPromise = runOnRequest(res, abort, ctx, onRequestHook);
-      Promise.all([bodyPromise, hookPromise]).then(async ([rawBody, allowed]) => {
-        if (!allowed || !abort.claim()) return;
+      const hookPromise = runAuthenticate(res, abort, ctx, authenticateHook);
+      Promise.all([bodyPromise, hookPromise]).then(async ([rawBody, authenticated]) => {
+        if (!authenticated.ok || !abort.claim()) return;
         try {
           await handler(res, dbId, rawBody, abort);
         } catch {
@@ -1632,8 +3046,18 @@ var SirannonServer = class {
       });
     };
   }
+  wrapOperationRoute(handler) {
+    return wrapOperationRoute(
+      {
+        cors: this.cors,
+        maxBodyBytes: this.maxBodyBytes,
+        authenticateHook: this.authenticateHook
+      },
+      handler
+    );
+  }
   wrapDbGetRoute(handler) {
-    const onRequestHook = this.onRequestHook;
+    const authenticateHook = this.authenticateHook;
     const corsHeaders = this.cors;
     return (res, req) => {
       const dbId = req.getParameter(0) ?? "";
@@ -1642,10 +3066,6 @@ var SirannonServer = class {
       if (corsHeaders) {
         writeCorsOrigin(res, corsHeaders, req.getHeader("origin"));
       }
-      if (!onRequestHook) {
-        handler(res, dbId);
-        return;
-      }
       const headers = {};
       req.forEach((key, value) => {
         headers[key] = value;
@@ -1658,10 +3078,18 @@ var SirannonServer = class {
         remoteAddress: decodeRemoteAddress(res)
       };
       const abort = initAbortHandler(res);
-      runOnRequest(res, abort, ctx, onRequestHook).then((allowed) => {
-        if (!allowed || !abort.claim()) return;
-        handler(res, dbId);
-      }).catch(() => {
+      const run = async () => {
+        if (authenticateHook && !(await runAuthenticate(res, abort, ctx, authenticateHook)).ok) return;
+        if (!abort.claim()) return;
+        try {
+          await handler(res, dbId, ctx, abort);
+        } catch {
+          if (!abort.aborted) {
+            sendError(res, 500, "INTERNAL_ERROR", "An unexpected error occurred");
+          }
+        }
+      };
+      run().catch(() => {
       });
     };
   }