improvement(execution): idle-TTL touch-on-read + LRU eviction for the large-value cache

Entry lifetimes were absolute-from-insert and eviction order was
insertion order, so a value a live run kept referencing could expire or
be pressure-evicted mid-use — while a genuinely idle entry survived the
full window. Every authorized read now refreshes the expiry and moves
the entry to the back of the eviction order: expiry and eviction only
ever take entries nothing has read for a full TTL, and pressure eviction
takes the least-recently-used recoverable entry. Strictly fewer
mid-execution misses; TTL values, the admission budget, and the
sole-copy (non-recoverable) eviction protection are unchanged.

Touching stays behind the scope check so an unauthorized probe cannot
extend a lifetime. Module TSDoc now records the standing constraint:
the warm pass runs once per execution start, so the TTL must outlive
the warm-to-first-reference gap — do not shorten it until warming is
per-block.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: icecrasher321

apps/sim/lib/execution/payloads/cache.test.ts

@@ -6,7 +6,26 @@ import {
   cacheLargeValue,
   clearLargeValueCacheForTests,
   getLargeValueCacheStats,
+  materializeLargeValueRefSync,
 } from '@/lib/execution/payloads/cache'
+import {
+  LARGE_VALUE_REF_VERSION,
+  type LargeValueRef,
+} from '@/lib/execution/payloads/large-value-ref'
+
+const MB = 1024 * 1024
+const SCOPE = { executionId: 'exec-1' }
+
+function makeRef(id: string, size: number): LargeValueRef {
+  return {
+    __simLargeValueRef: true,
+    version: LARGE_VALUE_REF_VERSION,
+    id,
+    kind: 'object',
+    size,
+    executionId: 'exec-1',
+  }
+}
 
 describe('large value cache sweep', () => {
   beforeEach(() => {
@@ -49,3 +68,66 @@ describe('large value cache sweep', () => {
     expect(getLargeValueCacheStats()).toEqual({ entries: 1, trackedBytes: 16 })
   })
 })
+
+describe('large value cache retention policy', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    clearLargeValueCacheForTests()
+  })
+
+  afterEach(() => {
+    clearLargeValueCacheForTests()
+    vi.useRealTimers()
+  })
+
+  it('refreshes the idle TTL on every read so in-use values outlive the absolute window', () => {
+    cacheLargeValue('lv_touchedvalue', { data: 'v' }, 32, SCOPE)
+
+    vi.advanceTimersByTime(10 * 60 * 1000)
+    expect(materializeLargeValueRefSync(makeRef('lv_touchedvalue', 32), SCOPE)).toEqual({
+      data: 'v',
+    })
+
+    vi.advanceTimersByTime(10 * 60 * 1000)
+    expect(materializeLargeValueRefSync(makeRef('lv_touchedvalue', 32), SCOPE)).toEqual({
+      data: 'v',
+    })
+
+    vi.advanceTimersByTime(16 * 60 * 1000)
+    expect(materializeLargeValueRefSync(makeRef('lv_touchedvalue', 32), SCOPE)).toBeUndefined()
+  })
+
+  it('pressure-evicts the least-recently-read recoverable entry, not the oldest-inserted', () => {
+    cacheLargeValue('lv_aaaaaaaaaaaa', { name: 'a' }, 120 * MB, SCOPE, { recoverable: true })
+    cacheLargeValue('lv_bbbbbbbbbbbb', { name: 'b' }, 120 * MB, SCOPE, { recoverable: true })
+
+    expect(materializeLargeValueRefSync(makeRef('lv_aaaaaaaaaaaa', 120 * MB), SCOPE)).toEqual({
+      name: 'a',
+    })
+
+    expect(
+      cacheLargeValue('lv_cccccccccccc', { name: 'c' }, 60 * MB, SCOPE, { recoverable: true })
+    ).toBe(true)
+
+    expect(materializeLargeValueRefSync(makeRef('lv_aaaaaaaaaaaa', 120 * MB), SCOPE)).toEqual({
+      name: 'a',
+    })
+    expect(
+      materializeLargeValueRefSync(makeRef('lv_bbbbbbbbbbbb', 120 * MB), SCOPE)
+    ).toBeUndefined()
+    expect(getLargeValueCacheStats()).toEqual({ entries: 2, trackedBytes: 180 * MB })
+  })
+
+  it('never pressure-evicts a sole-copy entry; admission fails instead', () => {
+    cacheLargeValue('lv_nnnnnnnnnnnn', { name: 'sole-copy' }, 200 * MB, SCOPE)
+
+    expect(
+      cacheLargeValue('lv_rrrrrrrrrrrr', { name: 'r' }, 100 * MB, SCOPE, { recoverable: true })
+    ).toBe(false)
+
+    expect(materializeLargeValueRefSync(makeRef('lv_nnnnnnnnnnnn', 200 * MB), SCOPE)).toEqual({
+      name: 'sole-copy',
+    })
+    expect(getLargeValueCacheStats()).toEqual({ entries: 1, trackedBytes: 200 * MB })
+  })
+})

apps/sim/lib/execution/payloads/cache.ts

@@ -4,6 +4,24 @@ import {
   type LargeValueRef,
 } from '@/lib/execution/payloads/large-value-ref'
 
+/**
+ * In-memory retention for large execution values. Durable storage is the
+ * source of truth — every recoverable entry also exists in object storage and
+ * transparently re-fetches through the async materialize path on a miss — so
+ * this layer is an accelerator plus one deliberate exception: an entry whose
+ * durable persist failed (`recoverable: false`) is the value's ONLY copy, and
+ * pressure eviction must never remove it (losing it fails the execution that
+ * stored it; expiry is its only exit).
+ *
+ * Lifetimes are IDLE TTLs, not absolute: every successful read refreshes the
+ * entry and moves it to the back of the eviction order, so a value a live run
+ * keeps referencing cannot expire mid-use, and pressure eviction always takes
+ * the least-recently-used recoverable entry. The TTL must comfortably outlive
+ * the gap between an execution's warm pass (`warmLargeValueRefs`, which runs
+ * ONCE at execution start over the resumed snapshot) and that value's first
+ * sync reference during the run — shorten it only if the warm becomes
+ * per-block.
+ */
 const FALLBACK_TTL_MS = 15 * 60 * 1000
 const MAX_IN_MEMORY_BYTES = 256 * 1024 * 1024
 const SWEEP_INTERVAL_MS = 60 * 1000
@@ -169,6 +187,14 @@ export function materializeLargeValueRefSync(
   if (!cached || !scopeMatchesRef(ref, cached.scope, callerScope)) {
     return undefined
   }
+  // Idle-TTL touch on every authorized read: refresh expiry and move the entry
+  // to the back of the eviction order. A value a live run keeps referencing can
+  // therefore never expire or be pressure-evicted mid-use — expiry and eviction
+  // only ever take entries nothing has read for a full TTL. Touching must stay
+  // behind the scope check so an unauthorized probe cannot extend a lifetime.
+  cached.expiresAt = Date.now() + FALLBACK_TTL_MS
+  inMemoryValues.delete(ref.id)
+  inMemoryValues.set(ref.id, cached)
   return cached.value
 }