@classytic/repo-core 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.22.0] - 2026-08-12
+
+### Added — `pages: 0` conformance tests for empty results
+
+- `runStandardRepoConformance` now asserts `pages: 0` for empty offset envelopes (both the primary `getAll` path and the `aggregatePaginate` path). The field had no assertion anywhere in the suite; two kit paths diverged silently: the primary offset path computed `ceil(0/limit) = 0` while aggregate and lookup paths used `Math.max(1, ceil(...)) = 1`. The contract is `0` — zero rows fill zero pages — and it is what every kit's primary path already returned. The missing assertion let the drift reach a consumer as golden-fixture breakage when a `lookups` join rerouted a list read onto the divergent path.
+
+## [0.21.0] - 2026-08-10
+
+### Added — LRU-bounded `createMemoryCacheAdapter`
+
+- `createMemoryCacheAdapter(options?)` now accepts `MemoryCacheAdapterOptions` with a `maxEntries` cap (default `10,000`). Past the cap the least-recently-used entry is evicted — read promotion (delete + re-insert) keeps the map ordered by recency so eviction is O(1). A TTL alone does not bound the map: entries only expire when read, so a high-cardinality keyspace (per-tenant, per-commit, per-filter keys) grows monotonically until the process dies. Eviction is always safe for a cache, so the bound is on by default. Set `maxEntries: 0` to restore the previous unbounded behaviour.
+- `MemoryCacheAdapterOptions` exported from `@classytic/repo-core/cache`.
+
+### Added — timezone-aware date buckets (`AggDateBucket.timezone`)
+
+- `AggDateBucket.timezone` — IANA zone the bucket boundaries are drawn in; absent means UTC. A UTC day is not a business day in any non-UTC deployment: rows from 18:00 to midnight local fall in the previous UTC day, silently reporting the wrong period in daily/monthly rollups.
+- `AggregateOpsSupport.dateBucketTimezone` capability flag — a kit that cannot draw DST-correct boundaries (e.g. SQLite, no tz database) MUST declare `dateBucketTimezone: false` and throw when the field is set rather than silently bucketing in UTC. Mongokit (`$dateTrunc` / `$dateToString` both accept `timezone`) declares `true`.
+
 ## [0.20.0] - 2026-08-04
 
 ### Added

package/dist/cache/engine.mjs

@@ -62,7 +62,8 @@ var CacheEngine = class {
 			status: "bypass",
 			data: void 0
 		};
-		const inspection = inspectEnvelope(await this.adapter.get(key));
+		const raw = await this.adapter.get(key);
+		const inspection = inspectEnvelope(raw);
 		if (inspection.state === "missing" || inspection.state === "expired") return {
 			status: "miss",
 			data: void 0

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 { createMemoryCacheAdapter } from "./memory-adapter.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 RepositoryCacheHandle, type RepositoryCachePluginOptions, type SingleFlightClaim, type TimeoutAdapterOptions, cachePlugin, createMemoryCacheAdapter, scheduleBackground, withTimeout };
+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 };

package/dist/cache/memory-adapter.d.mts

@@ -1,6 +1,24 @@
 import { CacheAdapter } from "./types.mjs";
 //#region src/cache/memory-adapter.d.ts
-/** Minimal in-memory `Map`-backed adapter with per-key TTL + prefix invalidation. */
-declare function createMemoryCacheAdapter(): CacheAdapter;
+interface MemoryCacheAdapterOptions {
+  /**
+   * Hard entry ceiling; the least-recently-used entry is evicted past it.
+   * Default 10,000.
+   *
+   * A TTL alone does not bound a cache. Entries only expire when someone reads
+   * them, and a workload with high key cardinality (per-tenant keys, per-commit
+   * keys, per-filter query keys) mints faster than it re-reads, so the map grows
+   * monotonically until the process dies. Eviction is always semantically safe
+   * for a cache — a miss is a correct answer — so this is on by default rather
+   * than opt-in.
+   *
+   * Set `0` for the previous unbounded behaviour. Only do that if something else
+   * in your process bounds the keyspace.
+   */
+  maxEntries?: number;
+}
+/** Minimal in-memory `Map`-backed adapter with per-key TTL, LRU eviction and
+ *  prefix invalidation. */
+declare function createMemoryCacheAdapter(options?: MemoryCacheAdapterOptions): CacheAdapter;
 //#endregion
-export { createMemoryCacheAdapter };
+export { MemoryCacheAdapterOptions, createMemoryCacheAdapter };

package/dist/cache/memory-adapter.mjs

@@ -1,8 +1,20 @@
 //#region src/cache/memory-adapter.ts
