@classytic/repo-core 0.2.0 → 0.4.0

package/dist/cache/options.d.mts

@@ -0,0 +1,112 @@
+//#region src/cache/options.d.ts
+/**
+ * Canonical per-call cache options. TanStack Query-shaped — the same
+ * `staleTime` / `gcTime` mental model browser developers already know,
+ * lifted to server-side multi-tenant safe.
+ *
+ * **Scope discipline.** This is the ONE shape used across every read
+ * method on every kit (`getById`, `getAll`, `aggregate`, `count`, ...).
+ * Replaces mongokit's `AggCacheOptions`, sqlitekit's per-op overrides,
+ * and arc's `QueryCacheConfig`. One mental model, one wire shape.
+ *
+ * **Freshness semantics:**
+ *   - `0 ≤ age < staleTime`            → fresh; serve cache, no refresh
+ *   - `staleTime ≤ age < staleTime + gcTime`
+ *       - `swr: true`  → serve cache, kick off background refresh
+ *       - `swr: false` → treat as miss, fetch fresh inline
+ *   - `age ≥ staleTime + gcTime`       → expired; entry evicted
+ *
+ * Defaults match TanStack v5 / Next.js App Router idioms — short
+ * `staleTime` (data is stale immediately, refetch on next request),
+ * generous `gcTime` (keep entries around so the next request can serve
+ * stale-while-revalidate).
+ */
+interface CacheOptions {
+  /**
+   * Seconds the entry is considered fresh. `0` (default) means "always
+   * stale" — the entry serves via SWR if `swr: true`, otherwise every
+   * call re-fetches.
+   */
+  staleTime?: number;
+  /**
+   * Seconds the entry stays in cache after it goes stale. Past this
+   * point the entry is evicted entirely. Default: `60`.
+   */
+  gcTime?: number;
+  /**
+   * Group invalidation tags. Pass to `repo.invalidateCache(tags)` to
+   * wipe every entry tagged with any of the matching tags. Convention:
+   * namespace by domain — `'orders'`, `'org:abc123'`, `'user:42'`.
+   *
+   * The plugin auto-injects scope tags (`org:<id>` / `user:<id>`) when
+   * `autoTagsFromScope: true` (default), so hosts only declare
+   * domain-level tags.
+   */
+  tags?: readonly string[];
+  /**
+   * Force a fresh fetch + cache write. Use for "Refresh" buttons or
+   * explicit revalidation flows where the user expects up-to-the-second
+   * data. Bypasses both the read AND any in-flight SWR refresh — the
+   * cached entry is overwritten with the fresh result.
+   */
+  bypass?: boolean;
+  /**
+   * Stale-while-revalidate. When `true`, stale entries serve
+   * immediately and a background refresh updates the cache for the
+   * next request. When `false` (default), stale entries trigger an
+   * inline refetch — caller waits for fresh data.
+   *
+   * **Recommended `true`** for high-traffic dashboards where
+   * cache-edge latency matters more than strict freshness.
+   */
+  swr?: boolean;
+  /**
+   * Skip cache entirely for this call. Equivalent to TanStack Query's
+   * `enabled: false`. Default: `true` (cache active).
+   *
+   * Distinguished from `bypass`: `enabled: false` skips both read AND
+   * write, so a fresh fetch doesn't pollute the cache. `bypass: true`
+   * skips read but DOES write the fresh result.
+   */
+  enabled?: boolean;
+  /**
+   * Override the auto-derived cache key. The default key includes
+   * model, op, version, params hash, and scope tags — sufficient for
+   * 99% of cases. Override only when you want explicit control
+   * (cross-call sharing, debugging).
+   *
+   * **Caller owns uniqueness.** Two calls passing the same `key` for
+   * different request shapes get the first writer's result.
+   */
+  key?: string;
+}
+/** Per-call result envelope returned by `CacheEngine.get()`. */
+interface CacheReadResult<TData = unknown> {
+  /**
+   * - `'fresh'`    — within `staleTime`; cache is authoritative
+   * - `'stale'`    — past `staleTime`, within gc window; serve + revalidate
+   * - `'miss'`     — no entry, expired entry, or cache disabled
+   * - `'disabled'` — `enabled: false` for this call
+   * - `'bypass'`   — `bypass: true` for this call
+   */
+  readonly status: 'fresh' | 'stale' | 'miss' | 'disabled' | 'bypass';
+  /** Cached data when `status` is `'fresh'` or `'stale'`; otherwise `undefined`. */
+  readonly data: TData | undefined;
+  /** Age of the cached entry in seconds (only when status is fresh/stale). */
+  readonly age?: number;
+}
+/**
+ * Resolved cache options after merging plugin defaults + per-op
+ * defaults + per-call overrides. All fields populated; never undefined.
+ */
+interface ResolvedCacheOptions {
+  staleTime: number;
+  gcTime: number;
+  tags: readonly string[];
+  bypass: boolean;
+  swr: boolean;
+  enabled: boolean;
+  key?: string;
+}
+//#endregion
+export { CacheOptions, CacheReadResult, ResolvedCacheOptions };

