@classytic/repo-core 0.3.0 → 0.4.0

package/dist/cache/keys.mjs

@@ -0,0 +1,131 @@
+import { stableStringify } from "./stable-stringify.mjs";
+//#region src/cache/keys.ts
+/**
+* Cache key derivation. Builds stable keys from operation context so
+* any kit + arc + Express/Nest hosts compute the same key for the
+* same logical request — letting one Redis serve a mixed-kit fleet.
+*
+* **Key shape:**
+*   `<prefix>:<op>:<model>:v<version>:<paramsHash>:<scopeHash>`
+*
+*   - `prefix`     — tenant of the cache namespace (`'rc'` default)
+*   - `op`         — repository operation name (`getById`, `aggregate`, ...)
+*   - `model`      — the entity model name
+*   - `version`    — collection version (bumped on writes; orphans all
+*                    keys for the model in O(1)). Per-scope when the
+*                    plugin extracts a scopeKey.
+*   - `paramsHash` — fnv1a64 of stable-stringified call params
+*                    (filter, id, sort, kit-specific options like
+*                    `lean`). The plugin's per-op allowlist decides
+*                    which fields participate.
+*   - `scopeHash`  — short hash of the auto-extracted scope tags
+*                    (`org:<id>` / `user:<id>`). Keeps the key short
+*                    while preserving cross-tenant isolation.
+*/
+/** Build the canonical cache key. */
+function buildCacheKey(input) {
+	const paramsHash = fnv1a64(stableStringify(input.params));
+	const scopeHash = input.scopeTags.length > 0 ? fnv1a64(input.scopeTags.join("|")) : "0";
+	return `${input.prefix}:${input.operation}:${input.model}:v${input.version}:${paramsHash}:${scopeHash}`;
+}
+/** Tag-index key — maps a tag to the set of cache keys carrying it. */
+function tagIndexKey(prefix, tag) {
+	return `${prefix}:tag:${tag}`;
+}
+/**
+* Collection-version key — bumped on writes to orphan all reads.
+*
+* Per-scope sharding when `scopeKey` is supplied — e.g. `'org:abc'`
+* keys to `<prefix>:ver:<model>:org:abc`, so writes inside `org:abc`
+* don't invalidate other tenants' cached reads. Without a scopeKey
+* the version is global (legacy semantic — invalidates all reads on
+* any write).
+*/
+function versionKey(prefix, model, scopeKey) {
+	return scopeKey ? `${prefix}:ver:${model}:${scopeKey}` : `${prefix}:ver:${model}`;
+}
+/**
+* Build a deterministic scope-key string from extracted scope tags.
+* Used to suffix `versionKey` so per-scope invalidation works.
+*
+* Returns `undefined` when no scope is present — caller falls back to
+* global version semantics.
+*/
+function scopeKeyFromTags(scopeTags) {
+	if (scopeTags.length === 0) return void 0;
+	return [...scopeTags].sort().join("|");
+}
+/**
+* Merge two tag lists, preserving first-seen order and deduping. Used
+* by the plugin to combine caller-supplied tags with auto-derived
+* scope tags into a single index-able set.
+*/
+function mergeTags(a, b) {
+	if (a.length === 0) return b;
+	if (b.length === 0) return a;
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const t of a) if (!seen.has(t)) {
+		seen.add(t);
+		out.push(t);
+	}
+	for (const t of b) if (!seen.has(t)) {
+		seen.add(t);
+		out.push(t);
+	}
+	return out;
+}
+/**
+* Extract scope tags from a hook context. Reads the canonical fields
+* multi-tenant + auth plugins inject (`organizationId`, `userId`).
+* Returns an empty array when no scope is present — public reads share
+* one cache slot.
+*
+* Looks at THREE locations in priority order:
+*   1. `context.filter.<field>`    — multi-tenant injects here
+*   2. `context.options.<field>`   — kit options bag (arc audit attribution)
+*   3. `context.<field>`           — top-level fallback
+*/
+function extractScopeTags(context) {
+	if (!context) return [];
+	const tags = [];
+	const orgId = pickScopeField(context, "organizationId");
+	if (orgId) tags.push(`org:${orgId}`);
+	const userId = pickScopeField(context, "userId");
+	if (userId) tags.push(`user:${userId}`);
+	return tags;
+}
+function pickScopeField(context, field) {
+	const filter = context["filter"];
+	if (filter && typeof filter[field] === "string") return filter[field];
+	const options = context["options"];
+	if (options && typeof options[field] === "string") return options[field];
+	if (typeof context[field] === "string") return context[field];
+}
+/**
+* FNV-1a 64-bit — non-cryptographic hash for cache-key shortening.
+* Emits stable base-36 strings (≤13 chars) for compact keys.
+*
+* **Why 64-bit, not 32-bit:** djb2 32-bit (~4B value space) hits ~50%
+* birthday-paradox collision probability around √(2^32) ≈ 65k distinct
+* keys — easily exceeded by a multi-tenant fleet. FNV-1a 64-bit pushes
+* that threshold to ~4B keys, which no realistic cache approaches.
+* Both are non-cryptographic; FNV-1a has better avalanche on short
+* ASCII strings (cache keys).
+*
+* BigInt is required — JS numbers lose precision past 2^53. The cost
+* is negligible at cache-key sizes (key strings are typically <1KB).
+*/
+const FNV_OFFSET_64 = 14695981039346656037n;
+const FNV_PRIME_64 = 1099511628211n;
+const FNV_MASK_64 = 18446744073709551615n;
+function fnv1a64(str) {
+	let hash = FNV_OFFSET_64;
+	for (let i = 0; i < str.length; i++) {
+		hash ^= BigInt(str.charCodeAt(i));
+		hash = hash * FNV_PRIME_64 & FNV_MASK_64;
+	}
+	return hash.toString(36);
+}
+//#endregion
+export { buildCacheKey, extractScopeTags, mergeTags, scopeKeyFromTags, tagIndexKey, versionKey };