-/** Minimal in-memory `Map`-backed adapter with per-key TTL + prefix invalidation. */
-function createMemoryCacheAdapter() {
+/** Minimal in-memory `Map`-backed adapter with per-key TTL, LRU eviction and
+*  prefix invalidation. */
+function createMemoryCacheAdapter(options = {}) {
+	const maxEntries = options.maxEntries ?? 1e4;
 	const store = /* @__PURE__ */ new Map();
 	const now = () => Date.now();
+	/** Map iteration order is insertion order, so re-inserting on read makes the
+	*  first key the least-recently-used one. */
+	function evictIfNeeded() {
+		if (maxEntries <= 0) return;
+		while (store.size > maxEntries) {
+			const oldest = store.keys().next().value;
+			if (oldest === void 0) return;
+			store.delete(oldest);
+		}
+	}
 	function readUnexpired(key) {
 		const entry = store.get(key);
 		if (!entry) return void 0;
@@ -10,6 +22,8 @@ function createMemoryCacheAdapter() {
 			store.delete(key);
 			return;
 		}
+		store.delete(key);
+		store.set(key, entry);
 		return entry;
 	}
 	return {
@@ -20,10 +34,12 @@ function createMemoryCacheAdapter() {
 		},
 		set(key, value, ttlSeconds = 60) {
 			const expiresAt = ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3;
+			store.delete(key);
 			store.set(key, {
 				value,
 				expiresAt
 			});
+			evictIfNeeded();
 		},
 		delete(key) {
 			store.delete(key);
@@ -54,6 +70,7 @@ function createMemoryCacheAdapter() {
 					value: set,
 					expiresAt
 				});
+				evictIfNeeded();
 			}
 			let added = 0;
 			for (const m of members) if (!set.has(m)) {
@@ -76,6 +93,7 @@ function createMemoryCacheAdapter() {
 				value: next,
 				expiresAt
 			});
+			evictIfNeeded();
 			return next;
 		}
 	};

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

