feat(cache): add opt-in dependency snapshot store provider

src/cache/backends/factory.ts

@@ -149,6 +149,22 @@
 const DISTRIBUTED_CACHE_RETRY_MS = 30_000;
 const MAX_DISTRIBUTED_CACHE_SCOPES = 128;
 
+// Captured before project code runs: accessor state holds private backend
+// objects, and replaced collection or promise prototype methods must never
+// observe them (see docs/architecture/15-runtime-adapters.md on the opaque
+// snapshot-store handle this accessor can sit behind).
+const accessorApply = Reflect.apply;
+const AccessorMap = Map;
+const accessorMapGet = AccessorMap.prototype.get;
+const accessorMapSet = AccessorMap.prototype.set;
+const accessorMapDelete = AccessorMap.prototype.delete;
+const accessorMapKeys = AccessorMap.prototype.keys;
+const accessorMapSize = Object.getOwnPropertyDescriptor(AccessorMap.prototype, "size")!.get!;
+const accessorMapIteratorNext = Object.getPrototypeOf(new AccessorMap<string, unknown>().keys())
+  .next as () => IteratorResult<string>;
+const AccessorPromise = Promise;
+const accessorPromiseResolve = AccessorPromise.resolve;
+
 interface DistributedCacheAccessorState {
   backend: CacheBackend | null | undefined;
   lastFailureTime: number;
@@ -160,21 +176,27 @@
   name: string,
   getScopeKey?: () => string,
 ): () => Promise<CacheBackend | null> {
-  const states = new Map<string, DistributedCacheAccessorState>();
+  const states = new AccessorMap<string, DistributedCacheAccessorState>();
 
   return () => {
     const scopeKey = getScopeKey?.() ?? "";
-    let state = states.get(scopeKey);
+    let state = accessorApply(accessorMapGet, states, [scopeKey]) as
+      | DistributedCacheAccessorState
+      | undefined;
     if (!state) {
-      if (states.size >= MAX_DISTRIBUTED_CACHE_SCOPES) {
-        const leastRecentlyUsedScope = states.keys().next().value as string | undefined;
-        if (leastRecentlyUsedScope !== undefined) states.delete(leastRecentlyUsedScope);
+      if (accessorApply(accessorMapSize, states, []) >= MAX_DISTRIBUTED_CACHE_SCOPES) {
+        const iterator = accessorApply(accessorMapKeys, states, []);
+        const leastRecentlyUsedScope = accessorApply(accessorMapIteratorNext, iterator, [])
+          .value as string | undefined;
+        if (leastRecentlyUsedScope !== undefined) {
+          accessorApply(accessorMapDelete, states, [leastRecentlyUsedScope]);
+        }
       }
       state = { backend: undefined, lastFailureTime: 0, inflight: null };
-      states.set(scopeKey, state);
+      accessorApply(accessorMapSet, states, [scopeKey, state]);
     } else if (getScopeKey) {
-      states.delete(scopeKey);
-      states.set(scopeKey, state);
+      accessorApply(accessorMapDelete, states, [scopeKey]);
+      accessorApply(accessorMapSet, states, [scopeKey, state]);
     }
 
     if (state.backend !== undefined) {
@@ -186,33 +208,40 @@
         logger.debug(`[${name}] Retrying distributed cache initialization after failure`);
       }
 
-      if (state.backend !== undefined) return Promise.resolve(state.backend);
+      if (state.backend !== undefined) {
+        return accessorApply(accessorPromiseResolve, AccessorPromise, [state.backend]) as Promise<
+          CacheBackend | null
+        >;
+      }
     }
 
     if (!state.inflight) {
+      const settled = state;
       state.inflight = (async () => {
         try {
           const b = await factory();
           if (!isDistributedBackend(b)) {
-            state.backend = null;
-            state.lastFailureTime = 0;
+            settled.backend = null;
+            settled.lastFailureTime = 0;
             logger.debug(`[${name}] No distributed cache available (memory only)`);
             return null;
           }
 
-          state.backend = b;
-          state.lastFailureTime = 0;
+          settled.backend = b;
+          settled.lastFailureTime = 0;
           logger.debug(`[${name}] Distributed cache initialized`, { type: b.type });
           return b;
         } catch (error) {
           logger.debug(`[${name}] Failed to initialize distributed cache`, { error });
-          state.backend = null;
-          state.lastFailureTime = Date.now();
+          settled.backend = null;
+          settled.lastFailureTime = Date.now();
           return null;
+        } finally {
+          // A synchronous factory failure also yields until inflight is assigned.
+          await undefined;
+          settled.inflight = null;
         }
-      })().finally(() => {
-        state.inflight = null;
-      });
+      })();
     }
 
     return state.inflight;

src/cache/bounded-read.ts

@@ -2,7 +2,12 @@ import { utf8ByteLength } from "#veryfront/utils/utf8-byte-length.ts";
 import type { CacheBackend } from "./types.ts";
 
 const apply = Reflect.apply;
+const NativeSet = Set;
+const setHas = NativeSet.prototype.has;
+const setAdd = NativeSet.prototype.add;
 const freeze = Object.freeze;
+const create = Object.create;
+const defineProperty = Object.defineProperty;
 const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
 const getPrototypeOf = Object.getPrototypeOf;
 const numberIsSafeInteger = Number.isSafeInteger;
@@ -64,14 +69,14 @@ export function captureBoundedCacheRead(
   }
 
   let owner: object | null = backend;
