@syncular/client 0.0.3-3 → 0.0.3-6

package/dist/engine/SyncEngine.js

@@ -4,9 +4,10 @@
  * Event-driven sync engine that manages push/pull cycles, connection state,
  * and provides a clean API for framework bindings to consume.
  */
-import { captureSyncException, countSyncMetric, distributionSyncMetric, isRecord, startSyncSpan, } from '@syncular/core';
+import { captureSyncException, countSyncMetric, distributionSyncMetric, isRecord, SyncTransportError, startSyncSpan, } from '@syncular/core';
 import { sql } from 'kysely';
 import { syncPushOnce } from '../push-engine.js';
+import { DEFAULT_SYNC_STATE_ID, getSubscriptionState as readSubscriptionState, listSubscriptionStates as readSubscriptionStates, } from '../subscription-state.js';
 import { syncOnce } from '../sync-loop.js';
 const DEFAULT_POLL_INTERVAL_MS = 10_000;
 const DEFAULT_MAX_RETRIES = 5;
@@ -14,6 +15,7 @@ const INITIAL_RETRY_DELAY_MS = 1000;
 const MAX_RETRY_DELAY_MS = 60000;
 const EXPONENTIAL_FACTOR = 2;
 const REALTIME_RECONNECT_CATCHUP_DELAY_MS = 500;
+const DEFAULT_AWAIT_TIMEOUT_MS = 60_000;
 function calculateRetryDelay(attemptIndex) {
     return Math.min(INITIAL_RETRY_DELAY_MS * EXPONENTIAL_FACTOR ** attemptIndex, MAX_RETRY_DELAY_MS);
 }
@@ -22,12 +24,85 @@ function isRealtimeTransport(transport) {
         transport !== null &&
         typeof transport.connect === 'function');
 }
