Performance improvements to cache

.github/workflows/benchmarks.yml

@@ -0,0 +1,66 @@
+name: Cache Benchmarks
+
+on:
+    pull_request:
+        paths:
+            - 'packages/houdini/src/runtime/cache/**'
+
+jobs:
+    benchmark:
+        name: Benchmark
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 24.9.0
+
+            - uses: pnpm/action-setup@v4.1.0
+
+            - name: Get pnpm store directory
+              id: pnpm-cache
+              run: echo "dir=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+            - uses: actions/cache@v4
+              with:
+                  path: ${{ steps.pnpm-cache.outputs.dir }}
+                  key: pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+                  restore-keys: pnpm-
+
+            # ── PR branch ────────────────────────────────────────────────────
+            - run: pnpm install --frozen-lockfile --prefer-offline
+
+            - name: Benchmark PR branch
+              run: BENCH_MAX_N=1000 npx vitest bench packages/houdini/src/runtime/cache/benchmarks/ --outputJson /tmp/benchmark.current.json
+
+            # ── Base branch ──────────────────────────────────────────────────
+            - name: Save benchmark suite from PR
+              run: cp -r packages/houdini/src/runtime/cache/benchmarks /tmp/houdini-benchmarks
+
+            - name: Checkout base branch
+              run: git checkout ${{ github.base_ref }}
+
+            - name: Restore benchmark suite onto base branch
+              run: |
+                  mkdir -p packages/houdini/src/runtime/cache/benchmarks
+                  cp -r /tmp/houdini-benchmarks/. packages/houdini/src/runtime/cache/benchmarks/
+
+            - run: pnpm install --frozen-lockfile --prefer-offline
+
+            - name: Benchmark base branch
+              run: BENCH_MAX_N=1000 npx vitest bench packages/houdini/src/runtime/cache/benchmarks/ --outputJson /tmp/benchmark.baseline.json
+
+            # ── Compare ──────────────────────────────────────────────────────
+            - name: Checkout PR branch
+              run: |
+                  git stash --include-untracked
+                  git checkout ${{ github.head_ref }}
+
+            - name: Compare
+              run: node perf/compare.js /tmp/benchmark.baseline.json /tmp/benchmark.current.json

.gitignore

@@ -27,3 +27,7 @@ vite.config.*.timestamp-*
 .netlify
 
 mise.toml
+
+# Benchmark outputs — only benchmark.json (the full baseline) is committed
+perf/benchmark.*.json
+perf/benchmark.quick.json

docs/shared/03-meta/03-contributing.mdx

@@ -109,6 +109,26 @@ pnpm compile:react     # recompile houdini-react only (react app)
 
 Each of these has `:dev`, `:generate`, and `:dev` suffixes that chain into the next step after compiling.
 
+### Cache benchmarks
+
+The cache has a benchmark suite in `packages/houdini/src/runtime/cache/benchmarks/`. Benchmarks are grouped into categories (`core`, `subscriptions`, `lists`, `multi-doc`, `optimistic`, `gc`, `ssr`) and can be run selectively.
+
+For active work on the cache, `watch-bench` re-runs a category in fast mode (minimal iterations, just enough to catch regressions) every time a file changes:
+
+```sh
+pnpm watch-bench gc          # re-run gc suite on every save
+pnpm watch-bench core        # re-run core suite on every save
+```
+
+To run the full suite at full statistical precision:
+
+```sh
+pnpm bench                        # all categories, full run
+BENCH=core pnpm bench             # single category, full run
+```
+
+A CI job runs automatically on any PR that touches `packages/houdini/src/runtime/cache/`. It benchmarks the base branch and the PR branch on the same runner and flags any benchmark that regressed beyond its noise band.
+
 ## Piecing It All Together
 
 When thinking about adding a feature, a few questions help frame the work:

package.json

@@ -8,6 +8,10 @@
 		"tests": "vitest",
 		"tests:ui": "vitest --ui --coverage",
 		"test": "pnpm run tests",
+		"bench": "vitest bench packages/houdini/src/runtime/cache/benchmarks/ --outputJson perf/benchmark.json",
+		"bench:check": "vitest bench packages/houdini/src/runtime/cache/benchmarks/ --outputJson perf/benchmark.current.json && node perf/compare.js",
+		"bench:quick": "BENCH_QUICK=1 vitest bench packages/houdini/src/runtime/cache/benchmarks/ --outputJson perf/benchmark.quick.json",
+		"watch-bench": "sh perf/watch-bench.sh",
 		"build:all": "turbo build",
 		"build": "turbo run build --filter=\"./packages/*\"",
 		"dev": "turbo dev --filter=\"./packages/*\"",