chore(depot-client): split sqlite vfs transports

[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

• chore(rivetkit): note duplicate admission logic #4948
• test(rivetkit): cover bypass fetch header forwarding #4947
• feat(kitchen-sink): add actor probe controls #4946
• fix(gateway): split actor response wait errors #4945
• fix(guard): handle bypass preflight before query parse #4944
• feat(kitchen-sink): add mock agent event log copy #4943
• fix(kitchen-sink): default mock agent to local endpoint #4942
• test(rivetkit): enable driver lifecycle regressions #4941
• test(rivetkit): verify cached websocket db refs exceed grace #4940
• fix(rivetkit-core): keep sleeping actors reachable during grace #4939
• test(rivetkit): cover async websocket close db access #4938
• fix(rivetkit): keep actors awake until keepAwake work finishes #4937
• fix(rivetkit): persist native onSleep state on errors #4936
• fix(rivetkit-core): allow dispatch during sleep grace #4935
• fix(rivetkit): make duplicate sleep requests idempotent #4934
• fix(rivetkit): align logs with engine logfmt #4933
• fix(ci): standardize publish rust toolchain #4931
• SPLIT UP: agentic loop test #4932
• chore(rivetkit): doc skip ready wait #4927
• fix(guard): parse gateway bypass query booleans #4926
• feat(depot-client): add vfs staging cache ttl #4930
• feat(depot-client): wire sqlite optimization flags #4923
• feat(rivetkit): support gateway bypass client overrides #4928
• test(depot-client): stabilize fault harness #4924
• chore(depot-client): split sqlite vfs transports #4922 👈 (View in Graphite)
• feat(rivetkit): support gateway bypass probes #4915
• feat(kitchen-sink): add mock agentic lifecycle loop #4914
• feat(kitchen-sink): add mock agentic loop #4891
• feat(rivetkit): support gateway bypass client requests #4917
• fix(pegboard): restore hibernating request ids #4898 : 2 other dependent PRs (#4899 , #4916 )
• chore(guard): configure local timeout knobs #4913
• docs(rivetkit): raise serverless start payload limit #4911
• test(kitchen-sink): add sqlite memory soak harness #4910
• feat(rivetkit): expose runtime diagnostics #4909
• chore(depot-client): migrate to worker thread #4907 : 2 other dependent PRs (#4912 , #4918 )
• test(driver): select matrix cells with vitest filters #4906
• fix(pegboard): restore hibernating requests on serverful start #4904 : 1 other dependent PR (#4905 )
• fix(rivetkit): drain shutdown work before sleep #4902 : 1 other dependent PR (#4903 )
• feat(sqlite): wire remote sqlite execute handlers #4897
• test(serverless): avoid pinning header validation order #4896
• chore(driver-test-runner): add native/wasm runtime matrix to skill #4884 : 3 other dependent PRs (#4892 , #4894 , #4901 )
• chroe: rename rivetkit-sqlite to depot-client #4883
• fix(rivetkit-wasm): fix mem leaks #4880
• chore(rivetkit): wasm support #4860
• feat(sqlite): add cold read benchmarks and simplify optimizations #4857
• feat(sqlite): benchmark cold reads #4848 : 1 other dependent PR (#4864 )
• docs(actors): document manual lifecycle controls #4847
• test(sqlite): expand db stress coverage #4846 : 1 other dependent PR (#4849 )
• test(raw-websocket): add serverless smoke coverage #4845
• feat(serverless): configure drain grace period #4844
• fix(publish): enable frontend build for engine target and use turbo build instead of turbo build:engine #4843
• feat(rivetkit): expose conn handle in onWebSocket context #4842
• fix(rivetkit): normalize waitUntil/keepAwake promises to null to avoid serde undefined error #4841
• fix(rivetkit): remove requirement for token #4839 : 1 other dependent PR (#4840 )
• fix(pegboard-envoy): allow sqlite requests across lifecycle states #4838
• fix(pegboard): route scoped actor key reads by runner dc #4837
• fix(sqlite-storage): let sqlite open take over stale owners #4834
• fix(engine-tests): parallelize multi-DC startup + enable 6 multi-DC tests #4833
• fix(api): honor cursor in actor_ids list path #4832
• fix(api): silently filter invalid IDs from actor_ids query instead of 400 #4831
• fix(api-peer): make actors_delete idempotent for already-destroyed actors #4830
• fix(pegboard): use Iterator streaming mode in list_names so limit param is honored #4829
• chore(engine-tests): convert envoy tests to Sleep crash policy + triage ignored #4828
• feat(engine-tests): wire envoy actor names through prepopulate_actor_names #4827
• chore(depot): fault injection tests #4868
• feat(sqlite): pitr & forking #4859 : 1 other dependent PR (#4863 )
• chore(sqlite): stateless storage refactor #4856
• main

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

[claude]

PR 4922 Review: chore(depot-client) split sqlite vfs transports

Overview

This PR refactors the SQLite VFS transport layer from a concrete enum-based design to a trait-based design. The key motivation is removing the rivet-envoy-client dependency from depot-client, which unblocks WASM builds. The three concrete transports become:

• EnvoySqliteTransport (in rivetkit-core) -- wraps EnvoyHandle for actor-side use
• EmbeddedDepotSqliteTransport (in depot-client/src/transport.rs) -- same-process Depot calls, formerly the Conveyer variant
• DirectDepotTransport / DirectMirrorTransport (test-only in vfs_support.rs) -- replace the old Direct enum variant and strict_mode flag

Strengths

• Clean architecture: Moving from an open enum with cfg(test) arms scattered through production code to a trait is a clear quality improvement.
• Correct WASM unblocking: Removing rivet-envoy-client from depot-client is the right fix.
• Strict-mode removal: Replacing the runtime AtomicBool flag with transport-type selection encodes behavior in the type, not runtime state.
• Deduplication: open_database_from_embedded_depot now delegates to open_database_from_transport, removing duplicated VFS registration logic.
• Debug assertions: The new cfg(debug_assertions) checks for pages within db_size_pages are useful for catching correctness bugs in dev.
• decode_serverless_actor_start_payload de-indentation: The function was accidentally nested inside impl EnvoyHandle -- legitimate fix.

Issues

1. Potential unused-variable warnings in release builds

Variables only used inside cfg(debug_assertions) blocks will be unused in release builds:

• db_size_pages in io_read (extracted alongside file_size but only used in the debug block)
• existing_db_size_pages in io_write (only consumed by the debug if let Some(...))
• db_size_pages returned from the tuple in resolve_pages

These will warn (or error under -W warnings) in release/clippy passes. Fix with an _ = discard, allow(unused_variables), or _-prefix on the binding.

2. sqlite_error_reason duplicated across modules

sqlite_error_reason now exists in both depot-client/src/transport.rs (private) and tests/inline/vfs_support.rs. Consider a pub(crate) utility in a shared location.

3. seed_page_as_cold_ref poison byte ordering

Dirty pages prioritize snapshot.pages over fetched_by_pgno. If the poisoned pgno is already in snapshot.pages, the fetched_by_pgno.entry(pgno).or_insert(bytes) inserts the poison bytes but the snapshot copy takes priority -- poison bytes are silently discarded. In practice strict_direct_reopen_ignores_poisoned_mirror_and_reads_depot still passes because DirectDepotTransport never reads mirrors, but the contract of poison_mirror_page is now fragile. A comment clarifying this behavior would help.

4. DirectDepotTransport.commit no longer seeds the mirror

The old non-strict Direct transport called apply_commit after depot commit to update the in-memory mirror. DirectDepotTransport skips this entirely. The new DirectMirrorTransport covers that path, but the divergence should be documented in vfs_support.rs.

5. register_with_transport (test-only) called without initial page fetch for DirectDepotTransport

Tests like direct_engine_marks_vfs_dead_after_transport_errors call the cfg(test)-gated register_with_transport without fetching an initial page, differing from production. Fine for error-injection tests but a comment noting the omission would help.

Minor

• Duplicated debug warning blocks: The db_size_pages mismatch check is copy-pasted for flush and atomic commit paths.
• worker.rs formatting change: Correct but a drive-by unrelated to the core change.
• server.ts diagnostics guard: Defensive and reasonable, but TypeScript should catch missing diagnostics upstream.

Verdict

The core architecture change is correct and the test adaptations are solid. Main actionable items before merge:

1. Address potential unused-variable warnings for db_size_pages / existing_db_size_pages in release builds.
2. Add a comment in seed_page_as_cold_ref about snapshot-priority behavior for poisoned pages.
3. Document the DirectDepotTransport mirror-skip semantics in vfs_support.rs.

The WASM unblocking and transport trait introduction are the right direction.

[NathanFlurry]

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