@stratasync/client 0.2.0

package/dist/sync-orchestrator.js

@@ -0,0 +1,1287 @@
+import { applyDeltas, createArchivePayload, createUnarchivePatch, getOrCreateClientId, isSyncIdGreaterThan, ModelRegistry, readArchivedAt, rebaseTransactions, ZERO_SYNC_ID, } from "@stratasync/core";
+import { getModelKey } from "./utils.js";
+/**
+ * Orchestrates the sync state machine
+ */
+export class SyncOrchestrator {
+    storage;
+    transport;
+    identityMaps;
+    outboxManager = null;
+    options;
+    registry;
+    _state = "disconnected";
+    _connectionState = "disconnected";
+    stateListeners = new Set();
+    connectionListeners = new Set();
+    schemaHash;
+    clientId = "";
+    lastSyncId = ZERO_SYNC_ID;
+    lastError = null;
+    firstSyncId = ZERO_SYNC_ID;
+    groups = [];
+    deltaSubscription = null;
+    // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+    deltaPacketQueue = Promise.resolve();
+    // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+    deltaReplayBarrier = Promise.resolve();
+    // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+    stateUpdateLock = Promise.resolve();
+    running = false;
+    runToken = 0;
+    emitEvent;
+    onTransactionConflict;
+    /** Conflict rollbacks deferred until the identity map batch. */
+    deferredConflictTxs = [];
+    constructor(options, identityMaps, emitEvent) {
+        this.options = options;
+        this.storage = options.storage;
+        this.transport = options.transport;
+        this.identityMaps = identityMaps;
+        this.registry = new ModelRegistry(options.schema ?? ModelRegistry.snapshot());
+        this.schemaHash = this.registry.getSchemaHash();
+        this.groups = options.groups ?? [];
+        this.emitEvent = emitEvent;
+        // Listen for transport connection changes
+        this.transport.onConnectionStateChange((state) => {
+            const previousState = this._connectionState;
+            this.setConnectionState(state);
+            this.handleConnectionChange(previousState, state);
+        });
+    }
+    setOutboxManager(outboxManager) {
+        this.outboxManager = outboxManager;
+    }
+    setConflictHandler(handler) {
+        this.onTransactionConflict = handler;
+    }
+    /**
+     * Gets the current sync state
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Gets the current connection state
+     */
+    get connectionState() {
+        return this._connectionState;
+    }
+    /**
+     * Gets the client ID
+     */
+    getClientId() {
+        return this.clientId;
+    }
+    /**
+     * Gets the last sync ID
+     */
+    getLastSyncId() {
+        return this.lastSyncId;
+    }
+    /**
+     * Gets the first sync ID from the last full bootstrap
+     */
+    getFirstSyncId() {
+        return this.firstSyncId;
+    }
+    /**
+     * Gets the last error
+     */
+    getLastError() {
+        return this.lastError;
+    }
+    /**
+     * Starts the sync orchestrator
+     */
+    async start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.runToken += 1;
+        const activeRunToken = this.runToken;
+        this.emitEvent?.({ type: "syncStart" });
+        this.setState("connecting");
+        try {
+            await this.openStorage();
+            if (!this.isRunActive(activeRunToken)) {
+                return;
+            }
+            const meta = await this.loadMetadata();
+            if (!this.isRunActive(activeRunToken)) {
+                return;
+            }
+            await this.configureGroups(meta);
+            if (!this.isRunActive(activeRunToken)) {
+                return;
+            }
+            await this.bootstrapIfNeeded(meta, activeRunToken);
+            if (!this.isRunActive(activeRunToken)) {
+                return;
+            }
+            await this.applyPendingOutboxTransactions();
+            if (!this.isRunActive(activeRunToken)) {
+                return;
+            }
+            // Local data is ready — mark as syncing so the UI can render
+            // cached content immediately without waiting for network ops.
+            this.setState("syncing");
+            // Network operations run in background, don't block start()
+            const subscribeAfterSyncId = this.lastSyncId;
+            this.startDeltaSubscription(subscribeAfterSyncId);
+            // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+            this.catchUpMissedDeltas(subscribeAfterSyncId, activeRunToken).catch(
+            // oxlint-disable-next-line prefer-await-to-callbacks -- event listener registration
+            (error) => {
+                if (this.isRunActive(activeRunToken)) {
+                    this.handleSyncError(error);
+                }
+            });
+            // oxlint-disable-next-line prefer-await-to-then, prefer-await-to-callbacks -- fire-and-forget error handler
+            this.processOutboxTransactions().catch((error) => {
+                if (this.isRunActive(activeRunToken)) {
+                    this.handleSyncError(error);
+                }
+            });
+        }
+        catch (error) {
+            this.handleSyncError(error);
+            throw error;
+        }
+    }
+    async openStorage() {
+        await this.storage.open({
+            name: this.options.dbName,
+            schema: this.options.schema ?? this.registry.snapshot(),
+            userId: this.options.userId,
+            userVersion: this.options.userVersion,
+            version: this.options.version,
+        });
+    }
+    async loadMetadata() {
+        const meta = await this.storage.getMeta();
+        this.clientId =
+            meta.clientId ??
+                getOrCreateClientId(`${this.options.dbName ?? "sync-db"}_client_id`);
+        this.lastSyncId = meta.lastSyncId ?? ZERO_SYNC_ID;
+        this.firstSyncId = meta.firstSyncId ?? this.lastSyncId;
+        return meta;
+    }
+    async configureGroups(meta) {
+        const storedGroups = meta.subscribedSyncGroups ?? [];
+        const configuredGroups = this.options.groups ?? storedGroups;
+        this.groups = configuredGroups.length > 0 ? configuredGroups : storedGroups;
+        if (SyncOrchestrator.areGroupsEqual(storedGroups, this.groups)) {
+            return;
+        }
+        this.firstSyncId = this.lastSyncId;
+        await this.storage.setMeta({
+            firstSyncId: this.firstSyncId,
+            subscribedSyncGroups: this.groups,
+            updatedAt: Date.now(),
+        });
+    }
+    async bootstrapIfNeeded(meta, runToken) {
+        const needsBootstrap = await this.shouldBootstrap(meta);
+        if (!needsBootstrap) {
+            await this.hydrateIdentityMaps(runToken);
+            return;
+        }
+        await this.runBootstrapStrategy(runToken);
+    }
+    async shouldBootstrap(meta) {
+        const bootstrapModels = this.registry.getBootstrapModelNames();
+        const arePersisted = await this.areModelsPersisted(bootstrapModels);
+        const storedHash = meta.schemaHash ?? "";
+        // Treat an empty/missing hash as a mismatch — a valid bootstrap always
+        // writes the hash, so an empty value means prior state is corrupt.
+        const hasSchemaMismatch = storedHash.length === 0 || storedHash !== this.schemaHash;
+        return (meta.bootstrapComplete === false ||
+            hasSchemaMismatch ||
+            this.lastSyncId === ZERO_SYNC_ID ||
+            !arePersisted);
+    }
+    async runBootstrapStrategy(runToken) {
+        const bootstrapMode = this.options.bootstrapMode ?? "auto";
+        if (bootstrapMode === "local") {
+            await this.localBootstrap(runToken);
+            return;
+        }
+        try {
+            await this.bootstrap(runToken);
+        }
+        catch (error) {
+            const canFallback = bootstrapMode === "auto" && (await this.hasLocalData());
+            if (canFallback) {
+                await this.localBootstrap(runToken);
+                return;
+            }
+            throw error;
+        }
+    }
+    async applyPendingOutboxTransactions() {
+        const pending = await this.getActiveOutboxTransactions();
+        await this.applyPendingTransactionsToIdentityMaps(pending);
+    }
+    async processOutboxTransactions() {
+        if (!this.outboxManager) {
+            return;
+        }
+        await this.outboxManager.completeUpToSyncId(this.lastSyncId);
+        await this.outboxManager.processPendingTransactions();
+        await this.emitOutboxCount();
+    }
+    /**
+     * Best-effort catch-up for deltas created between bootstrap completion and
+     * subscription readiness.
+     */
+    async catchUpMissedDeltas(afterSyncId, runToken) {
+        try {
+            await this.fetchAndApplyDeltaPages(afterSyncId, {
+                maxAttempts: 2,
+                runToken,
+                suppressFetchErrors: true,
+            });
+        }
+        catch (error) {
+            if (this.isRunActive(runToken)) {
+                this.handleSyncError(error);
+            }
+        }
+    }
+    async fetchAndApplyDeltaPages(afterSyncId, options = {}) {
+        let nextAfterSyncId = afterSyncId;
+        let releaseBarrier = null;
+        try {
+            while (true) {
+                const packet = await this.fetchDeltaPage(nextAfterSyncId, options);
+                if (!packet) {
+                    return;
+                }
+                if (options.runToken !== undefined &&
+                    !this.isRunActive(options.runToken)) {
+                    return;
+                }
+                if (packet.hasMore && !releaseBarrier) {
+                    releaseBarrier = this.acquireDeltaReplayBarrier();
+                }
+                await this.enqueueDeltaPacket(packet);
+                if (!packet.hasMore) {
+                    return;
+                }
+                if (!isSyncIdGreaterThan(packet.lastSyncId, nextAfterSyncId)) {
+                    return;
+                }
+                nextAfterSyncId = packet.lastSyncId;
+            }
+        }
+        finally {
+            releaseBarrier?.();
+        }
+    }
+    async fetchDeltaPage(afterSyncId, options) {
+        const maxAttempts = options.maxAttempts ?? 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+            if (options.runToken !== undefined &&
+                !this.isRunActive(options.runToken)) {
+                return null;
+            }
+            try {
+                return await this.transport.fetchDeltas(afterSyncId, undefined, this.groups);
+            }
+            catch (error) {
+                const isLastAttempt = attempt >= maxAttempts - 1;
+                if (isLastAttempt ||
+                    (options.runToken !== undefined &&
+                        !this.isRunActive(options.runToken))) {
+                    if (options.suppressFetchErrors) {
+                        return null;
+                    }
+                    throw error;
+                }
+                await SyncOrchestrator.wait(300 * (attempt + 1));
+            }
+        }
+        if (options.suppressFetchErrors) {
+            return null;
+        }
+        return null;
+    }
+    static wait(ms) {
+        // oxlint-disable-next-line avoid-new -- wrapping callback API in promise
+        return new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        });
+    }
+    isRunActive(runToken) {
+        return this.running && this.runToken === runToken;
+    }
+    shouldAbortBootstrap(runToken) {
+        if (this.isRunActive(runToken)) {
+            return false;
+        }
+        this.identityMaps.clearAll();
+        return true;
+    }
+    /**
+     * Stops the sync orchestrator
+     */
+    async stop() {
+        await this.reset();
+        await this.storage.close();
+    }
+    async reset() {
+        this.running = false;
+        this.runToken += 1;
+        if (this.deltaSubscription) {
+            try {
+                await this.deltaSubscription.return?.();
+            }
+            catch {
+                // Best-effort close while resetting.
+            }
+            this.deltaSubscription = null;
+        }
+        await this.transport.close();
+        await this.deltaPacketQueue.catch(() => {
+            /* noop */
+        });
+        // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+        this.deltaPacketQueue = Promise.resolve();
+        // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+        this.deltaReplayBarrier = Promise.resolve();
+        // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+        this.stateUpdateLock = Promise.resolve();
+        this.deferredConflictTxs = [];
+        this.clientId = "";
+        this.lastSyncId = ZERO_SYNC_ID;
+        this.firstSyncId = ZERO_SYNC_ID;
+        this.groups = this.options.groups ?? [];
+        this.lastError = null;
+        this.setConnectionState("disconnected");
+        this.setState("disconnected");
+    }
+    /**
+     * Forces an immediate sync
+     */
+    async syncNow() {
+        await this.fetchAndApplyDeltaPages(this.lastSyncId);
+        // Process pending outbox
+        if (this.outboxManager) {
+            await this.outboxManager.processPendingTransactions();
+        }
+    }
+    /**
+     * Subscribes to state changes
+     */
+    // oxlint-disable-next-line prefer-await-to-callbacks -- event listener registration
+    onStateChange(callback) {
+        this.stateListeners.add(callback);
+        return () => {
+            this.stateListeners.delete(callback);
+        };
+    }
+    /**
+     * Subscribes to connection state changes
+     */
+    onConnectionStateChange(
+    // oxlint-disable-next-line prefer-await-to-callbacks -- event listener registration
+    callback) {
+        this.connectionListeners.add(callback);
+        return () => {
+            this.connectionListeners.delete(callback);
+        };
+    }
+    async runWithStateLock(operation) {
+        const previous = this.stateUpdateLock;
+        let releaseCurrent;
+        // oxlint-disable-next-line avoid-new -- wrapping callback API in promise
+        const current = new Promise((resolve) => {
+            releaseCurrent = resolve;
+        });
+        this.stateUpdateLock = (async () => {
+            try {
+                await previous;
+            }
+            catch {
+                /* noop */
+            }
+            await current;
+        })();
+        try {
+            await previous;
+        }
+        catch {
+            /* noop */
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            releaseCurrent?.();
+        }
+    }
+    /**
+     * Performs initial bootstrap
+     */
+    async bootstrap(runToken) {
+        this.setState("bootstrapping");
+        // Clear existing model/meta state but keep outbox transactions so
+        // unsynced mutations survive a full bootstrap on restart.
+        await this.storage.clear({ preserveOutbox: true });
+        this.identityMaps.clearAll();
+        if (this.shouldAbortBootstrap(runToken)) {
+            return;
+        }
+        // Stream bootstrap data
+        const iterator = this.transport.bootstrap({
+            onlyModels: this.registry.getBootstrapModelNames(),
+            schemaHash: this.schemaHash,
+            syncGroups: this.groups,
+            type: "full",
+        });
+        const metadata = await this.readBootstrapStream(iterator, runToken);
+        if (!metadata) {
+            return;
+        }
+        const databaseVersion = this.applyBootstrapMetadata(metadata);
+        const persisted = await this.markBootstrapModelsPersisted(runToken);
+        if (!persisted) {
+            return;
+        }
+        await this.storage.setMeta({
+            bootstrapComplete: true,
+            databaseVersion,
+            firstSyncId: this.firstSyncId,
+            lastSyncAt: Date.now(),
+            lastSyncId: this.lastSyncId,
+            schemaHash: this.schemaHash,
+            subscribedSyncGroups: this.groups,
+            updatedAt: Date.now(),
+        });
+        this.emitEvent?.({ lastSyncId: this.lastSyncId, type: "syncComplete" });
+    }
+    async readBootstrapStream(iterator, runToken) {
+        while (true) {
+            const { value, done } = await iterator.next();
+            if (this.shouldAbortBootstrap(runToken)) {
+                return null;
+            }
+            if (done) {
+                if (!value) {
+                    throw new Error("Bootstrap completed without metadata");
+                }
+                return value;
+            }
+            await this.storeBootstrapRow(value);
+            if (this.shouldAbortBootstrap(runToken)) {
+                return null;
+            }
+        }
+    }
+    async storeBootstrapRow(row) {
+        const primaryKey = this.registry.getPrimaryKey(row.modelName);
+        const id = row.data[primaryKey];
+        if (typeof id !== "string") {
+            return;
+        }
+        await this.storage.put(row.modelName, row.data);
+        const map = this.identityMaps.getMap(row.modelName);
+        map.set(id, row.data);
+    }
+    applyBootstrapMetadata(metadata) {
+        if (metadata.lastSyncId === undefined) {
+            throw new Error("Bootstrap metadata is missing lastSyncId");
+        }
+        this.lastSyncId = metadata.lastSyncId;
+        this.firstSyncId = metadata.lastSyncId;
+        this.groups =
+            (metadata.subscribedSyncGroups?.length ?? 0) > 0
+                ? metadata.subscribedSyncGroups
+                : this.groups;
+        return metadata.databaseVersion;
+    }
+    async markBootstrapModelsPersisted(runToken) {
+        for (const modelName of this.registry.getBootstrapModelNames()) {
+            await this.storage.setModelPersistence(modelName, true);
+            if (this.shouldAbortBootstrap(runToken)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Performs a local-only bootstrap using existing storage data.
+     */
+    async localBootstrap(runToken) {
+        this.setState("bootstrapping");
+        await this.hydrateIdentityMaps(runToken);
+    }
+    /**
+     * Checks whether any hydrated models exist in storage.
+     */
+    async hasLocalData() {
+        for (const modelName of this.registry.getBootstrapModelNames()) {
+            const count = await this.storage.count(modelName);
+            if (count > 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Loads existing data from storage into identity maps
+     */
+    async hydrateIdentityMaps(runToken) {
+        for (const modelName of this.registry.getBootstrapModelNames()) {
+            if (!this.isRunActive(runToken)) {
+                return;
+            }
+            const rows = await this.storage.getAll(modelName);
+            if (!this.isRunActive(runToken)) {
+                return;
+            }
+            const map = this.identityMaps.getMap(modelName);
+            const primaryKey = this.registry.getPrimaryKey(modelName);
+            for (const row of rows) {
+                if (!this.isRunActive(runToken)) {
+                    return;
+                }
+                const id = row[primaryKey];
+                if (typeof id !== "string") {
+                    continue;
+                }
+                map.set(id, row);
+            }
+        }
+    }
+    async areModelsPersisted(modelNames) {
+        for (const modelName of modelNames) {
+            const persistence = await this.storage.getModelPersistence(modelName);
+            if (!persistence.persisted) {
+                return false;
+            }
+        }
+        return true;
+    }
+    static areGroupsEqual(a, b) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        const setA = new Set(a);
+        if (setA.size !== b.length) {
+            return false;
+        }
+        for (const value of b) {
+            if (!setA.has(value)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Starts the delta subscription
+     */
+    startDeltaSubscription(afterSyncId = this.lastSyncId) {
+        const subscription = this.transport.subscribe({
+            afterSyncId,
+            groups: this.groups,
+        });
+        this.deltaSubscription = subscription[Symbol.asyncIterator]();
+        // Process deltas in background
+        // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+        this.processDeltaStream().catch(() => {
+            /* noop */
+        });
+    }
+    async restartDeltaSubscription(afterSyncId) {
+        const current = this.deltaSubscription;
+        this.deltaSubscription = null;
+        if (current) {
+            try {
+                await current.return?.();
+            }
+            catch {
+                // Best-effort close of the existing iterator.
+            }
+        }
+        this.startDeltaSubscription(afterSyncId);
+    }
+    /**
+     * Processes the delta stream
+     */
+    async processDeltaStream() {
+        if (!this.deltaSubscription) {
+            return;
+        }
+        try {
+            while (this.running) {
+                await this.deltaReplayBarrier;
+                const subscription = this.deltaSubscription;
+                if (!subscription) {
+                    break;
+                }
+                const { value, done } = await subscription.next();
+                if (done) {
+                    break;
+                }
+                await this.deltaReplayBarrier;
+                await this.enqueueDeltaPacket(value);
+            }
+        }
+        catch (error) {
+            if (this.running) {
+                this.handleSyncError(error);
+                // Try to reconnect
+                setTimeout(() => {
+                    if (this.running) {
+                        this.startDeltaSubscription();
+                    }
+                }, 5000);
+            }
+        }
+    }
+    enqueueDeltaPacket(packet) {
+        const previous = this.deltaPacketQueue;
+        const run = (async () => {
+            await previous;
+            if (!this.running) {
+                return;
+            }
+            await this.runWithStateLock(async () => {
+                await this.applyDeltaPacket(packet);
+            });
+        })();
+        // oxlint-disable-next-line prefer-await-to-then -- fire-and-forget pattern
+        this.deltaPacketQueue = run.catch(() => {
+            /* noop */
+        });
+        return run;
+    }
+    handleSyncError(error) {
+        this.lastError = error instanceof Error ? error : new Error(String(error));
+        this.emitEvent?.({ error: this.lastError, type: "syncError" });
+        this.setState("error");
+    }
+    /**
+     * Applies a delta packet to local state.
+     *
+     * Identity map mutations are deferred and applied in a single batch at the
+     * end so that MobX observers never see an intermediate state where server
+     * data has been written but pending local (outbox) changes have not yet been
+     * re-applied.
+     */
+    async applyDeltaPacket(packet) {
+        const latestAppliedSyncId = this.lastSyncId;
+        const nextActions = packet.actions.filter((action) => isSyncIdGreaterThan(action.id, latestAppliedSyncId));
+        const filteredPacket = {
+            ...packet,
+            actions: nextActions,
+        };
+        if (filteredPacket.actions.length === 0) {
+            await this.handleEmptyPacket(filteredPacket);
+            return;
+        }
+        await this.storage.addSyncActions(filteredPacket.actions);
+        const activeTransactions = await this.getActiveOutboxTransactions();
+        // rebasePendingTransactions may detect conflicts and defer rollbacks
+        // into this.deferredConflictTxs (processed inside the batch below).
+        await this.rebasePendingTransactions(activeTransactions, filteredPacket.actions);
+        await this.handleCoverageActions(filteredPacket.actions);
+        await this.handleSyncGroupActions(filteredPacket.actions, filteredPacket.lastSyncId);
+        // Write to storage and collect identity map ops (no MobX reactions yet).
+        const deferredOps = [];
+        await this.collectDeferredDeltaOps(filteredPacket.actions, deferredOps);
+        const syncCursorAdvanced = await this.updateSyncMetadata(filteredPacket.lastSyncId);
+        await this.finishOutboxProcessing(filteredPacket.actions);
+        // Use the instance-local set of clientTxIds for echo suppression.
+        // Reading from shared storage (IndexedDB) would include cross-tab
+        // transactions, incorrectly suppressing identity map merges for them.
+        const localTxIds = this.outboxManager?.getLocalClientTxIds() ?? new Set();
+        const ownClientTxIds = SyncOrchestrator.buildOwnClientTxIds(filteredPacket.actions, localTxIds);
+        // Apply identity map changes in a single MobX action so observers
+        // only see the final state (server data + pending local changes).
+        // Deferred conflict rollbacks are processed here too — inside the
+        // batch — so their intermediate deletes are never visible.
+        const pending = await this.getActiveOutboxTransactions();
+        this.identityMaps.batch(() => {
+            // Process conflict rollbacks inside the batch.  This ensures that
+            // the rollback's map.delete() and the subsequent server merge's
+            // map.merge() are in the same runInAction — microtask-scheduled
+            // refreshSync only fires after both have completed.
+            // Also remove rolled-back clientTxIds from ownClientTxIds so the
+            // server merge's modelChange event emits properly for the model.
+            for (const tx of this.deferredConflictTxs) {
+                this.onTransactionConflict?.(tx);
+                if (tx.clientTxId) {
+                    ownClientTxIds.delete(tx.clientTxId);
+                }
+            }
+            this.deferredConflictTxs = [];
+            for (const op of deferredOps) {
+                const map = this.identityMaps.getMap(op.modelName);
+                const isOwnOptimisticEcho = op.type === "merge" &&
+                    typeof op.clientTxId === "string" &&
+                    ownClientTxIds.has(op.clientTxId) &&
+                    map.has(op.id);
+                if (isOwnOptimisticEcho) {
+                    continue;
+                }
+                if (op.type === "merge" && op.data) {
+                    map.merge(op.id, op.data);
+                }
+                else if (op.type === "delete") {
+                    map.delete(op.id);
+                }
+            }
+            this.applyPendingTransactionsToIdentityMaps(pending);
+        });
+        this.emitModelChangeEvents(filteredPacket.actions, ownClientTxIds);
+        await this.emitOutboxCount();
+        if (syncCursorAdvanced) {
+            this.emitEvent?.({ lastSyncId: this.lastSyncId, type: "syncComplete" });
+        }
+    }
+    async handleEmptyPacket(packet) {
+        const syncCursorAdvanced = await this.updateSyncMetadata(packet.lastSyncId);
+        if (this.outboxManager) {
+            await this.outboxManager.completeUpToSyncId(this.lastSyncId);
+        }
+        await this.emitOutboxCount();
+        if (syncCursorAdvanced) {
+            this.emitEvent?.({ lastSyncId: this.lastSyncId, type: "syncComplete" });
+        }
+    }
+    /**
+     * Build set of own-action keys for transactions that this local runtime
+     * already applied optimistically and then saw confirmed by the server.
+     *
+     * Uses the instance-local set of clientTxIds (in-memory, not from shared
+     * storage) so that cross-tab transactions sharing the same IndexedDB are
+     * not incorrectly treated as own optimistic echoes.
+     */
+    static buildOwnClientTxIds(actions, localTxIds) {
+        const clientTxIds = new Set();
+        for (const action of actions) {
+            if (action.clientTxId && localTxIds.has(action.clientTxId)) {
+                clientTxIds.add(action.clientTxId);
+            }
+        }
+        return clientTxIds;
+    }
+    async getActiveOutboxTransactions() {
+        const outbox = await this.storage.getOutbox();
+        return outbox.filter((tx) => tx.state === "queued" ||
+            tx.state === "sent" ||
+            tx.state === "awaitingSync");
+    }
+    /**
+     * Creates a delta target that writes to storage immediately but collects
+     * identity map operations for deferred application in a single batch.
+     */
+    createDeferredDeltaTarget(ops, action) {
+        return {
+            delete: async (modelName, id) => {
+                await this.storage.delete(modelName, id);
+                ops.push({
+                    clientTxId: action.clientTxId,
+                    id,
+                    modelName,
+                    type: "delete",
+                });
+            },
+            get: (modelName, id) => this.storage.get(modelName, id),
+            patch: async (modelName, id, changes) => {
+                const existing = await this.storage.get(modelName, id);
+                const pk = this.registry.getPrimaryKey(modelName);
+                const updated = existing
+                    ? { ...existing, ...changes }
+                    : { ...changes, [pk]: id };
+                await this.storage.put(modelName, updated);
+                ops.push({
+                    clientTxId: action.clientTxId,
+                    data: updated,
+                    id,
+                    modelName,
+                    type: "merge",
+                });
+            },
+            put: async (modelName, id, data) => {
+                const pk = this.registry.getPrimaryKey(modelName);
+                const row = { ...data, [pk]: id };
+                await this.storage.put(modelName, row);
+                ops.push({
+                    clientTxId: action.clientTxId,
+                    data: row,
+                    id,
+                    modelName,
+                    type: "merge",
+                });
+            },
+        };
+    }
+    async collectDeferredDeltaOps(actions, ops) {
+        for (const action of actions) {
+            const deferredTarget = this.createDeferredDeltaTarget(ops, action);
+            await applyDeltas({ actions: [action], lastSyncId: action.id }, deferredTarget, this.registry, { mergeUpdates: true });
+        }
+    }
+    async updateSyncMetadata(lastSyncId) {
+        if (!isSyncIdGreaterThan(lastSyncId, this.lastSyncId)) {
+            return false;
+        }
+        this.lastSyncId = lastSyncId;
+        await this.storage.setMeta({
+            lastSyncAt: Date.now(),
+            lastSyncId: this.lastSyncId,
+            updatedAt: Date.now(),
+        });
+        return true;
+    }
+    async finishOutboxProcessing(actions) {
+        const confirmedTxIds = await this.removeConfirmedTransactions(actions);
+        const redundantTxIds = await this.removeRedundantCreateTransactions(actions);
+        if (this.outboxManager) {
+            await this.outboxManager.completeUpToSyncId(this.lastSyncId);
+        }
+        for (const id of redundantTxIds) {
+            confirmedTxIds.add(id);
+        }
+        return confirmedTxIds;
+    }
+    static resolveModelChangeAction(action) {
+        switch (action) {
+            case "I": {
+                return "insert";
+            }
+            case "U": {
+                return "update";
+            }
+            case "D": {
+                return "delete";
+            }
+            case "A": {
+                return "archive";
+            }
+            case "V": {
+                return "unarchive";
+            }
+            default: {
+                return null;
+            }
+        }
+    }
+    emitModelChangeEvents(actions, ownClientTxIds) {
+        // Deduplicate by modelName:modelId and skip local optimistic echoes only.
+        // Cross-tab updates can share clientId and must still emit modelChange.
+        const lastByKey = new Map();
+        for (const action of actions) {
+            if (action.clientTxId && ownClientTxIds.has(action.clientTxId)) {
+                continue;
+            }
+            const key = getModelKey(action.modelName, action.modelId);
+            lastByKey.set(key, action);
+        }
+        for (const action of lastByKey.values()) {
+            const eventAction = SyncOrchestrator.resolveModelChangeAction(action.action);
+            if (!eventAction) {
+                continue;
+            }
+            this.emitEvent?.({
+                action: eventAction,
+                modelId: action.modelId,
+                modelName: action.modelName,
+                type: "modelChange",
+            });
+        }
+    }
+    async emitOutboxCount() {
+        if (!this.emitEvent) {
+            return;
+        }
+        // oxlint-disable-next-line no-await-expression-member
+        const pendingCount = (await this.getActiveOutboxTransactions()).length;
+        this.emitEvent({ pendingCount, type: "outboxChange" });
+    }
+    async rebasePendingTransactions(pending, actions) {
+        if (pending.length === 0) {
+            return;
+        }
+        const rebaseOptions = {
+            clientId: this.clientId,
+            defaultResolution: this.options.rebaseStrategy ?? "server-wins",
+            fieldLevelConflicts: this.options.fieldLevelConflicts ?? true,
+        };
+        const result = rebaseTransactions(pending, actions, rebaseOptions);
+        for (const conflict of result.conflicts) {
+            await this.handleConflict(conflict);
+        }
+        await this.updatePendingOriginals(result.pending, actions);
+    }
+    async handleConflict(conflict) {
+        const { localTransaction: tx } = conflict;
+        const resolution = conflict.resolution === "manual" ? "server-wins" : conflict.resolution;
+        if (resolution === "server-wins") {
+            await this.storage.removeFromOutbox(tx.clientTxId);
+            // Defer identity map rollback until the batch so it runs in the same
+            // runInAction as the server merge.  Firing it here would delete the
+            // item from the identity map and emit modelChange(delete) BEFORE the
+            // deferred batch re-adds it, causing a visible flash of empty state.
+            this.deferredConflictTxs.push(tx);
+        }
+        else if ((resolution === "client-wins" || resolution === "merge") &&
+            (tx.action === "U" || tx.action === "A" || tx.action === "V")) {
+            const updatedOriginal = {
+                ...tx.original,
+                ...conflict.serverAction.data,
+            };
+            tx.original = updatedOriginal;
+            await this.storage.updateOutboxTransaction(tx.clientTxId, {
+                original: updatedOriginal,
+            });
+        }
+        this.emitEvent?.({
+            conflictType: conflict.conflictType,
+            modelId: tx.modelId,
+            modelName: tx.modelName,
+            resolution,
+            type: "rebaseConflict",
+        });
+    }
+    async updatePendingOriginals(pending, actions) {
+        const actionsByKey = SyncOrchestrator.buildActionsByKey(actions);
+        for (const tx of pending) {
+            if (tx.action !== "U" && tx.action !== "A" && tx.action !== "V") {
+                continue;
+            }
+            const key = getModelKey(tx.modelName, tx.modelId);
+            const related = actionsByKey.get(key);
+            if (!related) {
+                continue;
+            }
+            const updatedOriginal = SyncOrchestrator.getUpdatedOriginal(tx, related);
+            if (!updatedOriginal) {
+                continue;
+            }
+            tx.original = updatedOriginal;
+            await this.storage.updateOutboxTransaction(tx.clientTxId, {
+                original: updatedOriginal,
+            });
+        }
+    }
+    static buildActionsByKey(actions) {
+        const actionsByKey = new Map();
+        for (const action of actions) {
+            const key = getModelKey(action.modelName, action.modelId);
+            const existing = actionsByKey.get(key) ?? [];
+            existing.push(action);
+            actionsByKey.set(key, existing);
+        }
+        return actionsByKey;
+    }
+    static shouldRebaseAction(action) {
+        return action === "U" || action === "I" || action === "V" || action === "C";
+    }
+    static getUpdatedOriginal(tx, related) {
+        const original = { ...tx.original };
+        let updated = false;
+        for (const action of related) {
+            if (!SyncOrchestrator.shouldRebaseAction(action.action)) {
+                continue;
+            }
+            for (const field of Object.keys(tx.payload)) {
+                if (field in action.data) {
+                    original[field] = action.data[field];
+                    updated = true;
+                }
+            }
+        }
+        return updated ? original : null;
+    }
+    /**
+     * Re-applies pending outbox transactions to identity maps after a server sync.
+     * This intentionally differs from rollbackTransaction (which inverts) and
+     * applyDeltas (which writes to storage) — it re-applies forward to restore
+     * optimistic state on top of newly-synced server data.
+     */
+    applyPendingTransactionsToIdentityMaps(pending) {
+        if (pending.length === 0) {
+            return;
+        }
+        for (const tx of pending) {
+            const map = this.identityMaps.getMap(tx.modelName);
+            switch (tx.action) {
+                case "I": {
+                    // Only re-create if the model was removed (e.g. conflict rollback).
+                    // If it already exists, the optimistic insert is still valid and
+                    // re-merging the full create payload would overwrite field changes
+                    // from optimistic updates whose outbox writes are still in-flight.
+                    if (!map.has(tx.modelId)) {
+                        map.merge(tx.modelId, tx.payload);
+                    }
+                    break;
+                }
+                case "U": {
+                    map.merge(tx.modelId, tx.payload);
+                    break;
+                }
+                case "D": {
+                    map.delete(tx.modelId);
+                    break;
+                }
+                case "A": {
+                    map.merge(tx.modelId, createArchivePayload(readArchivedAt(tx.payload)));
+                    break;
+                }
+                case "V": {
+                    const existing = map.get(tx.modelId);
+                    if (existing) {
+                        const updated = {
+                            ...existing,
+                            ...createUnarchivePatch(),
+                        };
+                        map.set(tx.modelId, updated);
+                    }
+                    break;
+                }
+                default: {
+                    break;
+                }
+            }
+        }
+    }
+    async removeConfirmedTransactions(actions) {
+        const confirmed = new Set();
+        const clientTxIds = actions
+            .map((action) => action.clientTxId)
+            .filter((value) => typeof value === "string");
+        if (clientTxIds.length === 0) {
+            return confirmed;
+        }
+        const outbox = await this.storage.getOutbox();
+        const known = new Set(outbox.map((tx) => tx.clientTxId));
+        for (const clientTxId of clientTxIds) {
+            if (known.has(clientTxId)) {
+                await this.storage.removeFromOutbox(clientTxId);
+                confirmed.add(clientTxId);
+            }
+        }
+        return confirmed;
+    }
+    async removeRedundantCreateTransactions(actions) {
+        const redundant = new Set();
+        const createdIds = actions
+            .filter((action) => action.action === "I")
+            .map((action) => action.modelId);
+        if (createdIds.length === 0) {
+            return redundant;
+        }
+        const createdSet = new Set(createdIds);
+        const outbox = await this.storage.getOutbox();
+        for (const tx of outbox) {
+            if (tx.action === "I" && createdSet.has(tx.modelId)) {
+                await this.storage.removeFromOutbox(tx.clientTxId);
+                redundant.add(tx.clientTxId);
+            }
+        }
+        return redundant;
+    }
+    async handleCoverageActions(actions) {
+        for (const action of actions) {
+            if (action.action !== "C") {
+                continue;
+            }
+            const { indexedKey } = action.data;
+            const { keyValue } = action.data;
+            if (typeof indexedKey === "string" && typeof keyValue === "string") {
+                await this.storage.setPartialIndex(action.modelName, indexedKey, keyValue);
+            }
+        }
+    }
+    async handleSyncGroupActions(actions, nextSyncId) {
+        const groupUpdates = [];
+        for (const action of actions) {
+            if (action.action !== "G" && action.action !== "S") {
+                continue;
+            }
+            const data = action.data;
+            const groups = data.subscribedSyncGroups;
+            if (Array.isArray(groups)) {
+                const filtered = groups.filter((group) => typeof group === "string");
+                if (filtered.length > 0) {
+                    groupUpdates.push(filtered);
+                }
+            }
+        }
+        if (groupUpdates.length === 0) {
+            return;
+        }
+        const nextGroups = groupUpdates.at(-1);
+        if (!nextGroups ||
+            SyncOrchestrator.areGroupsEqual(this.groups, nextGroups)) {
+            return;
+        }
+        const currentSet = new Set(this.groups);
+        const nextSet = new Set(nextGroups);
+        const addedGroups = nextGroups.filter((group) => !currentSet.has(group));
+        const removedGroups = this.groups.filter((group) => !nextSet.has(group));
+        if (addedGroups.length > 0) {
+            await this.bootstrapSyncGroups(addedGroups, nextSyncId);
+        }
+        if (removedGroups.length > 0) {
+            await this.removeSyncGroupData(removedGroups);
+        }
+        this.groups = nextGroups;
+        this.firstSyncId = nextSyncId;
+        await this.storage.setMeta({
+            firstSyncId: this.firstSyncId,
+            subscribedSyncGroups: this.groups,
+            updatedAt: Date.now(),
+        });
+        const pending = await this.getActiveOutboxTransactions();
+        this.identityMaps.batch(() => {
+            this.applyPendingTransactionsToIdentityMaps(pending);
+        });
+        if (this.running) {
+            await this.restartDeltaSubscription(nextSyncId);
+        }
+    }
+    async bootstrapSyncGroups(groups, firstSyncId) {
+        const iterator = this.transport.bootstrap({
+            firstSyncId,
+            noSyncPackets: true,
+            schemaHash: this.schemaHash,
+            syncGroups: groups,
+            type: "partial",
+        });
+        const hydrated = new Set(this.registry.getBootstrapModelNames());
+        while (true) {
+            const { value, done } = await iterator.next();
+            if (done) {
+                break;
+            }
+            const row = value;
+            const primaryKey = this.registry.getPrimaryKey(row.modelName);
+            const id = row.data[primaryKey];
+            if (typeof id !== "string") {
+                continue;
+            }
+            await this.storage.put(row.modelName, row.data);
+            if (hydrated.has(row.modelName)) {
+                const map = this.identityMaps.getMap(row.modelName);
+                map.merge(id, row.data);
+            }
+        }
+    }
+    async removeSyncGroupData(groups) {
+        if (groups.length === 0) {
+            return;
+        }
+        for (const model of this.registry.getAllModels()) {
+            const modelName = model.name ?? "";
+            const { groupKey } = model;
+            if (!(modelName && groupKey)) {
+                continue;
+            }
+            const primaryKey = model.primaryKey ?? "id";
+            const map = this.identityMaps.getMap(modelName);
+            for (const group of groups) {
+                const rows = await this.storage.getByIndex(modelName, groupKey, group);
+                for (const row of rows) {
+                    const id = row[primaryKey];
+                    if (typeof id !== "string") {
+                        continue;
+                    }
+                    await this.storage.delete(modelName, id);
+                    map.delete(id);
+                    this.emitEvent?.({
+                        action: "delete",
+                        modelId: id,
+                        modelName,
+                        type: "modelChange",
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Handles connection state changes
+     */
+    handleConnectionChange(previousState, state) {
+        if (!this.running ||
+            state !== "connected" ||
+            previousState === "connected" ||
+            this._state === "connecting" ||
+            this._state === "bootstrapping") {
+            return;
+        }
+        (async () => {
+            try {
+                await this.syncNow();
+                if (this.running) {
+                    this.setState("syncing");
+                }
+            }
+            catch {
+                // Ignore errors, will retry
+            }
+        })();
+    }
+    /**
+     * Sets the sync state
+     */
+    setState(state) {
+        if (this._state !== state) {
+            this._state = state;
+            if (state !== "error") {
+                this.lastError = null;
+            }
+            this.emitEvent?.({ state, type: "stateChange" });
+            for (const listener of this.stateListeners) {
+                listener(state);
+            }
+        }
+    }
+    /**
+     * Sets the connection state
+     */
+    setConnectionState(state) {
+        if (this._connectionState !== state) {
+            this._connectionState = state;
+            this.emitEvent?.({ state, type: "connectionChange" });
+            for (const listener of this.connectionListeners) {
+                listener(state);
+            }
+        }
+    }
+    /**
+     * Gets the model registry
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Gets the storage adapter
+     */
+    getStorage() {
+        return this.storage;
+    }
+    acquireDeltaReplayBarrier() {
+        const previousBarrier = this.deltaReplayBarrier;
+        // eslint-disable-next-line unicorn/consistent-function-scoping -- releaseBarrier is reassigned inside Promise constructor
+        let releaseBarrier = () => undefined;
+        // oxlint-disable-next-line avoid-new -- wrapping callback API in promise
+        const currentBarrier = new Promise((resolve) => {
+            releaseBarrier = resolve;
+        });
+        this.deltaReplayBarrier = (async () => {
+            await previousBarrier;
+            await currentBarrier;
+        })();
+        return () => {
+            releaseBarrier();
+        };
+    }
+}
+//# sourceMappingURL=sync-orchestrator.js.map