fix: keep a crank's store work inside one transaction

[sirtimid]

#1020 has merged; this is rebased onto main and stands alone. Replaces #1012, #1018 and #1011, which are closed.

Four PRs were editing the same rollbackCrank lines. This one owns all of the kernel's crank-rollback, savepoint and transaction-boundary semantics, so nothing else has to.

Closes #1016 — a throw out of deliver now rolls the delivery back instead of committing the partial crank.

Why these had to merge

#1012 rewrote rollbackCrank's finally into a try/catch that truncates the savepoint stack and rethrows. #1010 changed ctx.savepoints from string[] to {name, maybeFreeKrefs}[] and added a cache/GC-candidate restore further down the same function. Composed naively the rethrow fires before the restore, so a failed rollback leaves stale in-memory GC candidates and stale cached stored values behind. Neither PR could see that from inside itself.

A second one surfaced while assembling this branch, and is the sharper argument: #1020's audit and #1012's flush reorder are silently incompatible. The audit reads the run queue as ground truth, but a buffered item's refcounts are incremented at enqueueSend/enqueueNotify time, so auditing before the flush reports every buffered item as a leak. assertRefCountsIfAuditing now runs after the flush.

What's fixed

Carried from #1012:

1. releaseSavepoint is hardened the way rollbackSavepoint was. A RELEASE that threw left the savepoint on the stack and the transaction open with nothing that would ever commit or abort it, so every later write on the connection joined it, reported success, and vanished on close(). Both drivers now discard the transaction; the release failure still propagates. releaseAllSavepoints gets the companion case.
2. A crank's store work stays inside one transaction. A crank takes crank and delivery savepoints and the run loop rolls back only delivery. Rolling back the outermost one ended the transaction, so the work an aborted crank still owes — terminating the vat, collecting garbage — was autocommitting a statement at a time.
3. The wasm driver can no longer believe it is in a transaction it isn't. _inTx is cleared before the abort is attempted, because the abort can throw.

Fixing the four defects #1018 pinned as failing repros — its tests are carried here unmodified, with Ryan's authorship, and the fixes land as later commits so the branch reads test-then-fix:

4. RemoteHandle reports the release failure, not a missing savepoint. It released inside its try and rolled back in the catch; now that a failed RELEASE discards the stack, that rollback threw No such savepoint in place of the real error. RemoteManager had the identical shape at its peerIncarnation_* savepoint with zero coverage — test: failing repros for four defects found reviewing #1012 #1018 flagged it and it is fixed and covered here. The savepoint-stack model is shared (test/savepoint-stack.ts), so a fix applied to one and forgotten in the other can't leave a green suite.
5. endCrank no longer buries the error that killed the run loop. #runLoop called it from a bare finally. The in-flight error is boxed rather than compared against undefined, so a crank that threw undefined stays distinguishable from one that didn't throw.
6. The kernel store gets a logger. No production call site passed one to makeSQLKernelDatabase, making four logger?.error calls dead code. Fixed for both the nodejs path and kernel-browser-runtime's kernel-worker.ts, so both drivers' calls are live.
7. commitIfNeeded clears _inTx before the COMMIT, the ordering rollbackIfNeeded was already corrected for. A throwing COMMIT wedged _inTx true and beginIfNeeded became a permanent no-op.

And the composition bug above:

8. The in-memory revert runs on the failed-rollback path too. Extracted as revertStateBeneathRollback() and called from both sites. A failed ROLLBACK TO makes the driver discard the whole transaction, so the database has moved back at least as far as a successful rollback would have taken it — the caches are at least as stale, and that is precisely where a lost GC action does the most damage. If the revert itself throws while a rollback error is in flight, the rollback error is preserved as cause.

Note for the reviewer

refreshCachedValues() refreshes gcActions, and it now runs on both rollback paths. The GC-delivery hardening PR stacked after this one depends on that: a DB rollback restores the gcActions row but not the cached closure over it, so without this the audit builds its exemption set from a stale cache and kills the run loop. Verified against a real SQLite store.

Testing

