Findings from an adoption attempt of BrowserCollectionCoordinator (@tanstack/browser-db-sqlite-persistence 0.2.12, @tanstack/db-sqlite-persistence-core 0.2.12, @tanstack/db 0.7.2, Electric collections). Verified empirically with two pages in one Chromium context (shared storage partition) plus source reading. Happy to share probe scripts.
1. The coordinator holds one adapter, so per-collection schemaVersions destroy each other's tables
createBrowserWASQLitePersistence creates one adapter per distinct (schemaMismatchPolicy, schemaVersion) and calls coordinator.setAdapter(...) for each — the coordinator keeps whichever was created last. The schema check runs in ensureCollectionReadyInternal, which every adapter method reaches, and ensureCollectionState fires acquireLeadership → getStreamPosition for every subscribed collection through that single adapter. With per-collection versions (we compute one per Electric shape) the wrong-version adapter touches every other collection: under sync-present-reset we observed collection_reset_epoch climb 0→5 during one run, a 9,475-row table wiped to 0, every reload re-syncing cold, and the registry's schema_version flipping between two collections' hashes.
A second failure appears even with matching versions: two adapter instances race ensureCollectionReadyInternal for the same collection on a fresh registry (UNIQUE constraint failed: collection_registry.tombstone_table_name, then no such table: t_… when the loser tries to reset a table the winner has not created yet). Leadership is never acquired for those collections.
One global schemaVersion (all adapters collapse to one instance) avoids all of this, at the cost that any schema change resets the whole database. Suggestion: key leader-side adapter access by collection — e.g. requireAdapter(collectionId) with a resolver passed to the constructor — instead of a single setAdapter slot.
2. Sync-ingested transactions bypass leadership entirely
sourceSyncConfig.sync() runs unconditionally in every tab, and externally-synced transactions go straight to disk (persistAndBroadcastExternalSyncTransactionUnsafe → adapter.applyCommittedTx) with no leadership check. N same-partition tabs therefore write the same stream to the same file concurrently, each minting its own term/seq, and the applied_tx dedupe on (collection_id, term, seq) silently returns on a hit — two tabs minting the same pair for different transactions means the second is dropped. We did not observe corruption in the probe, but the hazard is structural, and it means adopting the coordinator does not remove the need for an app-level single-writer election for sync-sourced collections.
3. requestEnsureRemoteSubset fails structuredClone on real LoadSubsetOptions
The follower→leader RPC posts LoadSubsetOptions over BroadcastChannel verbatim. Ours carry a subscription object with a callback: DataCloneError: (event) => options.onUnsubscribe(event) could not be cloned, ~70 occurrences per tab, retried forever by scheduleRemoteEnsureRetry. Follower-side subset widening never reaches the leader. Suggestion: serialize a wire-safe projection of the options.
4. (Minor) coordinator RPC failure lands in the user write path after the server accepted
wrappedOnUpdate runs the app's own mutation handler first and the coordinator RPC after; a wedged leader stalls the write ~30 s (RPC timeout × retries) and then rejects, rolling optimistic state back for a write the backend already accepted.
Findings from an adoption attempt of
BrowserCollectionCoordinator(@tanstack/browser-db-sqlite-persistence0.2.12,@tanstack/db-sqlite-persistence-core0.2.12,@tanstack/db0.7.2, Electric collections). Verified empirically with two pages in one Chromium context (shared storage partition) plus source reading. Happy to share probe scripts.1. The coordinator holds one adapter, so per-collection
schemaVersions destroy each other's tablescreateBrowserWASQLitePersistencecreates one adapter per distinct(schemaMismatchPolicy, schemaVersion)and callscoordinator.setAdapter(...)for each — the coordinator keeps whichever was created last. The schema check runs inensureCollectionReadyInternal, which every adapter method reaches, andensureCollectionStatefiresacquireLeadership→getStreamPositionfor every subscribed collection through that single adapter. With per-collection versions (we compute one per Electric shape) the wrong-version adapter touches every other collection: undersync-present-resetwe observedcollection_reset_epochclimb 0→5 during one run, a 9,475-row table wiped to 0, every reload re-syncing cold, and the registry'sschema_versionflipping between two collections' hashes.A second failure appears even with matching versions: two adapter instances race
ensureCollectionReadyInternalfor the same collection on a fresh registry (UNIQUE constraint failed: collection_registry.tombstone_table_name, thenno such table: t_…when the loser tries to reset a table the winner has not created yet). Leadership is never acquired for those collections.One global
schemaVersion(all adapters collapse to one instance) avoids all of this, at the cost that any schema change resets the whole database. Suggestion: key leader-side adapter access by collection — e.g.requireAdapter(collectionId)with a resolver passed to the constructor — instead of a singlesetAdapterslot.2. Sync-ingested transactions bypass leadership entirely
sourceSyncConfig.sync()runs unconditionally in every tab, and externally-synced transactions go straight to disk (persistAndBroadcastExternalSyncTransactionUnsafe→adapter.applyCommittedTx) with no leadership check. N same-partition tabs therefore write the same stream to the same file concurrently, each minting its ownterm/seq, and theapplied_txdedupe on(collection_id, term, seq)silently returns on a hit — two tabs minting the same pair for different transactions means the second is dropped. We did not observe corruption in the probe, but the hazard is structural, and it means adopting the coordinator does not remove the need for an app-level single-writer election for sync-sourced collections.3.
requestEnsureRemoteSubsetfailsstructuredCloneon realLoadSubsetOptionsThe follower→leader RPC posts
LoadSubsetOptionsover BroadcastChannel verbatim. Ours carry a subscription object with a callback:DataCloneError: (event) => options.onUnsubscribe(event) could not be cloned, ~70 occurrences per tab, retried forever byscheduleRemoteEnsureRetry. Follower-side subset widening never reaches the leader. Suggestion: serialize a wire-safe projection of the options.4. (Minor) coordinator RPC failure lands in the user write path after the server accepted
wrappedOnUpdateruns the app's own mutation handler first and the coordinator RPC after; a wedged leader stalls the write ~30 s (RPC timeout × retries) and then rejects, rolling optimistic state back for a write the backend already accepted.