package/dist/cache/options.mjs

@@ -0,0 +1,25 @@
+//#region src/cache/options.ts
+/**
+* Merge precedence (highest wins): per-call > per-op-default > plugin-default > built-in.
+*
+* Built-in defaults: `staleTime=0`, `gcTime=60`, `swr=false`,
+* `enabled=true`, `bypass=false`, `tags=[]`.
+*/
+function resolveCacheOptions(callOpts, perOpDefaults, pluginDefaults) {
+	const merged = {
+		...pluginDefaults,
+		...perOpDefaults,
+		...callOpts
+	};
+	return {
+		staleTime: Math.max(0, merged.staleTime ?? 0),
+		gcTime: Math.max(0, merged.gcTime ?? 60),
+		tags: merged.tags ?? [],
+		bypass: merged.bypass ?? false,
+		swr: merged.swr ?? false,
+		enabled: merged.enabled ?? true,
+		...merged.key !== void 0 ? { key: merged.key } : {}
+	};
+}
+//#endregion
+export { resolveCacheOptions };

package/dist/cache/plugin/context.d.mts

@@ -0,0 +1,18 @@
+//#region src/cache/plugin/context.d.ts
+/**
+ * Default per-op allowlist of context fields that affect result shape
+ * (and therefore must participate in the cache key). Hosts can extend
+ * via `cachePlugin({ shapeKeysByOp })`.
+ *
+ * **Allowlist beats denylist** because:
+ *   - New context fields don't silently slip into the cache key (which
+ *     would explode the miss rate when ANY non-shape field varies
+ *     per request — request IDs, trace headers, timestamps).
+ *   - New ops require explicit registration (forces thinking about
+ *     what affects shape).
+ *   - Hosts can override per-kit when their kit accepts a non-standard
+ *     option (e.g. mongoose's `lean`, prisma's `select` shape, etc.).
+ */
+declare const DEFAULT_SHAPE_KEYS_BY_OP: Readonly<Record<string, readonly string[]>>;
+//#endregion
+export { DEFAULT_SHAPE_KEYS_BY_OP };

package/dist/cache/plugin/context.mjs