yarn lint clean, yarn build 31/31, four changelog:validate runs clean. kernel-store, ocap-kernel, kernel-node-runtime, kernel-browser-runtime and kernel-test all green.

Every fix mutation-verified — revert the production hunk and the named test fails for the stated reason.

@ocap/kernel-test is intermittently flaky, on this branch and on its base. Roughly two failures in twelve runs, always garbage-collection › survives until both importers let go or supervisor › initializes vat with powers, each passing in isolation and in five consecutive clean runs after. Both are GC/timing-dependent and untouched by crank, savepoint or logger code. The first is what the vat-lifecycle PR further up this stack targets, via makeGCAndFinalize draining the queues before gc(). Not introduced here, and not claimed green.

Not done

• No test pins the kernel-worker.ts logger wiring; kernel-browser-runtime has no test module for it and standing up the browser mock surface is disproportionate for a one-line change. The nodejs equivalent is pinned by test: failing repros for four defects found reviewing #1012 #1018's own repro.
• kernel-node-runtime/test/helpers/remote-comms.ts and kernel-test-local/src/lms-chat.ts still call makeSQLKernelDatabase without a logger — test harnesses, not production call sites.

Follow-ups filed

• Extract the duplicated sqlite savepoint methods into one module #1013 — the savepoint trio is byte-for-byte identical in both drivers; this PR writes the same fix and the same tests twice
• Crank savepoint ordering is an unexpressed invariant, not a nameable one #1014 — createCrankSavepoint's name parameter can't express "crank outer, delivery inner", the invariant that fails silently

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, README.md, CHANGELOG.md) as appropriate

---

Note

High Risk
Changes core persistence and crank commit/rollback paths plus remote message timing; bugs here could corrupt kernel state or lose GC work, though coverage is extensive.

Overview
Hardens SQLite kernel-store transaction semantics and aligns crank boundaries with how the run loop commits work, so partial failures no longer leave “successful” writes in orphaned transactions or interleave remote savepoints with cranks.

The nodejs and wasm drivers now discard transactions when RELEASE, ROLLBACK TO, or COMMIT fails, refuse further writes when an abort cannot end a wedged transaction, and (wasm) use SQLite’s autocommit state instead of a cached in-transaction flag. The node driver stops logging every SQL statement via verbose; browser and node runtimes pass a kernel-store sub-logger into makeSQLKernelDatabase.

Crank layering uses separate crank and delivery savepoints: only the delivery rolls back on abort, while post-delivery work (vat termination, GC) stays in the crank transaction. The crank buffer flushes after that fallible work (so callers aren’t answered from state that gets rolled back), and the reference-count audit runs after endCrank. rollbackCrank also refreshes cached stored values and restores GC candidate state the DB rollback can’t reach.

Concurrency: withStoreOutOfCrank / outOfCrankWorkPending block cranks while inbound remote handling and peer incarnation updates hold their own outer savepoints; RemoteHandle resolves redeemURL before opening a savepoint. Related savepoint rollback failures are logged without masking the original error. Kernel.stop records last-active time on a best-effort basis.

Extensive new tests cover transaction survival, savepoint/crank interleaving, audit ordering, and GC test stability (reap until settled).

