@classytic/repo-core 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.25.0] - 2026-08-24
+
+### Added
+
+- **`CacheAdapterResolver = () => CacheAdapter | undefined`** — a function consulted per call that returns the store for the current scope, or `undefined` for "no cache right now". `undefined` is inert — identical to `enabled: false` — and never falls back to a shared store, because that fallback is the cross-scope leak the scoping exists to prevent.
+- **`CacheAdapterSource = CacheAdapter | CacheAdapterResolver`** — `CacheEngine` and `cachePlugin` now accept either a fixed process-lifetime adapter (unchanged behaviour) or a resolver. A bare adapter is sugar for `() => adapter`; normalised at construction so every call site is on one path.
+- **`CacheAdapterResolver` and `CacheAdapterSource` exported from `@classytic/repo-core/cache`** and re-exported from the plugin index.
+
+## [0.24.0] - 2026-08-17
+
+Version bump only — republished 0.23.1's contents under a minor so consumers pinning `>=0.24.0` get the tenant guard by a floor rather than a patch. No source changes over 0.23.1.
+
+## [0.23.1] - 2026-08-17
+
+### Added — `assertNoLegacyTenantKeys(config, pkg, extra?)` (`/tenant`)
+
+Refuses a config still carrying a pre-consolidation tenant key (`multiTenant`, plus any package-specific retirees passed via `extra`) instead of ignoring it.
+
+The rename onto `TenantConfig` under `tenant` is trivial; the failure mode when a CALLER misses it is not. Every kernel resolver reads `resolveTenantConfig(config.tenant ?? false)`, so an absent `tenant` resolves to `strategy: 'none'` — no tenant field, no tenant filter, every read spanning ALL tenants, no error, and figures that look plausible. A host that asked for tenancy silently gets none.
+
+The guard lives beside the resolver every one of those packages already calls, rather than being hand-rolled nine times — nine chances to forget, and the one that forgets ships the leak. Additive and non-breaking: nothing calls it until a package renames.
+
 ## [0.23.0] - 2026-08-13
 
 ### Added — transactional-core contracts (Phase 1a + 1d) + fencing (Phase 2, first slice)

package/dist/cache/engine.d.mts

@@ -22,8 +22,36 @@ type SingleFlightClaim<T = unknown> = {
   readonly status: 'wait';
   readonly promise: Promise<T>;
 };
