feat(core): implement resource cache phase 1 - staleTime and deduplicate (#119)

Implements resource cache phase 1:

- cache.staleTime - time-based automatic staleness
- cache.deduplicate - in-flight load deduplication
- No cache.key, cacheTime, swr, or cross-navigation cache

Closes the cache phase 1 portion of the resource cache proposal.

Author: mahyarmlk

.changeset/seven-cobras-tan.md

@@ -0,0 +1,5 @@
+---
+"@intent-framework/core": patch
+---
+
+Implement resource cache semantics phase 1: `cache.staleTime` for time-based staleness and `cache.deduplicate` for in-flight load/reload deduplication. Resources without `cache` options behave exactly as before.

docs/Resources.md

@@ -251,14 +251,65 @@ On failure, `error` contains the error message and `status` is `"failed"`.
 
 See the [Inspect Screen and Diagnostics Guide](Inspect-Screen.md) for more detail.
 
+## Cache options (Phase 1)
+
+Resources support optional `cache` configuration:
+
+```ts
+const team = $.resource("team", {
+  load: async () => loadTeam(),
+  cache: {
+    staleTime: 5_000,    // ms (optional, default: Infinity — no time-based stale)
+    deduplicate: true,   // boolean (optional, default: true when cache is set)
+  },
+})
+```
+
+### staleTime
+
+`cache.staleTime` is an optional number in milliseconds. After a successful `load()` or `reload()`, a timer starts. When it fires, the resource transitions to stale automatically:
+
+- `resource.stale` becomes `true`
+- `resource.status` remains `"ready"`
+- `resource.value` remains available
+- Subscribers to the `stale` condition are notified
+
+Behavior:
+
+- **Timer resets** on every successful `load()` or `reload()`.
+- **`invalidate()`** always marks stale immediately, regardless of `staleTime`.
+- **Failed loads** do not start a stale timer.
+- **`dispose()`** clears the stale timer and prevents late notifications.
+
+### deduplicate
+
+`cache.deduplicate` is an optional boolean. When `true`, concurrent `load()` and `reload()` calls while a load is already pending share the same in-flight promise:
+
+- Only one loader invocation runs.
+- All callers resolve or fail with the same result.
+- The in-flight promise is cleared when the load completes (success or failure).
+
+When `false`, each call runs independently (preserving existing behavior).
+
+When `cache` is not set at all, deduplication is disabled to preserve backward compatibility. When `cache` is set, `deduplicate` defaults to `true`.
+
+### Future cache options
+
+The following cache options remain as future work and are **not yet supported**:
+
+- **`cache.key`** — cache key function for parameterized resources
+- **`cacheTime`** — retention period for stale values before eviction
+- **`swr`** — stale-while-revalidate background refreshing
+- **Cross-navigation cache store** — persistent cache across screen navigations
+
 ## Current boundaries
 
 Resources are intentionally limited:
 
 - **No global cache.** Each runtime owns its resource nodes. There is no shared cache between runtimes.
 - **No cache keys.** Resource identity is by name within a screen. There is no key-based deduplication or caching.
-- **No staleTime.** Invalidation is manual or action-driven. There is no TTL-based staleness.
-- **No automatic background refetching.** Stale resources stay stale until explicitly reloaded.
+- **No `cacheTime`.** There is no time-based retention of stale values beyond `staleTime` transitions.
+- **No stale-while-revalidate (SWR).** Stale resources stay stale until explicitly reloaded.
 - **No Suspense integration.** Resources do not integrate with React Suspense or any other framework's loading boundaries.
 - **No server framework integration yet.** Resources live on screen definitions and runtimes. Server-side resource hydration is not implemented.
 - **No full concurrent multi-mount resource ref semantics.** A `ResourceRef` connects to one runtime at a time. The last runtime to start owns the ref.

docs/proposals/Resource-Cache-And-Stale-Semantics.md

@@ -1,11 +1,14 @@
 # Resource Cache and Stale Semantics — Design Proposal
 
-**Status:** Proposal  
+**Status:** Implemented (Phase 1: staleTime + deduplicate)  
 **Date:** 2026-06-26  
 **Author:** Big Pickle  
 **Affected package:** `@intent-framework/core`  
 **Related docs:** `docs/Resources.md`, `docs/Specification.md`
 
+> **Phase 1 implementation** (PR #119): `cache.staleTime` and `cache.deduplicate` are implemented in `@intent-framework/core@0.1.0-alpha.8`.  
+> Remaining features (cache.key, cacheTime, swr, cross-navigation cache) remain as proposal/future work.
+
 ---
 
 ## Problem
@@ -572,3 +575,25 @@ No changeset is needed for this proposal — it is design-only.
 - `packages/core/src/resource.ts` — Current `ResourceNode`, `ResourceConfig`,
   `createResourceNode` implementation.
 - `docs/MVP-Checkpoint.md` — "Resource cache policy" listed as unproven.
+
+---
+
+## Implementation Status
+
+### Phase 1 (implemented in `@intent-framework/core@0.1.0-alpha.8`)
+
+- `cache.staleTime` — time-based automatic staleness
+- `cache.deduplicate` — in-flight load deduplication
+- Resources without `cache` options behave exactly as before
+
+### Future (not yet implemented)
+
+- `cache.key` — cache key function for parameterized resources
+- `cacheTime` — retention period for stale values before eviction
+- `swr` — stale-while-revalidate background refetching
+- Cross-navigation cache store (InMemoryResourceCache)
+- Dependency-tracked keys
+- Streaming resources
+- SSR hydration
+- Optimistic updates
+- Server resources

packages/core/src/core.test.ts

@@ -3214,3 +3214,188 @@ describe("resource loader context", () => {
     })
   })
 })
