[ianmacartney]

Allow completeTransactionally: true on enqueueQuery and enqueueQueryBatch to commit the selected success callback and completion bookkeeping together. Queries always read independent snapshots without adding read dependencies to the completion transaction. Their results may be stale when the callback commits; callbacks should read any data whose freshness they require.

Stacked on #238. Opted-in queries are individually scheduled through the existing mutation wrapper, including queries enqueued in a batch. The wrapper calls the query with transaction headroom reserved and invokes completion directly, without another wrapper UDF. Every query call in the mutation wrapper uses useStaleSnapshot: true, even if transactional completion is false or omitted. Queries without the flag keep their existing action-batch execution. Actions continue to reject transactional completion.

Callback or bookkeeping errors roll back completion and fail the scheduled wrapper; existing recovery later finalizes the job as failed and dispatches any selected failure callback. The job holds its concurrency slot until recovery. Query execution errors retain the normal failure-completion path. Existing stored and scheduled argument shapes already support queries, so no schema or generated component API shape changes are needed.

Requires Convex 1.42 or newer for useStaleSnapshot; the existing ^1.43 peer requirement from main covers this. README and client documentation describe the snapshot semantics and include queries in maxParallelism.

Validation: build, typecheck, lint, formatting, and all 282 tests pass after restacking onto #238 on current main. The local Convex deployment smoke check (npm run test:e2e) also passes, with generated component API files unchanged. Coverage includes default versus transactional routing, independent wrappers for query batches, query results and large payloads, skipped success callbacks, query errors, rollback after callback and late bookkeeping errors, recovery without duplicate callbacks, and single/batch client execution. Three snapshot regression cases verify that queries ignore uncommitted writes with transactional completion enabled, disabled, or omitted; all fail if stale snapshots are disabled. Client failure tests distinguish transactional execution from an ignored flag. Type tests cover query context and result inference plus continued action rejection.

Test limitations: convex-test 0.0.67 supports nested transaction limits, enabled in component wrapper tests, but does not simulate production OCC. Recovery tests supply the error text it omits from failed scheduled-job records after testing actual scheduled failures and rollback.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@convex-dev/workpool@239

commit: 2b4a41c

[ianmacartney]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Add transactional success completion for queries #239 👈 (View in Graphite)
• Add transactional success completion for mutations #238
• Filter onComplete callbacks by result status #237
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cubic-dev-ai]

All reported issues were addressed across 9 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[reeceyang]

Test limitations: convex-test does not simulate OCC or enforce nested transaction limits. Recovery tests supply the error text it omits from failed scheduled-job records after testing actual scheduled failures and rollback.

I thought convex-test does enforce nested transaction limits?

[ianmacartney]

convex-test can be provided with transaction limits to enforce. i can't recall if it does so by default, but it's certainly capable (though not sure if that's well documented)