fix(sqlite): serialize putBulk across shared-connection SqliteTabularStorage instances

[sroussey]

Summary

HIGH-priority correctness fix from a scheduled review of the last 24h of main (surfaced by review of the putBulk engine refactor in chore: release 0.3.27).

The bug

SqliteTabularStorage._putBulkInternal guarded on better-sqlite3's driver-level db.inTransaction, which is scoped to the connection, not to the storage instance. When two SqliteTabularStorage instances share one Sqlite.Database (the normal case for repos on the same file), a second putBulk starting during another's inter-chunk await gap read inTransaction === true, skipped its own BEGIN/COMMIT, executed rows inside the OTHER instance's transaction, emitted put events, and returned success. If the first instance later rolled back on a unique-constraint violation, the second's rows silently disappeared even though its caller had received the returned entities and subscribers had already seen put events for phantom rows.

The fix

• Module-scope WeakMap<Sqlite.Database, Promise<void>> plus a protected connectionMutex() helper — GC-safe, keyed by the DB handle.
• _putBulkInternal keys off this.inTransaction (per-instance) and wraps its BEGIN/runBulkPut/COMMIT|ROLLBACK bracket in connectionMutex(...) when not already in a transaction.
• withTransaction wraps its own bracket the same way, inside the existing per-instance mutex — instance-first / connection-second so two instances on one handle cannot deadlock.
• createTxView reports inTransaction === true through the proxy so the tx-routed putBulk path takes the nested branch and skips both BEGIN and the connection lock (the outer withTransaction already holds both).
• SqliteAiVectorStorage's overridden _putBulkInternal mirrors the parent — keys off this.inTransaction and takes connectionMutex on the owned-transaction path.

Verification

Regression tests added under packages/test/src/test/storage-tabular/SqliteTabularStorage.integration.test.ts:

• Two SqliteTabularStorage instances on DIFFERENT tables sharing one Sqlite.Database.
• Race Promise.allSettled([repoA.putBulk(large), repoB.putBulk(small)]) with runBulkPut spied to yield microtasks and then throw on A.
• Asserts A rejects, B fulfills, and repoB's rows survive.
• Second test asserts B's put event stream never includes rows that were rolled back with A.

Run:

bun x vitest run packages/test/src/test/storage-tabular/SqliteTabularStorage.integration.test.ts

Rollback

Revert the single file (providers/sqlite/src/storage/SqliteTabularStorage.ts, plus the mirror in SqliteAiVectorStorage.ts, plus the test). No schema/migration/API changes.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	63.06%	27385 / 43423
🔵	Statements	62.92%	28375 / 45096
🔵	Functions	63.44%	5213 / 8216
🔵	Branches	51.73%	13479 / 26054

File Coverage

No changed files found.

Generated in workflow #2775 for commit ae68280 by the Vitest Coverage Report Action

[sroussey]

Closing as superseded by #657 / #658 (both now merged to main).

This PR fixes a real bug — _putBulkInternal guarding on better-sqlite3's connection-scoped db.inTransaction instead of the per-instance flag, so a sibling putBulk on a shared Database handle could interleave inside another instance's transaction. #657 fixes the same underlying bug (its description calls out "an existing latent bug where Sqlite.Database's inTransaction check missed the wrapper — the code now consults our own this.inTransaction flag as well") but generalizes the remedy into a module-level ConnectionMutex (packages/storage/src/tabular/ConnectionMutex.ts) keyed on the connection handle, covering SQLite, SqliteAiVectorStorage, and the PGlite Postgres path in one place. #658 then hardens it for the browser ALS shim and adds an actionable ConnectionReentryError.

Because both PRs rewrite the same files (SqliteTabularStorage.ts, SqliteAiVectorStorage.ts, and the shared integration test) with the more general approach, this branch's instance-local WeakMap mutex would conflict on merge and is redundant. The merged stack was verified before landing: 40/40 packages type-check and the SQLite + Postgres integration suites pass (298 passed / 2 pre-existing skips) against current main (which had also picked up the JSONB PostgresTabularStorage change).

No action needed here — the fix is in main via #657/#658.

---

Generated by Claude Code