fix(rivetkit): surface native sqlite kv errors to callers

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

• chore(engine): publish engine bases in ci #4649 : 3 dependent PRs (#4650 , #4652 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645 👈 (View in Graphite)
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

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

[claude]

PR Review: fix(rivetkit): surface native sqlite kv errors to callers

Overview

This PR adds error enrichment to the native SQLite database wrapper so that underlying KV channel errors are surfaced when SQLite I/O operations fail. The fix appends the most recent KV error (retrieved via takeLastKvError) to the SQLite error message when the failure looks like an I/O-level fault.

---

Strengths

• Targeted scope: Only enriches errors that match I/O patterns (i/o error, unable to open database file), avoiding false enrichment for schema errors like no such table.
• Correct never typing: enrichNativeDatabaseError is correctly typed as never, letting TypeScript track control flow so result is guaranteed initialized after the try/catch in exec.
• Optional chaining is appropriate: ?. on takeLastKvError is correct per CLAUDE.md — this is a diagnostic/best-effort path.
• Double-enrichment guard: !error.message.includes(kvError) prevents appending the same KV context twice.
• Backward-compatible interface: Making takeLastKvError optional on JsNativeDatabaseLike correctly accounts for implementations that predate this field.

---

Issues

1. Incomplete test coverage (moderate)

The test file only exercises the run path via wrapJsNativeDatabase. The exec and query methods both call enrichNativeDatabaseError but have no corresponding tests. Given error enrichment is the core of this fix, all three method paths should be covered.

2. In-place error mutation (minor)

error.message is mutated directly. This preserves the stack trace (a reasonable trade-off), but can surprise callers that stored a reference to the original error before rethrowing. Wrapping via throw new Error(..., { cause: error }) is more idiomatic, though it changes the thrown type. Worth a deliberate decision either way.

3. Regex heuristic is undocumented (minor)

shouldAttachNativeKvError matches SQLite error messages by string pattern with no explanation of where the patterns come from. A single comment would help future maintainers avoid fragile edits:

// Matches SQLite error messages that indicate storage-layer failures
// mapping to KV channel errors in the native runtime.
function shouldAttachNativeKvError(message: string): boolean {

4. exec callback loop runs outside the try/catch (minor)

The callback loop in exec is intentionally outside the try/catch (callback errors are not KV errors), but there is no comment making this boundary explicit.

5. close is not wrapped (low)

close() is the only method without error enrichment. Errors during close are less actionable, so this is likely intentional — a comment would confirm the deliberate omission.

---

Verdict

Correct, well-scoped fix that addresses a real debuggability gap. The main gap before merging is test coverage: the enrichment logic for exec and query is untested. The other points are minor polish items.