-function createSyncError(code, message, cause) {
+function createSyncError(args) {
     return {
-        code,
+        code: args.code,
+        message: args.message,
+        cause: args.cause,
+        timestamp: Date.now(),
+        retryable: args.retryable ?? false,
+        httpStatus: args.httpStatus,
+        subscriptionId: args.subscriptionId,
+        stateId: args.stateId,
+    };
+}
+function classifySyncFailure(error) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    const message = cause.message || 'Sync failed';
+    const normalized = message.toLowerCase();
+    if (cause instanceof SyncTransportError) {
+        if (cause.status === 401 || cause.status === 403) {
+            return {
+                code: 'AUTH_FAILED',
+                message,
+                cause,
+                retryable: false,
+                httpStatus: cause.status,
+            };
+        }
+        if (cause.status === 404 &&
+            normalized.includes('snapshot') &&
+            normalized.includes('chunk')) {
+            return {
+                code: 'SNAPSHOT_CHUNK_NOT_FOUND',
+                message,
+                cause,
+                retryable: false,
+                httpStatus: cause.status,
+            };
+        }
+        if (cause.status !== undefined &&
+            (cause.status >= 500 || cause.status === 408 || cause.status === 429)) {
+            return {
+                code: 'NETWORK_ERROR',
+                message,
+                cause,
+                retryable: true,
+                httpStatus: cause.status,
+            };
+        }
+        return {
+            code: 'SYNC_ERROR',
+            message,
+            cause,
+            retryable: false,
+            httpStatus: cause.status,
+        };
+    }
+    if (normalized.includes('network') ||
+        normalized.includes('fetch') ||
+        normalized.includes('timeout') ||
+        normalized.includes('offline')) {
+        return {
+            code: 'NETWORK_ERROR',
+            message,
+            cause,
+            retryable: true,
+        };
+    }
+    if (normalized.includes('conflict')) {
+        return {
+            code: 'CONFLICT',
+            message,
+            cause,
+            retryable: false,
+        };
+    }
+    return {
+        code: 'SYNC_ERROR',
         message,
         cause,
-        timestamp: Date.now(),
+        retryable: false,
     };
 }
 function resolveSyncTriggerLabel(trigger) {
@@ -48,6 +123,15 @@ export class SyncEngine {
     retryTimeoutId = null;
     realtimeCatchupTimeoutId = null;
     hasRealtimeConnectedOnce = false;
+    transportHealth = {
+        mode: 'disconnected',
+        connected: false,
+        lastSuccessfulPollAt: null,
+        lastRealtimeMessageAt: null,
+        fallbackReason: null,
+    };
+    activeBootstrapSubscriptions = new Set();
+    bootstrapStartedAt = new Map();
     /**
      * In-memory map tracking local mutation timestamps by rowId.
      * Used for efficient fingerprint-based rerender optimization.
@@ -69,6 +153,13 @@ export class SyncEngine {
         this.config = config;
         this.listeners = new Map();
         this.state = this.createInitialState();
+        this.transportHealth = {
+            mode: this.state.transportMode === 'polling' ? 'polling' : 'disconnected',
+            connected: false,
+            lastSuccessfulPollAt: null,
+            lastRealtimeMessageAt: null,
+            fallbackReason: null,
+        };
     }
     /**
      * Get mutation timestamp for a row (used by query hooks for fingerprinting).
@@ -212,6 +303,125 @@ export class SyncEngine {
     getState() {
         return this.state;
     }
+    /**
+     * Get transport health details (realtime/polling/fallback).
+     */
+    getTransportHealth() {
+        return this.transportHealth;
+    }
+    /**
+     * Get subscription state metadata for the current profile.
+     */
+    async listSubscriptionStates(args) {
+        return readSubscriptionStates(this.config.db, {
+            stateId: args?.stateId ?? this.getStateId(),
+            table: args?.table,
+            status: args?.status,
+        });
+    }
+    /**
+     * Get a single subscription state by id.
+     */
+    async getSubscriptionState(subscriptionId, options) {
+        return readSubscriptionState(this.config.db, {
+            stateId: options?.stateId ?? this.getStateId(),
+            subscriptionId,
+        });
+    }
+    /**
+     * Get normalized progress for all active subscriptions in this state profile.
+     */
+    async getProgress() {
+        const subscriptions = await this.listSubscriptionStates();
+        const progress = subscriptions.map((sub) => this.mapSubscriptionToProgress(sub));
+        const channelPhase = this.resolveChannelPhase(progress);
+        const hasSubscriptions = progress.length > 0;
+        const basePercent = hasSubscriptions
+            ? Math.round(progress.reduce((sum, item) => sum + item.progressPercent, 0) /
+                progress.length)
+            : this.state.lastSyncAt !== null
+                ? 100
+                : 0;
+        const progressPercent = channelPhase === 'live'
+            ? 100
+            : Math.max(0, Math.min(100, Math.trunc(basePercent)));
+        return {
+            channelPhase,
+            progressPercent,
+            subscriptions: progress,
+        };
+    }
+    /**
+     * Wait until the channel reaches a target phase.
+     */
+    async awaitPhase(phase, options = {}) {
+        const timeoutMs = Math.max(0, options.timeoutMs ?? DEFAULT_AWAIT_TIMEOUT_MS);
+        const deadline = Date.now() + timeoutMs;
+        while (true) {
+            const progress = await this.getProgress();
+            if (progress.channelPhase === phase) {
+                return progress;
+            }
+            if (progress.channelPhase === 'error') {
+                const message = this.state.error?.message ?? 'Sync entered error state';
+                throw new Error(`[SyncEngine.awaitPhase] Failed while waiting for "${phase}": ${message}`);
+            }
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                throw new Error(`[SyncEngine.awaitPhase] Timed out after ${timeoutMs}ms waiting for phase "${phase}"`);
+            }
+            await this.waitForProgressSignal(remainingMs);
+        }
+    }
+    /**
+     * Wait until bootstrap finishes for a state or a specific subscription.
+     */
+    async awaitBootstrapComplete(options = {}) {
+        const timeoutMs = Math.max(0, options.timeoutMs ?? DEFAULT_AWAIT_TIMEOUT_MS);
+        const stateId = options.stateId ?? this.getStateId();
+        const deadline = Date.now() + timeoutMs;
+        while (true) {
+            const states = await this.listSubscriptionStates({ stateId });
+            const relevantStates = options.subscriptionId === undefined
+                ? states
+                : states.filter((state) => state.subscriptionId === options.subscriptionId);
+            const hasPendingBootstrap = relevantStates.some((state) => state.status === 'active' && state.bootstrapState !== null);
+            if (!hasPendingBootstrap) {
+                return this.getProgress();
+            }
+            if (this.state.error) {
+                throw new Error(`[SyncEngine.awaitBootstrapComplete] Failed while waiting for bootstrap completion: ${this.state.error.message}`);
+            }
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                const target = options.subscriptionId === undefined
+                    ? `state "${stateId}"`
+                    : `subscription "${options.subscriptionId}" in state "${stateId}"`;
+                throw new Error(`[SyncEngine.awaitBootstrapComplete] Timed out after ${timeoutMs}ms waiting for ${target}`);
+            }
+            await this.waitForProgressSignal(remainingMs);
+        }
+    }
+    /**
+     * Get a diagnostics snapshot suitable for debug UIs and bug reports.
+     */
+    async getDiagnostics() {
+        const [subscriptions, progress, outbox, conflicts] = await Promise.all([
+            this.listSubscriptionStates(),
+            this.getProgress(),
+            this.refreshOutboxStats({ emit: false }),
+            this.getConflicts(),
+        ]);
+        return {
+            timestamp: Date.now(),
+            state: this.state,
+            transport: this.transportHealth,
+            progress,
+            outbox,
+            conflictCount: conflicts.length,
+            subscriptions,
+        };
+    }
     /**
      * Get database instance
      */