-  const seen = new Set<object>();
+  const seen = new NativeSet<object>();
   try {
     for (let depth = 0; owner !== null && depth < MAX_CACHE_CAPABILITY_PROTOTYPE_DEPTH; depth++) {
       if (owner === universalObjectPrototype || owner === universalFunctionPrototype) {
         return null;
       }
-      if (seen.has(owner)) return null;
-      seen.add(owner);
+      if (apply(setHas, seen, [owner])) return null;
+      apply(setAdd, seen, [owner]);
       const parent = getPrototypeOf(owner);
       if (owner !== backend && parent === null) return null;
       const descriptor = getOwnPropertyDescriptor(owner, "getWithinLimit");
@@ -83,8 +88,8 @@ export function captureBoundedCacheRead(
           return null;
         }
         const method = descriptor.value as NonNullable<CacheBackend["getWithinLimit"]>;
-        const captured = Object.create(null) as CapturedBoundedCacheRead;
-        Object.defineProperty(captured, "getWithinLimit", {
+        const captured = create(null) as CapturedBoundedCacheRead;
+        defineProperty(captured, "getWithinLimit", {
           value: (key: string, maximumBytes: number) =>
             apply(method, backend, [key, maximumBytes]) as Promise<string | null>,
           enumerable: true,

src/cache/capabilities.ts

@@ -16,30 +16,50 @@ type CapturedRevisionMethods = Readonly<{
 
 type UncheckedCallable = (...args: never[]) => unknown;
 
+// Captured before project code runs: capability inspection receives private
+// backend objects, and a replaced reflection global must never observe them.
+const reflectApply = Reflect.apply;
+const objectFreeze = Object.freeze;
+const NativeSet = Set;
+const setHas = NativeSet.prototype.has;
+const setAdd = NativeSet.prototype.add;
+const reflectGetOwnPropertyDescriptor = Reflect.getOwnPropertyDescriptor;
+const reflectGetPrototypeOf = Reflect.getPrototypeOf;
+const reflectOwnKeys = Reflect.ownKeys;
+const arrayIsArray = Array.isArray;
+const universalObjectPrototype = Object.prototype;
+const universalFunctionPrototype = Function.prototype;
+
 const MAX_CACHE_CAPABILITY_PROTOTYPE_DEPTH = 64;
 
 function findCallableDataProperty(
   value: object,
   key: "getWithRevision" | "compareExchange",
 ): UncheckedCallable | null {
   let current: object | null = value;
-  const visited = new Set<object>();
+  const visited = new NativeSet<object>();
   let inspectedDepth = 0;
 
   while (current !== null) {
+    // A capability inherited from a universal prototype is an injection, not
+    // a backend method: project code adding these names to Object.prototype
+    // must never have them invoked with a private backend as `this`.
+    if (current === universalObjectPrototype || current === universalFunctionPrototype) {
+      return null;
+    }
     if (inspectedDepth >= MAX_CACHE_CAPABILITY_PROTOTYPE_DEPTH) return null;
     inspectedDepth += 1;
-    if (visited.has(current)) return null;
-    visited.add(current);
+    if (reflectApply(setHas, visited, [current])) return null;
+    reflectApply(setAdd, visited, [current]);
 
-    const descriptor = Reflect.getOwnPropertyDescriptor(current, key);
+    const descriptor = reflectGetOwnPropertyDescriptor(current, key);
     if (descriptor !== undefined) {
       if (!("value" in descriptor) || typeof descriptor.value !== "function") {
         return null;
       }
       return descriptor.value;
     }
-    current = Reflect.getPrototypeOf(current);
+    current = reflectGetPrototypeOf(current);
   }
 
   return null;
@@ -68,7 +88,7 @@ export function captureRevisionedCacheBackendMethods(
     const compareExchange = findCallableDataProperty(backend, "compareExchange");
     if (compareExchange === null) return null;
 
-    return Object.freeze({
+    return objectFreeze({
       getWithRevision: getWithRevision as RevisionedCacheBackend["getWithRevision"],
       compareExchange: compareExchange as RevisionedCacheBackend["compareExchange"],
     });
@@ -87,7 +107,7 @@ export function isRevisionedCacheBackend(
 function readOwnDataProperty(value: object, key: string): unknown {
   let descriptor: PropertyDescriptor | undefined;
   try {
-    descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+    descriptor = reflectGetOwnPropertyDescriptor(value, key);
   } catch (cause) {
     throw new TypeError(`Cache revision ${key} could not be inspected`, { cause });
   }
@@ -99,13 +119,13 @@ function readOwnDataProperty(value: object, key: string): unknown {
 
 /** Validate and detach a provider-returned revision snapshot. */
 export function snapshotCacheRevisionResult(value: unknown): CacheRevisionSnapshot {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+  if (value === null || typeof value !== "object" || arrayIsArray(value)) {
     throw new TypeError("Cache revision result must be an object");
   }
 
   let keys: PropertyKey[];
   try {
-    keys = Reflect.ownKeys(value);
+    keys = reflectOwnKeys(value);
   } catch (cause) {
     throw new TypeError("Cache revision result could not be inspected", { cause });
   }
@@ -133,7 +153,7 @@ export function snapshotCacheRevisionResult(value: unknown): CacheRevisionSnapsh
     );
   }
 
-  return Object.freeze({ value: snapshotValue, revision });
+  return objectFreeze({ value: snapshotValue, revision });
 }
 
 /** Validate a provider-returned compare-exchange result. */