Shared eager live-source conformance oracle for sync adapters, and the fixes it found

.changeset/convex-failed-load-release.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/convex-db-collection': patch
+---
+
+Release the Convex query subscription when a Collection's first load fails, or when a later acceptance failure stops the sync run, instead of keeping it until cleanup. A new subscription no longer fails from an error the Convex client cached for its query before it subscribed, such as a restart right after a failed run; it waits for the server's result, also when the server's answer arrives before the client replays the cached error. `awaitSync` during that wait no longer fails the run from the cached error. While the latest result is a failure, `awaitSync` rejects with the reported failure instead of reporting it again.

.changeset/electric-retry-health-and-evidence.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/electric-db-collection': patch
+---
+
+Report an extended Electric outage in `collection.health`. After the Collection is ready, five failed requests to the shape log in a row, retried by the client or by an `onError` that returns a retry, show as the source node's `failureReason` with the fifth attempt's error, and the next applied up-to-date clears it. Shorter outages, and retried subset snapshot requests, leave health unchanged. A restarted or reloaded Collection resolves `awaitTxId` for a txid the previous sync run delivered only once it is ready again, instead of at once, and the sync metadata it exports for hydration carries those txids only from then on. When the stream fails, pending `awaitTxId` and `awaitMatch` calls reject instead of waiting for their timeout, and so do calls made after the failure, also when an abort stopped the stream. An `onError` handler that throws now gives up the stream with its own error, without an unhandled rejection. A give-up while the first snapshot's acceptance is pending, under a persistence wrapper, now fails the Collection once that acceptance makes it ready, instead of leaving a stopped stream with healthy status. Aborting `shapeOptions.signal` after the Collection is ready now shows as the source node's `error`, since the Collection no longer syncs.

.changeset/powersync-failed-load-release.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/powersync-db-collection': patch
+---
+
+Release the change watcher and any diff trigger when an eager Collection's first load fails, instead of keeping them until cleanup.

.changeset/rxdb-buffered-insert-replay.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/rxdb-db-collection': patch
+---
+
+Fix initial sync failing with "Cannot insert document ... from sync because it already exists" when a document is inserted and then updated while the initial fetch is running. The buffered insert event is now applied over the row that the initial read already returned.

.changeset/rxdb-full-row-updates.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/rxdb-db-collection': patch
+---
+
+Remove a field from a synced row when an RxDB document update removes it. RxDB change events carry the whole document, so the adapter now replaces the row instead of merging the update into it.

.changeset/sync-negative-zero-change.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/db': patch
+'@tanstack/db-ivm': patch
+---
+
+Treat `-0` and `0` as distinct row values. A synced update, a replay that replaces a subscription's rows, and an optimistic update that change a field only from `-0` to `0` (or back) now publish a change; before, the Collection could store the new value while subscribers kept the old one. A draft write of `0` over `-0` is now recorded as a change instead of being dropped. A transaction that deletes a row and reinserts it with only a zero's sign changed now sends that update instead of dropping it, and an ordered live query or Effect (`orderBy`, with or without `limit`) now delivers an update that changes only a zero's sign; before, it kept the old value. Join, distinct, and grouping keys still treat `-0` and `0` as equal. A sync insert of a held key whose row differs only by a zero's sign is now a duplicate key, not an equal re-insert. The same holds inside typed arrays. An ordered Effect also delivers an update whose value is a class instance, which can change in private state its enumerable fields do not show.

.prettierignore

@@ -9,3 +9,4 @@ pnpm-lock.yaml
 **/routeTree.gen.ts
 packages/convex-db-collection/e2e/backend/.convex/
 packages/convex-db-collection/e2e/backend/convex/_generated/
+packages/db-adapter-conformance/tests/neon/vendor/

docs/collections/convex-collection.md

