fix(sqlite): disable incomplete preload hint flush

[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

• fix(sqlite): disable incomplete preload hint flush #4895 👈 (View in Graphite)
• fix(sqlite): avoid nested runtime during vfs register #4894
• chore(driver-test-runner): add native/wasm runtime matrix to skill #4884 : 3 other dependent PRs (#4892 , #4896 , #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]

Code Review: fix(sqlite): disable incomplete preload hint flush

Overview

This PR disables the SQLite preload hint flush feature by gutting the implementations of enqueue_preload_hint_flush_best_effort and flush_preload_hints_best_effort, making metrics() always return None, and removing the now-unused snapshot_preload_hints, protocol_preload_hints, VfsPreloadHintSnapshot import, and timeout import. The stated reason is that depot_client does not yet expose a stable NativeDatabaseHandle::sqlite_vfs_metrics surface.

This is a legitimate "disable while unblocked" approach. The changes are safe and remove ~150 lines of code that could not work anyway. A few things worth addressing before this lands:

---

Issues

1. Background task still spawns and ticks every 30 s when the flag is enabled

ensure_preload_hint_flush_task (line 367) guards on sqlite_optimization_flags().preload_hint_flush. If that flag is off the task is never spawned. But if it is on, a tokio::spawn fires every PRELOAD_HINT_FLUSH_INTERVAL to call an empty function. Consider making ensure_preload_hint_flush_task return early unconditionally until the feature is ready, so the flag cannot accidentally spin up a no-op timer.

2. PRELOAD_HINT_FLUSH_INTERVAL drives a no-op loop

The constant is still referenced in the active interval loop, so it is not dead code in the compiler sense, but it semantically controls nothing. A reader who sees the constant and the loop without noticing the empty called functions will be confused. A short inline comment on the constant noting it is disabled would help.

3. Empty stub functions with _-prefixed parameters is an unusual pattern

Underscored parameters are typically used to silence warnings inside a real body, not to mark a placeholder. Two cleaner options: (a) remove the stub functions entirely and comment out their call sites, or (b) add a one-line comment inside each body such as // Disabled: waiting for depot-client stable surface.

4. No deferred work item tracked

The comment on metrics() explains why it is disabled, but per project convention deferred work should have an entry in .agent/todo/. A small file noting what needs to happen in depot_client before this can be re-enabled would make the follow-up findable.

---

What is Good

• Import cleanup (timeout, VfsPreloadHintSnapshot) is correct and tight.
• PRELOAD_HINT_FLUSH_TIMEOUT constant was cleanly removed since it is no longer used.
• The explanatory comment on metrics() is appreciated over a silent None.
• Helper functions snapshot_preload_hints and protocol_preload_hints were fully deleted rather than left as dead code.