refactor(sqlite-storage): extract DBHead to vbare-versioned protocol crate

[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

• ci(publish): skip lfs for preview checkouts #4819
• test(engine): cover envoy Sleep crash policy wake and recovery paths #4816
• refactor(sqlite-storage): extract DBHead to vbare-versioned protocol crate #4815 👈 (View in Graphite)
• refactor(sqlite-storage): rename SqliteOrigin variants for clarity #4814
• fix(sqlite-storage): allow invalidate_v1_migration on non-migrating META #4813
• test(engine): stabilize runner and envoy suites #4809
• fix(pegboard): decode envoy actor eviction keys #4803 : 1 other dependent PR (#4804 )
• fix(pegboard-envoy): subscribe before registering envoy #4802
• fix(envoy-client): dedupe replayed commands by index #4811 : 1 other dependent PR (#4812 )
• fix(envoy-client): complete command and request lifecycles #4801
• fix(guard): serialize gateway actor keys correctly #4655 : 1 other dependent PR (#4800 )
• chore(rivetkit): remove inline tests #4668 : 1 other dependent PR (#4657 )
• fix(api): subscribe before namespace workflow dispatch #4654
• fix(rivetkit): restore hibernatable sockets and hydrate serverless starts #4658
• test(rivetkit): stabilize actor db driver tests #4664 : 1 other dependent PR (#4656 )
• fix(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 1 other dependent PR (#4665 )
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• chore: add CLAUDE.md guidance on test fixtures, SDK regen, and TS client layer #4796
• fix(inspector): stream patched state updates #4795
• fix(rivetkit): refresh stale actor handles #4794
• test(rivetkit-napi): move private tests to crate root #4793
• test(rivetkit-core): move private tests to crate root #4792
• test(runner-configs): assert envoy protocol version #4791
• fix(serverless): split metadata protocol errors #4789 : 1 other dependent PR (#4790 )
• chore(sqlite): add open close lifecycle for envoy actors #4788
• fix(rivetkit): share lifecycle shutdown grace #4810
• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 1 other dependent PR (#4797 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765
• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

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

[claude]

PR Review: refactor(sqlite-storage): extract DBHead to vbare-versioned protocol crate

Overview

This PR extracts DBHead and SqliteOrigin from engine/packages/sqlite-storage/src/types.rs into a new dedicated protocol crate rivet-sqlite-storage-protocol. It introduces a versioned BARE-schema encoding layer (via vbare) with a 2-byte version prefix, replacing the raw serde_bare calls throughout the codebase.

---

Critical: Breaking On-Disk Format Change

The old encoding stored DBHead as a raw serde_bare blob with no version prefix. The new encoding adds a 2-byte LE version prefix via vbare::OwnedVersionedData::serialize_with_embedded_version.

Any existing actor SQLite meta records written by the old code will fail to decode:

• deserialize_with_embedded_version reads the first 2 bytes as the version number.
• Old data starts with the BARE varint for schema_version: 2 (0x02) followed by generation (0x01), so the two bytes are read as version 0x0102 = 258.
• There is no 258 => branch in deserialize_version, so bail! fires.

The old decode_db_head handled two legacy formats (with and without the origin field). Both fallbacks are removed. The test decode_db_head_defaults_legacy_rows_to_created_on_v2_origin that explicitly covered this path is also deleted.

Action required: Either confirm that existing stored data is always wiped on upgrade (pre-release only), or add a migration bridge in versioned::decode_db_head that first tries the versioned prefix parse and, on failure, falls back to the old raw serde_bare decode (matching the two-step logic that was in types.rs).

---

Convention: Free Function vs. Extension Trait

DBHead::new() is replaced by a free function new_db_head(). CLAUDE.md says: when rivetkit needs ergonomic helpers on a re-exported type, prefer an extension trait plus prelude re-export instead of a free function. A small DBHeadExt trait with a new(creation_ts_ms: i64) -> DBHead method would keep the call-site ergonomics of the previous DBHead::new(...) while staying within the project convention.

---

Minor: Unnecessary Clone in encode_db_head

The types.rs wrapper takes &DBHead and clones it to pass to versioned::encode_db_head which takes DBHead by value. Since serialize_version only needs a reference (serde_bare::to_vec takes &T), changing versioned::encode_db_head to accept &v1::DBHead would eliminate the clone.

---

Positive Points

• Good architectural fit. Follows the established envoy-protocol / epoxy-protocol / ups-protocol crate pattern under engine/sdks/rust/.
• Complete migration. Every serde_bare::to_vec(&head) / serde_bare::from_slice call for DBHead is replaced uniformly across production code and all test fixtures.
• Forward-versioning foundation. The BARE schema + vbare 2-byte prefix makes future schema changes non-breaking by design (add v2.bare, new match arm, converter).
• Build script path. Traversal from engine/sdks/rust/sqlite-storage-protocol/ up three levels to engine/, then joining sdks/schemas/sqlite-storage, is correct and consistent with sibling protocol crates.
• Test name updated to db_head_round_trips_through_versioned_encoding, accurately reflecting the new encoding path.

---

Summary

Severity	Issue
Critical	On-disk format break: old serde_bare blobs fail to decode with the new versioned encoder; backward-compat fallback removed
Moderate	Free function new_db_head should be an extension trait per project convention
Minor	Unnecessary clone() in types::encode_db_head wrapper

The core refactoring direction is sound. The format-compatibility concern needs to be resolved (or explicitly acknowledged as intentional for a pre-release wipe) before merging.

[NathanFlurry]

Landed in main via stack-merge fast-forward push. Commits are in main; closing to match.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4815

All packages published as 0.0.0-pr.4815.3b70228 with tag pr-4815.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-3b70228
docker pull rivetdev/engine:full-3b70228

Individual packages

npm install rivetkit@pr-4815
npm install @rivetkit/react@pr-4815
npm install @rivetkit/rivetkit-napi@pr-4815
npm install @rivetkit/workflow-engine@pr-4815