@@ -322,9 +322,9 @@ convexCollectionOptions({
 })
 ```
 
-An initial subscription or projection error rejects `preload()` with the original error and ends that sync run. Call `collection.reload()` to try again. Later recoverable errors preserve existing rows, set `collection.health.failureReason`, and call `onError`. A valid query result clears that failure reason. `collection.utils.getSyncError()` returns the latest error, but this getter is not reactive. A rejected source acceptance stops the run and sets its health error; it also requires `reload()`.
+An initial subscription or projection error rejects `preload()` with the original error, ends that sync run, and releases its query subscription. Call `collection.reload()` to try again. Later recoverable errors preserve existing rows, set `collection.health.failureReason`, and call `onError`. A valid query result clears that failure reason. `collection.utils.getSyncError()` returns the latest error, but this getter is not reactive. A rejected source acceptance stops the run and sets its health error; it also requires `reload()`.
 
-Collection cleanup rejects while live queries or Effects read it. Unmount those consumers first, or use `collection.cleanup({ dependents: true })`. Cleanup unsubscribes and invalidates callbacks from that sync run. It does not close the shared Convex client. After a restart, the first result replaces retained data, including when the result is empty. Close the client separately when your application no longer needs it.
+Collection cleanup rejects while live queries or Effects read it. Unmount those consumers first, or use `collection.cleanup({ dependents: true })`. Cleanup unsubscribes and invalidates callbacks from that sync run. It does not close the shared Convex client. After a restart, the first result replaces retained data, including when the result is empty. The Convex client serves a query's cached result to a new subscription at once, so a restart soon after cleanup can start from the previous run's rows until the server's next result. A cached error does not fail the restarted run: it waits for the server's result instead, so a query that has recovered is not reported failed again. The same holds for a Collection that subscribes to a query another subscription on the same client has in error. Close the client separately when your application no longer needs it.
 
 ## Scope
 

docs/collections/electric-collection.md

@@ -341,11 +341,16 @@ await todosCollection.utils.awaitMatch(
 
 ### Cleanup and resume safety
 
-Transaction evidence and pending `awaitTxId`/`awaitMatch` calls belong to one
-collection lifecycle. Explicit cleanup and automatic garbage collection reject
-pending waits with `StreamAbortedError`; callbacks from the retired stream cannot
-settle waits in a restarted collection. Observe these promises even when the
-component or collection may be disposed before they settle.
+Pending `awaitTxId`/`awaitMatch` calls belong to one collection lifecycle.
+Explicit cleanup and automatic garbage collection reject pending waits with
+`StreamAbortedError`; callbacks from the retired stream cannot settle waits in
+a restarted collection. A txid the retired stream delivered still counts after
+a restart or reload, but only once the restarted collection is ready again,
+because its rows are read after that txid; until then `awaitTxId` waits. When
+the stream fails or gives up, pending waits reject with the failure, and a
+later `awaitTxId` or `awaitMatch` rejects unless its evidence was already
+seen. Observe these promises even when the component or collection may be
+disposed before they settle.
 
 An on-demand Collection with managed SQLite persistence can also replace its
 Electric provider session within the same Collection sync run when its cached
@@ -436,10 +441,29 @@ source node shows an `error` in `collection.health` and in each live query's
 `health` tree. This does not silently retry the failed stream;
 `collection.reload()` refetches.
 
-While the Electric stream retries a failed request, the Collection reports
-nothing: it stays `loading` before its first up-to-date, and keeps its health tree
-unchanged afterward. When the stream gives up, it calls `fail()`: a failed first load
-before readiness, or the source node's `error` after it. Complete updates from an explicit `replica: 'full'` stream remain valid.
+While the Electric stream retries a failed request, the Collection stays
+`loading` before its first up-to-date. After it, a short outage leaves the
+health tree unchanged, so a blip does not flap it. Once five requests to the
+shape log in a row have failed, whether the client retried them or your
+`onError` returned a retry, the source node shows the outage as its
+`failureReason`, with the error of the fifth attempt; the next applied
+up-to-date clears it. Any response the client accepts, such as a
+`must-refetch`, starts the count again. With the default backoff, five failed
+attempts take from under a second to about 15 seconds, because each retry
+waits a random part of a doubling delay. A source that keeps failing five
+times and then succeeding once shows and clears the outage each time. A
+subset snapshot request that the client retries does not count: its failure
+belongs to the live query that requested it. While the stream catches up on
+a log that spans several responses, such as after a `must-refetch`, the
+client also prefetches the next responses, and each failed prefetch attempt
+counts too, so the outage can show sooner than five rounds of retries. When the stream gives up, it
+calls `fail()` with the error, or with the error your `onError` threw: a
+failed first load before readiness, or the source node's `error` after it. A give-up while a persistence wrapper is
+still accepting the first snapshot fails the Collection once that acceptance
+makes it ready. Aborting `shapeOptions.signal` stops the stream for
+good: before readiness the first load fails, and after it the source node
+shows an `error`, because the Collection no longer syncs, whether or not the
+abort was deliberate. Complete updates from an explicit `replica: 'full'` stream remain valid.
 On-demand streams can observe updates outside their loaded subsets; unknown
 partial rows are ignored, while transaction acknowledgement evidence is retained.
 Outside scoped recovery, complete rows published by persistence reloads or

docs/contributing/glossary.md

@@ -82,7 +82,7 @@ until cleanup ends the run.
 | loading error | The `fail()` that ends a sync run's first load in status `error` (`isLoadingError`). It is final for its sync run: `markReady()` afterward does nothing, and only a new sync run can reach `ready`. | Sync error or a retry. |
 | crash | Moving a Collection to status `crashed` (`isCrashed`) from any active status, because it can no longer serve reads or admit writes. Core uses it for IndexedDB closure, terminal local persistence failures, a throwing sync function, and internal invariant failures. It cannot be recovered in place: nothing restarts it and `reload()` rejects. Only cleanup leaves it, and cleanup discards all of the Collection's state, so a later start is a fresh start. After a crash, the sync adapter's status calls (`markReady()`, `fail()`, `reportError()`, `reportHealthy()`) do nothing. Sync data that the run commits still applies, because closure keeps accepted sync obligations such as the confirmation of a write admitted before it. | Loading error, sync error, or cleanup. |
 | sync error | A problem after Collection readiness on a source's health node, from the sync adapter: a failure reason (`reportError()`, still trying; `reportHealthy()` clears it, and `reportHealthy(error)` removes one failure) or an error (`fail()`, stopped; it stays for the sync run, every later report throws, and a second `fail()` does nothing). A live query's `isSyncError` is `true` when it is `ready` and its tree has any problem. It never changes status or rows. Cleanup resets it. | Loading error or subscription status. |
-| failure reason | A node's `failureReason`: the problem while the sync adapter keeps trying, after TanStack Query's `failureReason`. Its frame is the sync run: it lists each `reportError()` since the slot was last clear, once per error value (a value already listed keeps its failure's place and `at`), `reportHealthy(error)` removes that value's failure, `reportHealthy()` ends it, and a reload's new run that reports starts a new one. The slot clears when its list empties. | An error or a retry count. |
+| failure reason | A node's `failureReason`: the problem while the sync adapter keeps trying, after TanStack Query's `failureReason`. When to report is the adapter's choice of threshold: a connection-aware source can report at once, while Electric, which syncs over HTTP, reports only after five failed attempts in a row. Its frame is the sync run: it lists each `reportError()` since the slot was last clear, once per error value (a value already listed keeps its failure's place and `at`), `reportHealthy(error)` removes that value's failure, `reportHealthy()` ends it, and a reload's new run that reports starts a new one. The slot clears when its list empties. | An error or a retry count. |
 | problem | A health node's `failureReason` or `error` (`HealthProblem`). Its `message`, `cause`, and `at` are its newest failure's, and `errors` lists every failure of its frame still open, oldest first, each `{ name, message, code?, at, cause }`. A failure that clears leaves the list; one error value is one failure, which keeps the place of its first failure. Adding or removing a failure changes the problem, so its node is a new object. | A failure, which is one entry of a problem. |
 | failure | One reported value in a problem's `errors`: one `reportError()`, the `fail()` of a sync run, a crash, or one failed request. | A problem. |
 | request error | A failed subset load (a rejection, or a synchronous throw, which is a rejection) for demand that a live query or Effect started after its initial-query readiness, shown as the `error` on that query's own node. The source Collection's node does not change. The node's problem lists every request failure still open. The public name stays general on purpose: an application sees a failed request for more data, not the subset-load mechanism. It clears when a later subset load for that demand fulfills, including one that the query's own reload issues, or when the demand retires. A load that core aborted decides nothing. A truncate's or a source reload's replay decides every request error of the demand it replayed: its success clears them all, and its failure replaces them with the replay's failures, which stay until a replay succeeds for the demand that remains (a replay failure belongs to the logical demand that failed, ARCHITECTURE law 9) or the demand retires. | Sync error or request data. |