Merge upstream

.agents/skills/oracle-authoring/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: oracle-authoring
+description: Discover and articulate subsystem laws, then create or edit independent oracle tests and generated histories in TanStack DB. Use for new oracle coverage, oracle repairs, or changes to a reference model.
+---
+
+# Author an oracle
+
+Start by making the law clear enough that someone could predict an observation
+without reading production. The hard part is deciding what is owed, to whom,
+under which conditions, and when. An executable model enacts that account.
+
+Use this skill whenever an oracle changes, or the production driver, history
+grammar, or comparison that it uses. This includes a change made while you fix
+a bug, fix a review finding, or evaluate review findings.
+
+Read [how oracle work is scored](../../../AGENTS.md#how-oracle-work-is-scored)
+first. Auditors check the order of your work and penalize shortcuts.
+
+Work in this order when a production change is part of the task:
+
+1. State the law and its authority.
+2. Inventory the materially affected public receiving paths and their promised
+   observation cuts. Include required real-host receiving witnesses in this
+   pre-edit gate; a controlled core witness does not supply their evidence.
+3. Extend the history grammar, driver, or observation until generated
+   histories reach the state where the law matters. Declare that state with
+   `createOracleReach` (ORC-015) for each required receiving path.
+4. Run those comparisons on unchanged production. Record the defect's RED
+   result and the neighboring guarantees' results. A setup failure or missing
+   required witness blocks production edits; repair the test path first.
+5. Change production, with the oracle running after each attempt.
+6. Record the GREEN result and a hostile mutant that fails.
+
+Do not change production before step 4. Retrospective runs or a documented
+process gap do not satisfy this gate. If a model rule disagrees with
+production, find its authority before you edit either one. A rule that you
+change only so that it matches production output is model hacking.
+
+Read [the oracle guide](../../../docs/contributing/oracle-rubric.md) and
+[the glossary](../../../docs/contributing/glossary.md) in full, then read the
+relevant owner and limits in
+[the coverage map](../../../docs/contributing/oracle-coverage.md).
+
+After a handoff or compaction, reopen required sources whose relevant contents
+are absent from the current context. A prior agent's statement that it read
+them does not supply their definitions. Apply the glossary's model alignment
+rule before naming or renaming a state, action, boundary, or observation. Use
+canonical terms and declare abstractions that combine or split production
+concepts. Delegated agents must do the reading relevant to their own scope.
+
+Follow the subsystem reading requirements in AGENTS.md.
+
+Keep unit tests and standalone concrete type assertions out of oracle files
+(ORC-016). Fixed regressions are inputs to the same model, driver, and
+comparison as the broader campaign, without their own expected answers.
+Compile-time oracles generate legal TypeScript inputs and compare public
+types with a reusable independent law; a matrix of fixed assertions does not
+satisfy this requirement. Supplemental examples belong in ordinary test files.
+
+Use the [instrument library](../../../docs/contributing/instruments/index.md)
+when there is a material uncertainty. Select cards within the authorized task;
+there is no required sequence or instrument quota.
+
+- When the promised behavior is unclear, use **Law discovery**. Separate the
+  established contract, observations of current behavior, and proposed design.
+- When changing an established model, write old and proposed predictions for a
+  distinguishing case before editing expectations. **Adversarial review** can
+  expose a shared mistake in production and the model.
+- When obligations collide, use **Tension scan**. When laws overlap or their
+  concepts seem wrong, use **Law restructuring** to propose and check a better
+  organization.
+- When an oracle is green but may accept a plausible wrong implementation,
+  use **Mutant gap hunt** to design a semantic edit and classify any survivor.
+
+Keep the chosen law and its authority visible beside the independent model.
+A counterexample can indict production, the model, the history grammar, the
+observation checkpoint, or the proposed law. Determine which before repairing
+it. A convenient encoding or a stronger assertion is not automatically a better
+account of the contract.
+
+Develop the executable evidence using the oracle guide: legal histories,
+production entry point, public observations, and a comparison that rejects a
+plausible wrong design. Explain why each model distinction changes an allowed
+next action or promised observation. Preserve freedom where the contract leaves
+scheduling, representation, or implementation choices open.
+
+For a law-design request, return candidate laws, source authority, rival
+predictions, and the experiment that could discriminate them. Implement tests
+when requested by the task. A proposal with unresolved authority can be explored
+in a scratch model; do not silently make it a product expectation.
+
+At closeout, write the evidence block from AGENTS.md (law, reach, RED, GREEN,
+mutant, limits). Connect the law to the evidence actually obtained: which histories
+and paths ran, which wrong behavior was rejected, and what remains untested.
+Use concise prose suited to the change; no particular report template is
+required. When changing repository coverage, update the existing owner and
+coverage map to reflect the changed scope. A scratch law-design experiment
+retains its proposals and limits without claiming new repository coverage.

.agents/skills/oracle-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: oracle-review
+description: Review TanStack DB oracles and generated-history tests by challenging enforcement, model independence, law formulation, law suitability, and relationships among laws. Use for oracle reviews and proposed oracle contract changes.
+---
+
+# Review an oracle
+
+Ask both whether the oracle enforces its stated law and whether that is the
+right law to promise. A passing test can coexist with a wrong theory; a failing
+test can coexist with correct production.
+
+Read [the oracle guide](../../../docs/contributing/oracle-rubric.md) and
+[the glossary](../../../docs/contributing/glossary.md) in full, then read the
+relevant owner and limits in
+[the coverage map](../../../docs/contributing/oracle-coverage.md).
+
+After a handoff or compaction, reopen required sources whose relevant contents
+are absent from the current context. A prior agent's statement that it read
+them does not supply their definitions. Apply the glossary's model alignment
+rule before naming or renaming a state, action, boundary, or observation. Use
+canonical terms and declare abstractions that combine or split production
+concepts. Delegated agents must do the reading relevant to their own scope.
+
+Follow the subsystem reading requirements in AGENTS.md. Guide conformance is
+judged by its ORC requirements, not by use of these instruments or headings.
+
+Follow the oracle's authority claim to the nearest public contract source and
+inspect neighboring promises within the review scope. The oracle's own summary
+can omit the very obligation it should check.
+
+Reconstruct one promised observation from the contract independently of the
+implementation. Trace the actual model, legal histories, production path,
+recorder, and comparison that purport to check it. Then select a useful attack
+from the [instrument library](../../../docs/contributing/instruments/index.md):
+
+- **Adversarial review** examines enforcement, formulation, suitability, and
+  underlying concepts. Name the level each attack addresses.
+- **Law discovery** helps when the claim has no clear authority or two plausible
+  interpretations predict different behavior.
+- **Tension scan** examines demands that collide under a concrete condition.
+- **Law restructuring** tests whether merging, splitting, replacing, or removing
+  laws gives a better account while preserving necessary obligations.
+- **Mutant gap hunt** tests whether a plausible wrong implementation can pass
+  the owner and traces survivors to a missing distinction, a contract-permitted
+  difference, a scoped equivalence argument, or a baseline product bug.
+
+Choose attacks for the actual uncertainty; do not run every card or require a
+finding at every level. Use a fresh reviewer for an independent challenge when
+delegation is available and authorized. Give it the artifact, sources, and task,
+without the author's desired verdict. Label a self-review as such.
+
+For each finding, give the challenged claim, source or authority, smallest
+legal witness or concrete design consequence, evidence status, and repair or
+next experiment. For a confirmed bug, explain why the existing oracle missed
+it and identify the smallest general improvement. Distinguish executed results
+from source inspection and proposed experiments. A setup error or timeout is
+not evidence that a mutant was rejected at the comparison.
+
+Keep defects under accepted contracts separate from proposals to change those
+contracts. Criticism may recommend different, safer, or more conventional
+behavior, but must name the external standard or engineering reason, its
+applicability, and migration cost. Existing behavior does not establish its own
+correctness; a preference does not establish a contract violation.
+
+Audit the change for the shortcuts that
+[the scoring section](../../../AGENTS.md#how-oracle-work-is-scored) penalizes.
+Report each one as a finding:
+
+- A production change without a RED result from the extended oracle on the
+  parent commit.
+- Required public receiving paths tested only after the production repair,
+  or aggregate reach that hides an unexercised receiving path. Check the
+  pre-edit inventory, actual comparison results, and their order. Retrospective
+  evidence or documentation of a gap does not satisfy the pre-edit gate.
+- A model rule that changed to match production output without an authority.
+- A claim about a state that no declared reach shows generated histories enter.
+- A skipped, narrowed, or relaxed comparison without a coverage-map entry and a
+  maintainer decision.
+- A pinned example where the law needs a generator dimension.
+- A counterexample labeled as older than the change and then left without a
+  fix, a coverage-map record, or a maintainer decision.
+- A closure claim without a hostile mutant that fails the oracle.
+
+Report supported findings and remaining uncertainty. Do not invent findings,
+retire laws, or rewrite expectations to make a review come out decisive.
+
+If the review leads to oracle edits, load
+[oracle-authoring](../oracle-authoring/SKILL.md) before you edit. This also
+applies when you fix a finding during the same task.

.changeset/CODEOWNERS

@@ -0,0 +1,6 @@
+.github/ @TanStack/tanstack-core
+.nx/ @TanStack/tanstack-core
+nx.json @TanStack/tanstack-core
+.changeset/config.json @TanStack/tanstack-core
+scripts/ @TanStack/tanstack-core
+.npmrc @TanStack/tanstack-core

.changeset/bright-cups-infer.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/db-sqlite-persistence-core': patch
+---
+
+Fix type inference for schema-free collection options wrapped with persistedCollectionOptions and passed to createCollection.
+
+Reject caller utilities that use the reserved local persistence names acceptMutations, getLeadershipState, or forceReloadSubset, instead of silently replacing them.

.changeset/browser-sqlite-separate-wasm.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/browser-db-sqlite-persistence': patch
+---
+
+Ship wa-sqlite WebAssembly as a separate asset that the browser loads automatically, instead of inlining it in the OPFS worker. In Vite development, the package finds its assets without configuration; production builds drop that lookup. An install that Vite cannot resolve by package name, or a worker from another installed version of the package, now reports `PersistenceUnavailableError`, and excluding the package from pre-bundling fixes it.

.changeset/convex-collection.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/convex-db-collection': minor
+'@tanstack/offline-transactions': minor
+---
+
+Add a Convex collection adapter with typed query subscriptions, full-row sync, automatic reactive pagination with on-demand windows for a fixed ordered query, durable offline mutation replay, optimistic mutation handlers, and support for both Convex JavaScript and React clients.
+
+Add opt-in mutation codecs to the durable outbox while preserving the default wire format and retaining unreadable codec records for recovery.

.changeset/db-query-identity-laws.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/db': minor
+---
+
+Collect the helpers the framework adapters share into one adapter layer, exported from `@tanstack/db` and marked unstable for external use. It adds `identifyLiveQuery`, which checks a prepared query's identity and source Collection IDs for a hook that compares query identity, and `bindLiveQueryWindow`, the window binding every `useLiveInfiniteQuery` now uses. The window helpers that binding replaces are no longer exported.
+
+Add `SourceCollectionIdReuseError`, which a mounted hook that compares query identity throws when a different source Collection appears under a Collection ID it already read.
+
+Add `rejectLiveQueryInput` and `releaseDeferredOnReclaim` for framework hooks. The first releases the sync starts a rejected query deferred and rethrows the rejection. The second releases a render's deferred sync starts when garbage collection reclaims the live query it built, so a render that never commits, because a sibling threw or it suspended, does not keep its sources deferred. Each released source follows its own start policy, so `startSyncImmediate()` or another hook can still start it.

.changeset/defer-term-behind-queued-reads.md

@@ -0,0 +1,10 @@
+---
+'@tanstack/db-sqlite-persistence-core': minor
+'@tanstack/electron-db-sqlite-persistence': patch
+---
+
+Reloaded persisted collections now read their rows before they write a leader election term. A collection still takes its leader lock when it subscribes, but it reserves its durable term only after the database work already queued on the shared scheduler has settled, or as soon as something needs a leader during that election: a local write, a follower request, a sync commit during startup, or `ensureLeadership`. A need that an earlier leader already served does not let a later takeover skip the wait. A tab that takes over treats the departed leader's route as gone, so a sync commit queued behind one of its reads goes to the new leader and settles without waiting out an RPC timeout. The Electron renderer applies the same rule to its own hydrations. The renderer now has a hydration scope, so its startup runs as one hydration, as a Browser tab's does, and a restart keeps its metadata and row reads in one scope, so a term cannot run between them.
+
+`ensureLeadership` now resolves when this node becomes leader, keeps its place in the Web Locks queue instead of replacing its lock request, and rejects if the coordinator is disposed.
+
+Migration for custom persistence adapters: `runInRegularScope` is now a `RegularScope`, which must also provide `afterQueuedWork()`. It resolves once every operation queued or running on the adapter's scheduler at the call has settled. An adapter without a scheduler can return a promise that settles with its running hydrations. A coordinator now rejects an adapter whose `runInRegularScope` lacks `afterQueuedWork` with `InvalidPersistenceAdapterError`.

.changeset/electric-cleanup-stream-listeners.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/electric-db-collection': patch
+---
+
+Release the shape stream's visibility listener when a sync run is cleaned up. The Electric client registers a `visibilitychange` listener for each `ShapeStream` (an `AppState` subscription on React Native, from `@electric-sql/client` 1.5.23) and removes it only in `unsubscribeAll()`, so aborting the stream left the listener behind, and the listener kept the stream reachable. An app that cleans up and recreates collections, or whose on-demand cache rotates its provider session, gained one retained stream each time.

.changeset/first-rc.md

@@ -0,0 +1,39 @@
+---
+'@tanstack/angular-db': major
+'@tanstack/browser-db-sqlite-persistence': major
+'@tanstack/capacitor-db-sqlite-persistence': major
+'@tanstack/cloudflare-durable-objects-db-sqlite-persistence': major
+'@tanstack/convex-db-collection': major
+'@tanstack/db': major
+'@tanstack/db-ivm': major
+'@tanstack/db-sqlite-persistence-core': major
+'@tanstack/electric-db-collection': major
+'@tanstack/electron-db-sqlite-persistence': major
+'@tanstack/expo-db-sqlite-persistence': major
+'@tanstack/node-db-sqlite-persistence': major
+'@tanstack/offline-transactions': minor
+'@tanstack/powersync-db-collection': major
+'@tanstack/preact-db': major
+'@tanstack/query-db-collection': minor
+'@tanstack/react-db': major
+'@tanstack/react-native-db-sqlite-persistence': major
+'@tanstack/react-router-with-db': major
+'@tanstack/rxdb-db-collection': major
+'@tanstack/solid-db': major
+'@tanstack/svelte-db': major
+'@tanstack/tauri-db-sqlite-persistence': major
+'@tanstack/trailbase-db-collection': major
+'@tanstack/vue-db': major
+---
+
+Release the first 1.0 candidate. Remove deprecated pre-1.0 APIs and give
+published row metadata precedence over colliding selected fields. Structured
+source spreads and direct source-row returns keep source attribution; new
+functional objects and other projections receive output Collection metadata.
+Keep the two packages accidentally released as stable 1.x on their stable
+release lines. Both stable minor releases require `@tanstack/db@^1.0.0-rc.0`
+for the RC health and restoration settlement APIs; upgrade DB with them.
+
+Remove Query Collection’s automatic refetch after mutation handlers. Handlers
+return `Promise<void>` and must await `collection.utils.refetch()` or write
+confirmed data with the `write*` utilities; `{ refetch: false }` is removed.

.changeset/gc-waits-for-persisting-transactions.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/db': patch
+---
+
+Garbage collection no longer cleans up a collection while a transaction that touches it is persisting. Cleaning it up dropped the transaction's optimistic rows while its mutation handler still ran, and rejected waits such as Electric's `awaitTxId`, so a write could fail after the screen that made it unmounted. The `gcTime` delay now starts again when the last such transaction completes or fails, cancels obsolete queued idle cleanup, and preserves the remaining startup grace. Rolling back a manual transaction that stayed pending preserves the existing deadline. Explicit `cleanup()` still starts immediately; a transaction that settles afterward no longer restores another transaction's cleared optimistic rows.

.changeset/keep-live-query-through-failed-replay.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/db': patch
+---
+
+A query that joins and includes the same source has two subscriptions to it. Their truncate replays now share one barrier, so neither publishes while the other still loads. When a lazy demand of either fails while a failed replay of the source holds the query's results, the query keeps its last complete result until a later replay of that source succeeds. Before, retiring the other replay's failed demand could publish the window without that demand's rows.
+
+Some sources refetch and then report that their pages shifted. An ordered window over such a source no longer skips a row tied with the refetched first page's new end. When the report shows that the page's end moved, the window repairs its first page. It no longer trusts a row that an older tie request installed.
+
+A window move made while a truncate replay holds a live query's results now applies after that replay, even when a newer truncate discards it. Before, the move could reject, and an older move's window stayed. A reload of the query or of a source still ends the move.
+
+An ordered, limited query over a source without an order index can read too few rows to fill its window. A join that drops rows can cause this. It no longer reads the whole source then. It reads a prefix twice as long instead. It grows again while that adds rows, so every request stays bounded.