@classytic/repo-core 0.23.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/dist/cleanup/types.d.mts

@@ -85,10 +85,27 @@ interface CleanupStepExecuteContext extends CleanupStepContext {
  * One preview line — maps 1:1 onto a host plan item. A business record class
  * (`'sales facts'`, `'journal entries'`), never a collection name.
  */
+/**
+ * What a step's `estimated` COUNTS. Absent ⇒ `'remove'`.
+ *
+ * `destructive: false` is NOT a substitute: it is true of both a protective
+ * guard (counts records it defends) and a projection rebuild (counts records it
+ * recomputes), and those mean opposite things in a "records to remove" headline.
+ * A guard reporting 173 protected journal entries once pushed that headline to
+ * 540 on a plan that removed 367 — a plausible, internally consistent, wrong
+ * number shown at the exact moment an operator authorises destruction.
+ */
+type CleanupStepDisposition = 'remove' | 'protect' | 'rebuild';
 interface CleanupStepEstimate {
   readonly resource: string;
   /** Estimated records this step would affect. */
   readonly estimated: number;
+  /**
+   * Whether `estimated` counts records REMOVED, PROTECTED, or REBUILT.
+   * Defaults to `'remove'`, so every existing purge step is unchanged and only
+   * a step that means something else has to say so.
+   */
+  readonly disposition?: CleanupStepDisposition | undefined;
   /** What this step RETAINS (e.g. `'measures kept, PII redacted'`). */
   readonly retained?: string | undefined;
   /**
@@ -147,6 +164,22 @@ interface CleanupStep {
    * recipe is destructive iff ANY of its steps is.
    */
   readonly destructive: boolean;
+  /**
+   * What this step IS, declared once — not merely what one estimate counted.
+   *
+   * Needed at the STEP because a caller has to know a step is protective
+   * WITHOUT running it. A host resolving an operator's exclusion list must
+   * refuse to switch a guard off, and asking `estimate()` to find out would mean
+   * running the counting queries for a line that is being taken out — and
+   * surfacing that line's blockers, so excluding a domain could still be refused
+   * because of it.
+   *
+   * `destructive: false` is not the same question: it is true of a guard AND of
+   * a projection rebuild, and a rebuild is perfectly reasonable to exclude.
+   *
+   * An estimate may restate it; absent everywhere ⇒ `'remove'`.
+   */
+  readonly disposition?: CleanupStepDisposition | undefined;
   /**
    * Projection / scaffolding rebuilds this step performs AFTER its cleanup —
    * surfaced in the preview's `rebuildActions` (e.g. `'rebuild sales rollup'`).
@@ -164,4 +197,4 @@ interface CleanupStep {
   verify?(ctx: CleanupStepContext): Promise<readonly CleanupStepCheck[]>;
 }
 //#endregion
-export { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress };
+export { CleanupStep, CleanupStepCheck, CleanupStepContext, CleanupStepDisposition, CleanupStepEstimate, CleanupStepExecuteContext, CleanupStepLogger, CleanupStepOutcome, CleanupStepProgress };

package/dist/tenant/index.d.mts

@@ -1,3 +1,3 @@
 import { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy } from "./types.mjs";
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, resolveTenantConfig, resolveTenantField };
+import { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/dist/tenant/index.mjs

@@ -1,2 +1,2 @@
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };
+import { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.d.mts

@@ -28,5 +28,36 @@ declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedT
  * scoping" and all return `false` — callers get one thing to branch on.
  */
 declare function resolveTenantField(config?: TenantConfig | boolean): string | false;
+/**
+ * Refuse a config that still carries a pre-consolidation tenant key.
+ *
+ * ## Why this belongs in repo-core and not in each kernel
+ *
+ * Kernels are migrating from a per-package tenant shape (`multiTenant`, plus a
+ * sibling `tenantFieldType` in some) onto {@link TenantConfig} under the key
+ * `tenant`. `@classytic/ledger` has landed; catalog, order, cart, crm, flow,
+ * party, review, transfer and yard have adopted the TYPE but still read
+ * `multiTenant`. Each of those is a future rename.
+ *
+ * The rename itself is trivial. What is not trivial is the failure mode when a
+ * CALLER misses it, because every one of these resolvers reads
+ * `resolveTenantConfig(config.tenant ?? false)`: 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 gets none, silently.
+ *
+ * Nine packages each remembering to hand-roll that check is nine chances to
+ * forget, and the one that forgets is the one that ships the leak. So the guard
+ * lives beside the resolver every one of them already calls.
+ *
+ * Additive and non-breaking: nothing calls it until a package renames.
+ *
+ * @param config the raw, unresolved shape as the host supplied it
+ * @param pkg package name for the message (e.g. `'defineOrder'`)
+ * @param extra additional legacy keys this package is retiring, as
+ *   `[oldKey, newPath]` — pass `['tenantFieldType', 'tenant.fieldType']` when
+ *   the package carried a sibling field-type option.
+ */
+declare function assertNoLegacyTenantKeys(config: unknown, pkg: string, extra?: ReadonlyArray<readonly [string, string]>): void;
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };
+export { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.mjs

@@ -71,5 +71,44 @@ function resolveTenantField(config) {
 	if (!resolved.enabled || resolved.strategy === "none") return false;
 	return resolved.tenantField;
 }
+/**
+* Refuse a config that still carries a pre-consolidation tenant key.
+*
+* ## Why this belongs in repo-core and not in each kernel
+*
+* Kernels are migrating from a per-package tenant shape (`multiTenant`, plus a
+* sibling `tenantFieldType` in some) onto {@link TenantConfig} under the key
+* `tenant`. `@classytic/ledger` has landed; catalog, order, cart, crm, flow,
+* party, review, transfer and yard have adopted the TYPE but still read
+* `multiTenant`. Each of those is a future rename.
+*
+* The rename itself is trivial. What is not trivial is the failure mode when a
+* CALLER misses it, because every one of these resolvers reads
+* `resolveTenantConfig(config.tenant ?? false)`: 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 gets none, silently.
+*
+* Nine packages each remembering to hand-roll that check is nine chances to
+* forget, and the one that forgets is the one that ships the leak. So the guard
+* lives beside the resolver every one of them already calls.
+*
+* Additive and non-breaking: nothing calls it until a package renames.
+*
+* @param config the raw, unresolved shape as the host supplied it
+* @param pkg package name for the message (e.g. `'defineOrder'`)
+* @param extra additional legacy keys this package is retiring, as
+*   `[oldKey, newPath]` — pass `['tenantFieldType', 'tenant.fieldType']` when
+*   the package carried a sibling field-type option.
+*/
+function assertNoLegacyTenantKeys(config, pkg, extra = []) {
+	if (config === null || typeof config !== "object") return;
+	const record = config;
+	const retired = [["multiTenant", "tenant"], ...extra];
+	for (const [key, became] of retired) {
+		if (record[key] === void 0) continue;
+		throw new Error(`${pkg}: \`${key}\` was renamed to \`${became}\`. It is REFUSED rather than ignored because ignoring it disables tenancy SILENTLY — no tenant field, no tenant filter, and every read spanning all tenants while returning plausible numbers. Move the value to \`tenant\` (\`tenant: false\` for a single-tenant deployment).`);
+	}
+}
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };
+export { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.23.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,