veryfront 0.1.1243 → 0.1.1244

package/esm/cli/commands/clean/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/clean/command.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvE"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/clean/command.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvE"}

package/esm/cli/commands/clean/command.js

@@ -1,8 +1,9 @@
 import { join } from "../../../src/platform/compat/path/index.js";
 import { getConfig } from "../../../src/config/index.js";
-import { runtime } from "../../../src/platform/index.js";
+import { getEnv, runtime } from "../../../src/platform/index.js";
 import { cliLogger } from "../../utils/index.js";
 import { DEFAULT_CACHE_DIR } from "../../../src/utils/constants/server.js";
+import { getProjectCacheDir } from "../../../src/utils/cache-dir.js";
 import { CacheCoordinator } from "../../../src/rendering/index.js";
 import { FilesystemCacheStore, KVCacheStore, MemoryCacheStore, RedisCacheStore, } from "../../../src/rendering/index.js";
 import { createFileSystem } from "../../../src/platform/index.js";
@@ -52,6 +53,29 @@ async function cleanDirectory(path) {
         cliLogger.error(`Failed to clean directory ${path}:`, error);
     }
 }
+function getFrameworkCacheDirectories(projectDir) {
+    const frameworkRoots = new Set([
+        getProjectCacheDir(projectDir),
+        getEnv("VERYFRONT_CACHE_DIR"),
+        getEnv("VF_CACHE_DIR"),
+    ].filter((root) => !!root));
+    const directories = new Set();
+    for (const root of frameworkRoots) {
+        for (const namespace of [
+            "veryfront-mdx-esm",
+            "veryfront-http-bundle",
+            "veryfront-files",
+            "veryfront-modules",
+            "veryfront-cycle-manifests",
+        ]) {
+            directories.add(join(root, namespace));
+        }
+    }
+    const diskRoot = getEnv("VF_DISK_CACHE_DIR");
+    if (diskRoot)
+        directories.add(join(diskRoot, "veryfront-files"));
+    return [...directories];
+}
 async function cleanCacheStore(projectDir) {
     try {
         const adapter = await runtime.get();
@@ -70,6 +94,11 @@ async function cleanCacheStore(projectDir) {
             await coordinator.destroy();
         }
         await cleanDirectory(join(projectDir, cacheDir));
+        // The framework cache root is separate from the render cache store and
+        // holds the compiled modules a dev server keeps across restarts, so a
+        // cache clean that leaves them in place is not a clean. Remove only
+        // Veryfront-owned directories because other tools can share `.cache`.
+        await Promise.all(getFrameworkCacheDirectories(projectDir).map(cleanDirectory));
     }
     catch (error) {
         cliLogger.error("Failed to clean cache store:", error);

package/esm/cli/commands/dev/command.d.ts

@@ -64,7 +64,7 @@ export declare function startDevServerOnFreePort<T>(requestedPort: number, start
     port: number;
 }>;
 /**
- * Clears the shared on-disk ESM caches, but only if `requestedPort` is free.
+ * Clears the shared on-disk ESM caches, but only if they are safe to remove.
  *
  * The caches live under the project's `.cache` directory, which every dev
  * server rooted at that project shares. A taken dev port is the signal that one
@@ -73,10 +73,15 @@ export declare function startDevServerOnFreePort<T>(requestedPort: number, start
  * the second `veryfront dev` falls forward to a free port and starts on a cache
  * it did not just destroy.
  *
- * Returns whether the clear ran. Takes `clear` and `probe` as parameters so the
- * decision can be tested without booting a dev server, the same seam
- * `startDevServerOnFreePort` uses.
+ * The clear is also skipped when the project keeps a persistent local dev
+ * cache. That cache stores compiled modules that reference these files, so
+ * removing them makes every entry fail validation and turns each restart cold
+ * again. Run `veryfront clean --cache` to reset both.
+ *
+ * Returns whether the clear ran. Takes `clear`, `probe`, and `persists` as
+ * parameters so the decision can be tested without booting a dev server, the
+ * same seam `startDevServerOnFreePort` uses.
  */
-export declare function clearLocalCachesIfPortFree(requestedPort: number, clear?: () => Promise<void>, probe?: (port: number) => Promise<boolean>): Promise<boolean>;
+export declare function clearLocalCachesIfPortFree(requestedPort: number, clear?: () => Promise<void>, probe?: (port: number) => Promise<boolean>, persists?: () => boolean): Promise<boolean>;
 export declare function devCommand(options: DevOptions): Promise<DevCommandResult>;
 //# sourceMappingURL=command.d.ts.map

package/esm/cli/commands/dev/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/dev/command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmBH,OAAO,EAAE,KAAK,YAAY,EAA2B,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE9E,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM1F,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAQD,wBAAsB,cAAc,CAClC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAQvE;AAED,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,GACrB,WAAW,CAEb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,MAAM,OAAO,CAAC,IAAI,CAAuB,EAChD,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAmB,GAC1D,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6TzE"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/dev/command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoBH,OAAO,EAAE,KAAK,YAAY,EAA2B,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE9E,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM1F,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAQD,wBAAsB,cAAc,CAClC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAQvE;AAED,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,GACrB,WAAW,CAEb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBtC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,MAAM,OAAO,CAAC,IAAI,CAAuB,EAChD,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAmB,EAC3D,QAAQ,GAAE,MAAM,OAAuC,GACtD,OAAO,CAAC,OAAO,CAAC,CAKlB;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6TzE"}

package/esm/cli/commands/dev/command.js

@@ -9,6 +9,7 @@ import { getConfig } from "../../../src/config/index.js";
 import { getEnvironmentConfig } from "../../../src/config/index.js";
 import { startDevServer } from "../../../src/server/index.js";
 import { clearAllLocalCaches } from "../../../src/transforms/mdx/esm-module-loader/cache/index.js";
+import { isPersistentLocalCacheEnabled } from "../../../src/cache/index.js";
 import { validateProviderConfig } from "../../../src/discovery/index.js";
 import { brand, devShortcuts, dim, error as errorColor, formatDuration, warning } from "../../ui/index.js";
 import { exitProcess, isTTY, isVerbose, registerTerminationSignals } from "../../utils/index.js";
@@ -79,7 +80,7 @@ export async function startDevServerOnFreePort(requestedPort, start) {
     }
 }
 /**
- * Clears the shared on-disk ESM caches, but only if `requestedPort` is free.
+ * Clears the shared on-disk ESM caches, but only if they are safe to remove.
  *
  * The caches live under the project's `.cache` directory, which every dev
  * server rooted at that project shares. A taken dev port is the signal that one
@@ -88,13 +89,20 @@ export async function startDevServerOnFreePort(requestedPort, start) {
  * the second `veryfront dev` falls forward to a free port and starts on a cache
  * it did not just destroy.
  *
- * Returns whether the clear ran. Takes `clear` and `probe` as parameters so the
- * decision can be tested without booting a dev server, the same seam
- * `startDevServerOnFreePort` uses.
+ * The clear is also skipped when the project keeps a persistent local dev
+ * cache. That cache stores compiled modules that reference these files, so
+ * removing them makes every entry fail validation and turns each restart cold
+ * again. Run `veryfront clean --cache` to reset both.
+ *
+ * Returns whether the clear ran. Takes `clear`, `probe`, and `persists` as
+ * parameters so the decision can be tested without booting a dev server, the
+ * same seam `startDevServerOnFreePort` uses.
  */
