lakesync 0.1.0

package/dist/gateway-D5SaaMvT.d.ts

@@ -0,0 +1,337 @@
+import { g as ActionHandler, i as ActionPush, l as AuthContext, j as ActionResponse, a as ActionValidationError, d as ActionDiscovery, b as SyncRulesContext } from './types-Bs-QyOe-.js';
+import { H as HLCTimestamp, R as Result, S as SchemaError, b as ClockDriftError, B as BackpressureError, a as AdapterNotFoundError, A as AdapterError, F as FlushError } from './result-CojzlFE2.js';
+import { I as IngestTarget } from './base-poller-Qo_SmCZs.js';
+import { R as RowDelta, a as RowKey, T as TableSchema, b as SyncPush, S as SyncPull, c as SyncResponse } from './types-V_jVu2sA.js';
+import { D as DatabaseAdapter } from './db-types-BR6Kt4uf.js';
+import { L as LakeAdapter } from './types-DSC_EiwR.js';
+import { N as NessieCatalogueClient } from './nessie-client-DrNikVXy.js';
+
+/**
+ * Dispatches imperative actions to registered handlers.
+ *
+ * Manages idempotency via actionId deduplication and idempotencyKey mapping.
+ * Completely decoupled from the HLC clock — takes a callback for timestamp generation.
+ */
+declare class ActionDispatcher {
+    private actionHandlers;
+    private executedActions;
+    private idempotencyMap;
+    constructor(handlers?: Record<string, ActionHandler>);
+    /**
+     * 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.
+     */
+    dispatch(msg: ActionPush, hlcNow: () => HLCTimestamp, context?: AuthContext): Promise<Result<ActionResponse, ActionValidationError>>;
+    /**
+     * Register a named action handler.
+     *
+     * @param name - Connector name (matches `Action.connector`).
+     * @param handler - The action handler to register.
+     */
+    registerHandler(name: string, handler: ActionHandler): void;
+    /**
+     * Unregister a named action handler.
+     *
+     * @param name - The connector name to remove.
+     */
+    unregisterHandler(name: string): void;
+    /**
+     * List all registered action handler names.
+     *
+     * @returns Array of registered connector names.
+     */
+    listHandlers(): string[];
+    /**
+     * 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(): ActionDiscovery;
+    /** Cache an action result for idempotency deduplication. */
+    private cacheActionResult;
+}
+
+/**
+ * Dual-structure delta buffer.
+ *
+ * Maintains an append-only log for event streaming (pull) and flush,
+ * plus a row-level index for O(1) conflict resolution lookups.
+ */
+declare class DeltaBuffer {
+    private log;
+    private index;
+    private deltaIds;
+    private estimatedBytes;
+    private createdAt;
+    private tableBytes;
+    private tableLog;
+    /** Append a delta to the log and upsert the index (post-conflict-resolution). */
+    append(delta: RowDelta): void;
+    /** Get the current merged state for a row (for conflict resolution). */
+    getRow(key: RowKey): RowDelta | undefined;
+    /** Check if a delta with this ID already exists in the log (for idempotency). */
+    hasDelta(deltaId: string): boolean;
+    /** Return change events from the log since a given HLC. */
+    getEventsSince(hlc: HLCTimestamp, limit: number): {
+        deltas: RowDelta[];
+        hasMore: boolean;
+    };
+    /** Check if the buffer should be flushed based on size or age thresholds. */
+    shouldFlush(config: {
+        maxBytes: number;
+        maxAgeMs: number;
+    }): boolean;
+    /** Per-table buffer statistics. */
+    tableStats(): Array<{
+        table: string;
+        byteSize: number;
+        deltaCount: number;
+    }>;
+    /** Drain only the specified table's deltas, leaving other tables intact. */
+    drainTable(table: string): RowDelta[];
+    /** Drain the log for flush. Returns log entries and clears both structures. */
+    drain(): RowDelta[];
+    /** Number of log entries */
+    get logSize(): number;
+    /** Number of unique rows in the index */
+    get indexSize(): number;
+    /** Estimated byte size of the buffer */
+    get byteSize(): number;
+    /** Average byte size per delta in the buffer (0 if empty). */
+    get averageDeltaBytes(): number;
+}
+
+/**
+ * Manages schema versioning and validation for the gateway.
+ *
+ * Validates incoming deltas against the current schema and supports
+ * safe schema evolution (adding nullable columns only).
+ */
+declare class SchemaManager {
+    private currentSchema;
+    private version;
+    private allowedColumns;
+    constructor(schema: TableSchema, version?: number);
+    /** Get the current schema and version. */
+    getSchema(): {
+        schema: TableSchema;
+        version: number;
+    };
+    /**
+     * 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: RowDelta): Result<void, SchemaError>;
+    /**
+     * Evolve the schema by adding new nullable columns.
+     *
+     * Only adding columns is allowed. Removing columns or changing types
+     * returns a SchemaError.
+     */
+    evolveSchema(newSchema: TableSchema): Result<{
+        version: number;
+    }, SchemaError>;
+}
+
+/** Result returned by {@link SyncGateway.handlePush}. */
+interface HandlePushResult {
+    /** Server HLC after processing the push. */
+    serverHlc: HLCTimestamp;
+    /** Number of deltas accepted (including idempotent re-pushes). */
+    accepted: number;
+    /** Deltas actually ingested (excludes idempotent re-pushes). */
+    deltas: RowDelta[];
+}
+/** Configuration for buffer thresholds (subset of GatewayConfig). */
+interface BufferConfig {
+    /** Maximum buffer size in bytes before triggering flush. */
+    maxBufferBytes: number;
+    /** Maximum buffer age in milliseconds before triggering flush. */
+    maxBufferAgeMs: number;
+    /** Adaptive buffer configuration for wide-column deltas. */
+    adaptiveBufferConfig?: {
+        /** Average delta byte threshold above which flush triggers earlier. */
+        wideColumnThreshold: number;
+        /** Factor to reduce effective maxBufferBytes (0-1). */
+        reductionFactor: number;
+    };
+    /** Maximum buffer bytes before rejecting pushes (default: 2 × maxBufferBytes). */
+    maxBackpressureBytes?: number;
+    /** Maximum buffer bytes per table before auto-flushing that table. */
+    perTableBudgetBytes?: number;
+}
+/** Configuration for the sync gateway */
+interface GatewayConfig extends BufferConfig {
+    /** Unique gateway identifier */
+    gatewayId: string;
+    /** Flush output format. Defaults to "parquet". */
+    flushFormat?: "json" | "parquet";
+    /** Table schema — required for Parquet flush. */
+    tableSchema?: TableSchema;
+    /** Optional Nessie catalogue client for Iceberg snapshot registration. */
+    catalogue?: NessieCatalogueClient;
+    /** Optional schema manager for delta validation. */
+    schemaManager?: SchemaManager;
+    /** Optional storage adapter — LakeAdapter (S3/R2) or DatabaseAdapter (Postgres/MySQL). */
+    adapter?: LakeAdapter | DatabaseAdapter;
+    /** Named source adapters for adapter-sourced pulls. */
+    sourceAdapters?: Record<string, DatabaseAdapter>;
+    /** Named action handlers for imperative action execution. */
+    actionHandlers?: Record<string, ActionHandler>;
+}
+/** Gateway runtime state */
+interface GatewayState {
+    /** Current server HLC */
+    hlc: HLCTimestamp;
+    /** Whether a flush is currently in progress */
+    flushing: boolean;
+}
+/** Versioned envelope for flushed data */
+interface FlushEnvelope {
+    /** Envelope format version */
+    version: 1;
+    /** Gateway that produced this flush */
+    gatewayId: string;
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+    /** Range of HLC timestamps in this flush */
+    hlcRange: {
+        min: HLCTimestamp;
+        max: HLCTimestamp;
+    };
+    /** Number of deltas in this flush */
+    deltaCount: number;
+    /** Estimated byte size */
+    byteSize: number;
+    /** The flushed deltas */
+    deltas: RowDelta[];
+}
+
+/**
+ * Sync gateway -- coordinates delta ingestion, conflict resolution, and flush.
+ *
+ * Thin facade composing ActionDispatcher, DeltaBuffer, and flushEntries.
+ */
+declare class SyncGateway implements IngestTarget {
+    private hlc;
+    readonly buffer: DeltaBuffer;
+    readonly actions: ActionDispatcher;
+    private config;
+    private adapter;
+    private flushing;
+    constructor(config: GatewayConfig, adapter?: LakeAdapter | DatabaseAdapter);
+    /** Restore drained entries back to the buffer for retry. */
+    private restoreEntries;
+    /**
+     * 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: SyncPush): Result<HandlePushResult, ClockDriftError | SchemaError | BackpressureError>;
+    /**
+     * Handle a pull request from a client.
+     *
+     * When `msg.source` is set, pulls deltas from the named source adapter
+     * instead of the in-memory buffer. Otherwise, returns change events
+     * from the log since the given HLC. When a {@link SyncRulesContext} is
+     * provided, deltas are post-filtered by the client's bucket definitions
+     * and JWT claims. The buffer path over-fetches (3x the requested limit)
+     * and retries up to 5 times to fill the page.
+     *
+     * @param msg - The pull message specifying the cursor and limit.
+     * @param context - Optional sync rules context for row-level filtering.
+     * @returns A `Result` containing the matching deltas, server HLC, and pagination flag.
+     */
+    handlePull(msg: SyncPull & {
+        source: string;
+    }, context?: SyncRulesContext): Promise<Result<SyncResponse, AdapterNotFoundError | AdapterError>>;
+    handlePull(msg: SyncPull, context?: SyncRulesContext): Result<SyncResponse, never>;
+    /** Pull from the in-memory buffer (original path). */
+    private handleBufferPull;
+    /** Pull from a named source adapter. */
+    private handleAdapterPull;
+    /**
+     * 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`.
+     */
+    flush(): Promise<Result<void, FlushError>>;
+    /**
+     * 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.
+     */
+    flushTable(table: string): Promise<Result<void, FlushError>>;
+    /** Handle an incoming action push from a client. */
+    handleAction(msg: ActionPush, context?: AuthContext): Promise<Result<ActionResponse, ActionValidationError>>;
+    /** Register a named action handler. */
+    registerActionHandler(name: string, handler: ActionHandler): void;
+    /** Unregister a named action handler. */
+    unregisterActionHandler(name: string): void;
+    /** List all registered action handler names. */
+    listActionHandlers(): string[];
+    /** Describe all registered action handlers and their supported actions. */
+    describeActions(): ActionDiscovery;
+    /**
+     * 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: string, adapter: DatabaseAdapter): void;
+    /**
+     * Unregister a named source adapter.
+     *
+     * @param name - The source name to remove.
+     */
+    unregisterSource(name: string): void;
+    /**
+     * List all registered source adapter names.
+     *
+     * @returns Array of registered source adapter names.
+     */
+    listSources(): string[];
+    /** Get per-table buffer statistics. */
+    get tableStats(): Array<{
+        table: string;
+        byteSize: number;
+        deltaCount: number;
+    }>;
+    /**
+     * Get tables that exceed the per-table budget.
+     */
+    getTablesExceedingBudget(): string[];
+    /** Check if the buffer should be flushed based on config thresholds. */
+    shouldFlush(): boolean;
+    /** Get buffer statistics for monitoring. */
+    get bufferStats(): {
+        logSize: number;
+        indexSize: number;
+        byteSize: number;
+    };
+}
+
+export { ActionDispatcher as A, type BufferConfig as B, DeltaBuffer as D, type FlushEnvelope as F, type GatewayConfig as G, type HandlePushResult as H, SyncGateway as S, type GatewayState as a, SchemaManager as b };

