Proof of concept: task eviction after snapshot for turbo-tasks-backend (#91790)

> **Note:** This is a **proof of concept** implementation. It is not yet
ready for production use.

## Summary

Implements memory eviction for the turbo-tasks engine. After a
persistence snapshot completes, tasks that are safe to remove are
evicted from in-memory storage and transparently restored from disk on
next access.

### Eviction levels

- **Full eviction**: Entire task removed from the in-memory map
(restored from disk on access). Only possible when the task has no
meaningful transient state (and other state is already on disk)
- **DataAndMeta eviction**: Both data and meta categories cleared, but
the task stays in the map to preserve transient state (e.g.
`current_session_clean`, aggregated session-clean counts).
- **DataOnly eviction**: Only data-category fields cleared; meta (graph
structure, output, dirty state) stays in memory.
- **MetaOnly eviction**: Only meta-category fields cleared; data stays
in memory.

Data and meta evictability are computed independently — if one category
is modified but the other is clean, the clean category can still be
dropped.

Eviction is gated behind `BackendOptions::evict_after_snapshot` (off by
default), and can be enabled in Next.js via the
`TURBO_ENGINE_EVICT_AFTER_SNAPSHOT=1` env var for testing.

## Key changes

- **Orthogonal eviction decision tree** (`storage_schema.rs`): Data and
meta evictability are computed independently. Full eviction additionally
requires no meaningful transient state (session-clean flags, aggregated
session-clean counts). Replaces the previous sequential bail-out
approach which was too aggressive on full eviction (losing transient
session state on leaf tasks) and not aggressive enough on partial
eviction (blocking all eviction when only one category was modified).

- **`drop_partial()` codegen** (`task_storage_macro.rs`): New generated
methods to drop data

- **`restore_from_*()` codegen changes** (`task_storage_macro.rs`): New
semantics for merging persistent data from the backend with transient
data stored in memory.

- **`task_cache` moved into `Storage`** (`storage.rs`): The
`CachedTaskType → TaskId` deduplication map was previously a separate
field on `TurboTasksBackendInner`. It is now owned by `Storage` so
eviction can remove entries when a task is fully evicted. Because
`task_cache` is a pure performance cache (entries are re-populated by
`task_by_type()` on miss once the task type is persisted to backing
storage), evicting entries is safe. After bulk eviction the map is
shrunk when it is less than half full.

- **Parallel shard eviction** (`storage.rs`): Eviction iterates all
storage shards in parallel after snapshot, applying the appropriate
eviction level per task. Each shard is shrunk after bulk eviction to
reclaim slack capacity.
- In principle this is O(N) work to scan, but because each pass drops
>98% of tasks there isn't wasted work and the logic is fast, taking
<100ms for even the largest applications.


## Design notes

- **SessionDependent tasks**: SessionDependent tasks can still be
evicted but if `current_session_clean` is set we prevent full eviction
to avoid rechecking. Within a session the file-watchers are responsible
for invalidations after setting `current_session_clean`.

## Known limitations (proof of concept)

- No LRU or access-frequency tracking — all eligible tasks are evicted
on every snapshot cycle
- No memory pressure feedback — eviction runs on a timer, not in
response to actual memory pressure
- Only runs after snapshotting which tends to be a high point in memory
- Future work will explore interleaving this logic with snapshotting to
trim the peak



<!-- NEXT_JS_LLM_PR -->

Author: lukesandberg

Cargo.lock

@@ -1495,8 +1495,8 @@ impl Project {
 
     /// Computes the whole app module graph without dropping issues.
     ///
-    /// Use this instead of [`whole_app_module_graphs`] when you need to collect issues from the
-    /// computation (e.g. for the `get_compilation_issues` MCP tool).
+    /// Use this instead of [Self::whole_app_module_graphs] when you need to collect issues from
+    /// the computation (e.g. for the `get_compilation_issues` MCP tool).
     #[turbo_tasks::function]
     pub async fn whole_app_module_graphs_without_dropping_issues(
         self: ResolvedVc<Self>,

crates/next-api/src/project.rs

@@ -256,6 +256,8 @@ pub fn create_turbo_tasks(
                 }),
                 dependency_tracking,
                 num_workers: Some(tokio::runtime::Handle::current().metrics().num_workers()),
+                evict_after_snapshot: std::env::var("TURBO_ENGINE_EVICT_AFTER_SNAPSHOT")
+                    .is_ok_and(|v| v == "1" || v == "true"),
                 ..Default::default()
             },
             Either::Left(backing_storage),

crates/next-napi-bindings/src/next_api/turbopack_ctx.rs

@@ -0,0 +1,91 @@
+import { nextTestSetup, isNextDev } from 'e2e-utils'
+import { retry, waitFor } from 'next-test-utils'
+
+// Eviction requires the dev server (HMR) and persistent caching (Turbopack).
+// Skip entirely in prod/start mode.
+;(isNextDev ? describe : describe.skip)('evict-after-snapshot', () => {
+  const envVars = [
+    'ENABLE_CACHING=1',
+    'TURBO_ENGINE_IGNORE_DIRTY=1',
+    'TURBO_ENGINE_SNAPSHOT_IDLE_TIMEOUT_MILLIS=1000',
+    'TURBO_ENGINE_EVICT_AFTER_SNAPSHOT=1',
+  ].join(' ')
+
+  const { skipped, next } = nextTestSetup({
+    files: __dirname,
+    skipDeployment: true,
+    packageJson: {
+      scripts: {
+        dev: `${envVars} next dev`,
+      },
+    },
+    installCommand: 'npm i',
+    startCommand: 'npm run dev',
+  })
+
+  if (skipped) {
+    return
+  }
+
+  async function waitForSnapshotAndEviction() {
+    // The idle timeout is 1s, give extra time for snapshot + eviction to complete
+    await waitFor(5000)
+  }
+
+  // Turbopack-only: eviction requires persistent caching
+  ;(process.env.IS_TURBOPACK_TEST ? it : it.skip)(
+    'should serve correct content after eviction and HMR',
+    async () => {
+      const browser = await next.browser('/')
+      await retry(async () => {
+        expect(await browser.elementByCss('p').text()).toBe('hello world')
+      })
+
+      let currentContent = 'hello world'
+      for (let cycle = 1; cycle <= 3; cycle++) {
+        await waitForSnapshotAndEviction()
+
+        const prevContent = currentContent
+        const nextContent = `cycle ${cycle}`
+        await next.patchFile('app/page.tsx', (content) =>
+          content.replace(prevContent, nextContent)
+        )
+        currentContent = nextContent
+
+        const expected = currentContent
+        await retry(async () => {
+          expect(await browser.elementByCss('p').text()).toBe(expected)
+        }, 10000)
+      }
+
+      await browser.close()
+    },
+    90000
+  )
+  ;(process.env.IS_TURBOPACK_TEST ? it : it.skip)(
+    'should handle client component HMR after eviction',
+    async () => {
+      const browser = await next.browser('/client')
+      await retry(async () => {
+        expect(await browser.elementByCss('p').text()).toBe('hello world')
+      })
+
+      await waitForSnapshotAndEviction()
+
+      await next.patchFile(
+        'app/client/page.tsx',
+        (content) => content.replace('hello world', 'hello eviction'),
+        async () => {
+          await retry(async () => {
+            expect(await browser.elementByCss('p').text()).toBe(
+              'hello eviction'
+            )
+          }, 10000)
+        }
+      )
+
+      await browser.close()
+    },
+    90000
+  )
+})

test/e2e/filesystem-cache/evict-after-snapshot.test.ts

@@ -619,8 +619,7 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES>
 
     /// Clears all caches of the database.
     pub fn clear_cache(&self) {
-        self.key_block_cache.clear();
-        self.value_block_cache.clear();
+        self.clear_block_caches();
         for meta in self.inner.write().meta_files.iter_mut() {
             meta.clear_cache();
         }

turbopack/crates/turbo-persistence/src/db.rs

@@ -97,6 +97,14 @@ impl<K: Hash + Eq, H: BuildHasher + Default, const I: usize> AutoSet<K, H, I> {
     pub fn contains(&self, key: &K) -> bool {
         self.map.contains_key(key)
     }
+
+    /// see [HashSet::retain](https://doc.rust-lang.org/std/collections/hash_set/struct.HashSet.html#method.retain)
+    pub fn retain<F>(&mut self, mut f: F)
+    where
+        F: FnMut(&K) -> bool,
+    {
+        self.map.retain(|k, _| f(k));
+    }
 }
 
 impl<K, H, const I: usize> AutoSet<K, H, I> {

turbopack/crates/turbo-tasks-auto-hash-map/src/set.rs

@@ -60,6 +60,7 @@ turbo-persistence = { workspace = true }
 turbo-rcstr = { workspace = true }
 turbo-tasks = { workspace = true }
 turbo-tasks-hash = { workspace = true }
+turbo-tasks-malloc = { workspace = true, default-features = false }
 thread_local = { workspace = true }
 
 [dev-dependencies]
@@ -68,6 +69,7 @@ futures = { workspace = true }
 indoc = { workspace = true }
 regex = { workspace = true }
 tempfile = { workspace = true }
+triomphe = { workspace = true }
 turbo-tasks-malloc = { workspace = true }
 rstest = { workspace = true }
 turbo-tasks-testing = { workspace = true }