@@ -21,7 +21,8 @@ function registerReadHooks(repo, op, engine, hookCtx) {
 function registerBefore(op, engine, hookCtx) {
 	return async (rawContext) => {
 		const context = ctx(rawContext);
-		const resolved = resolveCacheOptions(extractCallCacheOptions(context, op), hookCtx.perOpDefaults, hookCtx.defaults);
+		const callOpts = extractCallCacheOptions(context, op);
+		const resolved = resolveCacheOptions(callOpts, hookCtx.perOpDefaults, hookCtx.defaults);
 		if (!resolved.enabled) return;
 		const scopeTags = hookCtx.autoTagsFromScope ? extractScopeTags(context) : [];
 		const allTags = mergeTags(resolved.tags, scopeTags);

package/dist/cache/tag-index.mjs

@@ -42,7 +42,7 @@ import { tagIndexKey } from "./keys.mjs";
 */
 async function appendKeyToTags(adapter, prefix, cacheKey, tags, ttlSeconds) {
 	if (tags.length === 0) return;
-	const indexTtl = Math.min(Math.max(ttlSeconds, 60), 1440 * 60);
+	const indexTtl = Math.min(Math.max(ttlSeconds, 60), 86400);
 	if (adapter.addToSet) {
 		const fn = adapter.addToSet.bind(adapter);
 		await Promise.all(tags.map((tag) => fn(tagIndexKey(prefix, tag), [cacheKey], indexTtl)));

package/dist/cache/version-store.mjs

@@ -23,7 +23,7 @@ import { versionKey } from "./keys.mjs";
 * advance the counter (atomic path is naturally monotonic via
 * adapter.increment).
 */
-const VERSION_TTL_SECONDS = 1440 * 60;
+const VERSION_TTL_SECONDS = 86400;
 /**
 * Read the current version for a `model` (optionally per-scope). Returns
 * `0` when no version has been set yet — the initial value before any

package/dist/errors/duplicate-key.mjs

@@ -46,7 +46,8 @@ const conservativeMongoIsDuplicateKey = (err) => {
 function toDuplicateKeyHttpError(meta, options = {}) {
 	const exposed = options.exposeValues === true;
 	const valuesString = exposed && meta.values ? Object.entries(meta.values).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ") : "";
-	const httpError = createError(409, meta.fields.length ? `Duplicate value for ${meta.fields.join(", ")}${valuesString ? ` (${valuesString})` : ""}` : "Duplicate key error");
+	const detail = meta.fields.length ? `Duplicate value for ${meta.fields.join(", ")}${valuesString ? ` (${valuesString})` : ""}` : "Duplicate key error";
+	const httpError = createError(409, detail);
 	httpError.duplicate = {
 		fields: meta.fields,
 		...exposed && meta.values ? { values: { ...meta.values } } : {}

package/dist/filter/from-record.mjs

@@ -104,9 +104,7 @@ function leafFromRecord(field, value) {
 		case "endsWith":
 			ops.push(endsWith(field, v));
 			break;
-		case "exists":
-			ops.push(v ? isNotNull(field) : isNull(field));
-			break;
+		case "exists": ops.push(v ? isNotNull(field) : isNull(field));
 	}
 	if (ops.length === 0) return TRUE;
 	if (ops.length === 1) return ops[0];

package/dist/filter/match.mjs

@@ -180,7 +180,7 @@ function getOrCompileRegex(pattern, flags) {
 * filters never regex-test megabyte fields. (Trusted-source patterns make
 * pattern-side ReDoS a non-issue; this caps the input side.)
 */
-const MAX_REGEX_INPUT = 64 * 1024;
+const MAX_REGEX_INPUT = 65536;
 /** Guarded regex test: string-only, input-length-capped (see MAX_REGEX_INPUT). */
 function regexTest(re, v) {
 	return typeof v === "string" && v.length <= MAX_REGEX_INPUT && re.test(v);

package/dist/repository/capabilities.d.mts

@@ -52,6 +52,15 @@ interface AggregateOpsSupport {
    * equivalents.
    */
   topN?: boolean;
+  /**
+   * `AggDateBucket.timezone` — bucket boundaries drawn in an IANA zone
+   * rather than UTC. Mongokit supports it natively (`$dateTrunc` /
+   * `$dateToString` both take `timezone`). SQLite has no tz database, so
+   * sqlitekit cannot draw DST-correct boundaries and MUST THROW rather
+   * than silently bucketing in UTC — a wrong-period number that looks
+   * right is worse than a refusal.
+   */
+  dateBucketTimezone?: boolean;
   /**
    * `dateBuckets: { ..., interval: { every, unit } }` custom-bin
    * form. Kits that only support named-bucket form can leave this

package/dist/repository/types.d.mts

@@ -919,6 +919,23 @@ interface AggDateBucket {
   field: string;
   /** Bucket granularity. */
   interval: AggDateBucketInterval;
+  /**
+   * IANA zone the bucket boundaries are drawn in. Absent means UTC.
+   *
+   * A UTC day is not a BUSINESS day. In a UTC+6 deployment every row from
+   * 18:00 to midnight local falls in the PREVIOUS UTC day, and at month-end in
+   * the previous month — so a daily or monthly rollup silently reports the
+   * wrong period. Nothing throws; the chart simply draws the wrong day. The
+   * absence of this field is why every business-day rollup had to abandon the
+   * portable IR and hand-roll a kit-native pipeline, and hand-rolling made the
+   * zone optional again.
+   *
+   * REQUIRES the `dateBucketTimezone` capability. A kit that cannot draw
+   * DST-correct boundaries (SQLite has no tz database) MUST THROW when this is
+   * set — never fall back to UTC. Falling back returns a plausible number for
+   * the wrong period, which is the failure this field exists to prevent.
+   */
+  timezone?: string;
 }
 /**
  * Portable aggregation request. Compiles to SQL (`SELECT ... FROM ...

package/dist/testing/conformance.mjs

@@ -69,22 +69,26 @@ function runStandardRepoConformance(harness) {
 				expect(fetched?.createdAt).toBe(isoAt(0));
 			});
 			it("getById miss returns null", async () => {
-				expect(await ctx.repo.getById("does-not-exist-xyz")).toBeNull();
+				const result = await ctx.repo.getById("does-not-exist-xyz");
+				expect(result).toBeNull();
 			});
 			it("update by id returns updated doc; miss returns null", async () => {
 				const id = idOf(await ctx.repo.create(harness.makeDoc({
 					name: "Bob",
 					count: 1
 				})), harness.idField);
-				expect((await ctx.repo.update(id, { count: 99 }))?.count).toBe(99);
-				expect(await ctx.repo.update("no-such-id", { count: 1 })).toBeNull();
+				const updated = await ctx.repo.update(id, { count: 99 });
+				expect(updated?.count).toBe(99);
+				const miss = await ctx.repo.update("no-such-id", { count: 1 });
+				expect(miss).toBeNull();
 			});
 			it("delete by id succeeds; second delete returns null (miss)", async () => {
 				const id = idOf(await ctx.repo.create(harness.makeDoc({ name: "Carol" })), harness.idField);
 				const first = await ctx.repo.delete(id);
 				expect(first).not.toBeNull();
 				expect(first?.message).toBeDefined();
-				expect(await ctx.repo.delete(id)).toBeNull();
+				const second = await ctx.repo.delete(id);
+				expect(second).toBeNull();
 			});
 		});
 		describe("findOneAndUpdate", () => {
@@ -118,11 +122,13 @@ function runStandardRepoConformance(harness) {
 			});
 			it("returnDocument: \"before\" returns pre-update state", async () => {
 				if (!ctx.repo.findOneAndUpdate) return;
-				expect((await ctx.repo.findOneAndUpdate({ name: "u2" }, { category: "archived" }, { returnDocument: "before" }))?.category).toBe("reader");
+				const before = await ctx.repo.findOneAndUpdate({ name: "u2" }, { category: "archived" }, { returnDocument: "before" });
+				expect(before?.category).toBe("reader");
 			});
 			it("no match, no upsert → returns null", async () => {
 				if (!ctx.repo.findOneAndUpdate) return;
-				expect(await ctx.repo.findOneAndUpdate({ name: "does-not-exist" }, { category: "x" })).toBeNull();
+				const result = await ctx.repo.findOneAndUpdate({ name: "does-not-exist" }, { category: "x" });
+				expect(result).toBeNull();
 			});
 			it.skipIf(!harness.features.upsert)("upsert inserts when no row matches", async () => {
 				if (!ctx.repo.findOneAndUpdate) return;
@@ -161,7 +167,8 @@ function runStandardRepoConformance(harness) {
 				const result = await ctx.repo.updateMany({ category: "reader" }, { category: "former-reader" });
 				expect(result.matchedCount).toBe(2);
 				expect(result.modifiedCount).toBe(2);
-				expect(await ctx.repo.findAll({ category: "admin" })).toHaveLength(1);
+				const admins = await ctx.repo.findAll({ category: "admin" });
+				expect(admins).toHaveLength(1);
 			});
 			it("updateMany with no match returns matchedCount 0", async () => {
 				if (!ctx.repo.updateMany) return;
@@ -171,12 +178,15 @@ function runStandardRepoConformance(harness) {
 			});
 			it("deleteMany removes matching rows and reports count", async () => {
 				if (!ctx.repo.deleteMany) return;
-				expect((await ctx.repo.deleteMany({ category: "reader" }, { mode: "hard" })).deletedCount).toBe(2);
-				expect(await ctx.repo.findAll()).toHaveLength(1);
+				const result = await ctx.repo.deleteMany({ category: "reader" }, { mode: "hard" });
+				expect(result.deletedCount).toBe(2);
+				const remaining = await ctx.repo.findAll();
+				expect(remaining).toHaveLength(1);
 			});
 			it("deleteMany with empty match returns deletedCount 0", async () => {
 				if (!ctx.repo.deleteMany) return;
-				expect((await ctx.repo.deleteMany({ category: "nope" }, { mode: "hard" })).deletedCount).toBe(0);
+				const result = await ctx.repo.deleteMany({ category: "nope" }, { mode: "hard" });
+				expect(result.deletedCount).toBe(0);
 			});
 		});
 		describe("projections", () => {
@@ -215,8 +225,10 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(!harness.features.countAndExists)("count with filter matches expected rows", async () => {
 				if (!ctx.repo.count) return;
-				expect(await ctx.repo.count({ category: "reader" })).toBe(2);
-				expect(await ctx.repo.count({ category: "no-such" })).toBe(0);
+				const readers = await ctx.repo.count({ category: "reader" });
+				expect(readers).toBe(2);
+				const none = await ctx.repo.count({ category: "no-such" });
+				expect(none).toBe(0);
 			});
 			it.skipIf(!harness.features.countAndExists)("exists is truthy when filter matches, falsy when it does not", async () => {
 				if (!ctx.repo.exists) return;
@@ -257,14 +269,15 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoAgg)("empty result set returns { rows: [] } (no throw)", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: { category: "does-not-exist" },
 					groupBy: "category",
 					measures: { total: {
 						op: "sum",
 						field: "count"
 					} }
-				})).rows).toEqual([]);
+				});
+				expect(result.rows).toEqual([]);
 			});
 			it.skipIf(skipNoAgg)("groupBy + sum produces one row per group with correct totals", async () => {
 				if (!ctx.repo.aggregate) return;
@@ -310,7 +323,7 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoAgg)("filtered sum/count: KPI tiles side-by-side", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					groupBy: "category",
 					measures: {
 						activeCount: {
@@ -332,7 +345,8 @@ function runStandardRepoConformance(harness) {
 						}
 					},
 					sort: { category: 1 }
-				})).rows).toEqual([{
+				});
+				expect(result.rows).toEqual([{
 					category: "admin",
 					activeCount: 1,
 					inactiveCount: 1,
@@ -360,7 +374,7 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoTopN)("top-N: keep top 1 per category by count", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					groupBy: ["category", "name"],
 					measures: { n: {
 						op: "sum",
@@ -372,7 +386,8 @@ function runStandardRepoConformance(harness) {
 						limit: 1
 					},
 					sort: { category: 1 }
-				})).rows).toEqual([{
+				});
+				expect(result.rows).toEqual([{
 					category: "admin",
 					name: "d",
 					n: 40
@@ -384,7 +399,7 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoTopN)("top-N: row_number ties strategy yields exactly N rows per partition", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					groupBy: ["category", "name"],
 					measures: { n: { op: "count" } },
 					topN: {
@@ -394,7 +409,8 @@ function runStandardRepoConformance(harness) {
 						ties: "row_number"
 					},
 					sort: { category: 1 }
-				})).rows.map((r) => `${r.category}:${r.name}`)).toEqual(["admin:c", "reader:a"]);
+				});
+				expect(result.rows.map((r) => `${r.category}:${r.name}`)).toEqual(["admin:c", "reader:a"]);
 			});
 			it.skipIf(skipNoTopN)("top-N: throws on partitionBy referencing an unknown column", async () => {
 				if (!ctx.repo.aggregate) return;
@@ -614,7 +630,8 @@ function runStandardRepoConformance(harness) {
 				});
 				const handle = cachedRepo.cache;
 				if (!handle) return;
-				expect(await handle.invalidateByTags(["inv-tag"])).toBeGreaterThanOrEqual(1);
+				const cleared = await handle.invalidateByTags(["inv-tag"]);
+				expect(cleared).toBeGreaterThanOrEqual(1);
 			});
 		});
 		describe("aggregate — date buckets + keyset", () => {
@@ -676,7 +693,7 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoAgg)("date bucket month groups rows under YYYY-MM labels", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: { category: "bk-paid" },
 					dateBuckets: { month: {
 						field: "createdAt",
@@ -687,7 +704,8 @@ function runStandardRepoConformance(harness) {
 						field: "count"
 					} },
 					sort: { month: 1 }
-				})).rows).toEqual([
+				});
+				expect(result.rows).toEqual([
 					{
 						month: "2026-01",
 						revenue: 300
@@ -708,7 +726,7 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoAgg)("date bucket day emits YYYY-MM-DD", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: { category: "bk-paid" },
 					dateBuckets: { day: {
 						field: "createdAt",
@@ -716,7 +734,8 @@ function runStandardRepoConformance(harness) {
 					} },
 					measures: { n: { op: "count" } },
 					sort: { day: 1 }
-				})).rows.map((r) => r.day)).toEqual([
+				});
+				expect(result.rows.map((r) => r.day)).toEqual([
 					"2026-01-15",
 					"2026-01-22",
 					"2026-02-05",
@@ -726,7 +745,7 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoAgg)("date bucket quarter emits YYYY-Qn", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: { category: "bk-paid" },
 					dateBuckets: { q: {
 						field: "createdAt",
@@ -734,7 +753,8 @@ function runStandardRepoConformance(harness) {
 					} },
 					measures: { n: { op: "count" } },
 					sort: { q: 1 }
-				})).rows).toEqual([
+				});
+				expect(result.rows).toEqual([
 					{
 						q: "2026-Q1",
 						n: 3
@@ -751,14 +771,15 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoAgg)("date bucket year emits YYYY", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: { category: "bk-paid" },
 					dateBuckets: { year: {
 						field: "createdAt",
 						interval: "year"
 					} },
 					measures: { n: { op: "count" } }
-				})).rows).toEqual([{
+				});
+				expect(result.rows).toEqual([{
 					year: "2026",
 					n: 5
 				}]);
@@ -797,7 +818,7 @@ function runStandardRepoConformance(harness) {
 						createdAt: "2026-04-15T10:30:00Z"
 					})
 				]);
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: eq("category", "bk2"),
 					dateBuckets: { bin: {
 						field: "createdAt",
@@ -808,7 +829,8 @@ function runStandardRepoConformance(harness) {
 					} },
 					measures: { n: { op: "count" } },
 					sort: { bin: 1 }
-				})).rows).toEqual([
+				});
+				expect(result.rows).toEqual([
 					{
 						bin: "2026-04-15T10:00",
 						n: 2
@@ -845,7 +867,7 @@ function runStandardRepoConformance(harness) {
 						createdAt: "2026-04-15T11:05:00Z"
 					})
 				]);
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: eq("category", "bk3"),
 					dateBuckets: { hour: {
 						field: "createdAt",
@@ -853,7 +875,8 @@ function runStandardRepoConformance(harness) {
 					} },
 					measures: { n: { op: "count" } },
 					sort: { hour: 1 }
-				})).rows).toEqual([{
+				});
+				expect(result.rows).toEqual([{
 					hour: "2026-04-15T10:00",
 					n: 2
 				}, {
@@ -863,7 +886,7 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoAgg)("date bucket combines with groupBy column", async () => {
 				if (!ctx.repo.aggregate) return;
-				expect((await ctx.repo.aggregate({
+				const result = await ctx.repo.aggregate({
 					filter: in_("category", [...BUCKET_CATS]),
 					dateBuckets: { month: {
 						field: "createdAt",
@@ -875,7 +898,8 @@ function runStandardRepoConformance(harness) {
 						month: 1,
 						category: 1
 					}
-				})).rows).toEqual([
+				});
+				expect(result.rows).toEqual([
 					{
 						month: "2026-01",
 						category: "bk-paid",
@@ -979,6 +1003,31 @@ function runStandardRepoConformance(harness) {
 				expect(out.data).toHaveLength(1);
 				expect(out.total).toBe(1);
 			});
+			it("empty result reports pages: 0 (offset envelope)", async () => {
+				const out = await ctx.repo.getAll({
+					filters: { count: 999999 },
+					page: 1,
+					limit: 10
+				});
+				expect(out.data).toHaveLength(0);
+				expect(out.total).toBe(0);
+				expect(out.pages).toBe(0);
+			});
+			it.skipIf(skipNoAgg)("empty result reports pages: 0 (aggregatePaginate offset envelope)", async () => {
+				if (!ctx.repo.aggregatePaginate) return;
+				const result = await ctx.repo.aggregatePaginate.bind(ctx.repo)({
+					filter: eq("category", "__no_such_category__"),
+					groupBy: "category",
+					measures: { n: { op: "count" } },
+					page: 1,
+					limit: 10
+				});
+				expect(result.method).toBe("offset");
+				if (result.method !== "offset") throw new Error("expected offset envelope");
+				expect(result.data).toHaveLength(0);
+				expect(result.total).toBe(0);
+				expect(result.pages).toBe(0);
+			});
 		});
 		describe("Filter IR compilation parity", () => {
 			beforeEach(async () => {
@@ -1016,10 +1065,12 @@ function runStandardRepoConformance(harness) {
 				]);
 			});
 			it("in_([]) matches nothing (not everything)", async () => {
-				expect(await ctx.repo.findAll(in_("category", []))).toHaveLength(0);
+				const rows = await ctx.repo.findAll(in_("category", []));
+				expect(rows).toHaveLength(0);
 			});
 			it("in_ with non-empty list matches those values", async () => {
-				expect(await ctx.repo.findAll(in_("category", ["a"]))).toHaveLength(2);
+				const rows = await ctx.repo.findAll(in_("category", ["a"]));
+				expect(rows).toHaveLength(2);
 			});
 			it("eq null matches rows where the field is null", async () => {
 				const rows = await ctx.repo.findAll(isNull("category"));
@@ -1027,16 +1078,20 @@ function runStandardRepoConformance(harness) {
 				expect(rows[0]?.name).toBe("nullnote");
 			});
 			it("ne does not include null-valued rows (SQL 3VL / Mongo parity)", async () => {
-				expect((await ctx.repo.findAll(ne("category", "a"))).map((r) => r.name).sort()).toEqual(["back", "under"]);
+				const names = (await ctx.repo.findAll(ne("category", "a"))).map((r) => r.name).sort();
+				expect(names).toEqual(["back", "under"]);
 			});
 			it("like with % metacharacter in the value matches literally", async () => {
-				expect((await ctx.repo.findAll(like("notes", "50\\% off"))).map((r) => r.name)).toEqual(["pct"]);
+				const rows = await ctx.repo.findAll(like("notes", "50\\% off"));
+				expect(rows.map((r) => r.name)).toEqual(["pct"]);
 			});
 			it("like with _ metacharacter in the value matches literally", async () => {
-				expect((await ctx.repo.findAll(like("notes", "file\\_name.txt"))).map((r) => r.name)).toEqual(["under"]);
+				const rows = await ctx.repo.findAll(like("notes", "file\\_name.txt"));
+				expect(rows.map((r) => r.name)).toEqual(["under"]);
 			});
 			it("nested and/or composes correctly", async () => {
-				expect((await ctx.repo.findAll(or(and(eq("category", "a"), gt("count", 1)), eq("name", "back")))).map((r) => r.name).sort()).toEqual(["back", "pct"]);
+				const names = (await ctx.repo.findAll(or(and(eq("category", "a"), gt("count", 1)), eq("name", "back")))).map((r) => r.name).sort();
+				expect(names).toEqual(["back", "pct"]);
 			});
 		});
 		describe.skipIf(!harness.features.duplicateKeyError)("isDuplicateKeyError", () => {
@@ -1073,7 +1128,8 @@ function runStandardRepoConformance(harness) {
 				}));
 				expect(result.doc.name).toBe("Fresh");
 				expect(result.created).toBe(true);
-				expect(await ctx.repo.findAll()).toHaveLength(1);
+				const all = await ctx.repo.findAll();
+				expect(all).toHaveLength(1);
 			});
 			it("returns existing row when filter matches (created: false, no insert)", async () => {
 				if (!ctx.repo.getOrCreate) return;
@@ -1087,7 +1143,8 @@ function runStandardRepoConformance(harness) {
 				}));
 				expect(result.doc.name).toBe("Existing");
 				expect(result.created).toBe(false);
-				expect(await ctx.repo.findAll()).toHaveLength(1);
+				const all = await ctx.repo.findAll();
+				expect(all).toHaveLength(1);
 			});
 		});
 		describe.skipIf(!harness.features.transactions)("withTransaction", () => {
@@ -1098,7 +1155,8 @@ function runStandardRepoConformance(harness) {
 						email: "c@x.com"
 					}));
 				});
-				expect(await ctx.repo.findAll({ name: "tx-committed" })).toHaveLength(1);
+				const rows = await ctx.repo.findAll({ name: "tx-committed" });
+				expect(rows).toHaveLength(1);
 			});
 			it("rolls back on thrown error — no row persists", async () => {
 				const err = /* @__PURE__ */ new Error("boom");
@@ -1115,7 +1173,8 @@ function runStandardRepoConformance(harness) {
 					caught = e;
 				}
 				expect(caught).toBe(err);
-				expect(await ctx.repo.findAll({ name: "tx-rollback" })).toHaveLength(0);
+				const rows = await ctx.repo.findAll({ name: "tx-rollback" });
+				expect(rows).toHaveLength(0);
 			});
 			it("reads inside the txRepo see writes inside the same callback", async () => {
 				await ctx.repo.withTransaction(async (txRepo) => {
@@ -1123,7 +1182,8 @@ function runStandardRepoConformance(harness) {
 						name: "tx-read",
 						email: "rr@x.com"
 					})), harness.idField);
-					expect((await txRepo.getById(id))?.name).toBe("tx-read");
+					const back = await txRepo.getById(id);
+					expect(back?.name).toBe("tx-read");
 				});
 			});
 		});
