lakesync 0.1.0

package/dist/chunk-5YOFCJQ7.js

@@ -0,0 +1,1115 @@
+import {
+  isDatabaseAdapter
+} from "./chunk-X3RO5SYJ.js";
+import {
+  buildPartitionSpec,
+  lakeSyncTableName,
+  tableSchemaToIceberg
+} from "./chunk-P5DRFKIT.js";
+import {
+  writeDeltasToParquet
+} from "./chunk-4ARO6KTJ.js";
+import {
+  AdapterNotFoundError,
+  BackpressureError,
+  Err,
+  FlushError,
+  HLC,
+  Ok,
+  SchemaError,
+  bigintReplacer,
+  bigintReviver,
+  filterDeltas,
+  resolveLWW,
+  rowKey,
+  toError,
+  validateAction,
+  validateConnectorConfig,
+  validateSyncRules
+} from "./chunk-ICNT7I3K.js";
+
+// ../gateway/src/action-dispatcher.ts
+var ActionDispatcher = class {
+  actionHandlers = /* @__PURE__ */ new Map();
+  executedActions = /* @__PURE__ */ new Set();
+  idempotencyMap = /* @__PURE__ */ new Map();
+  constructor(handlers) {
+    if (handlers) {
+      for (const [name, handler] of Object.entries(handlers)) {
+        this.actionHandlers.set(name, handler);
+      }
+    }
+  }
+  /**
+   * Dispatch an action push to registered handlers.
+   *
+   * Iterates over actions, dispatches each to the registered ActionHandler
+   * by connector name. Supports idempotency via actionId deduplication and
+   * idempotencyKey mapping.
+   *
+   * @param msg - The action push containing one or more actions.
+   * @param hlcNow - Callback to get the current server HLC timestamp.
+   * @param context - Optional auth context for permission checks.
+   * @returns A `Result` containing results for each action.
+   */
+  async dispatch(msg, hlcNow, context) {
+    const results = [];
+    for (const action of msg.actions) {
+      const validation = validateAction(action);
+      if (!validation.ok) {
+        return Err(validation.error);
+      }
+      if (this.executedActions.has(action.actionId)) {
+        const cached = this.idempotencyMap.get(action.actionId);
+        if (cached) {
+          results.push(cached);
+          continue;
+        }
+        continue;
+      }
+      if (action.idempotencyKey) {
+        const cached = this.idempotencyMap.get(`idem:${action.idempotencyKey}`);
+        if (cached) {
+          results.push(cached);
+          continue;
+        }
+      }
+      const handler = this.actionHandlers.get(action.connector);
+      if (!handler) {
+        const errorResult = {
+          actionId: action.actionId,
+          code: "ACTION_NOT_SUPPORTED",
+          message: `No action handler registered for connector "${action.connector}"`,
+          retryable: false
+        };
+        results.push(errorResult);
+        this.cacheActionResult(action, errorResult);
+        continue;
+      }
+      const supported = handler.supportedActions.some((d) => d.actionType === action.actionType);
+      if (!supported) {
+        const errorResult = {
+          actionId: action.actionId,
+          code: "ACTION_NOT_SUPPORTED",
+          message: `Action type "${action.actionType}" not supported by connector "${action.connector}"`,
+          retryable: false
+        };
+        results.push(errorResult);
+        this.cacheActionResult(action, errorResult);
+        continue;
+      }
+      const execResult = await handler.executeAction(action, context);
+      if (execResult.ok) {
+        results.push(execResult.value);
+        this.cacheActionResult(action, execResult.value);
+      } else {
+        const err = execResult.error;
+        const errorResult = {
+          actionId: action.actionId,
+          code: err.code,
+          message: err.message,
+          retryable: "retryable" in err ? err.retryable : false
+        };
+        results.push(errorResult);
+        if (!errorResult.retryable) {
+          this.cacheActionResult(action, errorResult);
+        }
+      }
+    }
+    const serverHlc = hlcNow();
+    return Ok({ results, serverHlc });
+  }
+  /**
+   * Register a named action handler.
+   *
+   * @param name - Connector name (matches `Action.connector`).
+   * @param handler - The action handler to register.
+   */
+  registerHandler(name, handler) {
+    this.actionHandlers.set(name, handler);
+  }
+  /**
+   * Unregister a named action handler.
+   *
+   * @param name - The connector name to remove.
+   */
+  unregisterHandler(name) {
+    this.actionHandlers.delete(name);
+  }
+  /**
+   * List all registered action handler names.
+   *
+   * @returns Array of registered connector names.
+   */
+  listHandlers() {
+    return [...this.actionHandlers.keys()];
+  }
+  /**
+   * Describe all registered action handlers and their supported actions.
+   *
+   * Returns a map of connector name to its {@link ActionDescriptor} array,
+   * enabling frontend discovery of available actions.
+   *
+   * @returns An {@link ActionDiscovery} object listing connectors and their actions.
+   */
+  describe() {
+    const connectors = {};
+    for (const [name, handler] of this.actionHandlers) {
+      connectors[name] = handler.supportedActions;
+    }
+    return { connectors };
+  }
+  /** Cache an action result for idempotency deduplication. */
+  cacheActionResult(action, result) {
+    this.executedActions.add(action.actionId);
+    this.idempotencyMap.set(action.actionId, result);
+    if (action.idempotencyKey) {
+      this.idempotencyMap.set(`idem:${action.idempotencyKey}`, result);
+    }
+  }
+};
+
+// ../gateway/src/buffer.ts
+var BASE_DELTA_OVERHEAD = 8 + 8 + 8 + 8 + 1;
+function estimateValueBytes(value) {
+  if (value === null || value === void 0) return 4;
+  switch (typeof value) {
+    case "boolean":
+      return 4;
+    case "number":
+      return 8;
+    case "bigint":
+      return 8;
+    case "string":
+      return value.length * 2;
+    // UTF-16
+    default:
+      try {
+        return JSON.stringify(value).length;
+      } catch {
+        return 100;
+      }
+  }
+}
+function estimateDeltaBytes(delta) {
+  let bytes = BASE_DELTA_OVERHEAD;
+  bytes += delta.deltaId.length;
+  bytes += delta.table.length * 2;
+  bytes += delta.rowId.length * 2;
+  bytes += delta.clientId.length * 2;
+  for (const col of delta.columns) {
+    bytes += col.column.length * 2;
+    bytes += estimateValueBytes(col.value);
+  }
+  return bytes;
+}
+var DeltaBuffer = class {
+  log = [];
+  index = /* @__PURE__ */ new Map();
+  deltaIds = /* @__PURE__ */ new Set();
+  estimatedBytes = 0;
+  createdAt = Date.now();
+  tableBytes = /* @__PURE__ */ new Map();
+  tableLog = /* @__PURE__ */ new Map();
+  /** Append a delta to the log and upsert the index (post-conflict-resolution). */
+  append(delta) {
+    this.log.push(delta);
+    const key = rowKey(delta.table, delta.rowId);
+    this.index.set(key, delta);
+    this.deltaIds.add(delta.deltaId);
+    const bytes = estimateDeltaBytes(delta);
+    this.estimatedBytes += bytes;
+    this.tableBytes.set(delta.table, (this.tableBytes.get(delta.table) ?? 0) + bytes);
+    const tableEntries = this.tableLog.get(delta.table);
+    if (tableEntries) {
+      tableEntries.push(delta);
+    } else {
+      this.tableLog.set(delta.table, [delta]);
+    }
+  }
+  /** Get the current merged state for a row (for conflict resolution). */
+  getRow(key) {
+    return this.index.get(key);
+  }
+  /** Check if a delta with this ID already exists in the log (for idempotency). */
+  hasDelta(deltaId) {
+    return this.deltaIds.has(deltaId);
+  }
+  /** Return change events from the log since a given HLC. */
+  getEventsSince(hlc, limit) {
+    let lo = 0;
+    let hi = this.log.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (HLC.compare(this.log[mid].hlc, hlc) <= 0) {
+        lo = mid + 1;
+      } else {
+        hi = mid;
+      }
+    }
+    const hasMore = this.log.length - lo > limit;
+    return { deltas: this.log.slice(lo, lo + limit), hasMore };
+  }
+  /** Check if the buffer should be flushed based on size or age thresholds. */
+  shouldFlush(config) {
+    if (this.log.length === 0) return false;
+    return this.estimatedBytes >= config.maxBytes || Date.now() - this.createdAt >= config.maxAgeMs;
+  }
+  /** Per-table buffer statistics. */
+  tableStats() {
+    const stats = [];
+    for (const [table, bytes] of this.tableBytes) {
+      stats.push({
+        table,
+        byteSize: bytes,
+        deltaCount: this.tableLog.get(table)?.length ?? 0
+      });
+    }
+    return stats;
+  }
+  /** Drain only the specified table's deltas, leaving other tables intact. */
+  drainTable(table) {
+    const tableDeltas = this.tableLog.get(table) ?? [];
+    if (tableDeltas.length === 0) return [];
+    this.log = this.log.filter((d) => d.table !== table);
+    for (const delta of tableDeltas) {
+      this.index.delete(rowKey(delta.table, delta.rowId));
+      this.deltaIds.delete(delta.deltaId);
+    }
+    const tableByteSize = this.tableBytes.get(table) ?? 0;
+    this.estimatedBytes -= tableByteSize;
+    this.tableBytes.delete(table);
+    this.tableLog.delete(table);
+    return tableDeltas;
+  }
+  /** Drain the log for flush. Returns log entries and clears both structures. */
+  drain() {
+    const entries = [...this.log];
+    this.log = [];
+    this.index.clear();
+    this.deltaIds.clear();
+    this.estimatedBytes = 0;
+    this.createdAt = Date.now();
+    this.tableBytes.clear();
+    this.tableLog.clear();
+    return entries;
+  }
+  /** Number of log entries */
+  get logSize() {
+    return this.log.length;
+  }
+  /** Number of unique rows in the index */
+  get indexSize() {
+    return this.index.size;
+  }
+  /** Estimated byte size of the buffer */
+  get byteSize() {
+    return this.estimatedBytes;
+  }
+  /** Average byte size per delta in the buffer (0 if empty). */
+  get averageDeltaBytes() {
+    return this.log.length === 0 ? 0 : this.estimatedBytes / this.log.length;
+  }
+};
+
+// ../gateway/src/config-store.ts
+var MemoryConfigStore = class {
+  schemas = /* @__PURE__ */ new Map();
+  syncRules = /* @__PURE__ */ new Map();
+  connectors = {};
+  async getSchema(gatewayId) {
+    return this.schemas.get(gatewayId);
+  }
+  async setSchema(gatewayId, schema) {
+    this.schemas.set(gatewayId, schema);
+  }
+  async getSyncRules(gatewayId) {
+    return this.syncRules.get(gatewayId);
+  }
+  async setSyncRules(gatewayId, rules) {
+    this.syncRules.set(gatewayId, rules);
+  }
+  async getConnectors() {
+    return { ...this.connectors };
+  }
+  async setConnectors(connectors) {
+    this.connectors = { ...connectors };
+  }
+};
+
+// ../gateway/src/constants.ts
+var MAX_PUSH_PAYLOAD_BYTES = 1048576;
+var MAX_DELTAS_PER_PUSH = 1e4;
+var MAX_PULL_LIMIT = 1e4;
+var DEFAULT_PULL_LIMIT = 100;
+var VALID_COLUMN_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "json", "null"]);
+var DEFAULT_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
+var DEFAULT_MAX_BUFFER_AGE_MS = 3e4;
+
+// ../gateway/src/flush.ts
+function hlcRange(entries) {
+  let min = entries[0].hlc;
+  let max = entries[0].hlc;
+  for (let i = 1; i < entries.length; i++) {
+    const hlc = entries[i].hlc;
+    if (HLC.compare(hlc, min) < 0) min = hlc;
+    if (HLC.compare(hlc, max) > 0) max = hlc;
+  }
+  return { min, max };
+}
+async function flushEntries(entries, byteSize, deps, keyPrefix) {
+  if (isDatabaseAdapter(deps.adapter)) {
+    try {
+      const result = await deps.adapter.insertDeltas(entries);
+      if (!result.ok) {
+        deps.restoreEntries(entries);
+        return Err(new FlushError(`Database flush failed: ${result.error.message}`));
+      }
+      return Ok(void 0);
+    } catch (error) {
+      deps.restoreEntries(entries);
+      return Err(new FlushError(`Unexpected database flush failure: ${toError(error).message}`));
+    }
+  }
+  try {
+    const { min, max } = hlcRange(entries);
+    const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const prefix = keyPrefix ? `${keyPrefix}-` : "";
+    let objectKey;
+    let data;
+    let contentType;
+    if (deps.config.flushFormat === "json") {
+      const envelope = {
+        version: 1,
+        gatewayId: deps.config.gatewayId,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        hlcRange: { min, max },
+        deltaCount: entries.length,
+        byteSize,
+        deltas: entries
+      };
+      objectKey = `deltas/${date}/${deps.config.gatewayId}/${prefix}${min.toString()}-${max.toString()}.json`;
+      data = new TextEncoder().encode(JSON.stringify(envelope, bigintReplacer));
+      contentType = "application/json";
+    } else {
+      if (!deps.config.tableSchema) {
+        deps.restoreEntries(entries);
+        return Err(new FlushError("tableSchema required for Parquet flush"));
+      }
+      const parquetResult = await writeDeltasToParquet(entries, deps.config.tableSchema);
+      if (!parquetResult.ok) {
+        deps.restoreEntries(entries);
+        return Err(parquetResult.error);
+      }
+      objectKey = `deltas/${date}/${deps.config.gatewayId}/${prefix}${min.toString()}-${max.toString()}.parquet`;
+      data = parquetResult.value;
+      contentType = "application/vnd.apache.parquet";
+    }
+    const result = await deps.adapter.putObject(objectKey, data, contentType);
+    if (!result.ok) {
+      deps.restoreEntries(entries);
+      return Err(new FlushError(`Failed to write flush envelope: ${result.error.message}`));
+    }
+    if (deps.config.catalogue && deps.config.tableSchema) {
+      await commitToCatalogue(
+        objectKey,
+        data.byteLength,
+        entries.length,
+        deps.config.catalogue,
+        deps.config.tableSchema
+      );
+    }
+    return Ok(void 0);
+  } catch (error) {
+    deps.restoreEntries(entries);
+    return Err(new FlushError(`Unexpected flush failure: ${toError(error).message}`));
+  }
+}
+async function commitToCatalogue(objectKey, fileSizeInBytes, recordCount, catalogue, schema) {
+  const { namespace, name } = lakeSyncTableName(schema.table);
+  const icebergSchema = tableSchemaToIceberg(schema);
+  const partitionSpec = buildPartitionSpec(icebergSchema);
+  await catalogue.createNamespace(namespace);
+  const createResult = await catalogue.createTable(namespace, name, icebergSchema, partitionSpec);
+  if (!createResult.ok && createResult.error.statusCode !== 409) {
+    return;
+  }
+  const dataFile = {
+    content: "data",
+    "file-path": objectKey,
+    "file-format": "PARQUET",
+    "record-count": recordCount,
+    "file-size-in-bytes": fileSizeInBytes
+  };
+  const appendResult = await catalogue.appendFiles(namespace, name, [dataFile]);
+  if (!appendResult.ok && appendResult.error.statusCode === 409) {
+    await catalogue.appendFiles(namespace, name, [dataFile]);
+  }
+}
+
+// ../gateway/src/gateway.ts
+var SyncGateway = class {
+  hlc;
+  buffer;
+  actions;
+  config;
+  adapter;
+  flushing = false;
+  constructor(config, adapter) {
+    this.config = { sourceAdapters: {}, ...config };
+    this.hlc = new HLC();
+    this.buffer = new DeltaBuffer();
+    this.adapter = this.config.adapter ?? adapter ?? null;
+    this.actions = new ActionDispatcher(config.actionHandlers);
+  }
+  /** Restore drained entries back to the buffer for retry. */
+  restoreEntries(entries) {
+    for (const entry of entries) {
+      this.buffer.append(entry);
+    }
+  }
+  /**
+   * Handle an incoming push from a client.
+   *
+   * Validates HLC drift, resolves conflicts via LWW, and appends to the buffer.
+   *
+   * @param msg - The push message containing client deltas.
+   * @returns A `Result` with the new server HLC and accepted count,
+   *          or a `ClockDriftError` if the client clock is too far ahead.
+   */
+  handlePush(msg) {
+    const backpressureLimit = this.config.maxBackpressureBytes ?? this.config.maxBufferBytes * 2;
+    if (this.buffer.byteSize >= backpressureLimit) {
+      return Err(
+        new BackpressureError(
+          `Buffer backpressure exceeded (${this.buffer.byteSize} >= ${backpressureLimit} bytes)`
+        )
+      );
+    }
+    let accepted = 0;
+    const ingested = [];
+    for (const delta of msg.deltas) {
+      if (this.buffer.hasDelta(delta.deltaId)) {
+        accepted++;
+        continue;
+      }
+      if (this.config.schemaManager) {
+        const schemaResult = this.config.schemaManager.validateDelta(delta);
+        if (!schemaResult.ok) {
+          return Err(schemaResult.error);
+        }
+      }
+      const recvResult = this.hlc.recv(delta.hlc);
+      if (!recvResult.ok) {
+        return Err(recvResult.error);
+      }
+      const key = rowKey(delta.table, delta.rowId);
+      const existing = this.buffer.getRow(key);
+      if (existing) {
+        const resolved = resolveLWW(existing, delta);
+        if (resolved.ok) {
+          this.buffer.append(resolved.value);
+          ingested.push(resolved.value);
+        }
+      } else {
+        this.buffer.append(delta);
+        ingested.push(delta);
+      }
+      accepted++;
+    }
+    const serverHlc = this.hlc.now();
+    return Ok({ serverHlc, accepted, deltas: ingested });
+  }
+  handlePull(msg, context) {
+    if (msg.source) {
+      return this.handleAdapterPull(msg, context);
+    }
+    return this.handleBufferPull(msg, context);
+  }
+  /** Pull from the in-memory buffer (original path). */
+  handleBufferPull(msg, context) {
+    if (!context) {
+      const { deltas, hasMore: hasMore2 } = this.buffer.getEventsSince(msg.sinceHlc, msg.maxDeltas);
+      const serverHlc2 = this.hlc.now();
+      return Ok({ deltas, serverHlc: serverHlc2, hasMore: hasMore2 });
+    }
+    const maxRetries = 5;
+    const overFetchMultiplier = 3;
+    let cursor = msg.sinceHlc;
+    const collected = [];
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      const fetchLimit = msg.maxDeltas * overFetchMultiplier;
+      const { deltas: raw, hasMore: rawHasMore } = this.buffer.getEventsSince(cursor, fetchLimit);
+      if (raw.length === 0) {
+        const serverHlc2 = this.hlc.now();
+        return Ok({ deltas: collected, serverHlc: serverHlc2, hasMore: false });
+      }
+      const filtered = filterDeltas(raw, context);
+      collected.push(...filtered);
+      if (collected.length >= msg.maxDeltas) {
+        const trimmed2 = collected.slice(0, msg.maxDeltas);
+        const serverHlc2 = this.hlc.now();
+        return Ok({ deltas: trimmed2, serverHlc: serverHlc2, hasMore: true });
+      }
+      if (!rawHasMore) {
+        const serverHlc2 = this.hlc.now();
+        return Ok({ deltas: collected, serverHlc: serverHlc2, hasMore: false });
+      }
+      cursor = raw[raw.length - 1].hlc;
+    }
+    const serverHlc = this.hlc.now();
+    const hasMore = collected.length >= msg.maxDeltas;
+    const trimmed = collected.slice(0, msg.maxDeltas);
+    return Ok({ deltas: trimmed, serverHlc, hasMore });
+  }
+  /** Pull from a named source adapter. */
+  async handleAdapterPull(msg, context) {
+    const adapter = this.config.sourceAdapters?.[msg.source];
+    if (!adapter) {
+      return Err(new AdapterNotFoundError(`Source adapter "${msg.source}" not found`));
+    }
+    const queryResult = await adapter.queryDeltasSince(msg.sinceHlc);
+    if (!queryResult.ok) {
+      return Err(queryResult.error);
+    }
+    let deltas = queryResult.value;
+    if (context) {
+      deltas = filterDeltas(deltas, context);
+    }
+    const hasMore = deltas.length > msg.maxDeltas;
+    const sliced = deltas.slice(0, msg.maxDeltas);
+    const serverHlc = this.hlc.now();
+    return Ok({ deltas: sliced, serverHlc, hasMore });
+  }
+  // -----------------------------------------------------------------------
+  // Flush — delegates to flush module
+  // -----------------------------------------------------------------------
+  /**
+   * Flush the buffer to the configured adapter.
+   *
+   * Writes deltas as either a Parquet file (default) or a JSON
+   * {@link FlushEnvelope} to the adapter, depending on
+   * `config.flushFormat`. If the write fails, the buffer entries
+   * are restored so they can be retried.
+   *
+   * @returns A `Result` indicating success or a `FlushError`.
+   */
+  async flush() {
+    if (this.flushing) {
+      return Err(new FlushError("Flush already in progress"));
+    }
+    if (this.buffer.logSize === 0) {
+      return Ok(void 0);
+    }
+    if (!this.adapter) {
+      return Err(new FlushError("No adapter configured"));
+    }
+    this.flushing = true;
+    if (isDatabaseAdapter(this.adapter)) {
+      const entries2 = this.buffer.drain();
+      if (entries2.length === 0) {
+        this.flushing = false;
+        return Ok(void 0);
+      }
+      try {
+        return await flushEntries(entries2, 0, {
+          adapter: this.adapter,
+          config: {
+            gatewayId: this.config.gatewayId,
+            flushFormat: this.config.flushFormat,
+            tableSchema: this.config.tableSchema,
+            catalogue: this.config.catalogue
+          },
+          restoreEntries: (e) => this.restoreEntries(e)
+        });
+      } finally {
+        this.flushing = false;
+      }
+    }
+    const byteSize = this.buffer.byteSize;
+    const entries = this.buffer.drain();
+    try {
+      return await flushEntries(entries, byteSize, {
+        adapter: this.adapter,
+        config: {
+          gatewayId: this.config.gatewayId,
+          flushFormat: this.config.flushFormat,
+          tableSchema: this.config.tableSchema,
+          catalogue: this.config.catalogue
+        },
+        restoreEntries: (e) => this.restoreEntries(e)
+      });
+    } finally {
+      this.flushing = false;
+    }
+  }
+  /**
+   * Flush a single table's deltas from the buffer.
+   *
+   * Drains only the specified table's deltas and flushes them,
+   * leaving other tables in the buffer.
+   */
+  async flushTable(table) {
+    if (this.flushing) {
+      return Err(new FlushError("Flush already in progress"));
+    }
+    if (!this.adapter) {
+      return Err(new FlushError("No adapter configured"));
+    }
+    const entries = this.buffer.drainTable(table);
+    if (entries.length === 0) {
+      return Ok(void 0);
+    }
+    this.flushing = true;
+    try {
+      return await flushEntries(
+        entries,
+        0,
+        {
+          adapter: this.adapter,
+          config: {
+            gatewayId: this.config.gatewayId,
+            flushFormat: this.config.flushFormat,
+            tableSchema: this.config.tableSchema,
+            catalogue: this.config.catalogue
+          },
+          restoreEntries: (e) => this.restoreEntries(e)
+        },
+        table
+      );
+    } finally {
+      this.flushing = false;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Actions — delegates to ActionDispatcher
+  // -----------------------------------------------------------------------
+  /** Handle an incoming action push from a client. */
+  async handleAction(msg, context) {
+    return this.actions.dispatch(msg, () => this.hlc.now(), context);
+  }
+  /** Register a named action handler. */
+  registerActionHandler(name, handler) {
+    this.actions.registerHandler(name, handler);
+  }
+  /** Unregister a named action handler. */
+  unregisterActionHandler(name) {
+    this.actions.unregisterHandler(name);
+  }
+  /** List all registered action handler names. */
+  listActionHandlers() {
+    return this.actions.listHandlers();
+  }
+  /** Describe all registered action handlers and their supported actions. */
+  describeActions() {
+    return this.actions.describe();
+  }
+  // -----------------------------------------------------------------------
+  // Source adapters
+  // -----------------------------------------------------------------------
+  /**
+   * Register a named source adapter for adapter-sourced pulls.
+   *
+   * @param name - Unique source name (used as the `source` parameter in pull requests).
+   * @param adapter - The database adapter to register.
+   */
+  registerSource(name, adapter) {
+    this.config.sourceAdapters[name] = adapter;
+  }
+  /**
+   * Unregister a named source adapter.
+   *
+   * @param name - The source name to remove.
+   */
+  unregisterSource(name) {
+    delete this.config.sourceAdapters[name];
+  }
+  /**
+   * List all registered source adapter names.
+   *
+   * @returns Array of registered source adapter names.
+   */
+  listSources() {
+    return Object.keys(this.config.sourceAdapters);
+  }
+  // -----------------------------------------------------------------------
+  // Buffer queries
+  // -----------------------------------------------------------------------
+  /** Get per-table buffer statistics. */
+  get tableStats() {
+    return this.buffer.tableStats();
+  }
+  /**
+   * Get tables that exceed the per-table budget.
+   */
+  getTablesExceedingBudget() {
+    const budget = this.config.perTableBudgetBytes;
+    if (!budget) return [];
+    return this.buffer.tableStats().filter((s) => s.byteSize >= budget).map((s) => s.table);
+  }
+  /** Check if the buffer should be flushed based on config thresholds. */
+  shouldFlush() {
+    let effectiveMaxBytes = this.config.maxBufferBytes;
+    const adaptive = this.config.adaptiveBufferConfig;
+    if (adaptive && this.buffer.averageDeltaBytes > adaptive.wideColumnThreshold) {
+      effectiveMaxBytes = Math.floor(effectiveMaxBytes * adaptive.reductionFactor);
+    }
+    return this.buffer.shouldFlush({
+      maxBytes: effectiveMaxBytes,
+      maxAgeMs: this.config.maxBufferAgeMs
+    });
+  }
+  /** Get buffer statistics for monitoring. */
+  get bufferStats() {
+    return {
+      logSize: this.buffer.logSize,
+      indexSize: this.buffer.indexSize,
+      byteSize: this.buffer.byteSize
+    };
+  }
+};
+
+// ../gateway/src/validation.ts
+function validatePushBody(raw, headerClientId) {
+  let body;
+  try {
+    body = JSON.parse(raw, bigintReviver);
+  } catch {
+    return Err({ status: 400, message: "Invalid JSON body" });
+  }
+  if (!body.clientId || !Array.isArray(body.deltas)) {
+    return Err({ status: 400, message: "Missing required fields: clientId, deltas" });
+  }
+  if (headerClientId && body.clientId !== headerClientId) {
+    return Err({
+      status: 403,
+      message: "Client ID mismatch: push clientId does not match authenticated identity"
+    });
+  }
+  if (body.deltas.length > MAX_DELTAS_PER_PUSH) {
+    return Err({ status: 400, message: "Too many deltas in a single push (max 10,000)" });
+  }
+  return Ok(body);
+}
+function parsePullParams(params) {
+  if (!params.since || !params.clientId) {
+    return Err({ status: 400, message: "Missing required query params: since, clientId" });
+  }
+  let sinceHlc;
+  try {
+    sinceHlc = BigInt(params.since);
+  } catch {
+    return Err({
+      status: 400,
+      message: "Invalid 'since' parameter \u2014 must be a decimal integer"
+    });
+  }
+  const rawLimit = params.limit ? Number.parseInt(params.limit, 10) : DEFAULT_PULL_LIMIT;
+  if (Number.isNaN(rawLimit) || rawLimit < 1) {
+    return Err({
+      status: 400,
+      message: "Invalid 'limit' parameter \u2014 must be a positive integer"
+    });
+  }
+  const maxDeltas = Math.min(rawLimit, MAX_PULL_LIMIT);
+  const msg = {
+    clientId: params.clientId,
+    sinceHlc,
+    maxDeltas,
+    ...params.source ? { source: params.source } : {}
+  };
+  return Ok(msg);
+}
+function validateActionBody(raw, headerClientId) {
+  let body;
+  try {
+    body = JSON.parse(raw, bigintReviver);
+  } catch {
+    return Err({ status: 400, message: "Invalid JSON body" });
+  }
+  if (!body.clientId || !Array.isArray(body.actions)) {
+    return Err({ status: 400, message: "Missing required fields: clientId, actions" });
+  }
+  if (headerClientId && body.clientId !== headerClientId) {
+    return Err({
+      status: 403,
+      message: "Client ID mismatch: action clientId does not match authenticated identity"
+    });
+  }
+  return Ok(body);
+}
+function validateSchemaBody(raw) {
+  let schema;
+  try {
+    schema = JSON.parse(raw);
+  } catch {
+    return Err({ status: 400, message: "Invalid JSON body" });
+  }
+  if (!schema.table || !Array.isArray(schema.columns)) {
+    return Err({ status: 400, message: "Missing required fields: table, columns" });
+  }
+  for (const col of schema.columns) {
+    if (typeof col.name !== "string" || col.name.length === 0) {
+      return Err({ status: 400, message: "Each column must have a non-empty 'name' string" });
+    }
+    if (!VALID_COLUMN_TYPES.has(col.type)) {
+      return Err({
+        status: 400,
+        message: `Invalid column type "${col.type}" for column "${col.name}". Allowed: string, number, boolean, json, null`
+      });
+    }
+  }
+  return Ok(schema);
+}
+function pushErrorToStatus(code) {
+  switch (code) {
+    case "CLOCK_DRIFT":
+      return 409;
+    case "SCHEMA_MISMATCH":
+      return 422;
+    case "BACKPRESSURE":
+      return 503;
+    default:
+      return 500;
+  }
+}
+function buildSyncRulesContext(rules, claims) {
+  if (!rules || rules.buckets.length === 0) {
+    return void 0;
+  }
+  return { claims, rules };
+}
+
+// ../gateway/src/request-handler.ts
+function handlePushRequest(gateway, raw, headerClientId, opts) {
+  const validation = validatePushBody(raw, headerClientId);
+  if (!validation.ok) {
+    return { status: validation.error.status, body: { error: validation.error.message } };
+  }
+  const body = validation.value;
+  opts?.persistBatch?.(body.deltas);
+  const result = gateway.handlePush(body);
+  if (!result.ok) {
+    return {
+      status: pushErrorToStatus(result.error.code),
+      body: { error: result.error.message }
+    };
+  }
+  opts?.clearPersistence?.();
+  if (opts?.broadcastFn && result.value.deltas.length > 0) {
+    opts.broadcastFn(result.value.deltas, result.value.serverHlc, body.clientId);
+  }
+  return { status: 200, body: result.value };
+}
+async function handlePullRequest(gateway, params, claims, syncRules) {
+  const validation = parsePullParams(params);
+  if (!validation.ok) {
+    return { status: validation.error.status, body: { error: validation.error.message } };
+  }
+  const msg = validation.value;
+  const context = buildSyncRulesContext(syncRules, claims ?? {});
+  const result = msg.source ? await gateway.handlePull(
+    msg,
+    context
+  ) : gateway.handlePull(msg, context);
+  if (!result.ok) {
+    const err = result.error;
+    if (err.code === "ADAPTER_NOT_FOUND") {
+      return { status: 404, body: { error: err.message } };
+    }
+    return { status: 500, body: { error: err.message } };
+  }
+  return { status: 200, body: result.value };
+}
+async function handleActionRequest(gateway, raw, headerClientId, claims) {
+  const validation = validateActionBody(raw, headerClientId);
+  if (!validation.ok) {
+    return { status: validation.error.status, body: { error: validation.error.message } };
+  }
+  const context = claims ? { claims } : void 0;
+  const result = await gateway.handleAction(validation.value, context);
+  if (!result.ok) {
+    return { status: 400, body: { error: result.error.message } };
+  }
+  return { status: 200, body: result.value };
+}
+async function handleFlushRequest(gateway, opts) {
+  const result = await gateway.flush();
+  if (!result.ok) {
+    return { status: 500, body: { error: result.error.message } };
+  }
+  opts?.clearPersistence?.();
+  return { status: 200, body: { flushed: true } };
+}
+async function handleSaveSchema(raw, store, gatewayId) {
+  const validation = validateSchemaBody(raw);
+  if (!validation.ok) {
+    return { status: validation.error.status, body: { error: validation.error.message } };
+  }
+  await store.setSchema(gatewayId, validation.value);
+  return { status: 200, body: { saved: true } };
+}
+async function handleSaveSyncRules(raw, store, gatewayId) {
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    return { status: 400, body: { error: "Invalid JSON body" } };
+  }
+  const validation = validateSyncRules(config);
+  if (!validation.ok) {
+    return { status: 400, body: { error: validation.error.message } };
+  }
+  await store.setSyncRules(gatewayId, config);
+  return { status: 200, body: { saved: true } };
+}
+async function handleRegisterConnector(raw, store) {
+  let body;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    return { status: 400, body: { error: "Invalid JSON body" } };
+  }
+  const validation = validateConnectorConfig(body);
+  if (!validation.ok) {
+    return { status: 400, body: { error: validation.error.message } };
+  }
+  const config = validation.value;
+  const connectors = await store.getConnectors();
+  if (connectors[config.name]) {
+    return { status: 409, body: { error: `Connector "${config.name}" already exists` } };
+  }
+  connectors[config.name] = config;
+  await store.setConnectors(connectors);
+  return { status: 200, body: { registered: true, name: config.name } };
+}
+async function handleUnregisterConnector(name, store) {
+  const connectors = await store.getConnectors();
+  if (!connectors[name]) {
+    return { status: 404, body: { error: `Connector "${name}" not found` } };
+  }
+  delete connectors[name];
+  await store.setConnectors(connectors);
+  return { status: 200, body: { unregistered: true, name } };
+}
+async function handleListConnectors(store) {
+  const connectors = await store.getConnectors();
+  const list = Object.values(connectors).map((c) => ({
+    name: c.name,
+    type: c.type,
+    hasIngest: c.ingest !== void 0
+  }));
+  return { status: 200, body: list };
+}
+function handleMetrics(gateway, extra) {
+  const stats = gateway.bufferStats;
+  return { status: 200, body: { ...stats, ...extra } };
+}
+
+// ../gateway/src/schema-manager.ts
+var SchemaManager = class {
+  currentSchema;
+  version;
+  allowedColumns;
+  constructor(schema, version) {
+    this.currentSchema = schema;
+    this.version = version ?? 1;
+    this.allowedColumns = new Set(schema.columns.map((c) => c.name));
+  }
+  /** Get the current schema and version. */
+  getSchema() {
+    return { schema: this.currentSchema, version: this.version };
+  }
+  /**
+   * Validate that a delta's columns are compatible with the current schema.
+   *
+   * Unknown columns result in a SchemaError. Missing columns are fine (sparse deltas).
+   * DELETE ops with empty columns are always valid.
+   */
+  validateDelta(delta) {
+    if (delta.op === "DELETE" && delta.columns.length === 0) {
+      return Ok(void 0);
+    }
+    for (const col of delta.columns) {
+      if (!this.allowedColumns.has(col.column)) {
+        return Err(
+          new SchemaError(
+            `Unknown column "${col.column}" in delta for table "${delta.table}". Schema version ${this.version} does not include this column.`
+          )
+        );
+      }
+    }
+    return Ok(void 0);
+  }
+  /**
+   * Evolve the schema by adding new nullable columns.
+   *
+   * Only adding columns is allowed. Removing columns or changing types
+   * returns a SchemaError.
+   */
+  evolveSchema(newSchema) {
+    if (newSchema.table !== this.currentSchema.table) {
+      return Err(new SchemaError("Cannot evolve schema: table name mismatch"));
+    }
+    const oldColumnMap = new Map(this.currentSchema.columns.map((c) => [c.name, c.type]));
+    const newColumnMap = new Map(newSchema.columns.map((c) => [c.name, c.type]));
+    for (const [name] of oldColumnMap) {
+      if (!newColumnMap.has(name)) {
+        return Err(
+          new SchemaError(
+            `Cannot remove column "${name}" \u2014 only adding nullable columns is supported`
+          )
+        );
+      }
+    }
+    for (const [name, oldType] of oldColumnMap) {
+      const newType = newColumnMap.get(name);
+      if (newType && newType !== oldType) {
+        return Err(
+          new SchemaError(
+            `Cannot change type of column "${name}" from "${oldType}" to "${newType}"`
+          )
+        );
+      }
+    }
+    this.currentSchema = newSchema;
+    this.version++;
+    this.allowedColumns = new Set(newSchema.columns.map((c) => c.name));
+    return Ok({ version: this.version });
+  }
+};
+
+export {
+  ActionDispatcher,
+  DeltaBuffer,
+  MemoryConfigStore,
+  MAX_PUSH_PAYLOAD_BYTES,
+  MAX_DELTAS_PER_PUSH,
+  MAX_PULL_LIMIT,
+  DEFAULT_PULL_LIMIT,
+  VALID_COLUMN_TYPES,
+  DEFAULT_MAX_BUFFER_BYTES,
+  DEFAULT_MAX_BUFFER_AGE_MS,
+  hlcRange,
+  flushEntries,
+  commitToCatalogue,
+  SyncGateway,
+  validatePushBody,
+  parsePullParams,
+  validateActionBody,
+  validateSchemaBody,
+  pushErrorToStatus,
+  buildSyncRulesContext,
+  handlePushRequest,
+  handlePullRequest,
+  handleActionRequest,
+  handleFlushRequest,
+  handleSaveSchema,
+  handleSaveSyncRules,
+  handleRegisterConnector,
+  handleUnregisterConnector,
+  handleListConnectors,
+  handleMetrics,
+  SchemaManager
+};
+//# sourceMappingURL=chunk-5YOFCJQ7.js.map