fix: invalidate stale predicate-scoped cache entries on manual-sync writes

[marbemac]

🎯 Changes

Fixes a cache-poisoning bug in @tanstack/query-db-collection (syncMode: 'on-demand') where any manual-sync write (writeInsert / writeUpdate / writeDelete / writeUpsert / writeBatch) overwrote every cache entry under the collection's queryKey with the full post-write syncedData snapshot — regardless of the predicate that originally produced each entry.

For stale entries (no live observer) within gcTime, this stamped them with rows that didn't satisfy their original where. A subsequent cache-hit re-subscribe re-applied those wrong rows via applySuccessfulResult, the per-subscription where filter discarded them, and the subscriber received [] for predicates whose matching rows still existed in the source. In our app this surfaced as "not found" errors on rows that demonstrably existed in Postgres, with no exception thrown anywhere in tanstack-db.

Fix: stale cache entries are now invalidated (removeQueries) instead of overwritten, so the next subscribe re-runs queryFn against the source of truth. Active entries continue to receive the full snapshot — predicate scoping for the consumer is enforced downstream by subscribeChanges's where. The original ghost-row protection is preserved because deleted rows no longer reappear from a stale snapshot.

Three new tests under Predicate-scoped cache invalidation on manual writes cover the headline bug, the positive case (newly inserted matching rows visible on re-subscribe), and overlapping predicates (a write into a broader active scope must not poison a narrower stale entry). Verified by stashing the src fix that two of the three tests fail without it.

✅ Checklist

• I have tested this code locally with pnpm test.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

[pkg-pr-new]

More templates

• todos
• offline-first-electron
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• offline-transactions-react-native
• shopping-list-react-native
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@1497

@tanstack/browser-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1497

@tanstack/capacitor-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1497

@tanstack/cloudflare-durable-objects-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1497

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@1497

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@1497

@tanstack/db-sqlite-persistence-core

npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1497

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@1497

@tanstack/electron-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1497

@tanstack/expo-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1497

@tanstack/node-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1497

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1497

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1497

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@1497

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@1497

@tanstack/react-native-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1497

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1497

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@1497

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@1497

@tanstack/tauri-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1497

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1497

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@1497

commit: b71e4a9