-export async function clearLocalCachesIfPortFree(requestedPort, clear = clearAllLocalCaches, probe = isPortAvailable) {
+export async function clearLocalCachesIfPortFree(requestedPort, clear = clearAllLocalCaches, probe = isPortAvailable, persists = isPersistentLocalCacheEnabled) {
     if (!await probe(requestedPort))
         return false;
+    if (persists())
+        return false;
     await clear();
     return true;
 }

package/esm/deno.d.ts

@@ -160,6 +160,7 @@ declare namespace _default {
         "veryfront/utils/import-lockfile": string;
         "veryfront/utils/env-loader": string;
         "veryfront/utils/logger": string;
+        "veryfront/utils/cache-dir": string;
         "veryfront/utils/package-client": string;
         "veryfront/proxy/main": string;
         "veryfront/proxy/handler": string;
@@ -476,6 +477,7 @@ declare namespace _default {
         "lint:skipped-tests": string;
         "lint:cwd-relative-test-reads": string;
         "lint:anti-slop": string;
+        "lint:render-mode-defaults": string;
         "lint:dnt-meta-properties": string;
         "test:scripts": string;
         "test:sentry-runtime-packages": string;

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.1243",
+    "version": "0.1.1244",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "minimumDependencyAge": {
@@ -230,6 +230,7 @@ export default {
         "veryfront/utils/import-lockfile": "./src/utils/import-lockfile.ts",
         "veryfront/utils/env-loader": "./src/utils/env-loader.ts",
         "veryfront/utils/logger": "./src/utils/logger/index.ts",
+        "veryfront/utils/cache-dir": "./src/utils/cache-dir.ts",
         "veryfront/utils/package-client": "./src/utils/package-client.ts",
         "veryfront/proxy/main": "./src/proxy/main.ts",
         "veryfront/proxy/handler": "./src/proxy/handler.ts",
@@ -499,12 +500,12 @@ export default {
         "build:storybook": "npm --prefix storybook run build-storybook",
         "storybook:check": "deno test --no-lock --config=scripts/test.deno.json --no-check --allow-read scripts/storybook/storybook-workbench.test.ts",
         "lint": "DENO_NO_PACKAGE_JSON=1 deno lint && deno lint --config=scripts/test.deno.json scripts/test/ scripts/build/dnt-meta-property-safety.ts scripts/build/dnt-meta-property-safety.test.ts scripts/build/dnt-polyfill.ts scripts/build/dnt-polyfill.test.ts scripts/build/npm-package-metadata.test.ts scripts/build/prepare-framework-sources.test.ts && deno lint --config=scripts/codemods/deno.json scripts/codemods/",
-        "lint:ci": "deno task lint && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:client-bundle && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:secret-scanning-config && deno task lint:skipped-tests && deno task lint:chat-ratchets && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:esm-sh-codemod && deno task lint:test-typecheck && deno task lint:cwd-relative-test-reads && deno task lint:anti-slop && deno task lint:dnt-meta-properties && deno task storybook:check && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:public:check && deno test --frozen --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run=bash scripts/ci/setup-deno-workflow.test.ts scripts/ci/prepare-rc-build.test.ts scripts/build/generated-artifact-checks.test.ts scripts/release.test.ts",
+        "lint:ci": "deno task lint && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:client-bundle && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:secret-scanning-config && deno task lint:skipped-tests && deno task lint:chat-ratchets && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:esm-sh-codemod && deno task lint:test-typecheck && deno task lint:cwd-relative-test-reads && deno task lint:anti-slop && deno task lint:render-mode-defaults && deno task lint:dnt-meta-properties && deno task storybook:check && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:public:check && deno test --frozen --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run=bash scripts/ci/setup-deno-workflow.test.ts scripts/ci/prepare-rc-build.test.ts scripts/build/generated-artifact-checks.test.ts scripts/release.test.ts",
         "fmt": "deno fmt src/ cli/ react/ templates/ && deno fmt --config=scripts/test.deno.json scripts/test/ scripts/build/dnt-meta-property-safety.ts scripts/build/dnt-meta-property-safety.test.ts scripts/build/dnt-polyfill.ts scripts/build/dnt-polyfill.test.ts scripts/build/prepare-framework-sources.test.ts && deno fmt --config=scripts/codemods/deno.json scripts/codemods/",
         "fmt:check": "deno fmt --check src/ cli/ react/ templates/ && deno fmt --check --config=scripts/test.deno.json scripts/test/ scripts/build/dnt-meta-property-safety.ts scripts/build/dnt-meta-property-safety.test.ts scripts/build/dnt-polyfill.ts scripts/build/dnt-polyfill.test.ts scripts/build/prepare-framework-sources.test.ts && deno fmt --check --config=scripts/codemods/deno.json scripts/codemods/",
         "typecheck": "deno task generate:manifests:check && deno check src/index.ts cli/main.ts src/server/index.ts src/routing/api/index.ts src/rendering/index.ts src/platform/index.ts src/platform/adapters/index.ts src/build/index.ts src/build/production-build/index.ts src/transforms/index.ts src/config/index.ts src/utils/index.ts src/data/index.ts src/security/index.ts src/middleware/index.ts src/server/handlers/dev/index.ts src/server/handlers/request/api/index.ts src/rendering/cache/index.ts src/rendering/cache/stores/index.ts src/rendering/rsc/actions/index.ts src/html/index.ts src/html/hydration-script-builder/runtime/main.ts src/modules/index.ts src/proxy/main.ts src/react/components/ui/index.ts src/chat/index.ts src/markdown/index.ts src/mdx/index.ts src/fs/index.ts src/oauth/index.ts src/agent/index.ts src/agent/service/route-export.check.ts src/eval/index.ts src/tool/index.ts src/workflow/index.ts src/prompt/index.ts src/resource/index.ts src/runs/index.ts src/mcp/index.ts src/provider/index.ts",
-        "verify": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:anti-slop && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck && deno task typecheck:consumer && deno task test && deno task test:scripts && deno task test:e2e:binary",
-        "verify:quick": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:anti-slop && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck",
+        "verify": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:anti-slop && deno task lint:render-mode-defaults && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck && deno task typecheck:consumer && deno task test && deno task test:scripts && deno task test:e2e:binary",
+        "verify:quick": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:anti-slop && deno task lint:render-mode-defaults && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck",
         "typecheck:consumer": "deno run --allow-read --allow-run --allow-env --allow-write scripts/typecheck/run-consumer-typecheck.ts",
         "codemod:chat": "deno run --frozen --config=scripts/codemods/deno.json --allow-read --allow-write --allow-env=BABEL_TYPES_8_BREAKING scripts/codemods/migrate-chat-composition.ts",
         "codemod:esm-sh": "deno run --frozen --config=scripts/codemods/deno.json --allow-read --allow-write --allow-env=BABEL_TYPES_8_BREAKING scripts/codemods/migrate-esm-sh-imports.ts",
@@ -552,8 +553,9 @@ export default {
         "lint:skipped-tests": "deno run --allow-read scripts/lint/check-skipped-tests-baseline.ts",
         "lint:cwd-relative-test-reads": "deno run --allow-read scripts/lint/audit-cwd-relative-test-reads.ts",
         "lint:anti-slop": "deno run --allow-read scripts/lint/audit-anti-slop.ts",
+        "lint:render-mode-defaults": "deno run --allow-read scripts/lint/audit-render-mode-defaults.ts",
         "lint:dnt-meta-properties": "deno run --config=scripts/test.deno.json --frozen --allow-read scripts/build/dnt-meta-property-safety.ts",
-        "test:scripts": "deno test --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run scripts/build/feature-files-detection.test.ts scripts/ci/prepare-rc-build.test.ts scripts/ci/publish-npm-packages.test.ts scripts/ci/setup-deno-workflow.test.ts scripts/build/compile-binary.test.ts scripts/build/dnt-meta-property-safety.test.ts scripts/build/dnt-polyfill.test.ts scripts/build/generate-sbom.test.ts scripts/build/generated-artifact-checks.test.ts scripts/build/npm-dependency-sources.test.ts scripts/build/npm-extension-package-metadata.test.ts scripts/build/npm-package-metadata.test.ts scripts/build/npm-react-shims.test.ts scripts/build/npm-runtime-helper-contract.test.ts scripts/build/prepare-framework-sources.test.ts scripts/build/report-artifact-sizes.test.ts scripts/build/run-generate.test.ts scripts/docs/docs-coverage.test.ts scripts/docs/generate-api-reference.test.ts scripts/docs/guide-validation.test.ts scripts/lint/audit-chat-composability.test.ts scripts/lint/audit-rfc-status.test.ts scripts/lint/audit-core-deps.test.ts scripts/lint/audit-cwd-relative-test-reads.test.ts scripts/lint/audit-cross-runtime-jsr.test.ts scripts/lint/audit-dependency-boundaries.test.ts scripts/lint/audit-extension-capabilities.test.ts scripts/lint/audit-extension-contracts.test.ts scripts/lint/audit-deps.test.ts scripts/lint/check-module-boundaries.test.ts scripts/lint/lint-config.test.ts scripts/lint/ban-test-only.test.ts scripts/lint/check-sanitizer-baseline.test.ts scripts/lint/check-skipped-tests-baseline.test.ts scripts/lint/audit-anti-slop.test.ts scripts/lint/check-test-typecheck-baseline.test.ts scripts/lint/check-coverage.test.ts scripts/security/audit-npm.test.ts scripts/security/secret-scanning-config.test.ts scripts/security/submit-dependency-snapshot.test.ts scripts/test/template-runtime-e2e.test.ts && deno task test:tool-search-live",
+        "test:scripts": "deno test --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run scripts/build/feature-files-detection.test.ts scripts/ci/prepare-rc-build.test.ts scripts/ci/publish-npm-packages.test.ts scripts/ci/setup-deno-workflow.test.ts scripts/build/compile-binary.test.ts scripts/build/dnt-meta-property-safety.test.ts scripts/build/dnt-polyfill.test.ts scripts/build/generate-sbom.test.ts scripts/build/generated-artifact-checks.test.ts scripts/build/npm-dependency-sources.test.ts scripts/build/npm-extension-package-metadata.test.ts scripts/build/npm-package-metadata.test.ts scripts/build/npm-react-shims.test.ts scripts/build/npm-runtime-helper-contract.test.ts scripts/build/prepare-framework-sources.test.ts scripts/build/report-artifact-sizes.test.ts scripts/build/run-generate.test.ts scripts/docs/docs-coverage.test.ts scripts/docs/generate-api-reference.test.ts scripts/docs/guide-validation.test.ts scripts/lint/audit-chat-composability.test.ts scripts/lint/audit-rfc-status.test.ts scripts/lint/audit-core-deps.test.ts scripts/lint/audit-cwd-relative-test-reads.test.ts scripts/lint/audit-cross-runtime-jsr.test.ts scripts/lint/audit-dependency-boundaries.test.ts scripts/lint/audit-extension-capabilities.test.ts scripts/lint/audit-extension-contracts.test.ts scripts/lint/audit-deps.test.ts scripts/lint/check-module-boundaries.test.ts scripts/lint/lint-config.test.ts scripts/lint/ban-test-only.test.ts scripts/lint/check-sanitizer-baseline.test.ts scripts/lint/check-skipped-tests-baseline.test.ts scripts/lint/audit-anti-slop.test.ts scripts/lint/audit-render-mode-defaults.test.ts scripts/lint/check-test-typecheck-baseline.test.ts scripts/lint/check-coverage.test.ts scripts/security/audit-npm.test.ts scripts/security/secret-scanning-config.test.ts scripts/security/submit-dependency-snapshot.test.ts scripts/test/template-runtime-e2e.test.ts && deno task test:tool-search-live",
         "test:sentry-runtime-packages": "deno test --config=scripts/test.deno.json --no-check --no-lock --allow-read --allow-write --allow-run --allow-env=DENO_DIR,HOME,XDG_CACHE_HOME,LOCALAPPDATA,USERPROFILE scripts/build/sentry-runtime-packages.test.ts",
         "test:tool-search-live": "VF_DISABLE_LRU_INTERVAL=1 deno test --no-check -A tests/agent/verify-tool-search-live.test.ts",
         "test:cross-runtime": "deno run --allow-all src/platform/compat/cross-runtime.test.ts",

package/esm/src/cache/backend.d.ts

@@ -10,7 +10,7 @@
  *
  * @module cache/backend
  */
-export { ApiCacheBackend, type CacheBackendConfig, CacheBackends, createCacheBackend, createDistributedCacheAccessor, createDistributedCodeCacheAccessor, createTokenizingGateway, isApiCacheAvailable, isDiskCacheConfigured, isDistributedBackend, MemoryCacheBackend, RedisCacheBackend, } from "./backends/index.js";
+export { ApiCacheBackend, type CacheBackendConfig, CacheBackends, createCacheBackend, createDistributedCacheAccessor, createDistributedCodeCacheAccessor, createTokenizingGateway, isApiCacheAvailable, isDiskCacheConfigured, isDistributedBackend, isLocalDevDiskCacheEnabled, isPersistentLocalCacheEnabled, localDevCodeCacheBackend, MemoryCacheBackend, RedisCacheBackend, } from "./backends/index.js";
 export { assertCacheReadMaximumBytes, assertCacheValueWithinLimit, CacheValueTooLargeError, captureBoundedCacheRead, readCacheValueWithinLimit, } from "./bounded-read.js";
 export { buildRevisionedCacheKey, isRevisionedCacheBackend, isRevisionedCacheKey, MAX_REVISIONED_CACHE_SOURCE_KEY_LENGTH, requireCacheExchangeResult, REVISIONED_CACHE_KEY_PREFIX, snapshotCacheRevisionResult, } from "./capabilities.js";
 export { MAX_CACHE_REVISION_LENGTH } from "./types.js";

package/esm/src/cache/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/src/cache/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,EACvB,aAAa,EACb,kBAAkB,EAClB,8BAA8B,EAC9B,kCAAkC,EAClC,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,sCAAsC,EACtC,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/src/cache/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,EACvB,aAAa,EACb,kBAAkB,EAClB,8BAA8B,EAC9B,kCAAkC,EAClC,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,sCAAsC,EACtC,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC"}

package/esm/src/cache/backend.js

@@ -11,7 +11,7 @@
  * @module cache/backend
  */
 // Re-export everything from the backends barrel
-export { ApiCacheBackend, CacheBackends, createCacheBackend, createDistributedCacheAccessor, createDistributedCodeCacheAccessor, createTokenizingGateway, isApiCacheAvailable, isDiskCacheConfigured, isDistributedBackend, MemoryCacheBackend, RedisCacheBackend, } from "./backends/index.js";
+export { ApiCacheBackend, CacheBackends, createCacheBackend, createDistributedCacheAccessor, createDistributedCodeCacheAccessor, createTokenizingGateway, isApiCacheAvailable, isDiskCacheConfigured, isDistributedBackend, isLocalDevDiskCacheEnabled, isPersistentLocalCacheEnabled, localDevCodeCacheBackend, MemoryCacheBackend, RedisCacheBackend, } from "./backends/index.js";
 export { assertCacheReadMaximumBytes, assertCacheValueWithinLimit, CacheValueTooLargeError, captureBoundedCacheRead, readCacheValueWithinLimit, } from "./bounded-read.js";
 export { buildRevisionedCacheKey, isRevisionedCacheBackend, isRevisionedCacheKey, MAX_REVISIONED_CACHE_SOURCE_KEY_LENGTH, requireCacheExchangeResult, REVISIONED_CACHE_KEY_PREFIX, snapshotCacheRevisionResult, } from "./capabilities.js";
 // Re-export types

package/esm/src/cache/backends/disk.d.ts

@@ -17,12 +17,35 @@ export declare class DiskCacheBackend implements CacheBackend {
     private readonly maxValueBytes;
     private readonly maxFileBytes;
     private mutationTail;
+    private writesUntilExpiryPrune;
+    private expiryPruneOffset;
     constructor(baseDir?: string, keyPrefix?: string, maxValueBytes?: number);
     private filePath;
     private ensureDir;
     private withMutation;
     private readFramedFile;
     private readEnvelopeWithinValueLimit;
+    /**
+     * Remove a cache file, but only while it still holds the expired entry.
+     *
+     * Dev servers and build steps share a project cache, so another process can
+     * replace the pathname between the expiry check and the deletion. Deleting by
+     * pathname would then remove that fresh entry. The file is claimed with an
+     * atomic rename and revalidated on the claimed inode instead, and a claim
+     * that turns out to hold a fresh entry is linked back under its original
+     * name. Both the write-time sweep and the read-time cleanup go through this,
+     * so neither can delete a write that won the race.
+     */
+    private removeExpiredEntryFile;
+    /**
+     * Drop an entry a read found expired.
+     *
+     * Queued on the mutation tail so it cannot interleave with this instance's
+     * own writes, and so a caller can flush it by awaiting any later operation.
+     */
+    private expireEntry;
+    private pruneExpiredEntries;
+    private maybePruneExpiredEntries;
     get(key: string): Promise<string | null>;
     getWithinLimit(key: string, maximumBytes: number): Promise<string | null>;
     getRemainingTtlSeconds(key: string): Promise<number | null>;

package/esm/src/cache/backends/disk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../../../src/src/cache/backends/disk.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAqShD;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,YAAY,CAAoC;gBAGtD,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,SAA0B;YAc3B,QAAQ;YAIR,SAAS;YAKT,YAAY;YAcZ,cAAc;YAyEd,4BAA4B;IAoBpC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAsCxC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAyBzE,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/B,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAqDrD"}
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../../../src/src/cache/backends/disk.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuShD;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,sBAAsB,CAAK;IACnC,OAAO,CAAC,iBAAiB,CAAK;gBAG5B,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,SAA0B;YAc3B,QAAQ;YAIR,SAAS;YAKT,YAAY;YAcZ,cAAc;YAyEd,4BAA4B;IAoB1C;;;;;;;;;;OAUG;YACW,sBAAsB;IAkCpC;;;;;OAKG;IACH,OAAO,CAAC,WAAW;YAML,mBAAmB;YA+BnB,wBAAwB;IAShC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAsCxC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAyBzE,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/B,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAqDrD"}

package/esm/src/cache/backends/disk.js

@@ -14,6 +14,8 @@ const MAX_CACHE_KEY_CODE_UNITS = 64 * 1024;
 const KEY_DIGEST_LOG_CHARS = 12;
 const MAX_CACHE_NAMESPACE_BYTES = 240;
 const MAX_DIRECTORY_SCAN_ENTRIES = 100_000;
+const EXPIRY_PRUNE_BATCH_SIZE = 256;
+const EXPIRY_PRUNE_WRITE_INTERVAL = 32;
 const DEFAULT_MAX_VALUE_BYTES = 64 * 1024 * 1024;
 const MAX_CONFIGURED_VALUE_BYTES = 512 * 1024 * 1024;
 const FRAME_HEADER_BYTES = 40;
@@ -261,6 +263,8 @@ export class DiskCacheBackend {
     maxValueBytes;
     maxFileBytes;
     mutationTail = Promise.resolve();
+    writesUntilExpiryPrune = 1;
+    expiryPruneOffset = 0;
     constructor(baseDir, keyPrefix, maxValueBytes = DEFAULT_MAX_VALUE_BYTES) {
         const base = join(baseDir ?? getCacheBaseDir(), CACHE_SUBDIR);
         this.dir = keyPrefix ? join(base, encodeCacheNamespace(keyPrefix)) : base;
@@ -362,6 +366,105 @@ export class DiskCacheBackend {
             throw error;
         }
     }
+    /**
+     * Remove a cache file, but only while it still holds the expired entry.
+     *
+     * Dev servers and build steps share a project cache, so another process can
+     * replace the pathname between the expiry check and the deletion. Deleting by
+     * pathname would then remove that fresh entry. The file is claimed with an
+     * atomic rename and revalidated on the claimed inode instead, and a claim
+     * that turns out to hold a fresh entry is linked back under its original
+     * name. Both the write-time sweep and the read-time cleanup go through this,
+     * so neither can delete a write that won the race.
+     */
+    async removeExpiredEntryFile(filePath) {
+        const { link, rename, unlink } = await fsPromises;
+        const claimPath = `${filePath}.prune.${dntShim.crypto.randomUUID()}`;
+        try {
+            await rename(filePath, claimPath);
+        }
+        catch {
+            // Another process already replaced or removed the entry.
+            return;
+        }
+        let restoreClaim = true;
+        try {
+            const claimed = await this.readFramedFile(claimPath, undefined, undefined, false);
+            if (claimed.expiresAt !== undefined && Date.now() >= claimed.expiresAt) {
+                await unlink(claimPath);
+                restoreClaim = false;
+            }
+        }
+        catch {
+            // An unreadable claim is restored rather than deleted: the pathname may
+            // now hold a fresh entry this process never validated.
+        }
+        if (!restoreClaim)
+            return;
+        let discardClaim = false;
+        try {
+            await link(claimPath, filePath);
+            discardClaim = true;
+        }
+        catch (error) {
+            // A newer writer already owns the pathname, so its entry wins.
+            if (error.code === "EEXIST")
+                discardClaim = true;
+        }
+        if (discardClaim)
+            await unlink(claimPath).catch(() => { });
+    }
+    /**
+     * Drop an entry a read found expired.
+     *
+     * Queued on the mutation tail so it cannot interleave with this instance's
+     * own writes, and so a caller can flush it by awaiting any later operation.
+     */
+    expireEntry(key) {
+        return this.withMutation(async () => {
+            await this.removeExpiredEntryFile(await this.filePath(key));
+        });
+    }
+    async pruneExpiredEntries() {
+        const { opendir } = await fsPromises;
+        const directory = await opendir(this.dir);
+        let scanned = 0;
+        let eligible = 0;
+        let processed = 0;
+        for await (const entry of directory) {
+            scanned++;
+            if (scanned > MAX_DIRECTORY_SCAN_ENTRIES)
+                break;
+            if (!entry.isFile() || !CACHE_FILE_PATTERN.test(entry.name))
+                continue;
+            if (eligible++ < this.expiryPruneOffset)
+                continue;
+            if (processed >= EXPIRY_PRUNE_BATCH_SIZE)
+                break;
+            processed++;
+            const filePath = join(this.dir, entry.name);
+            try {
+                const envelope = await this.readFramedFile(filePath, undefined, undefined, false);
+                if (envelope.expiresAt !== undefined && Date.now() >= envelope.expiresAt) {
+                    await this.removeExpiredEntryFile(filePath);
+                }
+            }
+            catch {
+                // Cache files are disposable and may be replaced by another process.
+            }
+        }
+        this.expiryPruneOffset = processed < EXPIRY_PRUNE_BATCH_SIZE
+            ? 0
+            : this.expiryPruneOffset + processed;
+    }
+    async maybePruneExpiredEntries() {
+        if (this.writesUntilExpiryPrune > 0) {
+            this.writesUntilExpiryPrune--;
+            return;
+        }
+        this.writesUntilExpiryPrune = EXPIRY_PRUNE_WRITE_INTERVAL - 1;
+        await this.pruneExpiredEntries();
+    }
     async get(key) {
         try {
             await this.mutationTail;
@@ -380,7 +483,7 @@ export class DiskCacheBackend {
                 return null;
             }
             if (envelope.expiresAt !== undefined && Date.now() >= envelope.expiresAt) {
-                this.del(key).catch(async (cleanupError) => {
+                this.expireEntry(key).catch(async (cleanupError) => {
                     logger.debug("[DiskCache] Expired entry cleanup failed", {
                         keyDigest: await logKeyDigest(key),
                         error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
@@ -409,7 +512,7 @@ export class DiskCacheBackend {
             if (!envelope || envelope.key !== key)
                 return null;
             if (envelope.expiresAt !== undefined && Date.now() >= envelope.expiresAt) {
-                void this.del(key);
+                void this.expireEntry(key);
                 return null;
             }
             if (envelope.value === undefined)
@@ -470,6 +573,8 @@ export class DiskCacheBackend {
             const { writeFile, rename, unlink } = await fsPromises;
             try {
                 await writeFile(tmpPath, content, { flag: "wx", mode: 0o600 });
+                // This atomic replacement is also the commit point used by expiry
+                // pruning. The pruner claims and revalidates whichever entry wins it.
                 await rename(tmpPath, filePath);
             }
             catch (error) {
@@ -480,6 +585,11 @@ export class DiskCacheBackend {
                 });
                 throw error;
             }
+            await this.maybePruneExpiredEntries().catch((error) => {
+                logger.debug("[DiskCache] Expired entry pruning failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
         });
     }
     async del(key) {

package/esm/src/cache/backends/factory.d.ts

@@ -10,9 +10,38 @@ export interface CacheBackendConfig {
 }
 export declare function isApiCacheAvailable(): boolean;
 export declare function isDiskCacheConfigured(): boolean;
+/**
+ * Whether a local dev server must keep compiled code on disk.
+ *
+ * A local dev server has no hosted API cache and no Redis, so its code caches
+ * live in memory and every restart recompiles the whole import tree. The disk
+ * backend keeps that work under the project cache directory, so a restart
+ * stays warm with no setup.
+ *
+ * This never changes a hosted or production runtime: the API and Redis
+ * backends are resolved first, an explicit `VF_CACHE_BACKEND` always wins, and
+ * anything other than a development environment keeps its current backend.
+ */
+export declare function isLocalDevDiskCacheEnabled(): boolean;
+/**
+ * Whether this runtime has a cache that outlives the process.
+ *
+ * Servers use this to decide whether to run the distributed-cache
+ * initializers at startup. Without initialization the SSR module cache stays
+ * disabled and the loader skips both reads and writes, so a gate that only
+ * checks the explicit disk configuration leaves the local dev cache inert.
+ */
+export declare function isPersistentLocalCacheEnabled(): boolean;
+/**
+ * Backend preference for caches that hold compiled code.
+ *
+ * Returns `undefined` outside local dev so the normal API, Redis, disk, memory
+ * resolution order applies unchanged.
+ */
+export declare function localDevCodeCacheBackend(): CacheBackendConfig["preferredBackend"];
 export declare function createCacheBackend(config?: CacheBackendConfig): Promise<CacheBackend>;
 export declare function isDistributedBackend(backend: CacheBackend): boolean;
-export declare function createDistributedCacheAccessor(factory: () => Promise<CacheBackend>, name: string): () => Promise<CacheBackend | null>;
+export declare function createDistributedCacheAccessor(factory: () => Promise<CacheBackend>, name: string, getScopeKey?: () => string): () => Promise<CacheBackend | null>;
 export declare const CacheBackends: {
     transform: () => Promise<CacheBackend>;
     file: () => Promise<CacheBackend>;
@@ -41,6 +70,6 @@ export declare const CacheBackends: {
  * Create a distributed cache accessor that returns a TokenizingCacheGateway.
  * This wraps createDistributedCacheAccessor with automatic gateway creation.
  */
-export declare function createDistributedCodeCacheAccessor(factory: () => Promise<CacheBackend>, name: string): () => Promise<TokenizingCacheGateway | null>;
+export declare function createDistributedCodeCacheAccessor(factory: () => Promise<CacheBackend>, name: string, getScopeKey?: () => string): () => Promise<TokenizingCacheGateway | null>;
 export { createTokenizingGateway };
 //# sourceMappingURL=factory.d.ts.map

package/esm/src/cache/backends/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/src/cache/backends/factory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,KAAK,gBAAgB,EACrB,uBAAuB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,0BAA0B,CAAC;AAWlC,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAU7C;AAED,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC,CAiDzF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAEnE;AAID,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACpC,IAAI,EAAE,MAAM,GACX,MAAM,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA+CpC;AAED,eAAO,MAAM,aAAa;;;;;;;;;IAWxB;;;;;;;;;;;;OAYG;sBAEK,MAAM,WACJ,kBAAkB,KACzB,OAAO,CAAC,sBAAsB,CAAC;CAInC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACpC,IAAI,EAAE,MAAM,GACX,MAAM,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAQ9C;AAGD,OAAO,EAAE,uBAAuB,EAAE,CAAC"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/src/cache/backends/factory.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,KAAK,gBAAgB,EACrB,uBAAuB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,0BAA0B,CAAC;AAWlC,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAU7C;AAED,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAGpD;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,CAAC,kBAAkB,CAAC,CASjF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC,CAiDzF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAEnE;AAWD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,MAAM,GACzB,MAAM,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA0DpC;AAED,eAAO,MAAM,aAAa;;;;;;;;;IAgBxB;;;;;;;;;;;;OAYG;sBAEK,MAAM,WACJ,kBAAkB,KACzB,OAAO,CAAC,sBAAsB,CAAC;CAInC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,MAAM,GACzB,MAAM,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAQ9C;AAGD,OAAO,EAAE,uBAAuB,EAAE,CAAC"}