@@ -0,0 +1,121 @@
+//#region src/cache/plugin/context.ts
+/**
+* Cast a raw hook context into the typed slots view. One call per
+* hook entry; subsequent slot reads/writes use plain dotted access.
+*/
+function ctx(raw) {
+	return raw;
+}
+/**
+* Default per-op allowlist of context fields that affect result shape
+* (and therefore must participate in the cache key). Hosts can extend
+* via `cachePlugin({ shapeKeysByOp })`.
+*
+* **Allowlist beats denylist** because:
+*   - New context fields don't silently slip into the cache key (which
+*     would explode the miss rate when ANY non-shape field varies
+*     per request — request IDs, trace headers, timestamps).
+*   - New ops require explicit registration (forces thinking about
+*     what affects shape).
+*   - Hosts can override per-kit when their kit accepts a non-standard
+*     option (e.g. mongoose's `lean`, prisma's `select` shape, etc.).
+*/
+const DEFAULT_SHAPE_KEYS_BY_OP = Object.freeze({
+	getById: [
+		"id",
+		"lean",
+		"select",
+		"populate",
+		"populateOptions"
+	],
+	getOne: [
+		"filter",
+		"select",
+		"populate",
+		"populateOptions",
+		"lean"
+	],
+	getByQuery: [
+		"query",
+		"select",
+		"populate",
+		"populateOptions",
+		"lean"
+	],
+	getAll: [
+		"filter",
+		"filters",
+		"sort",
+		"select",
+		"populate",
+		"populateOptions",
+		"lean",
+		"page",
+		"limit",
+		"after"
+	],
+	count: ["filter", "filters"],
+	exists: ["filter", "filters"],
+	distinct: [
+		"filter",
+		"filters",
+		"field"
+	],
+	aggregate: ["aggRequest"],
+	aggregatePaginate: ["aggRequest"]
+});
+/**
+* Pick the shape-affecting fields from a context for the given op.
+* Returns `undefined` when no shape keys are registered for the op or
+* none of them have values — the caller then keys solely on op + model.
+*
+* Aggregate ops get their `aggRequest` field auto-stripped of
+* operational slots (`cache`, `executionHints`) before hashing —
+* those don't affect the result, only HOW the call runs. Without
+* stripping, `bypass: true` and `bypass: false` would produce
+* different keys, defeating the "bypass overwrites cache" semantic.
+*/
+function extractShapeFields(context, op, shapeKeysByOp) {
+	const keys = shapeKeysByOp[op];
+	if (!keys || keys.length === 0) return void 0;
+	const isAggregate = AGGREGATE_OPS.has(op);
+	const out = {};
+	for (const k of keys) {
+		const v = context[k];
+		if (v === void 0) continue;
+		out[k] = isAggregate && k === "aggRequest" ? stripAggOperationalSlots(v) : v;
+	}
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/**
+* Strip operational slots from an `AggRequest` before hashing.
+* `cache` and `executionHints` describe HOW the call runs, not WHAT
+* it computes — including them in the key would cause spurious
+* misses on per-call config tweaks.
+*/
+function stripAggOperationalSlots(value) {
+	if (!value || typeof value !== "object") return value;
+	const { cache: _c, executionHints: _eh, ...rest } = value;
+	return rest;
+}
+/** Aggregate ops carry their cache slot inside the AggRequest IR. */
+const AGGREGATE_OPS = new Set(["aggregate", "aggregatePaginate"]);
+/**
+* Extract per-call `CacheOptions` from a hook context. Three valid
+* locations covered (kit-dependent):
+*   1. Aggregate ops: `context.aggRequest.cache`
+*   2. CRUD with merged options: `context.cache` (mongokit spreads)
+*   3. CRUD with options bag: `context.options.cache` (sqlitekit-style)
+*
+* Returns `undefined` when no per-call options are set; caller falls
+* back to plugin defaults / per-op defaults.
+*/
+function extractCallCacheOptions(context, op) {
+	if (AGGREGATE_OPS.has(op)) return context["aggRequest"]?.cache;
+	const direct = context["cache"];
+	if (direct && typeof direct === "object") return direct;
+	const inOptions = context["options"]?.["cache"];
+	if (inOptions && typeof inOptions === "object") return inOptions;
+}
+//#endregion
+export { AGGREGATE_OPS, DEFAULT_SHAPE_KEYS_BY_OP, ctx, extractCallCacheOptions, extractShapeFields };

package/dist/cache/plugin/index.d.mts

@@ -0,0 +1,86 @@
+import { Plugin } from "../../repository/plugin-types.mjs";
+import { CacheOptions, CacheReadResult } from "../options.mjs";
+import { CacheAdapter } from "../types.mjs";
+import { CacheEngine } from "../engine.mjs";
+import { DEFAULT_SHAPE_KEYS_BY_OP } from "./context.mjs";
+
+//#region src/cache/plugin/index.d.ts
+/** Default read ops the plugin caches. Kits may override per resource. */
+declare const DEFAULT_CACHEABLE_OPS: readonly ["getById", "getAll", "getOne", "getByQuery", "count", "exists", "distinct", "aggregate", "aggregatePaginate"];
+/** Default mutating ops that bump version + invalidate tags on success. */
+declare const DEFAULT_INVALIDATING_OPS: readonly ["create", "createMany", "update", "updateMany", "findOneAndUpdate", "upsert", "delete", "deleteMany", "restore", "claim", "claimVersion", "increment", "bulkWrite"];
+/** Observability callbacks — pipe to metrics, traces, or stdout. */
+interface LogCallbacks {
+  onHit?: (key: string, op: string, ageSeconds: number) => void;
+  onStale?: (key: string, op: string, ageSeconds: number) => void;
+  onMiss?: (key: string, op: string) => void;
+  /**
+   * Single-flight coalesce — the caller awaited an in-flight fetch
+   * for the same key instead of running its own executor. High
+   * coalesce rates indicate burst load on uncached entries — useful
+   * signal for capacity planning + cache-warming.
+   */
+  onCoalesce?: (key: string, op: string) => void;
+  onWrite?: (key: string, op: string, tags: readonly string[]) => void;
+  onInvalidate?: (model: string, version: number, tagCount: number) => void;
+}
+interface RepositoryCachePluginOptions {
+  /** Concrete adapter — Redis, in-memory, custom KV. */
+  readonly adapter: CacheAdapter;
+  /** Read ops the plugin caches. Default: every op in `DEFAULT_CACHEABLE_OPS`. */
+  readonly enabled?: readonly string[];
+  /** Mutating ops that trigger invalidation. Default: every op in `DEFAULT_INVALIDATING_OPS`. */
+  readonly invalidating?: readonly string[];
+  /** Plugin-level defaults — applied to every call where the caller didn't override. */
+  readonly defaults?: Partial<CacheOptions>;
+  /** Per-op default overrides — `{ getById: { staleTime: 600 } }`. */
+  readonly perOpDefaults?: Record<string, Partial<CacheOptions>>;
+  /** Cache key namespace prefix. Default: `'rc'`. */
+  readonly prefix?: string;
+  /**
+   * Auto-inject scope tags (`org:<id>`, `user:<id>`) extracted from
+   * `context.filter`. Default: `true`. Disable when the host wires
+   * scope manually via the `tags` option per-call.
+   */
+  readonly autoTagsFromScope?: boolean;
+  /** TTL jitter — symmetric fractional or custom function. Default: `0`. */
+  readonly jitter?: number | ((ttl: number) => number);
+  /**
+   * Per-op shape-key allowlist — overrides / extends defaults. Use
+   * to register kit-specific shape-affecting fields (e.g. mongoose
+   * `lean`, custom projection flags). Hosts merge with defaults via
+   * standard object spread.
+   *
+   * @example
+   * ```ts
+   * cachePlugin({
+   *   adapter,
+   *   shapeKeysByOp: {
+   *     ...DEFAULT_SHAPE_KEYS_BY_OP,
+   *     getById: ['id', 'lean', 'select', 'myCustomFlag'],
+   *   },
+   * });
+   * ```
+   */
+  readonly shapeKeysByOp?: Readonly<Record<string, readonly string[]>>;
+  /** Observability callbacks. Each fires per cache event. */
+  readonly log?: LogCallbacks;
+}
+/** Plugin-attached cache surface — exposed so kits can offer convenience methods. */
+interface RepositoryCacheHandle {
+  readonly engine: CacheEngine;
+  /** Invalidate every entry tagged with ANY of the provided tags. */
+  invalidateByTags(tags: readonly string[]): Promise<number>;
+  /** Bump the model's version — wipes every cached read for it. */
+  bumpModelVersion(model: string): Promise<number>;
+  /** Wipe the entire cache namespace (when the adapter supports it). */
+  clear(): Promise<void>;
+}
+/**
+ * Build the unified cache plugin. Compose alongside other plugins via
+ * `repo.use(cachePlugin({ adapter }))` — install AFTER `multiTenant`
+ * and `softDelete` so policy filters land in the cache key.
+ */
+declare function cachePlugin(options: RepositoryCachePluginOptions): Plugin;
+//#endregion
+export { DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, LogCallbacks, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin };

package/dist/cache/plugin/index.mjs

@@ -0,0 +1,78 @@
+import { CacheEngine } from "../engine.mjs";
+import { DEFAULT_SHAPE_KEYS_BY_OP } from "./context.mjs";
+import { registerInvalidationHooks } from "./invalidation-hooks.mjs";
+import { registerReadHooks } from "./read-hooks.mjs";
+//#region src/cache/plugin/index.ts
+/** Default read ops the plugin caches. Kits may override per resource. */
+const DEFAULT_CACHEABLE_OPS = [
+	"getById",
+	"getAll",
+	"getOne",
+	"getByQuery",
+	"count",
+	"exists",
+	"distinct",
+	"aggregate",
+	"aggregatePaginate"
+];
+/** Default mutating ops that bump version + invalidate tags on success. */
+const DEFAULT_INVALIDATING_OPS = [
+	"create",
+	"createMany",
+	"update",
+	"updateMany",
+	"findOneAndUpdate",
+	"upsert",
+	"delete",
+	"deleteMany",
+	"restore",
+	"claim",
+	"claimVersion",
+	"increment",
+	"bulkWrite"
+];
+/**
+* Build the unified cache plugin. Compose alongside other plugins via
+* `repo.use(cachePlugin({ adapter }))` — install AFTER `multiTenant`
+* and `softDelete` so policy filters land in the cache key.
+*/
+function cachePlugin(options) {
+	const enabled = new Set(options.enabled ?? DEFAULT_CACHEABLE_OPS);
+	const invalidating = new Set(options.invalidating ?? DEFAULT_INVALIDATING_OPS);
+	const defaults = options.defaults;
+	const perOpDefaults = options.perOpDefaults ?? {};
+	const autoTagsFromScope = options.autoTagsFromScope ?? true;
+	const log = options.log ?? {};
+	const prefix = options.prefix ?? "rc";
+	const shapeKeysByOp = options.shapeKeysByOp ?? DEFAULT_SHAPE_KEYS_BY_OP;
+	const engine = new CacheEngine(options.adapter, {
+		prefix,
+		...options.jitter !== void 0 ? { jitter: options.jitter } : {}
+	});
+	return {
+		name: "cache",
+		apply(repo) {
+			repo.cache = {
+				engine,
+				invalidateByTags: (tags) => engine.invalidateByTags(tags),
+				bumpModelVersion: (model) => engine.bumpVersion(model),
+				clear: () => engine.clear()
+			};
+			for (const op of enabled) registerReadHooks(repo, op, engine, {
+				defaults,
+				perOpDefaults: perOpDefaults[op],
+				autoTagsFromScope,
+				log,
+				prefix,
+				repo,
+				shapeKeysByOp
+			});
+			for (const op of invalidating) registerInvalidationHooks(repo, op, engine, {
+				autoTagsFromScope,
+				log
+			});
+		}
+	};
+}
+//#endregion
+export { DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, cachePlugin };

package/dist/cache/plugin/invalidation-hooks.mjs

@@ -0,0 +1,35 @@
+import { HOOK_PRIORITY } from "../../hooks/priority.mjs";
+import { extractScopeTags, mergeTags, scopeKeyFromTags } from "../keys.mjs";
+import { ctx } from "./context.mjs";
+//#region src/cache/plugin/invalidation-hooks.ts
+/**
+* Write-side hook registration: `after:<op>` for every mutating op
+* bumps the model's version (per-scope when possible) and invalidates
+* the model-tag.
+*
+* **Targeted invalidation (TanStack `exact: true` semantic).** Writes
+* inside `org:abc` bump only that scope's version key, leaving
+* `org:xyz`'s cached reads hot. Falls back to a global bump when no
+* scope is present (single-tenant apps, public reads).
+*
+* **Cross-cutting tag invalidation runs alongside.** Hosts who tag
+* aggregations with the model name (default behavior — `'<model>'` is
+* always included) get implicit invalidation when any write to the
+* model lands, including writes in OTHER resources that auto-invalidate
+* by tag.
+*/
+function registerInvalidationHooks(repo, op, engine, hookCtx) {
+	repo.on(`after:${op}`, async (rawPayload) => {
+		const context = ctx(rawPayload.context);
+		const model = context["model"];
+		if (!model) return;
+		const scopeTags = hookCtx.autoTagsFromScope ? extractScopeTags(context) : [];
+		const scopeKey = scopeKeyFromTags(scopeTags);
+		const version = await engine.bumpVersion(model, scopeKey);
+		const tagsToInvalidate = mergeTags([model], scopeTags);
+		const count = await engine.invalidateByTags(tagsToInvalidate);
+		hookCtx.log.onInvalidate?.(model, version, count);
+	}, { priority: HOOK_PRIORITY.CACHE });
+}
+//#endregion
+export { registerInvalidationHooks };

package/dist/cache/plugin/read-hooks.mjs

@@ -0,0 +1,96 @@
+import { HOOK_PRIORITY } from "../../hooks/priority.mjs";
+import { buildCacheKey, extractScopeTags, mergeTags, scopeKeyFromTags } from "../keys.mjs";
+import { ctx, extractCallCacheOptions, extractShapeFields } from "./context.mjs";
+import { resolveCacheOptions } from "../options.mjs";
+import { scheduleSwrRefresh } from "./swr.mjs";
+//#region src/cache/plugin/read-hooks.ts
+/**
+* Read-side hook registration: `before:<op>` (cache check + single-
+* flight claim), `after:<op>` (cache write + resolve waiters), and
+* `error:<op>` (reject waiters fail-fast).
+*
+* All three hooks coordinate via typed slots on the shared context bag
+* (see `./context.ts`). The kit's read method short-circuits when
+* `_cacheHit === true` via `RepositoryBase._cachedValue<T>(context)`.
+*/
+function registerReadHooks(repo, op, engine, hookCtx) {
+	repo.on(`before:${op}`, registerBefore(op, engine, hookCtx), { priority: HOOK_PRIORITY.CACHE });
+	repo.on(`after:${op}`, registerAfter(op, engine, hookCtx), { priority: HOOK_PRIORITY.CACHE });
+	repo.on(`error:${op}`, registerError(engine), { priority: HOOK_PRIORITY.CACHE });
+}
+function registerBefore(op, engine, hookCtx) {
+	return async (rawContext) => {
+		const context = ctx(rawContext);
+		const resolved = resolveCacheOptions(extractCallCacheOptions(context, op), hookCtx.perOpDefaults, hookCtx.defaults);
+		if (!resolved.enabled) return;
+		const scopeTags = hookCtx.autoTagsFromScope ? extractScopeTags(context) : [];
+		const allTags = mergeTags(resolved.tags, scopeTags);
+		const key = resolved.key ?? await deriveKey(engine, op, context, scopeTags, hookCtx);
+		context._cacheKey = key;
+		context._cacheResolved = {
+			...resolved,
+			tags: allTags
+		};
+		const result = await engine.get(key, resolved);
+		if (result.status === "fresh" || result.status === "stale") {
+			context._cacheHit = true;
+			context._cachedResult = result.data;
+			context._cacheStatus = result.status;
+			if (result.status === "fresh") hookCtx.log.onHit?.(key, op, result.age ?? 0);
+			else hookCtx.log.onStale?.(key, op, result.age ?? 0);
+			return;
+		}
+		hookCtx.log.onMiss?.(key, op);
+		if (resolved.bypass) return;
+		const claim = engine.claimPending(key);
+		if (claim.status === "wait") try {
+			const data = await claim.promise;
+			context._cacheHit = true;
+			context._cachedResult = data;
+			context._cacheStatus = "fresh";
+			context._cacheCoalesced = true;
+			hookCtx.log.onCoalesce?.(key, op);
+		} catch {}
+	};
+}
+function registerAfter(op, engine, hookCtx) {
+	return async (rawPayload) => {
+		const payload = rawPayload;
+		const context = ctx(payload.context);
+		if (context._cacheHit === true && context._cacheStatus === "stale") {
+			scheduleSwrRefresh(op, hookCtx.repo, context);
+			return;
+		}
+		if (context._cacheHit === true && context._cacheStatus === "fresh") return;
+		const key = context._cacheKey;
+		const resolved = context._cacheResolved;
+		if (!key || !resolved) return;
+		await engine.set(key, payload.result, resolved);
+		engine.resolvePending(key, payload.result);
+		hookCtx.log.onWrite?.(key, op, resolved.tags);
+	};
+}
+function registerError(engine) {
+	return async (rawPayload) => {
+		const payload = rawPayload;
+		const key = ctx(payload.context)._cacheKey;
+		if (!key) return;
+		engine.rejectPending(key, payload.error);
+	};
+}
+async function deriveKey(engine, op, context, scopeTags, hookCtx) {
+	const model = context["model"] ?? "unknown";
+	const scopeKey = scopeKeyFromTags(scopeTags);
+	const version = await engine.getVersion(model, scopeKey);
+	const params = extractShapeFields(context, op, hookCtx.shapeKeysByOp);
+	return buildCacheKey({
+		prefix: engine.keyPrefix,
+		operation: op,
+		model,
+		version,
+		params: params ?? {},
+		scopeTags
+	});
+}
+//#endregion
+export { registerReadHooks };

package/dist/cache/plugin/swr.mjs

@@ -0,0 +1,20 @@
+import { AGGREGATE_OPS } from "./context.mjs";
+import { scheduleBackground } from "../runtime.mjs";
+//#region src/cache/plugin/swr.ts
+function scheduleSwrRefresh(op, repo, context) {
+	if (!AGGREGATE_OPS.has(op)) return;
+	const aggReq = context["aggRequest"];
+	if (!aggReq) return;
+	const refreshReq = {
+		...aggReq,
+		cache: {
+			...aggReq.cache ?? {},
+			bypass: true
+		}
+	};
+	scheduleBackground(() => {
+		repo[op]?.(refreshReq).catch(() => {});
+	});
+}
+//#endregion
+export { scheduleSwrRefresh };

package/dist/cache/runtime.d.mts

@@ -0,0 +1,43 @@
+//#region src/cache/runtime.d.ts
+/**
+ * Cross-runtime scheduling primitives.
+ *
+ * The cache layer targets every JS runtime kits + arc + Express/Nest
+ * hosts run on — Node, Bun, Deno Deploy, Cloudflare Workers, edge
+ * functions. Most Web-style APIs (`Map`, `Promise`, `setTimeout`,
+ * `BigInt`, `queueMicrotask`) are available across all of them, but
+ * `setImmediate` is Node-specific — Workers / Deno / browsers throw a
+ * `ReferenceError` if you call it.
+ *
+ * `scheduleBackground` resolves the right primitive at module load and
+ * exposes a single API the rest of the cache layer uses.
+ *
+ * **Semantics:**
+ *
+ * | Runtime     | Mechanism            | When the callback fires             |
+ * | ----------- | -------------------- | ----------------------------------- |
+ * | Node / Bun  | `setImmediate(fn)`   | After current I/O phase             |
+ * | Workers     | `setTimeout(fn, 0)`  | After current task (min 0ms)        |
+ * | Deno Deploy | `setTimeout(fn, 0)`  | After current task                  |
+ * | Browser     | `setTimeout(fn, 0)`  | After current task (clamped 4ms)    |
+ *
+ * Every runtime guarantees the callback runs AFTER the current sync
+ * block + any pending microtasks of the current task — which is the
+ * actual contract callers rely on (don't run the bg work synchronously
+ * in the response path).
+ *
+ * **Why not `queueMicrotask`?** Microtasks flush BEFORE the current
+ * I/O phase completes. For SWR, that means the bg refresh's first
+ * `await` could delay the user's HTTP response write. `setImmediate`
+ * (or `setTimeout(0)` on edge runtimes) defers past the I/O phase.
+ */
+/**
+ * Schedule a fire-and-forget callback to run after the current task.
+ *
+ * Used by SWR background refresh + (potentially) any future hook that
+ * wants "run after response" semantics. Caller is responsible for
+ * error handling — this helper does NOT add a default `.catch`.
+ */
+declare const scheduleBackground: (fn: () => void) => void;
+//#endregion
+export { scheduleBackground };

package/dist/cache/runtime.mjs

@@ -0,0 +1,14 @@
+/**
+* Schedule a fire-and-forget callback to run after the current task.
+*
+* Used by SWR background refresh + (potentially) any future hook that
+* wants "run after response" semantics. Caller is responsible for
+* error handling — this helper does NOT add a default `.catch`.
+*/
+const scheduleBackground = typeof globalThis.setImmediate === "function" ? (fn) => {
+	globalThis.setImmediate(fn);
+} : (fn) => {
+	setTimeout(fn, 0);
+};
+//#endregion
+export { scheduleBackground };