fix(sqlite-native): restore kv error hook

[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]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• 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 👈 (View in Graphite)
• 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(sqlite-native): restore kv error hook

This PR restores and properly wires the KV error hook in the native SQLite VFS layer, surfacing storage failures through to JavaScript with actionable context. The overall approach is sound.

---

Bugs / Correctness

kv_vfs_get_last_error uses clone_last_error not take_last_error (vfs.rs)

Using clone_last_error is correct because SQLite may call xGetLastError more than once, but it means the error lingers until a later successful operation clears it. The clear_last_error() calls on success guard against stale values being returned via takeLastKvError(), but a comment explaining this design choice would help future readers.

wrapNativeStorageError always throws but callers don't signal that (wrapper.js)

Both branches of wrapNativeStorageError throw, so callers rely on implicit never semantics:

} catch (error) {
    wrapNativeStorageError(nativeDb, error);
    // silent fall-through if the above ever stops throwing
}
return [];

If a future change makes wrapNativeStorageError not always throw, the caller silently returns []. Prefer an explicit pattern:

} catch (error) {
    throw wrapNativeStorageError(nativeDb, error);
}

Or rename to throwNativeStorageError to make intent clear at call sites.

Missing // SAFETY: comment on raw pointer dereference (vfs.rs, KvVfs::take_last_kv_error)

fn take_last_kv_error(&self) -> Option<String> {
    unsafe { (*self.ctx_ptr).take_last_error() }
}

This needs a // SAFETY: comment explaining the invariant: ctx_ptr is heap-allocated in KvVfs::register and freed only in KvVfs::drop, so dereferencing it is valid for any call made through NativeDatabase (which owns the KvVfs).

---

Minor Issues

read_cache change is a silent type fix (vfs.rs, kv_io_write)

The change from state.read_cache.get(...) to state.read_cache.as_ref().and_then(...) implies read_cache is now Option<_>. Since the old code would not compile with Option<HashMap>, this must reflect a type change that landed elsewhere. A brief note in the commit or a comment would help during bisects.

Unrelated bug fixes bundled in

The notGlobal ?? false, read_cache.as_ref(), and .as_deref() fixes are correctness improvements but unrelated to the KV error hook. Separating them into their own commit would make the history cleaner.

---

Before merge

• Tests for the takeLastKvError() round-trip (actor shutdown scenario)
• // SAFETY: comment on the unsafe block in take_last_kv_error
• Explicit throw (or rename) in wrapNativeStorageError callers

---

What is good

• Error propagation path (Rust VFS -> NAPI -> JS) is clean and well-layered.
• clone_last_error in xGetLastError correctly handles SQLite calling the callback multiple times.
• The typeof nativeDb.takeLastKvError === "function" defensive check is a solid backwards-compatibility guard.
• Error message in wrapNativeStorageError is specific and actionable (c.abortSignal guidance).
• sqlite_error_message helper gives better diagnostics on open/pragma failures.
• Proper null-termination and length bounds in kv_vfs_get_last_error -- no buffer overflow possible.

Generated with Claude Code