[Web] Preserve caller ownership of cached shape tuples

Signed-off-by: Akaash Parthasarathy <akaashrp@gmail.com>

Author: akaashrp

web/src/cache_state.ts

@@ -124,8 +124,8 @@ export class LRUCache<K, V> {
  *     the JS→WASM FFI boundary each time. During LLM decode, the same shapes
  *     repeat every token (e.g. [1,32,128]), so caching avoids thousands of
  *     redundant FFI round-trips.
- *   - Invalidation: Never. Shape tuples are immutable value objects that
- *     remain valid for the lifetime of the TVM instance.
+ *   - Invalidation: Cache entries may be evicted, but returned shape tuples
+ *     hold independent references and remain valid for their caller's scope.
  *
  * Future additions (follow-up PR):
  * - **uniformCache**: Caches GPU uniform buffers keyed by content hash.
@@ -142,7 +142,8 @@ export class CacheState {
    * Key: comma-separated dimension string, e.g. "1,32,128"
    * Value: TVM ShapeTuple object (Disposable)
    *
-   * Invalidation rule: None required — shape tuples are immutable.
+   * Eviction releases only the cache's reference. Shape tuples returned to
+   * callers have independent references and normal scope-managed lifetimes.
    */
   readonly shapeCache: LRUCache<string, Disposable>;
 

web/src/ctypes.ts

@@ -176,6 +176,11 @@ export type FTVMFFIWasmFunctionCreate = (
  */
 export type FTVMFFIWasmFunctionDeleter = (self: Pointer) => void;
 
+/**
+ * int TVMFFIObjectIncRef(TVMFFIObjectHandle obj);
+ */
+export type FTVMFFIObjectIncRef = (obj: Pointer) => number;
+
 /**
  * int TVMFFIObjectDecRef(TVMFFIObjectHandle obj);
  */

web/src/runtime.ts

@@ -1868,13 +1868,27 @@ export class Instance implements Disposable {
    */
   makeShapeTuple(shape: Array<number>): TVMObject {
     const key = CacheState.computeShapeKey(shape);
-    return this.cacheState.shapeCache.get(key, () => {
+    const cachedTuple = this.cacheState.shapeCache.get(key, () => {
       const shapeArray = shape.map((value) => new Scalar(value, "int"));
       const tuple = this.ctx.makeShapeTuple(...shapeArray);
       // Detach from scope so the cached object survives across scopes.
       this.detachFromCurrentScope(tuple);
       return tuple;
     }) as TVMObject;
+
+    // The cache owns its wrapper and may release it on eviction. Give the
+    // caller an independent strong reference with the usual scope lifetime.
+    const handle = cachedTuple.getHandle();
+    this.lib.checkCall(
+      (this.lib.exports.TVMFFIObjectIncRef as ctypes.FTVMFFIObjectIncRef)(handle)
+    );
+    const callerTuple = new TVMObject(handle, this.lib, this.ctx);
+    try {
+      return this.attachToCurrentScope(callerTuple);
+    } catch (err) {
+      callerTuple.dispose();
+      throw err;
+    }
   }
   /**
    * Get type index from type key.

web/tests/node/test_object.js

@@ -43,3 +43,21 @@ test("object", () => {
     assert(t1.getHandle() == t.getHandle());
   });
 });
+
+test("shape cache does not invalidate caller-owned tuples", () => {
+  tvm.beginScope();
+  const disposedTuple = tvm.makeShapeTuple([987654321, -1]);
+  disposedTuple.dispose();
+  const cachedTuple = tvm.makeShapeTuple([987654321, -1]);
+  assert.doesNotThrow(() => cachedTuple.typeKey());
+
+  const evictedTuple = tvm.makeShapeTuple([987654321, 0]);
+  for (let i = 1; i <= 256; ++i) {
+    tvm.makeShapeTuple([987654321, i]);
+  }
+  assert.doesNotThrow(() => evictedTuple.typeKey());
+
+  tvm.endScope();
+  assert.throws(() => cachedTuple.getHandle(), /already been disposed/);
+  assert.throws(() => evictedTuple.getHandle(), /already been disposed/);
+});