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

• 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): reject empty actor kv values #4808
• fix(pegboard): stabilize actor2 validation and lifecycle #4804 : 1 other dependent PR (#4805 )
• fix(pegboard): decode envoy actor eviction keys #4803
• fix(pegboard-envoy): subscribe before registering envoy #4802
• fix(envoy-client): clear processed_command_idx after ack send #4812
• fix(envoy-client): dedupe replayed commands by index #4811
• fix(envoy-client): complete command and request lifecycles #4801
• fix(envoy-protocol): advertise current protocol version #4800
• fix(guard): serialize gateway actor keys correctly #4655
• fix(rivetkit-native): expose full hibernation metadata to JS #4657
• chore(rivetkit): remove inline tests #4668
• fix(api): subscribe before namespace workflow dispatch #4654
• fix(rivetkit): restore hibernatable sockets and hydrate serverless starts #4658
• fix(pegboard): persist and replay hibernating requests #4656
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• test(rivetkit): stabilize actor db driver tests #4664
• 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): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• docs: add replay guidance notes #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]

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

Overall this is a clean extraction that follows the established vbare versioning pattern used by other protocol crates in the repo. The structure is correct and the mechanical changes are consistent across all call sites. A few things worth addressing before this ships:

---

Breaking Change: Legacy format no longer readable

The old decode_db_head in types.rs had two fallback paths:

1. Decode as the new format (with origin field).
2. Decode as the legacy LegacyDBHead (without origin), defaulting origin to CreatedOnV2.

Both paths are now gone. The new versioned::decode_db_head calls deserialize_with_embedded_version, which expects a 2-byte LE version prefix. Any existing stored bytes — including data written by the old serde_bare::to_vec path — have no version prefix and will produce a deserialization error at read time.

The test decode_db_head_defaults_legacy_rows_to_created_on_v2_origin was deleted without explanation. If there are any deployed actors with rows in the old format, this will cause read failures after deploy.

Questions:

• Is a migration handled in a downstack PR in this Graphite stack?
• If not, does deserialize_with_embedded_version have any fallback for un-prefixed data?

Per CLAUDE.md: "Never modify an existing published *.bare runner protocol version unless explicitly asked to do so." This is a new crate so that rule doesn't apply here, but the on-disk compatibility concern is similar in spirit.

---

Minor: Inconsistent ownership at encode boundary

types::encode_db_head takes head: &DBHead but internally calls versioned::encode_db_head(head.clone()), which takes ownership. This unnecessary clone could be avoided by either:

• Making versioned::encode_db_head accept &v1::DBHead and cloning inside only if vbare forces it, or
• Changing all call sites to pass by value (most are already constructing a temporary).

Not a correctness issue, just a minor inconsistency.

---

build.rs path resolution

The 3-parent() walk from CARGO_MANIFEST_DIR to find the workspace root is consistent with the other protocol crates (e.g. envoy-protocol), so this is fine as-is. Just worth noting that it will silently break if the crate moves to a different nesting depth.

---

Nit: PR description is empty

The PR body has no description or test plan. Since this is a DRAFT that's fine for now, but should be filled in before promotion — especially given the migration risk above.

---

What looks good

• The vbare versioning pattern (OwnedVersionedData, serialize_with_embedded_version, deserialize_with_embedded_version) is applied correctly and matches the other protocol crates.
• The v1.bare schema accurately reflects the struct fields.
• All 9 call sites in shard.rs, worker.rs, open.rs, read.rs, quota.rs, commit.rs, and the pegboard integration test are consistently updated.
• SQLITE_STORAGE_PROTOCOL_VERSION = 1 is correctly set for the initial introduction.
• The free-function API (new_db_head, encode_db_head, decode_db_head) is cleaner than the previous DBHead::new associated method.
• The inline comment in v1.bare pointing future changes toward adding a v2.bare is a good guardrail.