feat: native SQLite backend via napi-rs with KV channel protocol

[NathanFlurry]

No description provided.

[railway-app]

🚅 Deployed to the rivet-pr-4496 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
kitchen-sink	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:45 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:11 am
website	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:11 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:10 am
ladle	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:10 am
mcp-hub	✅ Success (View Logs)	Web	Apr 5, 2026 at 10:20 am

[NathanFlurry]

• chore: remove global epoxy contention #4554
• feat: native SQLite backend via napi-rs with KV channel protocol #4496 👈 (View in Graphite)
• feat: actor query in gateway #4553
• feat: add sleep and reschedule endpoints for actors #4556
• fix: optimize e2e actor path #4551
• feat(pb): actor v1 to v2 migration #4548
• feat(envoy-client): fully flesh out tunnel impl #4547
• feat: basic rivetkit impl #4544
• feat: basic envoy tunnel impl #4534
• chore: envoy client #4521 : 1 other dependent PR (#4531 )
• feat(pb): actors v3 #4463
• feat(ups): implement queue subs #4486
• feat(cache): add in flight deduping #4459
• fix(cache): clean up lib #4457
• fix(config): allow configuring topo dcs via map, fix pg ssl mode config #4456
• fix(api): dont 500 on cross dc response #4449
• chore: update byte units on frontend #4444
• fix: runner alloc idx logic, api auth for actor get #4443
• main

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

[claude]

PR Review: Native SQLite Backend via napi-rs with KV Channel Protocol

This is a substantial feature (~14.6k additions across 96 files) introducing a native SQLite backend that routes page-level I/O over a new WebSocket KV channel protocol. The architecture is well-designed overall.

---

Architecture Assessment

The design choices are sound:

• Separate KV channel protocol (independent of runner protocol) keeps concerns cleanly separated.
• Single-writer lock enforcement per actor with per-actor mpsc channel + sequential task correctly preserves intra-actor ordering while enabling cross-actor parallelism.
• Lock eviction on reconnect handles stale connection races.
• Preloaded KV bundled into CommandStartActor for near-zero cold-read latency is clever, and the decision to never persist it in workflow history is correct since it is non-deterministic data.

---

Issues

1. Breaking Metric Renames Without Documentation

engine/packages/pegboard-runner/src/metrics.rs renames two Prometheus metrics:

• pegboard_runner_event_multiplexer_count -> pegboard_event_multiplexer_count
• pegboard_runner_ingested_events_total -> pegboard_ingested_events_total

These are silent breaking changes for any existing dashboards or alerts. There is no migration note, no changelog entry, and no update to dashboard definitions in the repo. Existing Grafana dashboards or alert rules referencing these metric names will silently stop working after deployment.

2. Committed Binary Artifact

rivetkit-typescript/packages/sqlite-native/sqlite-native.linux-x64-gnu.node is a compiled native addon binary committed directly to the repository. This is problematic:

• It bloats git history permanently.
• There is no way to verify its provenance or that it matches the source in src/.
• It creates a supply chain risk: if the binary is loaded without a checksum/signature check, a tampered binary would be silently used.

Native addon binaries should be built in CI and distributed via npm platform packages (the npm/ subdirectory already has the platform package structure), not committed to the repo.

3. Fragile prefix_range Implementation

In engine/packages/pegboard/src/actor_kv/preload.rs, the prefix_range function manually strips the trailing 0x00 that FDB tuple encoding appends to byte arrays, then appends 0xFF to compute the prefix end. This relies on an undocumented implementation detail of the tuple layer. If the tuple encoding changes, or if the prefix is empty, this silently produces wrong ranges. FDB tuple layer prefix range helpers should be used instead.

4. Silent Error Swallowing in fetch_preloaded_kv

In engine/packages/pegboard/src/actor_kv/preload.rs:

let Some(preload_config) = metadata_map
    .get("preload")
    .and_then(|value| serde_json::from_value::<PreloadConfig>(value.clone()).ok())
else {
    return Ok(None);
};

A malformed preload metadata field silently returns None (no preloading) instead of an error. Actors will appear to work but with degraded performance and no indication of why. At minimum, log a warning when deserialization fails but a preload key is present.

5. Token in Query Parameter Exposed in Logs

In engine/packages/guard/src/routing/kv_channel.rs, the admin_token is passed as a URL query parameter (?token=...). The full URL (including the token) is present in the HTTP upgrade request and will appear in access logs on intermediate proxies or load balancers. This is worth documenting as a known trade-off, or the token should be redacted from logs.

6. MAX_ACTORS_PER_CONNECTION = 1000 Is Not Configurable

The hardcoded limit in engine/packages/pegboard-kv-channel/ is reasonable as a default but should be surfaced in the pegboard config (like preload_max_total_bytes) so operators can tune it without a code change.

---

Nits

Benchmark scripts in examples/kitchen-sink/scripts/: Four large diagnostic/benchmark scripts (~1700 lines total) are added to the kitchen-sink example. If these are internal development tools, consider moving them or noting they are not intended for end-user consumption.

No PR description: The PR body is empty. For a feature this large (new protocol, new crate, new native addon, schema changes), a description covering motivation, architecture decisions, and testing approach would be valuable for reviewers and future git archaeology.

---

What Looks Good

• Constant-time token comparison (subtle::ConstantTimeEq) in both runner and KV channel auth paths.
• CLAUDE.md updated with VFS parity requirements and KV channel sync guidance.
• Cross-backend VFS compatibility tests (cross-backend-vfs.ts) and DB stress tests are well-motivated.
• Protocol version fallback updated from hard-coded 1 to PROTOCOL_VERSION constant in pegboard-outbound.
• Per-actor sequential ordering with cross-actor parallelism is the right model for this workload.

[NathanFlurry]

Merge activity

• Apr 5, 11:11 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 5, 11:45 AM UTC: Graphite rebased this pull request as part of a merge.
• Apr 5, 11:45 AM UTC: @NathanFlurry merged this pull request with Graphite.