^{Reviewed by Cursor Bugbot for commit 0304ddc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	72.62% ⬆️ +0.08%	9736 / 13406
🔵	Statements	72.47% ⬆️ +0.07%	9899 / 13658
🔵	Functions	73.03% ⬆️ +0.04%	2281 / 3123
🔵	Branches	66.91% ⬆️ +0.02%	3994 / 5969

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/kernel-browser-runtime/src/kernel-worker/kernel-worker.ts	0% 🟰 ±0%	0% 🟰 ±0%	0% 🟰 ±0%	0% 🟰 ±0%	26-128
packages/kernel-node-runtime/src/kernel/make-kernel.ts	100% 🟰 ±0%	88.88% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%
packages/kernel-store/src/sqlite/nodejs.ts	99.07% ⬆️ +0.07%	93.33% 🟰 ±0%	100% 🟰 ±0%	99.07% ⬆️ +0.07%	82
packages/kernel-store/src/sqlite/wasm.ts	98.19% ⬆️ +0.16%	89.47% 🟰 ±0%	100% 🟰 ±0%	98.18% ⬆️ +0.16%	252-255
packages/ocap-kernel/src/KernelQueue.ts	98% ⬇️ -0.56%	89.47% ⬇️ -0.80%	100% 🟰 ±0%	98% ⬇️ -0.56%	149, 196, 544
packages/ocap-kernel/src/remotes/kernel/RemoteHandle.ts	95.91% ⬆️ +0.03%	89.47% 🟰 ±0%	98.03% 🟰 ±0%	95.88% ⬆️ +0.03%	389, 396-401, 447, 526, 569, 579-581, 641-644, 993, 1070-1072, 1123
packages/ocap-kernel/src/remotes/kernel/RemoteManager.ts	99.07% ⬆️ +0.02%	100% 🟰 ±0%	95.65% 🟰 ±0%	99.07% ⬆️ +0.02%	442-444
packages/ocap-kernel/src/store/index.ts	98.83% ⬇️ -0.07%	95.23% 🟰 ±0%	100% 🟰 ±0%	98.82% ⬇️ -0.06%	396
packages/ocap-kernel/src/store/types.ts	100% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%
packages/ocap-kernel/src/store/methods/crank.ts	97.87% ⬇️ -2.13%	88.88% ⬇️ -4.87%	100% 🟰 ±0%	97.87% ⬇️ -2.13%	80

Generated in workflow #4699 for commit e75a20d by the Vitest Coverage Report Action

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0304ddc. Configure here.}

[cursor]

Terminate commits crank without flushing

High Severity

Clearing #deliveryRollbackAllowed after #terminateVat means a later throw from collectGarbage skips both rollback and #flushCrankBuffer, then #endCrank commits the delivery. Promise resolutions and other vat outputs stay in the store while their notifies never reach the run queue, so waiters hang across restart. exitVat is the path that terminates without abort, and the new test throws from collectGarbage on exactly that path.

 

^{Reviewed by Cursor Bugbot for commit 0304ddc. Configure here.}

[sirtimid]

Converting to draft. This stack is being split into small, single-purpose PRs against main rather than reviewed as a whole; it stays open as the reference to cherry-pick from and will be closed once its last piece has landed. Please do not spend review time on it in this form.

[sirtimid]

Closing: this is now fully re-landed as individually reviewed PRs against main.

The split is described in the plan agreed on 2026-09-15; the design question the concurrency work turned on is answered in the accompanying decision record, only the run loop writes the store, which is why the Tier 3 pieces below are rewritten rather than cherry-picked. withStoreOutOfCrank, outOfCrankWorkPending, the run loop's gate re-check and the savepoint-inside-crank refusals do not appear in any of them.

What this PR became:

piece	PR
Kernel-store logging: no better-sqlite3 verbose, no per-kv debug lines, a store logger in both runtimes	#1086
wasm driver reads inTransaction from sqlite3_get_autocommit	#1089
One copy of the savepoint/transaction methods, shared by both drivers	#1092
A failed RELEASE / COMMIT / SAVEPOINT discards the transaction; writes refused while it is abandoned	#1094
Crank rollback reverts the in-memory caches	#1087
Two crank savepoints, so termination and GC after an abort stay in the crank's transaction	#1090
Audit vs flush ordering — by crediting the crank buffer, so the audit can run before the flush	#1095
Post-commit hook; an outbound remote delivery is sent after its crank commits	#1101
An inbound remote message is a run-queue item, taken in a crank of its own	#1103
A peer's incarnation change is a run-queue item	#1104
clearStorage / reset / stop stop the run loop before writing	#1105
A savepoint taken while the run loop runs is refused	#1106
makeGCAndFinalize drains the queues before gc()	#1083

Each is motivated on its own, reproduces on main where it is a defect, and carries a test named for the behaviour. Nothing here is lost; the branch stays for reference.