package/dist/gateway-server.d.ts

@@ -0,0 +1,306 @@
+export { A as AuthClaims, a as AuthError, v as verifyToken } from './auth-CAVutXzx.js';
+import { D as DatabaseAdapter } from './db-types-BR6Kt4uf.js';
+import { S as SyncGateway } from './gateway-D5SaaMvT.js';
+import { R as RowDelta, c as SyncResponse } from './types-V_jVu2sA.js';
+import { L as LakeAdapter } from './types-DSC_EiwR.js';
+import { H as HLCTimestamp } from './result-CojzlFE2.js';
+import './types-Bs-QyOe-.js';
+import './base-poller-Qo_SmCZs.js';
+import './hlc-DiD8QNG3.js';
+import './nessie-client-DrNikVXy.js';
+
+/**
+ * Interface for distributed locking across gateway-server instances.
+ *
+ * Used to coordinate exclusive operations (e.g. flush) across
+ * multiple instances behind a load balancer.
+ */
+interface DistributedLock {
+    /** Attempt to acquire a lock. Returns true if acquired. */
+    acquire(key: string, ttlMs: number): Promise<boolean>;
+    /** Release a previously acquired lock. */
+    release(key: string): Promise<void>;
+}
+/**
+ * Database-backed distributed lock using an advisory lock row.
+ *
+ * Uses a `lakesync_locks` table with columns: key, holder, expires_at.
+ * Lock acquisition is atomic via INSERT ... ON CONFLICT or UPDATE WHERE expires_at < NOW().
+ */
+declare class AdapterBasedLock implements DistributedLock {
+    private readonly adapter;
+    private readonly instanceId;
+    constructor(adapter: DatabaseAdapter, instanceId?: string);
+    acquire(key: string, ttlMs: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+    private makeLockDelta;
+}
+
+/** Generic query function — abstracts any SQL database. */
+type QueryFn = (sql: string, params?: unknown[]) => Promise<Record<string, unknown>[]>;
+/** Configuration for a single polling ingest source. */
+interface IngestSourceConfig {
+    /** Unique name for this source (used as clientId prefix). */
+    name: string;
+    /** Generic query function for the source database. */
+    queryFn: QueryFn;
+    /** Tables to poll. */
+    tables: IngestTableConfig[];
+    /** Poll interval in ms. Default 10_000 (10s). */
+    intervalMs?: number;
+}
+/** Configuration for a single table within an ingest source. */
+interface IngestTableConfig {
+    /** Target table name in LakeSync (where deltas appear). */
+    table: string;
+    /** SQL query to fetch rows. Must return a row ID column + data columns. */
+    query: string;
+    /** Column used as the unique row identifier. Default: "id". */
+    rowIdColumn?: string;
+    /** Change detection strategy. */
+    strategy: CursorStrategy | DiffStrategy;
+}
+/** Cursor-based change detection — fast, requires a monotonically increasing column. */
+interface CursorStrategy {
+    type: "cursor";
+    /** Column name for cursor (e.g. "updated_at"). Must be monotonically increasing. */
+    cursorColumn: string;
+    /** Look-back overlap in ms to catch late-committing transactions. Default 5000. */
+    lookbackMs?: number;
+}
+/** Full-diff change detection — slower, detects deletes, no schema requirement. */
+interface DiffStrategy {
+    type: "diff";
+}
+
+/**
+ * Polls an external data source and pushes detected changes into a
+ * {@link SyncGateway} via `handlePush()`.
+ *
+ * Supports two change detection strategies:
+ * - **cursor**: fast incremental polling using a monotonically increasing column
+ * - **diff**: full-table comparison detecting inserts, updates, and deletes
+ */
+declare class SourcePoller {
+    private readonly config;
+    private readonly gateway;
+    private readonly hlc;
+    private readonly clientId;
+    private timer;
+    private running;
+    /** Cursor state per table (keyed by table name). */
+    private cursorStates;
+    /** Diff snapshot per table (keyed by table name). */
+    private diffStates;
+    constructor(config: IngestSourceConfig, gateway: SyncGateway);
+    /** Start the polling loop. */
+    start(): void;
+    /** Stop the polling loop. */
+    stop(): void;
+    /** Whether the poller is currently running. */
+    get isRunning(): boolean;
+    private schedulePoll;
+    /** Execute a single poll cycle across all configured tables. */
+    poll(): Promise<void>;
+    private pollCursor;
+    private pollDiff;
+}
+
+/**
+ * Persistence interface for buffering unflushed deltas across restarts.
+ *
+ * Implementations must be synchronous (no async) to avoid race conditions
+ * during the push-then-flush cycle.
+ */
+interface DeltaPersistence {
+    /** Append a batch of deltas to the persistence store. */
+    appendBatch(deltas: RowDelta[]): void;
+    /** Load all persisted deltas. */
+    loadAll(): RowDelta[];
+    /** Clear all persisted deltas (after successful flush). */
+    clear(): void;
+    /** Release resources. */
+    close(): void;
+}
+/**
+ * In-memory persistence (no durability across restarts).
+ * Used as the default when `persistence` is "memory".
+ */
+declare class MemoryPersistence implements DeltaPersistence {
+    private buffer;
+    appendBatch(deltas: RowDelta[]): void;
+    loadAll(): RowDelta[];
+    clear(): void;
+    close(): void;
+}
+/**
+ * SQLite-backed persistence using `better-sqlite3`.
+ *
+ * Stores deltas as JSON rows in a single table. On startup, loads all
+ * rows back as RowDeltas. On flush success, truncates the table.
+ */
+declare class SqlitePersistence implements DeltaPersistence {
+    private db;
+    constructor(path: string);
+    appendBatch(deltas: RowDelta[]): void;
+    loadAll(): RowDelta[];
+    clear(): void;
+    close(): void;
+}
+
+/** Configuration for the self-hosted gateway server. */
+interface GatewayServerConfig {
+    /** Port to listen on (default 3000). */
+    port?: number;
+    /** Unique gateway identifier. */
+    gatewayId: string;
+    /** Storage adapter — LakeAdapter (S3/R2) or DatabaseAdapter (Postgres/MySQL). */
+    adapter?: LakeAdapter | DatabaseAdapter;
+    /** Maximum buffer size in bytes before triggering flush (default 4 MiB). */
+    maxBufferBytes?: number;
+    /** Maximum buffer age in milliseconds before triggering flush (default 30s). */
+    maxBufferAgeMs?: number;
+    /** HMAC-SHA256 secret for JWT verification. When omitted, auth is disabled. */
+    jwtSecret?: string;
+    /** Interval in milliseconds between periodic flushes (default 30s). */
+    flushIntervalMs?: number;
+    /** CORS allowed origins. When omitted, all origins are reflected. */
+    allowedOrigins?: string[];
+    /** DeltaBuffer persistence strategy (default "memory"). */
+    persistence?: "memory" | "sqlite";
+    /** Path to the SQLite file when `persistence` is "sqlite" (default "./lakesync-buffer.sqlite"). */
+    sqlitePath?: string;
+    /** Polling ingest sources. Each source is polled independently. */
+    ingestSources?: IngestSourceConfig[];
+    /** Optional clustering configuration for multi-instance deployment. */
+    cluster?: {
+        /** Distributed lock for coordinated flush. */
+        lock: DistributedLock;
+        /** Shared database adapter for cross-instance visibility. */
+        sharedAdapter: DatabaseAdapter;
+    };
+}
+/**
+ * Self-hosted HTTP gateway server wrapping {@link SyncGateway}.
+ *
+ * Provides the same route surface as the Cloudflare Workers gateway-worker
+ * but runs as a standalone Node/Bun HTTP server. Supports optional JWT
+ * authentication, CORS, periodic flush, and SQLite-based buffer persistence.
+ *
+ * @example
+ * ```ts
+ * const server = new GatewayServer({
+ *   gatewayId: "my-gateway",
+ *   port: 3000,
+ *   adapter: new PostgresAdapter({ connectionString: "..." }),
+ *   jwtSecret: process.env.JWT_SECRET,
+ * });
+ * await server.start();
+ * ```
+ */
+declare class GatewayServer {
+    private gateway;
+    private config;
+    private httpServer;
+    private flushTimer;
+    private configStore;
+    private persistence;
+    private resolvedPort;
+    private wss;
+    private wsClients;
+    private pollers;
+    private connectorAdapters;
+    private connectorPollers;
+    private sharedBuffer;
+    constructor(config: GatewayServerConfig);
+    /**
+     * Start the HTTP server and periodic flush timer.
+     *
+     * Rehydrates unflushed deltas from the persistence layer before
+     * accepting connections.
+     */
+    start(): Promise<void>;
+    /**
+     * Handle HTTP -> WebSocket upgrade.
+     *
+     * Authenticates via Bearer token in Authorization header or `?token=` query param.
+     */
+    private handleUpgrade;
+    /**
+     * Handle an incoming WebSocket message (binary protobuf).
+     */
+    private handleWsMessage;
+    /**
+     * Build sync rules context from WebSocket client claims.
+     */
+    private buildWsSyncRulesContext;
+    /**
+     * Broadcast ingested deltas to all connected WebSocket clients except the sender.
+     */
+    private broadcastDeltas;
+    private broadcastDeltasAsync;
+    /** Stop the server and clear the flush timer. */
+    stop(): Promise<void>;
+    /** The port the server is listening on (available after start). */
+    get port(): number;
+    /** The underlying SyncGateway instance for direct access. */
+    get gatewayInstance(): SyncGateway;
+    private handleRequest;
+    /**
+     * Handle `POST /sync/:gatewayId/push` -- ingest client deltas.
+     */
+    private handlePush;
+    /**
+     * Handle `GET /sync/:gatewayId/pull` -- retrieve deltas since a given HLC.
+     */
+    private handlePull;
+    /**
+     * Handle `POST /sync/:gatewayId/action` -- execute imperative actions.
+     */
+    private handleAction;
+    /** Handle `GET /sync/:gatewayId/actions` -- describe available action handlers. */
+    private handleDescribeActions;
+    /** Handle `POST /admin/flush/:gatewayId` -- manual flush. */
+    private handleFlush;
+    /** Handle `POST /admin/schema/:gatewayId` -- save table schema. */
+    private handleSaveSchemaRoute;
+    /** Handle `POST /admin/sync-rules/:gatewayId` -- save sync rules. */
+    private handleSaveSyncRulesRoute;
+    /** Handle `POST /admin/connectors/:gatewayId` -- register a new connector. */
+    private handleRegisterConnector;
+    /** Handle `DELETE /admin/connectors/:gatewayId/:name` -- unregister a connector. */
+    private handleUnregisterConnector;
+    /** Handle `GET /admin/connectors/:gatewayId` -- list registered connectors. */
+    private handleListConnectorsRoute;
+    /** Handle `GET /admin/metrics/:gatewayId` -- return buffer stats and process memory. */
+    private handleMetricsRoute;
+    private periodicFlush;
+    private corsHeaders;
+}
+
+/**
+ * Write-through buffer that pushes to both the in-memory gateway buffer
+ * and a shared database adapter for cross-instance visibility.
+ *
+ * Pull merges in-memory buffer results with adapter query results,
+ * deduplicating by deltaId.
+ */
+declare class SharedBuffer {
+    private readonly sharedAdapter;
+    constructor(sharedAdapter: DatabaseAdapter);
+    /**
+     * Write-through push: write to shared adapter for cross-instance visibility.
+     *
+     * Gateway buffer handles fast reads; shared adapter handles
+     * cross-instance visibility and durability.
+     */
+    writeThroughPush(deltas: RowDelta[]): Promise<void>;
+    /**
+     * Merge pull: combine local buffer results with shared adapter results.
+     *
+     * Deduplicates by deltaId to avoid returning the same delta twice.
+     */
+    mergePull(localResult: SyncResponse, sinceHlc: HLCTimestamp): Promise<SyncResponse>;
+}
+
+export { AdapterBasedLock, type CursorStrategy, type DeltaPersistence, type DiffStrategy, type DistributedLock, GatewayServer, type GatewayServerConfig, type IngestSourceConfig, type IngestTableConfig, MemoryPersistence, type QueryFn, SharedBuffer, SourcePoller, SqlitePersistence };