record-adapter-do-sqlite: a Workers story for SQLite records

[cuibonobo]

Summary

• Adds @haverstack/record-adapter-do-sqlite, a StackRecordAdapter over Cloudflare Durable Objects' SQLite storage — a Workers-native record adapter with no Node runtime dependency, closing record-adapter-do-sqlite — a Workers story that fits the sync SqlExecutor and the ownership rule #161.
• Reuses SharedSqlRecordLogic, the FTS5 schema/strategy, query builder, cursor codec, and row mappers from @haverstack/sqlite-shared, via a new ./record subpath that excludes the Node-only token-store and file-lock code (a bare import of either survives esbuild's tree-shaking as a dead-but-still-imported node:crypto/node:fs module, which throws at load time in a Worker without nodejs_compat).
• No lock file: a Durable Object id maps to exactly one running instance, so the platform itself is the single-writer guarantee. No persist/flush step: every write through ctx.storage.sql is durable by the time the call returns.
• SqlExecutor (in @haverstack/sqlite-shared) gains a transaction<T>(fn: () => T): T primitive, replacing the raw BEGIN/COMMIT/ROLLBACK statements record-logic.ts issued directly. A pre-implementation spike against the real Workers runtime found DO SQLite rejects those statements outright, and does not roll back a write on a later exception the way an open SQL transaction would — its real primitive is ctx.storage.transactionSync(fn), a callback boundary three independent string-based exec() calls can't reach. record-adapter-sqlite's executor implements transaction() as literal BEGIN/COMMIT/ROLLBACK around fn(), behavior-identical to the code it replaces.

Spec

Yes — docs/spec/adapters.md updated:

• New row in the adapter backends table, and a capabilities note (shares record-adapter-sqlite's capabilities via SharedSqlRecordLogic).
• @haverstack/sqlite-shared's two entry points (. vs ./record) and why the split exists.
• SqlExecutor.transaction() as the interface's transaction primitive, and why it replaced raw BEGIN/COMMIT/ROLLBACK.
• § Concurrency & storage ownership: a new bullet for record-adapter-do-sqlite — "the DO is the lock."

README.md's package table and directory tree also updated.

Verification

• pnpm run format:check && pnpm run lint && pnpm test && pnpm run build && pnpm run typecheck — all green across the entire workspace (11 packages), not just the touched ones.
• record-adapter-sqlite's full existing suite (116 tests) passes unchanged after the transaction() refactor — confirms it's behavior-preserving.
• record-adapter-do-sqlite's new suite (16 tests) runs against the real Workers runtime (@cloudflare/vitest-pool-workers), not environment: 'node' — a targeted subset (CRUD, FK/unique constraint mapping, FTS5, cursor pagination, associations, commitMigration), plus the load-bearing case for the transaction refactor: a rejected patchContent must leave the FTS index consistent with stored content, which only holds if the rollback actually rolls back.
• The Workers-runtime findings that shaped this design (raw transactions rejected, no auto-rollback-on-throw, PRAGMA journal_mode = WAL rejected, FK/unique error strings match, FTS5 available, cursor/binding shape) came from a spike against the real runtime, not documentation assumptions.

Notes for reviewers

• record-adapter-do-sqlite is deliberately absent from scripts/verify-pack.mjs's EXPECTATIONS map (see the comment added there) — its entry point uses ambient Durable Object globals that don't exist under plain Node, so a bare import() there would fail for reasons unrelated to packaging correctness. It's still packed and installed into the throwaway consumer, so a missing files entry or an accidentally-unbundled @haverstack/sqlite-shared would still be caught.
• Adds .npmrc to keep @types/chai (pulled in only by this package's vitest 4 / @cloudflare/vitest-pool-workers) out of pnpm's shared @types hoist folder, where it was colliding with the chai types vendored in @vitest/expect@2 that the rest of the repo uses on vitest 2 — a real cross-package typecheck regression during development, fixed before it could land.
• .gitignore gained a narrow exception for hand-authored ambient .d.ts files under tests/support/ (this package's cloudflare:test type reference) — the blanket *.d.ts rule is meant for build output, and was silently dropping this file.
• Not urgent per the issue itself, but there's a real demand signal in the issue comments (a Cloudflare Pages + D1 + R2 site's migration decision hinges on whether this exists).

---

Generated by Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 9154fe3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@haverstack/record-adapter-do-sqlite	Patch
@haverstack/record-adapter-sqlite	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR