@syncular/relay 0.0.1-100

package/dist/client-role/forward-engine.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @syncular/relay - Forward Engine
+ *
+ * Forwards commits from the relay's local outbox to the main server.
+ * Preserves original client_id + client_commit_id for idempotency.
+ */
+import type { SyncTransport } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import type { ForwardConflictEntry, RelayDatabase } from '../schema';
+import type { SequenceMapper } from './sequence-mapper';
+/**
+ * Forward engine options.
+ */
+export interface ForwardEngineOptions<DB extends RelayDatabase = RelayDatabase> {
+    db: Kysely<DB>;
+    transport: SyncTransport;
+    clientId: string;
+    sequenceMapper: SequenceMapper<DB>;
+    retryIntervalMs?: number;
+    onConflict?: (conflict: ForwardConflictEntry) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Forward engine for sending local commits to the main server.
+ */
+export declare class ForwardEngine<DB extends RelayDatabase = RelayDatabase> {
+    private readonly db;
+    private readonly transport;
+    private readonly clientId;
+    private readonly sequenceMapper;
+    private readonly retryIntervalMs;
+    private readonly onConflict?;
+    private readonly onError?;
+    private running;
+    private timer;
+    private wakeUpRequested;
+    constructor(options: ForwardEngineOptions<DB>);
+    /**
+     * Start the forward engine loop.
+     */
+    start(): void;
+    /**
+     * Stop the forward engine.
+     */
+    stop(): void;
+    /**
+     * Wake up the engine to process immediately.
+     */
+    wakeUp(): void;
+    /**
+     * Forward a single commit (for manual/testing use).
+     */
+    forwardOnce(): Promise<boolean>;
+    private scheduleNext;
+    private processOne;
+    private getNextSendable;
+    private markSending;
+    private markPending;
+    private markForwarded;
+    private markFailed;
+    private recordConflict;
+}
+//# sourceMappingURL=forward-engine.d.ts.map

package/dist/client-role/forward-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward-engine.d.ts","sourceRoot":"","sources":["../../src/client-role/forward-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAGV,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,KAAK,EACV,oBAAoB,EAEpB,aAAa,EAEd,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,oBAAoB,CACnC,EAAE,SAAS,aAAa,GAAG,aAAa;IAExC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,aAAa,CAAC,EAAE,SAAS,aAAa,GAAG,aAAa;IACjE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA2C;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAyB;IAElD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAA8C;IAE3D,OAAO,CAAC,eAAe,CAAS;IAEhC,YAAY,OAAO,EAAE,oBAAoB,CAAC,EAAE,CAAC,EAQ5C;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAIZ;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAMX;IAED;;OAEG;IACH,MAAM,IAAI,IAAI,CAQb;IAED;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAEpC;IAED,OAAO,CAAC,YAAY;YAoBN,UAAU;YAsDV,eAAe;YAgEf,WAAW;YAcX,WAAW;YAUX,aAAa;YAmBb,UAAU;YAkBV,cAAc;CAsC7B"}

package/dist/client-role/forward-engine.js

@@ -0,0 +1,257 @@
+/**
+ * @syncular/relay - Forward Engine
+ *
+ * Forwards commits from the relay's local outbox to the main server.
+ * Preserves original client_id + client_commit_id for idempotency.
+ */
+import { randomId } from '@syncular/core';
+import { sql } from 'kysely';
+/**
+ * Forward engine for sending local commits to the main server.
+ */
+export class ForwardEngine {
+    db;
+    transport;
+    clientId;
+    sequenceMapper;
+    retryIntervalMs;
+    onConflict;
+    onError;
+    running = false;
+    timer = null;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: assigned in scheduleWakeUp and read in tick
+    wakeUpRequested = false;
+    constructor(options) {
+        this.db = options.db;
+        this.transport = options.transport;
+        this.clientId = options.clientId;
+        this.sequenceMapper = options.sequenceMapper;
+        this.retryIntervalMs = options.retryIntervalMs ?? 5000;
+        this.onConflict = options.onConflict;
+        this.onError = options.onError;
+    }
+    /**
+     * Start the forward engine loop.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.scheduleNext(0);
+    }
+    /**
+     * Stop the forward engine.
+     */
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Wake up the engine to process immediately.
+     */
+    wakeUp() {
+        if (!this.running)
+            return;
+        this.wakeUpRequested = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.scheduleNext(0);
+    }
+    /**
+     * Forward a single commit (for manual/testing use).
+     */
+    async forwardOnce() {
+        return this.processOne();
+    }
+    scheduleNext(delayMs) {
+        if (!this.running)
+            return;
+        if (this.timer)
+            return;
+        this.timer = setTimeout(async () => {
+            this.timer = null;
+            this.wakeUpRequested = false;
+            try {
+                const forwarded = await this.processOne();
+                // If we forwarded something, immediately try again
+                const nextDelay = forwarded ? 0 : this.retryIntervalMs;
+                this.scheduleNext(nextDelay);
+            }
+            catch (err) {
+                this.onError?.(err instanceof Error ? err : new Error(String(err)));
+                this.scheduleNext(this.retryIntervalMs);
+            }
+        }, delayMs);
+    }
+    async processOne() {
+        const next = await this.getNextSendable();
+        if (!next)
+            return false;
+        await this.markSending(next.id);
+        let response;
+        try {
+            const combined = await this.transport.sync({
+                clientId: next.client_id,
+                push: {
+                    clientCommitId: next.client_commit_id,
+                    operations: next.operations,
+                    schemaVersion: next.schema_version,
+                },
+            });
+            if (!combined.push) {
+                throw new Error('Server returned no push response');
+            }
+            response = combined.push;
+        }
+        catch (err) {
+            // Network error - mark as pending for retry
+            await this.markPending(next.id, String(err));
+            throw err;
+        }
+        const responseJson = JSON.stringify(response);
+        if (response.status === 'applied' || response.status === 'cached') {
+            const mainCommitSeq = response.commitSeq ?? null;
+            // Update outbox entry
+            await this.markForwarded(next.id, mainCommitSeq, responseJson);
+            // Update sequence mapper
+            if (mainCommitSeq != null) {
+                await this.sequenceMapper.markForwarded(next.local_commit_seq, mainCommitSeq);
+            }
+            return true;
+        }
+        // Rejected - store conflict and mark as failed
+        const conflict = await this.recordConflict(next, responseJson);
+        await this.markFailed(next.id, 'REJECTED', responseJson);
+        this.onConflict?.(conflict);
+        return true;
+    }
+    async getNextSendable() {
+        const staleThreshold = Date.now() - 30000;
+        const rowResult = await sql `
+      select
+        id,
+        local_commit_seq,
+        client_id,
+        client_commit_id,
+        operations_json,
+        schema_version,
+        status,
+        main_commit_seq,
+        error,
+        last_response_json,
+        created_at,
+        updated_at,
+        attempt_count
+      from ${sql.table('relay_forward_outbox')}
+      where
+        status = 'pending'
+        or (status = 'forwarding' and updated_at < ${staleThreshold})
+      order by created_at asc
+      limit 1
+    `.execute(this.db);
+        const row = rowResult.rows[0];
+        if (!row)
+            return null;
+        const operations = typeof row.operations_json === 'string'
+            ? JSON.parse(row.operations_json)
+            : row.operations_json;
+        return {
+            id: row.id,
+            local_commit_seq: row.local_commit_seq,
+            client_id: row.client_id,
+            client_commit_id: row.client_commit_id,
+            operations,
+            schema_version: row.schema_version,
+            status: row.status,
+            main_commit_seq: row.main_commit_seq,
+            error: row.error,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+            attempt_count: row.attempt_count,
+        };
+    }
+    async markSending(id) {
+        const now = Date.now();
+        await sql `
+      update ${sql.table('relay_forward_outbox')}
+      set
+        status = 'forwarding',
+        updated_at = ${now},
+        attempt_count = attempt_count + 1,
+        error = ${null}
+      where id = ${id}
+    `.execute(this.db);
+    }
+    async markPending(id, error) {
+        const now = Date.now();
+        await sql `
+      update ${sql.table('relay_forward_outbox')}
+      set status = 'pending', updated_at = ${now}, error = ${error}
+      where id = ${id}
+    `.execute(this.db);
+    }
+    async markForwarded(id, mainCommitSeq, responseJson) {
+        const now = Date.now();
+        await sql `
+      update ${sql.table('relay_forward_outbox')}
+      set
+        status = 'forwarded',
+        main_commit_seq = ${mainCommitSeq},
+        updated_at = ${now},
+        error = ${null},
+        last_response_json = ${responseJson}
+      where id = ${id}
+    `.execute(this.db);
+    }
+    async markFailed(id, error, responseJson) {
+        const now = Date.now();
+        await sql `
+      update ${sql.table('relay_forward_outbox')}
+      set
+        status = 'failed',
+        updated_at = ${now},
+        error = ${error},
+        last_response_json = ${responseJson}
+      where id = ${id}
+    `.execute(this.db);
+    }
+    async recordConflict(entry, responseJson) {
+        const now = Date.now();
+        const id = randomId();
+        await sql `
+      insert into ${sql.table('relay_forward_conflicts')} (
+        id,
+        local_commit_seq,
+        client_id,
+        client_commit_id,
+        response_json,
+        created_at,
+        resolved_at
+      )
+      values (
+        ${id},
+        ${entry.local_commit_seq},
+        ${entry.client_id},
+        ${entry.client_commit_id},
+        ${responseJson},
+        ${now},
+        ${null}
+      )
+    `.execute(this.db);
+        return {
+            id,
+            local_commit_seq: entry.local_commit_seq,
+            client_id: entry.client_id,
+            client_commit_id: entry.client_commit_id,
+            response: JSON.parse(responseJson),
+            created_at: now,
+            resolved_at: null,
+        };
+    }
+}
+//# sourceMappingURL=forward-engine.js.map

package/dist/client-role/forward-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward-engine.js","sourceRoot":"","sources":["../../src/client-role/forward-engine.ts"],"names":[],"mappings":"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"}

package/dist/client-role/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @syncular/relay - Client Role
+ *
+ * Components for the relay's role as a client to the main server.
+ */
+export * from './forward-engine';
+export * from './pull-engine';
+export * from './sequence-mapper';
+//# sourceMappingURL=index.d.ts.map

package/dist/client-role/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client-role/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/client-role/index.js

@@ -0,0 +1,9 @@
+/**
+ * @syncular/relay - Client Role
+ *
+ * Components for the relay's role as a client to the main server.
+ */
+export * from './forward-engine.js';
+export * from './pull-engine.js';
+export * from './sequence-mapper.js';
+//# sourceMappingURL=index.js.map

package/dist/client-role/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client-role/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/client-role/pull-engine.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @syncular/relay - Pull Engine
+ *
+ * Pulls changes from the main server and stores them locally
+ * on the relay for local clients to access.
+ */
+import type { ScopeValues, SyncTransport } from '@syncular/core';
+import type { ServerSyncDialect, TableRegistry } from '@syncular/server';
+import { type Kysely } from 'kysely';
+import type { RelayRealtime } from '../realtime';
+import type { RelayDatabase } from '../schema';
+import type { SequenceMapper } from './sequence-mapper';
+/**
+ * Pull engine options.
+ */
+export interface PullEngineOptions<DB extends RelayDatabase = RelayDatabase> {
+    db: Kysely<DB>;
+    dialect: ServerSyncDialect;
+    transport: SyncTransport;
+    clientId: string;
+    /** Tables to subscribe to */
+    tables: string[];
+    /** Scope values for subscriptions */
+    scopes: ScopeValues;
+    shapes: TableRegistry<DB>;
+    sequenceMapper: SequenceMapper<DB>;
+    realtime: RelayRealtime;
+    intervalMs?: number;
+    onError?: (error: Error) => void;
+    onPullComplete?: () => Promise<void>;
+}
+/**
+ * Pull engine for receiving changes from the main server.
+ */
+export declare class PullEngine<DB extends RelayDatabase = RelayDatabase> {
+    private readonly db;
+    private readonly dialect;
+    private readonly transport;
+    private readonly clientId;
+    private readonly tables;
+    private readonly scopes;
+    private readonly shapes;
+    private readonly sequenceMapper;
+    private readonly realtime;
+    private readonly intervalMs;
+    private readonly onError?;
+    private readonly onPullComplete?;
+    private running;
+    private timer;
+    private cursors;
+    constructor(options: PullEngineOptions<DB>);
+    /**
+     * Start the pull engine loop.
+     */
+    start(): void;
+    /**
+     * Stop the pull engine.
+     */
+    stop(): void;
+    /**
+     * Pull once (for manual/testing use).
+     */
+    pullOnce(): Promise<boolean>;
+    private loadCursors;
+    private saveCursors;
+    private scheduleNext;
+    private processOne;
+    private applyCommitLocally;
+}
+//# sourceMappingURL=pull-engine.d.ts.map

package/dist/client-role/pull-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-engine.d.ts","sourceRoot":"","sources":["../../src/client-role/pull-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EAIX,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEzE,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,EAAE,SAAS,aAAa,GAAG,aAAa;IACzE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACf,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qCAAqC;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;IACnC,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,qBAAa,UAAU,CAAC,EAAE,SAAS,aAAa,GAAG,aAAa;IAC9D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsB;IAEtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAA6B;IAE5C,YAAY,OAAO,EAAE,iBAAiB,CAAC,EAAE,CAAC,EAazC;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAcZ;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAMX;IAED;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAEjC;YAEa,WAAW;YA0BX,WAAW;IAezB,OAAO,CAAC,YAAY;YAmBN,UAAU;YAqFV,kBAAkB;CA6DjC"}

package/dist/client-role/pull-engine.js

@@ -0,0 +1,247 @@
+/**
+ * @syncular/relay - Pull Engine
+ *
+ * Pulls changes from the main server and stores them locally
+ * on the relay for local clients to access.
+ */
+import { pushCommit } from '@syncular/server';
+import { sql } from 'kysely';
+/**
+ * Pull engine for receiving changes from the main server.
+ */
+export class PullEngine {
+    db;
+    dialect;
+    transport;
+    clientId;
+    tables;
+    scopes;
+    shapes;
+    sequenceMapper;
+    realtime;
+    intervalMs;
+    onError;
+    onPullComplete;
+    running = false;
+    timer = null;
+    cursors = new Map();
+    constructor(options) {
+        this.db = options.db;
+        this.dialect = options.dialect;
+        this.transport = options.transport;
+        this.clientId = options.clientId;
+        this.tables = options.tables;
+        this.scopes = options.scopes;
+        this.shapes = options.shapes;
+        this.sequenceMapper = options.sequenceMapper;
+        this.realtime = options.realtime;
+        this.intervalMs = options.intervalMs ?? 10000;
+        this.onError = options.onError;
+        this.onPullComplete = options.onPullComplete;
+    }
+    /**
+     * Start the pull engine loop.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        void this.loadCursors()
+            .catch((error) => {
+            this.onError?.(error instanceof Error ? error : new Error(String(error)));
+        })
+            .finally(() => {
+            if (this.running) {
+                this.scheduleNext(0);
+            }
+        });
+    }
+    /**
+     * Stop the pull engine.
+     */
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Pull once (for manual/testing use).
+     */
+    async pullOnce() {
+        return this.processOne();
+    }
+    async loadCursors() {
+        try {
+            // Load cursors from config
+            const rowResult = await sql `
+        select value_json
+        from ${sql.table('relay_config')}
+        where key = 'main_cursors'
+        limit 1
+      `.execute(this.db);
+            const row = rowResult.rows[0];
+            if (row?.value_json) {
+                const parsed = JSON.parse(row.value_json);
+                if (typeof parsed === 'object' && parsed !== null) {
+                    for (const [key, value] of Object.entries(parsed)) {
+                        if (typeof value === 'number') {
+                            this.cursors.set(key, value);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore - start from scratch
+        }
+    }
+    async saveCursors() {
+        const cursorObj = {};
+        for (const [key, value] of this.cursors) {
+            cursorObj[key] = value;
+        }
+        const valueJson = JSON.stringify(cursorObj);
+        await sql `
+      insert into ${sql.table('relay_config')} (key, value_json)
+      values ('main_cursors', ${valueJson})
+      on conflict (key)
+      do update set value_json = ${valueJson}
+    `.execute(this.db);
+    }
+    scheduleNext(delayMs) {
+        if (!this.running)
+            return;
+        if (this.timer)
+            return;
+        this.timer = setTimeout(async () => {
+            this.timer = null;
+            try {
+                const pulled = await this.processOne();
+                // If we pulled something, immediately try again
+                const nextDelay = pulled ? 0 : this.intervalMs;
+                this.scheduleNext(nextDelay);
+            }
+            catch (err) {
+                this.onError?.(err instanceof Error ? err : new Error(String(err)));
+                this.scheduleNext(this.intervalMs);
+            }
+        }, delayMs);
+    }
+    async processOne() {
+        // Build subscriptions for each table
+        const subscriptionRequests = this.tables.map((table) => ({
+            id: table,
+            shape: table,
+            scopes: this.scopes,
+            cursor: this.cursors.get(table) ?? -1,
+        }));
+        let response;
+        try {
+            const combined = await this.transport.sync({
+                clientId: this.clientId,
+                pull: {
+                    subscriptions: subscriptionRequests,
+                    limitCommits: 100,
+                },
+            });
+            if (!combined.pull) {
+                return false;
+            }
+            response = combined.pull;
+        }
+        catch {
+            // Network error - will retry
+            return false;
+        }
+        if (!response.ok) {
+            return false;
+        }
+        let hasChanges = false;
+        const affectedTables = new Set();
+        for (const sub of response.subscriptions) {
+            if (sub.status !== 'active')
+                continue;
+            const table = sub.id;
+            // Process commits
+            let canAdvanceCursor = true;
+            for (const commit of sub.commits) {
+                const outcome = await this.applyCommitLocally(commit, table);
+                if (outcome === 'applied') {
+                    hasChanges = true;
+                    affectedTables.add(table);
+                }
+                if (outcome === 'rejected') {
+                    canAdvanceCursor = false;
+                    break;
+                }
+            }
+            // Update cursor
+            if (canAdvanceCursor &&
+                sub.nextCursor > (this.cursors.get(table) ?? -1)) {
+                this.cursors.set(table, sub.nextCursor);
+            }
+        }
+        // Save updated cursors
+        await this.saveCursors();
+        // Notify local clients if we have changes
+        if (hasChanges && affectedTables.size > 0) {
+            const maxCursor = await this.dialect.readMaxCommitSeq(this.db);
+            this.realtime.notifyScopeKeys(Array.from(affectedTables), maxCursor);
+        }
+        // Trigger rate-limited prune after successful pull
+        await this.onPullComplete?.();
+        return hasChanges;
+    }
+    /**
+     * Apply a commit from main server locally.
+     *
+     * This re-applies the commit through the local shape handlers
+     * to ensure proper indexing and scope assignment.
+     */
+    async applyCommitLocally(commit, table) {
+        if (commit.changes.length === 0)
+            return 'cached';
+        // Convert changes to operations
+        const operations = commit.changes.map((change) => ({
+            table: change.table,
+            row_id: change.row_id,
+            op: change.op,
+            payload: change.row_json,
+        }));
+        // Generate a unique commit ID for this relay instance
+        const relayCommitId = `main:${commit.commitSeq}:${table}`;
+        // Push through local handler
+        const result = await pushCommit({
+            db: this.db,
+            dialect: this.dialect,
+            shapes: this.shapes,
+            actorId: commit.actorId,
+            request: {
+                clientId: `relay:${this.clientId}`,
+                clientCommitId: relayCommitId,
+                operations,
+                schemaVersion: 1,
+            },
+        });
+        if (result.response.ok === true &&
+            result.response.status === 'applied' &&
+            typeof result.response.commitSeq === 'number') {
+            // Record sequence mapping
+            await this.sequenceMapper.createConfirmedMapping(result.response.commitSeq, commit.commitSeq);
+            return 'applied';
+        }
+        // Already applied (cached) - that's fine
+        if (result.response.status === 'cached') {
+            return 'cached';
+        }
+        // Rejected - this shouldn't happen for pulls from main
+        // Do not advance cursor; signal error so caller can react.
+        const error = new Error(`Relay: Failed to apply commit ${commit.commitSeq} locally (status=${result.response.status})`);
+        console.warn(`Relay: Failed to apply commit ${commit.commitSeq} locally:`, result.response);
+        this.onError?.(error);
+        return 'rejected';
+    }
+}
+//# sourceMappingURL=pull-engine.js.map