@@ -230,6 +440,366 @@ export class SyncEngine {
     getClientId() {
         return this.config.clientId;
     }
+    getStateId() {
+        return this.config.stateId ?? DEFAULT_SYNC_STATE_ID;
+    }
+    makeBootstrapKey(stateId, subscriptionId) {
+        return `${stateId}:${subscriptionId}`;
+    }
+    updateTransportHealth(partial) {
+        this.transportHealth = {
+            ...this.transportHealth,
+            ...partial,
+        };
+        this.emit('state:change', {});
+    }
+    waitForProgressSignal(timeoutMs) {
+        return new Promise((resolve) => {
+            const cleanups = [];
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutId);
+                for (const cleanup of cleanups)
+                    cleanup();
+                resolve();
+            };
+            const listen = (event) => {
+                cleanups.push(this.on(event, finish));
+            };
+            listen('sync:start');
+            listen('sync:complete');
+            listen('sync:error');
+            listen('sync:live');
+            listen('bootstrap:start');
+            listen('bootstrap:progress');
+            listen('bootstrap:complete');
+            const timeoutId = setTimeout(finish, Math.max(1, timeoutMs));
+        });
+    }
+    mapSubscriptionToProgress(subscription) {
+        if (subscription.status === 'revoked') {
+            return {
+                stateId: subscription.stateId,
+                id: subscription.subscriptionId,
+                table: subscription.table,
+                phase: 'error',
+                progressPercent: 0,
+                startedAt: subscription.createdAt,
+                completedAt: subscription.updatedAt,
+                lastErrorCode: 'SUBSCRIPTION_REVOKED',
+                lastErrorMessage: 'Subscription is revoked',
+            };
+        }
+        if (subscription.bootstrapState) {
+            const tableCount = Math.max(0, subscription.bootstrapState.tables.length);
+            const tableIndex = Math.max(0, subscription.bootstrapState.tableIndex);
+            const tablesProcessed = Math.min(tableCount, tableIndex);
+            const progressPercent = tableCount === 0
+                ? 0
+                : Math.max(0, Math.min(100, Math.round((tablesProcessed / tableCount) * 100)));
+            return {
+                stateId: subscription.stateId,
+                id: subscription.subscriptionId,
+                table: subscription.table,
+                phase: 'bootstrapping',
+                progressPercent,
+                tablesProcessed,
+                tablesTotal: tableCount,
+                startedAt: this.bootstrapStartedAt.get(this.makeBootstrapKey(subscription.stateId, subscription.subscriptionId)),
+            };
+        }
+        if (this.state.error) {
+            return {
+                stateId: subscription.stateId,
+                id: subscription.subscriptionId,
+                table: subscription.table,
+                phase: 'error',
+                progressPercent: subscription.cursor >= 0 ? 100 : 0,
+                startedAt: subscription.createdAt,
+                lastErrorCode: this.state.error.code,
+                lastErrorMessage: this.state.error.message,
+            };
+        }
+        if (this.state.isSyncing) {
+            return {
+                stateId: subscription.stateId,
+                id: subscription.subscriptionId,
+                table: subscription.table,
+                phase: 'catching_up',
+                progressPercent: subscription.cursor >= 0 ? 90 : 0,
+                startedAt: subscription.createdAt,
+            };
+        }
+        if (subscription.cursor >= 0 || this.state.lastSyncAt !== null) {
+            return {
+                stateId: subscription.stateId,
+                id: subscription.subscriptionId,
+                table: subscription.table,
+                phase: 'live',
+                progressPercent: 100,
+                startedAt: subscription.createdAt,
+                completedAt: subscription.updatedAt,
+            };
+        }
+        return {
+            stateId: subscription.stateId,
+            id: subscription.subscriptionId,
+            table: subscription.table,
+            phase: 'idle',
+            progressPercent: 0,
+            startedAt: subscription.createdAt,
+        };
+    }
+    resolveChannelPhase(subscriptions) {
+        if (this.state.error)
+            return 'error';
+        if (subscriptions.some((sub) => sub.phase === 'error'))
+            return 'error';
+        if (subscriptions.some((sub) => sub.phase === 'bootstrapping')) {
+            return 'bootstrapping';
+        }
+        if (this.state.isSyncing) {
+            return this.state.lastSyncAt === null ? 'starting' : 'catching_up';
+        }
+        if (this.state.lastSyncAt !== null)
+            return 'live';
+        return 'idle';
+    }
+    deriveProgressFromPullSubscription(sub) {
+        const stateId = this.getStateId();
+        const key = this.makeBootstrapKey(stateId, sub.id);
+        const startedAt = this.bootstrapStartedAt.get(key);
+        if (sub.status === 'revoked') {
+            return {
+                stateId,
+                id: sub.id,
+                phase: 'error',
+                progressPercent: 0,
+                startedAt,
+                completedAt: Date.now(),
+                lastErrorCode: 'SUBSCRIPTION_REVOKED',
+                lastErrorMessage: 'Subscription is revoked',
+            };
+        }
+        if (sub.bootstrap && sub.bootstrapState) {
+            const tableCount = Math.max(0, sub.bootstrapState.tables.length);
+            const tableIndex = Math.max(0, sub.bootstrapState.tableIndex);
+            const tablesProcessed = Math.min(tableCount, tableIndex);
+            const progressPercent = tableCount === 0
+                ? 0
+                : Math.max(0, Math.min(100, Math.round((tablesProcessed / tableCount) * 100)));
+            return {
+                stateId,
+                id: sub.id,
+                phase: 'bootstrapping',
+                progressPercent,
+                tablesProcessed,
+                tablesTotal: tableCount,
+                startedAt,
+            };
+        }
+        return {
+            stateId,
+            id: sub.id,
+            phase: this.state.isSyncing ? 'catching_up' : 'live',
+            progressPercent: this.state.isSyncing ? 90 : 100,
+            startedAt,
+            completedAt: this.state.isSyncing ? undefined : Date.now(),
+        };
+    }
+    handleBootstrapLifecycle(response) {
+        const stateId = this.getStateId();
+        const now = Date.now();
+        const seenKeys = new Set();
+        for (const sub of response.subscriptions ?? []) {
+            const key = this.makeBootstrapKey(stateId, sub.id);
+            seenKeys.add(key);
+            const isBootstrapping = sub.bootstrap === true;
+            const wasBootstrapping = this.activeBootstrapSubscriptions.has(key);
+            if (isBootstrapping && !wasBootstrapping) {
+                this.activeBootstrapSubscriptions.add(key);
+                this.bootstrapStartedAt.set(key, now);
+                this.emit('bootstrap:start', {
+                    timestamp: now,
+                    stateId,
+                    subscriptionId: sub.id,
+                });
+            }
+            if (isBootstrapping) {
+                this.emit('bootstrap:progress', {
+                    timestamp: now,
+                    stateId,
+                    subscriptionId: sub.id,
+                    progress: this.deriveProgressFromPullSubscription(sub),
+                });
+            }
+            if (!isBootstrapping && wasBootstrapping) {
+                const startedAt = this.bootstrapStartedAt.get(key) ?? now;
+                this.activeBootstrapSubscriptions.delete(key);
+                this.bootstrapStartedAt.delete(key);
+                this.emit('bootstrap:complete', {
+                    timestamp: now,
+                    stateId,
+                    subscriptionId: sub.id,
+                    durationMs: Math.max(0, now - startedAt),
+                });
+            }
+        }
+        for (const key of Array.from(this.activeBootstrapSubscriptions)) {
+            if (seenKeys.has(key))
+                continue;
+            if (!key.startsWith(`${stateId}:`))
+                continue;
+            const subscriptionId = key.slice(stateId.length + 1);
+            if (!subscriptionId)
+                continue;
+            const startedAt = this.bootstrapStartedAt.get(key) ?? now;
+            this.activeBootstrapSubscriptions.delete(key);
+            this.bootstrapStartedAt.delete(key);
+            this.emit('bootstrap:complete', {
+                timestamp: now,
+                stateId,
+                subscriptionId,
+                durationMs: Math.max(0, now - startedAt),
+            });
+        }
+        if (this.activeBootstrapSubscriptions.size === 0 && !this.state.error) {
+            this.emit('sync:live', { timestamp: now });
+        }
+    }
+    async resolveResetTargets(options) {
+        const stateId = options.stateId ?? this.getStateId();
+        if (options.scope === 'all') {
+            return readSubscriptionStates(this.config.db);
+        }
+        if (options.scope === 'state') {
+            return readSubscriptionStates(this.config.db, { stateId });
+        }
+        const subscriptionIds = options.subscriptionIds ?? [];
+        if (subscriptionIds.length === 0) {
+            throw new Error('[SyncEngine.reset] subscriptionIds is required when scope="subscription"');
+        }
+        const allInState = await readSubscriptionStates(this.config.db, {
+            stateId,
+        });
+        const wanted = new Set(subscriptionIds);
+        return allInState.filter((state) => wanted.has(state.subscriptionId));
+    }
+    async clearSyncedTablesForReset(trx, options, targets) {
+        const clearedTables = [];
+        if (!options.clearSyncedTables) {
+            return clearedTables;
+        }
+        if (options.scope === 'all') {
+            for (const handler of this.config.handlers.getAll()) {
+                await handler.clearAll({ trx, scopes: {} });
+                clearedTables.push(handler.table);
+            }
+            return clearedTables;
+        }
+        const seen = new Set();
+        for (const target of targets) {
+            const handler = this.config.handlers.get(target.table);
+            if (!handler)
+                continue;
+            const key = `${target.table}:${JSON.stringify(target.scopes)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            await handler.clearAll({ trx, scopes: target.scopes });
+            clearedTables.push(target.table);
+        }
+        return clearedTables;
+    }
+    async reset(options) {
+        const resetOptions = {
+            clearOutbox: false,
+            clearConflicts: false,
+            clearSyncedTables: false,
+            ...options,
+        };
+        const targets = await this.resolveResetTargets(resetOptions);
+        const stateId = resetOptions.stateId ?? this.getStateId();
+        this.stop();
+        const result = await this.config.db.transaction().execute(async (trx) => {
+            const clearedTables = await this.clearSyncedTablesForReset(trx, resetOptions, targets);
+            let deletedSubscriptionStates = 0;
+            if (resetOptions.scope === 'all') {
+                const res = await sql `
+          delete from ${sql.table('sync_subscription_state')}
+        `.execute(trx);
+                deletedSubscriptionStates = Number(res.numAffectedRows ?? 0);
+            }
+            else if (resetOptions.scope === 'state') {
+                const res = await sql `
+          delete from ${sql.table('sync_subscription_state')}
+          where ${sql.ref('state_id')} = ${sql.val(stateId)}
+        `.execute(trx);
+                deletedSubscriptionStates = Number(res.numAffectedRows ?? 0);
+            }
+            else {
+                const subscriptionIds = resetOptions.subscriptionIds ?? [];
+                const res = await sql `
+          delete from ${sql.table('sync_subscription_state')}
+          where
+            ${sql.ref('state_id')} = ${sql.val(stateId)}
+            and ${sql.ref('subscription_id')} in (${sql.join(subscriptionIds.map((id) => sql.val(id)))})
+        `.execute(trx);
+                deletedSubscriptionStates = Number(res.numAffectedRows ?? 0);
+            }
+            let deletedOutboxCommits = 0;
+            if (resetOptions.clearOutbox) {
+                const res = await sql `
+          delete from ${sql.table('sync_outbox_commits')}
+        `.execute(trx);
+                deletedOutboxCommits = Number(res.numAffectedRows ?? 0);
+            }
+            let deletedConflicts = 0;
+            if (resetOptions.clearConflicts) {
+                const res = await sql `
+          delete from ${sql.table('sync_conflicts')}
+        `.execute(trx);
+                deletedConflicts = Number(res.numAffectedRows ?? 0);
+            }
+            return {
+                deletedSubscriptionStates,
+                deletedOutboxCommits,
+                deletedConflicts,
+                clearedTables,
+            };
+        });
+        if (resetOptions.scope === 'all') {
+            this.activeBootstrapSubscriptions.clear();
+            this.bootstrapStartedAt.clear();
+        }
+        else {
+            for (const target of targets) {
+                const key = this.makeBootstrapKey(target.stateId, target.subscriptionId);
+                this.activeBootstrapSubscriptions.delete(key);
+                this.bootstrapStartedAt.delete(key);
+            }
+        }
+        this.resetLocalState();
+        await this.refreshOutboxStats();
+        this.updateState({ error: null });
+        return result;
+    }
+    async repair(options) {
+        if (options.mode !== 'rebootstrap-missing-chunks') {
+            throw new Error(`[SyncEngine.repair] Unsupported repair mode: ${options.mode}`);
+        }
+        return this.reset({
+            scope: options.subscriptionIds ? 'subscription' : 'state',
+            stateId: options.stateId,
+            subscriptionIds: options.subscriptionIds,
+            clearOutbox: options.clearOutbox ?? false,
+            clearConflicts: options.clearConflicts ?? false,
+            clearSyncedTables: true,
+        });
+    }
     /**
      * Subscribe to sync events
      */
@@ -323,7 +893,17 @@ export class SyncEngine {
             catch (err) {
                 const migrationError = err instanceof Error ? err : new Error(String(err));
                 this.config.onMigrationError?.(migrationError);
-                const error = createSyncError('SYNC_ERROR', 'Migration failed', migrationError);
+                const error = createSyncError({
+                    code: 'MIGRATION_FAILED',
+                    message: 'Migration failed',
+                    cause: migrationError,
+                    retryable: false,
+                    stateId: this.getStateId(),
+                });
+                this.updateState({
+                    isSyncing: false,
+                    error,
+                });
                 this.handleError(error);
                 return;
             }
@@ -381,7 +961,12 @@ export class SyncEngine {
                 pushedCommits: 0,
                 pullRounds: 0,
                 pullResponse: { ok: true, subscriptions: [] },
-                error: createSyncError('SYNC_ERROR', 'Sync not enabled'),
+                error: createSyncError({
+                    code: 'SYNC_ERROR',
+                    message: 'Sync not enabled',
+                    retryable: false,
+                    stateId: this.getStateId(),
+                }),
             };
         }
         this.syncPromise = this.performSyncLoop(opts?.trigger);
@@ -398,7 +983,12 @@ export class SyncEngine {
             pushedCommits: 0,
             pullRounds: 0,
             pullResponse: { ok: true, subscriptions: [] },
-            error: createSyncError('SYNC_ERROR', 'Sync not started'),
+            error: createSyncError({
+                code: 'SYNC_ERROR',
+                message: 'Sync not started',
+                retryable: false,
+                stateId: this.getStateId(),
+            }),
         };
         do {
             this.syncRequestedWhileRunning = false;
@@ -457,6 +1047,9 @@ export class SyncEngine {
                 retryCount: 0,
                 isRetrying: false,
             });
+            this.updateTransportHealth({
+                lastSuccessfulPollAt: Date.now(),
+            });
             this.emit('sync:complete', {
                 timestamp: Date.now(),
                 pushedCommits: result.pushedCommits,
@@ -472,6 +1065,7 @@ export class SyncEngine {
                 });
                 this.config.onDataChange?.(changedTables);
             }
+            this.handleBootstrapLifecycle(result.pullResponse);
             // Refresh outbox stats (fire-and-forget — don't block sync:complete)
             this.refreshOutboxStats().catch((error) => {
                 console.warn('[SyncEngine] Failed to refresh outbox stats after sync:', error);
@@ -499,7 +1093,15 @@ export class SyncEngine {
             return syncResult;
         }
         catch (err) {
-            const error = createSyncError('SYNC_ERROR', err instanceof Error ? err.message : 'Sync failed', err instanceof Error ? err : undefined);
+            const classified = classifySyncFailure(err);
+            const error = createSyncError({
+                code: classified.code,
+                message: classified.message,
+                cause: classified.cause,
+                retryable: classified.retryable,
+                httpStatus: classified.httpStatus,
+                stateId: this.getStateId(),
+            });
             this.updateState({
                 isSyncing: false,
                 error,
@@ -527,7 +1129,7 @@ export class SyncEngine {
             });
             // Schedule retry if under max retries
             const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
-            if (this.state.retryCount < maxRetries) {
+            if (error.retryable && this.state.retryCount < maxRetries) {
                 this.scheduleRetry();
             }
             return {
@@ -666,12 +1268,19 @@ export class SyncEngine {
             retryCount: 0,
             isRetrying: false,
         });
+        this.updateTransportHealth({
+            mode: 'realtime',
+            connected: true,
+            fallbackReason: null,
+            lastSuccessfulPollAt: Date.now(),
+        });
         this.emit('sync:complete', {
             timestamp: Date.now(),
             pushedCommits: 0,
             pullRounds: 0,
             pullResponse: { ok: true, subscriptions: [] },
         });
+        this.emit('sync:live', { timestamp: Date.now() });
         this.refreshOutboxStats().catch((error) => {
             console.warn('[SyncEngine] Failed to refresh outbox stats after WS apply:', error);
         });
@@ -780,6 +1389,11 @@ export class SyncEngine {
             }
         }, interval);
         this.setConnectionState('connected');
+        this.updateTransportHealth({
+            mode: 'polling',
+            connected: true,
+            fallbackReason: null,
+        });
     }
     stopPolling() {
         if (this.pollerId) {
@@ -795,6 +1409,11 @@ export class SyncEngine {
             return;
         }
         this.setConnectionState('connecting');
+        this.updateTransportHealth({
+            mode: 'disconnected',
+            connected: false,
+            fallbackReason: null,
+        });
         const transport = this.config.transport;
         // Wire up presence events if transport supports them
         if (transport.onPresenceEvent) {
@@ -817,6 +1436,9 @@ export class SyncEngine {
         }
         this.realtimeDisconnect = transport.connect({ clientId: this.config.clientId }, (event) => {
             if (event.event === 'sync') {
+                this.updateTransportHealth({
+                    lastRealtimeMessageAt: Date.now(),
+                });
                 countSyncMetric('sync.client.ws.events', 1, {
                     attributes: { type: 'sync' },
                 });
@@ -840,6 +1462,11 @@ export class SyncEngine {
                     const wasConnectedBefore = this.hasRealtimeConnectedOnce;
                     this.hasRealtimeConnectedOnce = true;
                     this.setConnectionState('connected');
+                    this.updateTransportHealth({
+                        mode: 'realtime',
+                        connected: true,
+                        fallbackReason: null,
+                    });
                     this.stopFallbackPolling();
                     this.triggerSyncInBackground(undefined, 'realtime connected state');
                     if (wasConnectedBefore) {
@@ -849,9 +1476,17 @@ export class SyncEngine {
                 }
                 case 'connecting':
                     this.setConnectionState('connecting');
+                    this.updateTransportHealth({
+                        mode: 'disconnected',
+                        connected: false,
+                    });
                     break;
                 case 'disconnected':
                     this.setConnectionState('reconnecting');
+                    this.updateTransportHealth({
+                        mode: 'disconnected',
+                        connected: false,
+                    });
                     this.startFallbackPolling();
                     break;
             }
@@ -871,6 +1506,10 @@ export class SyncEngine {
             this.realtimeDisconnect = null;
         }
         this.stopFallbackPolling();
+        this.updateTransportHealth({
+            mode: 'disconnected',
+            connected: false,
+        });
     }
     scheduleRealtimeReconnectCatchupSync() {
         if (this.realtimeCatchupTimeoutId) {
@@ -889,6 +1528,11 @@ export class SyncEngine {
         if (this.fallbackPollerId)
             return;
         const interval = this.config.realtimeFallbackPollMs ?? 30_000;
+        this.updateTransportHealth({
+            mode: 'polling',
+            connected: false,
+            fallbackReason: 'network',
+        });
         this.fallbackPollerId = setInterval(() => {
             if (!this.state.isSyncing && !this.isDestroyed) {
                 this.triggerSyncInBackground(undefined, 'realtime fallback poll');
@@ -900,6 +1544,7 @@ export class SyncEngine {
             clearInterval(this.fallbackPollerId);
             this.fallbackPollerId = null;
         }
+        this.updateTransportHealth({ fallbackReason: null });
     }
     /**
      * Clear all in-memory mutation state and emit data:change so UI re-renders.