package/dist/cache/memory-adapter.mjs

@@ -3,15 +3,20 @@
 function createMemoryCacheAdapter() {
 	const store = /* @__PURE__ */ new Map();
 	const now = () => Date.now();
+	function readUnexpired(key) {
+		const entry = store.get(key);
+		if (!entry) return void 0;
+		if (entry.expiresAt !== 0 && entry.expiresAt < now()) {
+			store.delete(key);
+			return;
+		}
+		return entry;
+	}
 	return {
 		get(key) {
-			const entry = store.get(key);
-			if (!entry) return void 0;
-			if (entry.expiresAt !== 0 && entry.expiresAt < now()) {
-				store.delete(key);
-				return;
-			}
-			return entry.value;
+			const value = readUnexpired(key)?.value;
+			if (value instanceof Set) return Array.from(value);
+			return value;
 		},
 		set(key, value, ttlSeconds = 60) {
 			const expiresAt = ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3;
@@ -30,6 +35,35 @@ function createMemoryCacheAdapter() {
 			}
 			const prefix = pattern.endsWith("*") ? pattern.slice(0, -1) : pattern;
 			for (const key of store.keys()) if (key.startsWith(prefix)) store.delete(key);
+		},
+		addToSet(key, members, ttlSeconds = 60) {
+			const existing = readUnexpired(key);
+			let set;
+			if (existing && existing.value instanceof Set) set = existing.value;
+			else {
+				set = /* @__PURE__ */ new Set();
+				const expiresAt = existing?.expiresAt ?? (ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3);
+				store.set(key, {
+					value: set,
+					expiresAt
+				});
+			}
+			let added = 0;
+			for (const m of members) if (!set.has(m)) {
+				set.add(m);
+				added++;
+			}
+			return added;
+		},
+		increment(key, by = 1, ttlSeconds = 60) {
+			const existing = readUnexpired(key);
+			const next = (existing && typeof existing.value === "number" && Number.isFinite(existing.value) ? existing.value : 0) + by;
+			const expiresAt = existing ? existing.expiresAt : ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3;
+			store.set(key, {
+				value: next,
+				expiresAt
+			});
+			return next;
 		}
 	};
 }

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 };