chore(publish): temp force release build for rivetkit-native preview

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

.github/workflows/publish.yaml

@@ -200,7 +200,11 @@ jobs:
         if: steps.gate.outputs.skip != 'true'
         id: mode
         run: |
-          if [ "${{ needs.context.outputs.trigger }}" = "release" ]; then
+          # TEMP perf bench: force release mode for rivetkit-native regardless
+          # of trigger so PR previews ship optimized native addons.
+          if [ "${{ matrix.build_target }}" = "rivetkit-native" ]; then
+            echo "build_mode=release" >> $GITHUB_OUTPUT
+          elif [ "${{ needs.context.outputs.trigger }}" = "release" ]; then
             echo "build_mode=release" >> $GITHUB_OUTPUT
           else
             echo "build_mode=debug" >> $GITHUB_OUTPUT

…l/rivetkit-typescript/sqlite-ltx/SPEC.md …engine/design-choicse/sqlite-vfs/SPEC.mddocs-internal/rivetkit-typescript/sqlite-ltx/SPEC.md renamed to docs-internal/engine/design-choicse/sqlite-vfs/SPEC.md docs-internal/rivetkit-typescript/sqlite-ltx/SPEC.md renamed to docs-internal/engine/design-choicse/sqlite-vfs/SPEC.md

@@ -0,0 +1,63 @@
+# SQLite Journal Mode (VFS v2)
+
+## Goals
+
+- One SQLite handle per actor, single-writer, no in-process reader-writer concurrency
+- Capture each commit as a single shippable artifact for storage in our KV (DELTA blob in FDB) and for future cold archival (PITR)
+- Avoid maintaining a local SQLite-on-disk file. The KV is the file.
+- Keep the VFS implementation as small as possible
+
+## Decision
+
+Use `journal_mode = DELETE` with `locking_mode = EXCLUSIVE`.
+
+Pragmas (set at open in `rivetkit-typescript/packages/sqlite-native/src/v2/vfs.rs`):
+
+- `PRAGMA journal_mode = DELETE`
+- `PRAGMA locking_mode = EXCLUSIVE`
+- `PRAGMA synchronous = NORMAL`
+- `PRAGMA temp_store = MEMORY`
+- `PRAGMA auto_vacuum = NONE`
+- `PRAGMA page_size = 4096`
+
+Capture dirty pages at xWrite/xSync and assemble one LTX V3 DELTA blob per commit, written atomically to FDB.
+
+We do **not** use `journal_mode = WAL`. We do not implement xShmMap/xShmLock and have no SQLite WAL stream to sniff.
+
+## Evaluation
+
+### journal_mode = WAL (rejected)
+
+WAL mode is the natural choice when SQLite operates against a real local file with concurrent readers and a writer. It is rejected for v2 because:
+
+- The substrate is a remote KV, not a filesystem. There is no `db.sqlite` or `db.sqlite-wal`; both would have to be virtualized over KV.
+- Requires implementing `-shm` (shared-memory WAL index): xShmMap, xShmLock, xShmBarrier, xShmUnmap. Non-trivial over KV; unnecessary for a single-writer-per-actor model.
+- Requires driving SQLite's checkpoint loop. Our SHARD set is already the checkpointed state, so checkpoint has no useful target to write into.
+- Requires WAL recovery on open. Our durability story is "the prior commit either reached FDB atomically or it did not"; takeover handles fencing. There is no half-written WAL state to recover.
+- WAL frames captured via VFS sniffing would still need to be re-packaged into a per-commit page-set blob for dense storage in FDB. The end artifact is identical to today's DELTA blob, reached via a longer path.
+- The headline benefit of WAL mode (concurrent readers + one writer without writer-blocks-readers) is moot because we hold an EXCLUSIVE lock per actor.
+
+The DELTA blob is therefore not a re-implementation of WAL. It is the captured commit page-set from a non-WAL-mode SQLite. Functionally equivalent to WAL frames at a commit boundary with same-page overwrites collapsed, by construction.
+
+### journal_mode = DELETE (chosen)
+
+- No `-shm` file. No checkpoint loop. No WAL recovery semantics to virtualize.
+- xWrite captures dirty pages directly. xSync (or xLock state transitions) marks the commit boundary.
+- Rollback journal is short-lived per transaction; with our VFS it lives in memory only.
+- Maps cleanly to "one DELTA blob per commit, atomic FDB write."
+
+### journal_mode = MEMORY / OFF (rejected)
+
+- MEMORY: rollback journal in RAM. Functionally similar to DELETE for our purposes, but loses crash-safety semantics SQLite depends on for its own recovery during a transaction. Not worth the deviation from defaults given DELETE already costs us nothing extra.
+- OFF: disables the rollback journal entirely. SQLite cannot roll back a failed transaction; partial writes can corrupt the DB. Unacceptable.
+
+### locking_mode = EXCLUSIVE
+
+- One SQLite handle per actor; only the actor's own process writes.
+- Avoids the overhead of repeated SHARED/RESERVED/EXCLUSIVE lock transitions per transaction.
+- Removes the need for any cross-process file locking primitives in the VFS.
+
+## Implications for future work
+
+- **PITR**: The DELTA blob stream is our equivalent of LiteFS Cloud / Cloudflare DO WAL streams. Cold archival can ship DELTAs to object storage with the same semantics they ship WAL frames, without changing journal mode.
+- **A future v3 with a local-file hot tier** would re-open the WAL question. If we ever want microsecond local-disk reads instead of FDB-RTT reads, switching to WAL mode against a real local file becomes the natural choice and Cloudflare's hot-path design is the right reference.