@soulcraft/sdk 2.2.0 → 2.4.0

package/docs/ADR-006-rpc-cache.md

@@ -0,0 +1,132 @@
+# ADR-006: RPC Response Cache — Namespace Router Cache Layer
+
+**Status:** Accepted
+**Date:** 2026-03-18
+**SDK version:** 2.4.0
+
+---
+
+## Context
+
+Brainy with Cortex + mmap-filesystem is already sub-millisecond for reads on the server
+side (SQ8 HNSW distance = 0.27 μs, entity lookups = O(1) HashMap on mmap'd SSTables).
+The value of an application-level cache is **not** avoiding Brainy reads — it's:
+
+1. **Avoiding auth + dispatch + JSON serialization overhead** at high QPS (thousands of
+   anonymous Venue visitors or Workshop published-app users hitting the same tenant data)
+2. **Singleflight deduplication** — concurrent identical requests share one execution
+3. **HTTP cache headers** — `Cache-Control` + `ETag` on responses so browsers, CDNs, and
+   reverse proxies can participate
+
+---
+
+## Decision
+
+### Layer: Namespace Router (server-side)
+
+The cache wraps the `NamespaceRouter` via `createCachedDispatch()`. This means all
+transports (HTTP, WebSocket, local) benefit automatically. The Hono router's
+`SoulcraftRouterConfig` accepts an optional `cache` field for zero-effort integration.
+
+### Invalidation: TTL + Scope-Flush on Write
+
+Each cacheable method has a TTL (seconds). When any write method (`add`, `update`,
+`delete`, `writeFile`, etc.) succeeds in a scope, **all** cached entries for that scope
+are flushed. This is slightly aggressive but:
+
+- Simple and correct — no stale reads after writes
+- Acceptable for expected cache sizes (< 2000 entries per LRU)
+- Avoids the complexity of tag-based invalidation
+
+### Scale: Pluggable CacheProvider
+
+The `CacheProvider` interface (`get`, `set`, `invalidateScope`, `delete`, `size`) allows
+swapping the default in-process LRU for Redis/Memcached in multi-server deployments.
+Ships with `LruCacheProvider` backed by `lru-cache` (already a dependency).
+
+### Opt-in: Off by Default
+
+Cache is disabled unless the product passes `cache` config. The `scopeKey` function
+can also return `null` per-request to bypass caching selectively (e.g. Workshop skips
+caching for workspace editing but caches published-app reads).
+
+---
+
+## Cache Key Format
+
+```
+${scope}:${namespace}.${method}:${sha256(JSON.stringify(args)).slice(0,16)}
+```
+
+- **scope** — product-defined (workspace ID, tenant ID, `pub:${workspaceId}`, etc.)
+- **namespace.method** — e.g. `brainy.find`, `graph.getData`
+- **args hash** — 16-char truncated SHA-256 of the JSON-serialized args array
+
+---
+
+## Default Cacheable Methods
+
+| Method | TTL |
+|--------|-----|
+| `brainy.find`, `brainy.get`, `brainy.getRelations` | 10s |
+| `graph.getData`, `graph.getFocused`, `graph.getNeighbors` | 30s |
+| `graph.getStats` | 60s |
+| `search.query`, `search.unified` | 10s |
+| `collections.list`, `collections.get`, `collections.getItems` | 30s |
+| `config.get` | 5min |
+| `brainy.vfs.readFile`, `brainy.vfs.readdir`, `brainy.vfs.stat` | 10s |
+| `brainy.vfs.tree` | 30s |
+| `workspace.list`, `workspace.get` | 30s |
+
+Products can override entirely via `RpcCacheConfig.methods`.
+
+---
+
+## Singleflight Deduplication
+
+Follows the proven pattern from `src/modules/billing/portal-provider.ts`: a
+`Map<string, Promise<DispatchResult>>` keyed by cache key, deleted in `finally`.
+When multiple concurrent requests arrive for the same cache key, only one dispatches
+to the inner router — all others await the same promise.
+
+---
+
+## HTTP Headers
+
+Successful cached responses carry:
+
+- `Cache-Control: public, max-age=${ttlSeconds}` — enables CDN/browser caching
+- `ETag: "${sha256(body).slice(0,32)}"` — quoted, 32-char truncated hash
+- `X-Cache: HIT | MISS` — observability
+
+No `304 / If-None-Match` — POST requests don't conventionally use conditional responses.
+The headers exist for CDN layers (Cloudflare Cache Rules can cache POST by header).
+
+---
+
+## What the Cache Does NOT Do
+
+- **Does not replace Brainy's mmap reads** — Brainy is already sub-ms
+- **Does not cache streaming responses** — `stream: true` always bypasses
+- **Does not cache error responses** — only successful results are stored
+- **Does not use canonical JSON** — `JSON.stringify` is deterministic for same input
+  from JSON-parsed client requests; no normalization needed for v1
+
+---
+
+## Consequences
+
+- Products get transparent read caching with a single config object
+- Write-after-read correctness is guaranteed by scope-flush
+- Singleflight prevents thundering herd on cold cache / TTL expiry
+- CDN integration is possible via standard HTTP headers
+- Multi-server deployments can implement `CacheProvider` for shared cache
+- Metrics callback enables product-specific monitoring (hit rate, invalidation frequency)
+
+---
+
+## References
+
+- `src/server/rpc-cache.ts` — implementation
+- `tests/server/rpc-cache.test.ts` — 17-test suite
+- `src/modules/billing/portal-provider.ts:119-171` — singleflight pattern origin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/sdk",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
   "type": "module",
   "publishConfig": {