+
+describe("resource cache semantics", () => {
+  describe("staleTime", () => {
+    it("resource without cache keeps current manual-stale behavior", () => {
+      const resource = createResourceNode("team", "team", async () => "data")
+      expect(resource.stale.current).toBe(false)
+      resource.invalidate()
+      expect(resource.stale.current).toBe(true)
+      // No stale timer should have been started
+    })
+
+    it("marks resource stale after staleTime elapses", async () => {
+      const resource = createResourceNode("team", "team", async () => "data", true, { staleTime: 10 })
+      expect(resource.stale.current).toBe(false)
+      await resource.load()
+      expect(resource.stale.current).toBe(false)
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(resource.stale.current).toBe(true)
+    })
+
+    it("leaves status ready and value available when stale", async () => {
+      const resource = createResourceNode("team", "team", async () => "hello", true, { staleTime: 10 })
+      await resource.load()
+      expect(resource.status).toBe("ready")
+      expect(resource.value).toBe("hello")
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(resource.stale.current).toBe(true)
+      expect(resource.status).toBe("ready")
+      expect(resource.value).toBe("hello")
+    })
+
+    it("notifies stale subscribers when staleTime fires", async () => {
+      const resource = createResourceNode("team", "team", async () => "data", true, { staleTime: 10 })
+      await resource.load()
+      const values: boolean[] = []
+      const unsub = resource.stale.subscribe(() => {
+        values.push(resource.stale.current)
+      })
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(values).toContain(true)
+      unsub()
+    })
+
+    it("reload clears stale and restarts stale timer", async () => {
+      const resource = createResourceNode("team", "team", async () => "data", true, { staleTime: 10 })
+      await resource.load()
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(resource.stale.current).toBe(true)
+      await resource.reload()
+      expect(resource.stale.current).toBe(false)
+      // Should not be stale right after reload
+      await new Promise(resolve => setTimeout(resolve, 5))
+      expect(resource.stale.current).toBe(false)
+    })
+
+    it("invalidate marks stale immediately even before staleTime", async () => {
+      const resource = createResourceNode("team", "team", async () => "data", true, { staleTime: 10_000 })
+      await resource.load()
+      expect(resource.stale.current).toBe(false)
+      resource.invalidate()
+      expect(resource.stale.current).toBe(true)
+    })
+
+    it("failed load does not start stale timer", async () => {
+      const resource = createResourceNode("team", "team", async () => { throw new Error("fail") }, true, { staleTime: 10 })
+      await resource.load()
+      expect(resource.status).toBe("failed")
+      await new Promise(resolve => setTimeout(resolve, 20))
+      // failed resources should not become stale
+      expect(resource.stale.current).toBe(false)
+    })
+
+    it("dispose clears stale timer and prevents later notifications", async () => {
+      let notified = false
+      const resource = createResourceNode("team", "team", async () => "data", true, { staleTime: 10 })
+      await resource.load()
+      const unsub = resource.stale.subscribe(() => { notified = true })
+      resource.dispose()
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(notified).toBe(false)
+      unsub()
+    })
+  })
+
+  describe("deduplicate", () => {
+    it("deduplicate true shares concurrent load promises", async () => {
+      let resolveLoad!: (value: string) => void
+      const loadPromise = new Promise<string>(resolve => { resolveLoad = resolve })
+      let callCount = 0
+
+      const resource = createResourceNode("team", "team", async () => {
+        callCount++
+        return loadPromise
+      }, true, { deduplicate: true })
+
+      const load1 = resource.load()
+      const load2 = resource.load()
+      const load3 = resource.load()
+
+      resolveLoad("result")
+      await Promise.all([load1, load2, load3])
+
+      expect(callCount).toBe(1)
+    })
+
+    it("deduplicate true invokes loader only once for concurrent load/reload calls", async () => {
+      let resolveLoad!: (value: string) => void
+      const loadPromise = new Promise<string>(resolve => { resolveLoad = resolve })
+      let callCount = 0
+
+      const resource = createResourceNode("team", "team", async () => {
+        callCount++
+        return loadPromise
+      }, true, { deduplicate: true })
+
+      // Concurrent load + reload should share the same in-flight promise
+      const p1 = resource.load()
+      const p2 = resource.reload()
+      resolveLoad("result")
+      await Promise.all([p1, p2])
+
+      expect(callCount).toBe(1)
+    })
+
+    it("deduplicate false preserves independent concurrent loader calls", async () => {
+      let callCount = 0
+      let resolveLoad!: (value: string) => void
+      const deferred = new Promise<string>(resolve => { resolveLoad = resolve })
+
+      const resource = createResourceNode("team", "team", async () => {
+        callCount++
+        return deferred
+      }, true, { deduplicate: false })
+
+      const load1 = resource.load()
+      const load2 = resource.load()
+
+      resolveLoad("data")
+      await Promise.all([load1, load2])
+
+      expect(callCount).toBe(2)
+    })
+
+    it("failed deduplicated load marks failed status and clears in-flight promise", async () => {
+      let callCount = 0
+
+      const resource = createResourceNode("team", "team", async () => {
+        callCount++
+        throw new Error("fail")
+      }, true, { deduplicate: true })
+
+      const load1 = resource.load()
+      const load2 = resource.load()
+
+      await load1
+      await load2
+
+      expect(callCount).toBe(1)
+      expect(resource.status).toBe("failed")
+      expect(resource.error).toBeInstanceOf(Error)
+      expect((resource.error as Error).message).toBe("fail")
+    })
+
+    it("a later load after a deduped failure can retry normally", async () => {
+      let callCount = 0
+
+      const resource = createResourceNode("team", "team", async () => {
+        callCount++
+        if (callCount === 1) throw new Error("fail")
+        return "success"
+      }, true, { deduplicate: true })
+
+      // First load fails
+      await resource.load()
+      expect(resource.status).toBe("failed")
+      expect(callCount).toBe(1)
+
+      // Second load retries and succeeds (in-flight promise was cleared)
+      await resource.load()
+      expect(resource.status).toBe("ready")
+      expect(resource.value).toBe("success")
+      expect(callCount).toBe(2)
+    })
+  })
+})

packages/core/src/index.ts

@@ -7,7 +7,7 @@ export type { AskNode, AnyAskNode, AskKind, AskBuilder } from "./ask.js"
 export type { ActNode, ActCondition, ActStatus, FeedbackConfig, ActBuilder, NavigationService, ActionExecutionContext, DefaultScreenServices } from "./act.js"
 export type { FlowNode, FlowStep, FlowBuilder } from "./flow.js"
 export type { SurfaceNode, SurfaceBuilder } from "./surface.js"
-export type { ResourceNode, ResourceConfig, ResourceLoadContext, ResourceStatus, AnyResourceNode } from "./resource.js"
+export type { ResourceNode, ResourceConfig, ResourceCacheOptions, ResourceLoadContext, ResourceStatus, AnyResourceNode } from "./resource.js"
 export { ResourceRef, createResourceNode } from "./resource.js"
 export { createScreenRuntime } from "./runtime.js"
 export type { ScreenRuntime } from "./runtime.js"