+/**
+ * Resolve the adapter to use for THIS call, or `undefined` for "no cache
+ * right now".
+ *
+ * Exists so a cache can be scoped to something narrower than the process —
+ * a request, a job run, a unit of work — without this package learning what
+ * any of those are. The resolver is the whole seam: repo-core asks "is there
+ * a store for the current scope?", and whoever owns the lifecycle answers.
+ *
+ * **`undefined` must mean INERT, never "make one".** A resolver that returns
+ * nothing outside its scope is the correct, safe answer for cron jobs,
+ * scripts and tests — the alternative (falling back to a process-wide store)
+ * is exactly the cross-request leak the scoping exists to prevent, and it
+ * would be invisible.
+ */
+type CacheAdapterResolver = () => CacheAdapter | undefined;
+/**
+ * Either a fixed adapter (process-lifetime, the original contract) or a
+ * resolver consulted per call. A bare adapter is sugar for `() => adapter`.
+ */
+type CacheAdapterSource = CacheAdapter | CacheAdapterResolver;
 declare class CacheEngine {
-  private readonly adapter;
+  /**
+   * Consulted PER CALL, never cached in a field.
+   *
+   * Memoising the first resolution would defeat the entire purpose: the
+   * second request would be served the first request's store. The whole
+   * point of the indirection is that the answer changes.
+   */
+  private readonly resolveAdapter;
   private readonly prefix;
   private readonly jitter;
   /**
@@ -34,7 +62,7 @@ declare class CacheEngine {
    * unbounded burst).
    */
   private readonly pending;
-  constructor(adapter: CacheAdapter, options?: CacheEngineOptions);
+  constructor(adapter: CacheAdapterSource, options?: CacheEngineOptions);
   /**
    * Read a cache entry under SWR + TTL semantics. Returns a
    * structured `CacheReadResult` describing freshness state — the
@@ -123,4 +151,4 @@ declare class CacheEngine {
   prefetch<TData>(key: string, opts: ResolvedCacheOptions, fetcher: () => Promise<TData>): Promise<TData>;
 }
 //#endregion
-export { CacheEngine, CacheEngineOptions, SingleFlightClaim };
+export { CacheAdapterResolver, CacheAdapterSource, CacheEngine, CacheEngineOptions, SingleFlightClaim };

package/dist/cache/engine.mjs

@@ -24,7 +24,14 @@ import { bumpModelVersion, getModelVersion } from "./version-store.mjs";
 * call it directly when they need fine-grained control.
 */
 var CacheEngine = class {
-	adapter;
+	/**
+	* Consulted PER CALL, never cached in a field.
+	*
+	* Memoising the first resolution would defeat the entire purpose: the
+	* second request would be served the first request's store. The whole
+	* point of the indirection is that the answer changes.
+	*/
+	resolveAdapter;
 	prefix;
 	jitter;
 	/**
@@ -36,7 +43,7 @@ var CacheEngine = class {
 	*/
 	pending = /* @__PURE__ */ new Map();
 	constructor(adapter, options = {}) {
-		this.adapter = adapter;
+		this.resolveAdapter = typeof adapter === "function" ? adapter : () => adapter;
 		this.prefix = options.prefix ?? "rc";
 		this.jitter = resolveJitter(options.jitter);
 	}
@@ -62,7 +69,12 @@ var CacheEngine = class {
 			status: "bypass",
 			data: void 0
 		};
-		const raw = await this.adapter.get(key);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return {
+			status: "disabled",
+			data: void 0
+		};
+		const raw = await adapter.get(key);
 		const inspection = inspectEnvelope(raw);
 		if (inspection.state === "missing" || inspection.state === "expired") return {
 			status: "miss",
@@ -98,12 +110,14 @@ var CacheEngine = class {
 	*/
 	async set(key, value, opts) {
 		if (!opts.enabled) return;
+		const adapter = this.resolveAdapter();
+		if (!adapter) return;
 		const tags = opts.tags;
 		const envelope = buildEnvelope(value, opts.staleTime, opts.gcTime, tags);
 		const totalSeconds = opts.staleTime + opts.gcTime;
 		const ttl = this.jitter(totalSeconds);
-		await this.adapter.set(key, envelope, ttl);
-		if (tags.length > 0) await appendKeyToTags(this.adapter, this.prefix, key, tags, ttl);
+		await adapter.set(key, envelope, ttl);
+		if (tags.length > 0) await appendKeyToTags(adapter, this.prefix, key, tags, ttl);
 	}
 	/**
 	* Look up an in-flight fetch for `key`. Returns the promise the
@@ -157,7 +171,9 @@ var CacheEngine = class {
 	* the index. Returns the count of entries removed.
 	*/
 	async invalidateByTags(tags) {
-		return invalidateByTags(this.adapter, this.prefix, tags);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return 0;
+		return invalidateByTags(adapter, this.prefix, tags);
 	}
 	/**
 	* Read a model's current version (optionally per-scope). Used by
@@ -165,7 +181,9 @@ var CacheEngine = class {
 	* version bump orphans the model's cache space.
 	*/
 	async getVersion(model, scopeKey) {
-		return getModelVersion(this.adapter, this.prefix, model, scopeKey);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return 0;
+		return getModelVersion(adapter, this.prefix, model, scopeKey);
 	}
 	/**
 	* Bump the model's version (per-scope when `scopeKey` is supplied)
@@ -174,11 +192,15 @@ var CacheEngine = class {
 	* invalidation.
 	*/
 	async bumpVersion(model, scopeKey) {
-		return bumpModelVersion(this.adapter, this.prefix, model, scopeKey);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return 0;
+		return bumpModelVersion(adapter, this.prefix, model, scopeKey);
 	}
 	/** Wipe the entire cache namespace (when the adapter supports `clear`). */
 	async clear() {
-		if (this.adapter.clear) await this.adapter.clear(`${this.prefix}:*`);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return;
+		if (adapter.clear) await adapter.clear(`${this.prefix}:*`);
 	}
 	/** Expose the prefix so plugins building keys downstream stay aligned. */
 	get keyPrefix() {

package/dist/cache/index.d.mts

@@ -1,9 +1,9 @@
 import { CacheOptions, CacheReadResult } from "./options.mjs";
 import { CacheAdapter } from "./types.mjs";
-import { CacheEngine, CacheEngineOptions, SingleFlightClaim } from "./engine.mjs";
+import { CacheAdapterResolver, CacheAdapterSource, CacheEngine, CacheEngineOptions, SingleFlightClaim } from "./engine.mjs";
 import { MemoryCacheAdapterOptions, createMemoryCacheAdapter } from "./memory-adapter.mjs";
 import { DEFAULT_SHAPE_KEYS_BY_OP } from "./plugin/context.mjs";
 import { DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, LogCallbacks, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin } from "./plugin/index.mjs";
 import { scheduleBackground } from "./runtime.mjs";
 import { CacheTimeoutError, TimeoutAdapterOptions, withTimeout } from "./timeout-adapter.mjs";
-export { type CacheAdapter, CacheEngine, type CacheEngineOptions, type CacheOptions, type CacheReadResult, CacheTimeoutError, DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, DEFAULT_SHAPE_KEYS_BY_OP, type LogCallbacks, type MemoryCacheAdapterOptions, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type SingleFlightClaim, type TimeoutAdapterOptions, cachePlugin, createMemoryCacheAdapter, scheduleBackground, withTimeout };
+export { type CacheAdapter, type CacheAdapterResolver, type CacheAdapterSource, CacheEngine, type CacheEngineOptions, type CacheOptions, type CacheReadResult, CacheTimeoutError, DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, DEFAULT_SHAPE_KEYS_BY_OP, type LogCallbacks, type MemoryCacheAdapterOptions, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type SingleFlightClaim, type TimeoutAdapterOptions, cachePlugin, createMemoryCacheAdapter, scheduleBackground, withTimeout };

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

@@ -1,7 +1,6 @@
 import { Plugin } from "../../repository/plugin-types.mjs";
 import { CacheOptions, CacheReadResult } from "../options.mjs";
-import { CacheAdapter } from "../types.mjs";
-import { CacheEngine } from "../engine.mjs";
+import { CacheAdapterSource, 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. */
@@ -24,8 +23,27 @@ interface LogCallbacks {
   onInvalidate?: (model: string, version: number, tagCount: number) => void;
 }
 interface RepositoryCachePluginOptions {
-  /** Concrete adapter — Redis, in-memory, custom KV. */
-  readonly adapter: CacheAdapter;
+  /**
+   * Concrete adapter — Redis, in-memory, custom KV — OR a resolver consulted
+   * per call that returns the store for the current scope.
+   *
+   * The resolver form is what makes a cache narrower than the process
+   * possible (per-request, per-job, per-unit-of-work) without this package
+   * knowing what those are. Returning `undefined` means "no cache right now"
+   * and the call behaves exactly as `enabled: false` — it does not fall back
+   * to a shared store, because that fallback IS the cross-scope leak the
+   * scoping exists to prevent.
+   *
+   * @example Process-lifetime (unchanged)
+   * ```ts
+   * cachePlugin({ adapter: createMemoryCacheAdapter() })
+   * ```
+   * @example Request-scoped — dies with the request, no TTL needed
+   * ```ts
+   * cachePlugin({ adapter: () => requestScopedCache() })
+   * ```
+   */
+  readonly adapter: CacheAdapterSource;
   /** 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`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,