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

extensions/ext-image-sharp/deno.json

@@ -21,7 +21,7 @@
     ]
   },
   "imports": {
-    "sharp": "npm:sharp@0.35.3",
+    "sharp": "npm:sharp@0.35.4",
     "@std/assert": "jsr:@std/assert@1.0.19",
     "@std/testing/bdd": "jsr:@std/testing@1.0.17/bdd",
     "veryfront/extensions": "../../src/extensions/types.ts",

extensions/ext-image-sharp/src/index.test.ts

@@ -54,7 +54,7 @@ describe("ext-image-sharp", () => {
 
   it("keeps cache identity immutable and backend-specific", () => {
     const engine = new SharpImageOptimizationEngine();
-    assertStringIncludes(engine.cacheIdentity, "sharp@0.35.3");
+    assertStringIncludes(engine.cacheIdentity, "sharp@0.35.4");
     assertStringIncludes(engine.cacheIdentity, `vips@${sharp.versions.vips}`);
     assertEquals(Object.isFrozen(engine), true);
     assertThrows(

src/cache/backends/factory.ts

@@ -149,6 +149,23 @@ export function isDistributedBackend(backend: CacheBackend): boolean {
 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 accessorPromiseFinally = Promise.prototype.finally;
+const AccessorPromise = Promise;
+const accessorPromiseResolve = AccessorPromise.resolve;
+
 interface DistributedCacheAccessorState {
   backend: CacheBackend | null | undefined;
   lastFailureTime: number;
@@ -160,21 +177,27 @@ export function createDistributedCacheAccessor(
   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 +209,42 @@ export function createDistributedCacheAccessor(
         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) {
-      state.inflight = (async () => {
-        try {
-          const b = await factory();
-          if (!isDistributedBackend(b)) {
-            state.backend = null;
-            state.lastFailureTime = 0;
-            logger.debug(`[${name}] No distributed cache available (memory only)`);
+      const settled = state;
+      state.inflight = accessorApply(
+        accessorPromiseFinally,
+        (async () => {
+          try {
+            const b = await factory();
+            if (!isDistributedBackend(b)) {
+              settled.backend = null;
+              settled.lastFailureTime = 0;
+              logger.debug(`[${name}] No distributed cache available (memory only)`);
+              return null;
+            }
+
+            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 });
+            settled.backend = null;
+            settled.lastFailureTime = Date.now();
             return null;
           }
-
-          state.backend = b;
-          state.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();
-          return null;
-        }
-      })().finally(() => {
-        state.inflight = null;
-      });
+        })(),
+        [() => {
+          settled.inflight = null;
+        }],
+      ) as Promise<CacheBackend | 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. */