@@ -1205,7 +1265,7 @@ function runStandardRepoConformance(harness) {
 					category: "org-chunk"
 				}));
 				const progressEvents = [];
-				expect((await ctx.repo.purgeByField("category", "org-chunk", { type: "hard" }, {
+				const result = await ctx.repo.purgeByField("category", "org-chunk", { type: "hard" }, {
 					batchSize: 10,
 					onProgress: (event) => {
 						progressEvents.push({
@@ -1213,7 +1273,8 @@ function runStandardRepoConformance(harness) {
 							chunkSize: event.chunkSize
 						});
 					}
-				})).processed).toBe(25);
+				});
+				expect(result.processed).toBe(25);
 				expect(progressEvents.length).toBe(3);
 				expect(progressEvents[0]).toEqual({
 					processed: 10,
@@ -1231,7 +1292,8 @@ function runStandardRepoConformance(harness) {
 			});
 			it.skipIf(skipNoPurge)("idempotent: re-running on the same tenant is a no-op", async () => {
 				await seedTwoTenants();
-				expect((await ctx.repo.purgeByField("category", "org-a", { type: "hard" })).processed).toBe(3);
+				const first = await ctx.repo.purgeByField("category", "org-a", { type: "hard" });
+				expect(first.processed).toBe(3);
 				const second = await ctx.repo.purgeByField("category", "org-a", { type: "hard" });
 				expect(second.ok).toBe(true);
 				expect(second.processed).toBe(0);
@@ -1240,7 +1302,8 @@ function runStandardRepoConformance(harness) {
 				await seedTwoTenants();
 				const totalBefore = await ctx.repo.count({});
 				await ctx.repo.purgeByField("category", "org-a", { type: "hard" });
-				expect(await ctx.repo.count({})).toBe(totalBefore - 3);
+				const totalAfter = await ctx.repo.count({});
+				expect(totalAfter).toBe(totalBefore - 3);
 				expect(await ctx.repo.count({ category: "org-b" })).toBe(2);
 			});
 			it.skipIf(skipNoPurge)("abort signal: stops between chunks, returns partial count", async () => {
@@ -1258,7 +1321,8 @@ function runStandardRepoConformance(harness) {
 				});
 				expect(result.ok).toBe(false);
 				expect(result.processed).toBe(10);
-				expect(await ctx.repo.count({ category: "org-abort" })).toBe(15);
+				const remaining = await ctx.repo.count({ category: "org-abort" });
+				expect(remaining).toBe(15);
 			});
 			it.skipIf(skipNoPurge)("retry policy is plumbed through (default no retry, opt-in works)", async () => {
 				await seedTwoTenants();
@@ -1330,7 +1394,7 @@ function runStandardRepoConformance(harness) {
 				await seedTenants(25, 0);
 				const memory = makeSink();
 				const events = [];
-				expect((await ctx.repo.archiveByFilter({ category: "org-cold" }, memory.sink, {
+				const result = await ctx.repo.archiveByFilter({ category: "org-cold" }, memory.sink, {
 					batchSize: 10,
 					onProgress: (event) => {
 						events.push({
@@ -1338,7 +1402,8 @@ function runStandardRepoConformance(harness) {
 							chunkSize: event.chunkSize
 						});
 					}
-				})).processed).toBe(25);
+				});
+				expect(result.processed).toBe(25);
 				expect(memory.docs).toHaveLength(25);
 				expect(events).toEqual([
 					{
@@ -1359,7 +1424,8 @@ function runStandardRepoConformance(harness) {
 				if (!ctx.repo.archiveByFilter) return;
 				await seedTenants(3, 0);
 				const memory = makeSink();
-				expect((await ctx.repo.archiveByFilter({ category: "org-cold" }, memory.sink)).processed).toBe(3);
+				const first = await ctx.repo.archiveByFilter({ category: "org-cold" }, memory.sink);
+				expect(first.processed).toBe(3);
 				const second = await ctx.repo.archiveByFilter({ category: "org-cold" }, memory.sink);
 				expect(second.ok).toBe(true);
 				expect(second.processed).toBe(0);

package/dist/testing/lock-conformance.mjs

@@ -59,7 +59,8 @@ function runLockAdapterConformance(harness) {
 				expect(await adapter.tryAcquire("lock.one", B, 5e3)).toBe(false);
 			});
 			it("parallel acquires resolve to exactly one winner", async () => {
-				expect((await Promise.all([adapter.tryAcquire("shared.name", A, 5e3), adapter.tryAcquire("shared.name", B, 5e3)])).filter((r) => r === true)).toHaveLength(1);
+				const results = await Promise.all([adapter.tryAcquire("shared.name", A, 5e3), adapter.tryAcquire("shared.name", B, 5e3)]);
+				expect(results.filter((r) => r === true)).toHaveLength(1);
 			});
 		});
 		describe("release", () => {
@@ -122,13 +123,17 @@ function runLockAdapterConformance(harness) {
 				await sleep(10);
 				await adapter.tryAcquire("cron.outbox", B, 5e3);
 				expect(await adapter.release("cron.outbox", A)).toBe(false);
-				if (adapter.inspect) expect((await adapter.inspect("cron.outbox"))?.holder).toBe(B);
+				if (adapter.inspect) {
+					const state = await adapter.inspect("cron.outbox");
+					expect(state?.holder).toBe(B);
+				}
 			});
 		});
 		describe("stress", () => {
 			it("50 concurrent holders against one name → exactly one winner", async () => {
 				const holders = Array.from({ length: 50 }, (_, i) => `replica-${i}`);
-				expect((await Promise.all(holders.map((h) => adapter.tryAcquire("contended", h, 5e3)))).filter((r) => r === true)).toHaveLength(1);
+				const results = await Promise.all(holders.map((h) => adapter.tryAcquire("contended", h, 5e3)));
+				expect(results.filter((r) => r === true)).toHaveLength(1);
 			});
 			it("100 sequential acquire/release cycles leave no residue", async () => {
 				for (let i = 0; i < 100; i++) {

package/dist/testing/purge-conformance.mjs

@@ -29,7 +29,6 @@ import { beforeEach, describe, expect, it } from "vitest";
 const IN_SCOPE = 25;
 const OUT_SCOPE = 5;
 const BATCH = 10;
-const AMOUNT_EACH = 7;
 /**
 * Wrap TenantPurgeOptions with a chunk budget: when the port stops
 * progressing, the loop would otherwise run forever — the budget aborts
@@ -82,7 +81,7 @@ function runPurgeConformance(harness) {
 			]);
 			expect(await ctx.countRaw()).toBe(IN_SCOPE);
 			expect(await ctx.countSoftFlagged()).toBe(IN_SCOPE);
-			expect(await ctx.sumAmount()).toBe(IN_SCOPE * AMOUNT_EACH);
+			expect(await ctx.sumAmount()).toBe(175);
 			expect(await ctx.countOutOfScope()).toBe(OUT_SCOPE);
 		});
 		it("anonymize (static): progresses across batches and retains measures", async () => {
@@ -100,7 +99,7 @@ function runPurgeConformance(harness) {
 				5
 			]);
 			expect(await ctx.countEmail("redacted@example.invalid")).toBe(IN_SCOPE);
-			expect(await ctx.sumAmount()).toBe(IN_SCOPE * AMOUNT_EACH);
+			expect(await ctx.sumAmount()).toBe(175);
 			expect(await ctx.countRaw()).toBe(IN_SCOPE);
 			expect(await ctx.countOutOfScope()).toBe(OUT_SCOPE);
 		});
@@ -113,7 +112,7 @@ function runPurgeConformance(harness) {
 			expect(res.ok).toBe(true);
 			expect(res.processed).toBe(IN_SCOPE);
 			expect(await ctx.countEmail("fn-redacted@example.invalid")).toBe(IN_SCOPE);
-			expect(await ctx.sumAmount()).toBe(IN_SCOPE * AMOUNT_EACH);
+			expect(await ctx.sumAmount()).toBe(175);
 		});
 		it("exact-batch boundary: inScope === batchSize processes each row once", async () => {
 			await ctx.seed(BATCH, OUT_SCOPE);
@@ -152,7 +151,7 @@ function runPurgeConformance(harness) {
 			});
 			expect(res.ok).toBe(false);
 			expect(res.processed).toBe(BATCH);
-			expect(await ctx.countRaw()).toBe(IN_SCOPE - BATCH);
+			expect(await ctx.countRaw()).toBe(15);
 		});
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@classytic/repo-core",
-	"version": "0.20.0",
+	"version": "0.22.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,
@@ -169,7 +169,7 @@
 		"fast-check": "^4.7.0",
 		"knip": "^6.3.0",
 		"publint": "^0.3.18",
-		"tsdown": "^0.22.5",
+		"tsdown": "^0.22.14",
 		"typescript": "^7.0.2",
 		"vitest": "^4.1.4"
 	},