HealthLog/src/lib/ai/coach/snapshot-cache.ts

/**
 * In-memory result cache for the Coach snapshot builder.
 *
 * v1.4.33 — 60-second in-memory cache for `buildCoachSnapshot()`. The
 * snapshot reads only persisted data; a single chat conversation sends
 * 2-4 turns within a minute and the snapshot would otherwise rebuild
 * from the same rows each turn. Caching the result for 60s shaves the
 * ~10 measurement reads + the GLP-1 / mood / intake side-fetches off
 * every turn after the first, which `.planning/round-v1433-audit-perf.md`
 * §3.3 estimates at 200-800 ms of server-side tail.
 *
 * Scope is part of the cache key so a switch from `last30days` to
 * `last7days` (or a different `sources` set) computes fresh. The map
 * is bounded at 64 entries — a multi-tenant deployment with a few
 * active power users sits well inside that ceiling even if each cycles
 * through several scopes per minute.
 *
 * Split out of `snapshot.ts` so the builder file carries only the
 * assembly logic; the public surface (`buildCoachSnapshot`,
 * `__resetCoachSnapshotCacheForTests`) stays importable from
 * `./snapshot` via re-export.
 */
import type { CoachSnapshotResult } from "./snapshot";
import type { CoachScope, CoachScopeWindow } from "./types";
import { reachCacheToken, type CoachHistoryReach } from "./history-reach";

/** Default window when the caller doesn't pass a scope. */
export const DEFAULT_WINDOW: CoachScopeWindow = "last30days";

const SNAPSHOT_TTL_MS = 60_000;
const SNAPSHOT_LRU_MAX = 64;
const snapshotCache = new Map<
  string,
  { expiresAt: number; result: CoachSnapshotResult }
>();

export function snapshotCacheKey(
  userId: string,
  scope: CoachScope | undefined,
  /**
   * The lookback limit the build honoured. Part of the key so a build read
   * without a limit (MCP) is never served to a limited Coach turn, nor the
   * other way round. No limit adds nothing, so those keys are unchanged.
   */
  reach?: CoachHistoryReach,
): string {
  // v1.7.0 — when the request pins an explicit source list, key on it.
  // Otherwise the source set is derived from the user's saved
  // `dataClusters`, which we don't read here (the cache must stay
  // I/O-free on a hit) — key on a stable `clusters` marker instead.
  // A cluster change is reflected on the next cache miss (≤60 s), the
  // same staleness window every other pref change already tolerates.
  const window = scope?.window ?? DEFAULT_WINDOW;
  const sourceList =
    scope?.sources && scope.sources.length > 0
      ? Array.from(scope.sources).sort().join(",")
      : "clusters";
  return `${userId}|${window}|${sourceList}${reachCacheToken(reach)}`;
}

export function readSnapshotCache(key: string): CoachSnapshotResult | null {
  const entry = snapshotCache.get(key);
  if (!entry) return null;
  if (entry.expiresAt <= Date.now()) {
    snapshotCache.delete(key);
    return null;
  }
  // Touch for LRU — re-insert moves to the end of the Map's iteration order.
  snapshotCache.delete(key);
  snapshotCache.set(key, entry);
  return entry.result;
}

export function writeSnapshotCache(
  key: string,
  result: CoachSnapshotResult,
): void {
  if (snapshotCache.size >= SNAPSHOT_LRU_MAX) {
    // Evict the oldest entry — JS Map iteration order is insertion order,
    // so the first key is the least-recently inserted/touched.
    const oldest = snapshotCache.keys().next().value;
    if (oldest !== undefined) {
      snapshotCache.delete(oldest);
    }
  }
  snapshotCache.set(key, {
    expiresAt: Date.now() + SNAPSHOT_TTL_MS,
    result,
  });
}

/** Clear the snapshot cache. Test-only escape hatch. */
export function __resetCoachSnapshotCacheForTests(): void {
  snapshotCache.clear();
}