feat(vbare): add conversion boilerplate generator, fix envoy protocol conversion

[MasterPtato]

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

[railway-app]

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

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	May 9, 2026 at 11:29 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	May 9, 2026 at 11:22 pm
ladle	❌ Build Failed (View Logs)	Web	May 9, 2026 at 11:22 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	May 9, 2026 at 11:22 pm
kitchen-sink	❌ Build Failed (View Logs)	Web	May 9, 2026 at 11:21 pm
mcp-hub	✅ Success (View Logs)	Web	May 8, 2026 at 12:27 am

[MasterPtato]

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

• feat(vbare): add conversion boilerplate generator, fix envoy protocol conversion #5000 👈 (View in Graphite)
• chore: clean up types #4999
• chore: clean up err tracker wf, ignore silenced wf #4979
• main

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

[claude]

Code Review: feat(vbare): add conversion boilerplate generator, fix envoy protocol conversion

Overview

This PR replaces the monolithic 1846-line versioned.rs with a versioned/ directory of per-step converter files generated by a new TypeScript scaffolding script. The core goals — eliminating the convert_same_bytes round-trip anti-pattern and fixing the collapsed single-variant wrapper enum — are both achieved. The generator script and documentation are well-designed.

---

Required Changes

1. Unfilled todo!() in sqlite helpers — v2_to_v3.rs and v3_to_v2.rs

Several todo!() placeholders remain in sqlite helper functions:

• v2_to_v3.rs: convert_sqlite_get_pages_request_v2_to_v3 (fields expected_generation, expected_head_txid), convert_sqlite_commit_request_v2_to_v3 (fields db_size_pages, now_ms, expected_generation, expected_head_txid), and several response variants.
• v3_to_v2.rs: convert_sqlite_get_pages_request_v3_to_v2 (field generation), convert_sqlite_commit_request_v3_to_v2 (fields generation, expected_head_txid, new_db_size_pages), convert_sqlite_commit_response_v3_to_v2 (SqliteCommitOk variant).

The outer union arms bail unconditionally before reaching these helpers, so they are dead code in practice. But todo!() panics if ever reached. The correct treatment is bail!(...) with a descriptive message (matching the style of incompatible(...) calls elsewhere) or deleting the unreachable helper functions entirely. Leaving todo!() violates the CLAUDE.md guideline to fill in every todo!() before shipping.

2. Inline #[cfg(test)] block in versioned/mod.rs

Four tests live in an inline #[cfg(test)] mod tests block. CLAUDE.md rule: "Rust tests live under tests/, not inline #[cfg(test)] mod tests in src/." Move these to engine/sdks/rust/envoy-protocol/tests/.

---

Should Fix

3. Silent drop of sqlite_startup_data in v2_to_v3

convert_command_start_actor_v2_to_v3 discards sqlite_startup_data without explanation. The v3_to_v2.rs direction has the comment "v3 dropped the field; downgrade leaves it absent on the v2 wire." The forward direction needs an equivalent comment so the silent drop is clearly intentional.

4. @generated marker and #![allow] not cleaned up from fully-filled files

v1_to_v2.rs, v2_to_v1.rs, v3_to_v4.rs, v4_to_v3.rs, v4_to_v5.rs, and v5_to_v4.rs have all todo!()s filled in but still carry the @generated initial scaffold header and #![allow(dead_code, unused_variables)]. The documented intent is to drop these once the file is finalized. (Both are legitimately needed in v2_to_v3.rs and v3_to_v2.rs where the sqlite helpers are genuinely dead code.)

---

Low Priority

• No per-step round-trip tests: actor_command_key_data_round_trips_to_v1 covers the full chain but per-step tests (v4<->v5, v3<->v4, v2<->v3) would add targeted coverage, especially at sqlite-gated boundaries.
• Generator emitFile ordering is not topological: Does not affect Rust compilation but can make generated files harder to read when a converter references another defined later in the file.
• Generator typesEqual is AST-level, not semantic: If a field type is an alias resolving to the same underlying shape under a different name, the script conservatively emits todo!(). Safe but may produce unnecessary noise for future schema authors.

---

What Is Done Well

• convert_same_bytes fully eliminated: Zero instances in any added file. The only new serde_bare calls are the correct deserialize-from-wire / serialize-to-wire at the deserialize_version / serialize_version boundaries.
• Multi-variant wrapper enums are correct: All six wrapper types (ToEnvoy, ToRivet, ToEnvoyConn, ToGateway, ToOutbound, ActorCommandKeyData) now have V1-V5 variants instead of the collapsed V5-only form.
• deserialize_converters / serialize_converters ordering is correct: Bottom-up and top-down respectively, matching the documented invariant.
• incompatible(...) used consistently: Structured ProtocolCompatibilityError at every bail site that drops a feature version.
• Test fix in remote_sql_compat.rs is correct: Changing target_version assertions from the loop variable to 3 (the version where the v4_to_v3 bail fires) is accurate and well-explained.
• Generator script handles all type shapes: structs, unions, enums, optionals, vecs, and maps are rendered correctly with proper Result-propagating expressions.
• Documentation is thorough: .claude/reference/vbare-migrations.md clearly documents the converter chain ordering gotcha, the anti-patterns to avoid, and the step-by-step workflow for future schema additions.