@classytic/repo-core 0.3.0 → 0.4.1

package/dist/filter/match.mjs

@@ -30,12 +30,12 @@ function matchFilter(doc, filter) {
 			const v = getField(doc, filter.field);
 			if (typeof v !== "string") return false;
 			const flags = filter.caseSensitivity === "sensitive" ? "" : "i";
-			return new RegExp(`^${likeToRegex(filter.pattern)}$`, flags).test(v);
+			return getOrCompileLike(filter.pattern, flags).test(v);
 		}
 		case "regex": {
 			const v = getField(doc, filter.field);
 			if (typeof v !== "string") return false;
-			return new RegExp(filter.pattern, filter.flags).test(v);
+			return getOrCompileRegex(filter.pattern, filter.flags).test(v);
 		}
 		case "raw": return false;
 	}
@@ -78,6 +78,42 @@ function toComparable(value) {
 	if (typeof value === "number" || typeof value === "string") return value;
 	if (typeof value === "boolean") return value ? 1 : 0;
 }
+/**
+* Compiled-RegExp caches keyed by `pattern|flags`. Without these, a
+* filter run via `asPredicate(filter)` over an N-doc array compiles a
+* fresh `new RegExp(...)` on every doc — at 100k docs and a non-trivial
+* pattern, that's measurable. Bounded LRU eviction keeps the cache
+* from growing unboundedly when callers hand us thousands of distinct
+* patterns (e.g. "name LIKE %" personalization at scale).
+*/
+const REGEX_CACHE_LIMIT = 256;
+const likeCache = /* @__PURE__ */ new Map();
+const regexCache = /* @__PURE__ */ new Map();
+function getOrCompileLike(pattern, flags) {
+	const key = `${flags}|${pattern}`;
+	let re = likeCache.get(key);
+	if (re) return re;
+	re = new RegExp(`^${likeToRegex(pattern)}$`, flags);
+	if (likeCache.size >= REGEX_CACHE_LIMIT) {
+		const oldest = likeCache.keys().next().value;
+		if (oldest !== void 0) likeCache.delete(oldest);
+	}
+	likeCache.set(key, re);
+	return re;
+}
+function getOrCompileRegex(pattern, flags) {
+	const f = flags ?? "";
+	const key = `${f}|${pattern}`;
+	let re = regexCache.get(key);
+	if (re) return re;
+	re = new RegExp(pattern, f);
+	if (regexCache.size >= REGEX_CACHE_LIMIT) {
+		const oldest = regexCache.keys().next().value;
+		if (oldest !== void 0) regexCache.delete(oldest);
+	}
+	regexCache.set(key, re);
+	return re;
+}
 /** SQL `LIKE` pattern → JS regex body. Escapes regex metachars; `%` → `.*`, `_` → `.`. */
 function likeToRegex(pattern) {
 	let out = "";

package/dist/lock/index.d.mts

@@ -0,0 +1,132 @@
+//#region src/lock/index.d.ts
+/**
+ * Distributed lock contract for the @classytic ecosystem.
+ *
+ * Coordinates exclusive access to a *named resource* across multiple
+ * processes / replicas. The canonical use case: cron leader election.
+ * Multi-pod deployments fire every scheduled tick on every replica;
+ * without coordination the same sweep runs N times. A lock per cron
+ * name lets exactly one replica win each cycle.
+ *
+ * Distinct from `leasePlugin` (mongokit / sqlitekit) — that one
+ * leases existing **rows** (work-queue items) to workers. This
+ * adapter leases **names** (no underlying row required), so it
+ * doubles as singleton-flag, election-leader, and rate-limit
+ * coordination primitive.
+ *
+ * ## Why this lives in repo-core
+ *
+ * The contract is driver-free: any K-V or row store with conditional
+ * upsert can implement it. Mongokit ships a Mongo-backed adapter
+ * (`@classytic/mongokit/lock`); sqlitekit ships a SQLite-backed one
+ * (`@classytic/sqlitekit/lock`); future kits (pgkit, prismakit) wire
+ * their own. Hosts pick the adapter that matches their primary store
+ * and treat the lock as an implementation detail of "we already have
+ * a database, use it for coordination too."
+ *
+ * ## Lease semantics
+ *
+ * `tryAcquire(name, holderId, leaseMs)` returns `true` when `holderId`
+ * now holds the lock — either because it was free, the prior lease
+ * expired, or the same holder is extending. `false` means another
+ * holder owns an unexpired lease.
+ *
+ * `release(name, holderId)` releases the lock if held by this holder.
+ * Returns `true` on actual release, `false` when the holder didn't
+ * own it. Idempotent.
+ *
+ * Crashed leaders are reclaimed when their lease expires — adapters
+ * MUST treat `expiresAt < now` as "free for the taking" inside the
+ * atomic acquire path. Hosts size `leaseMs` based on cron interval
+ * (typically 80–95%); too long delays failover, too short risks the
+ * lease lapsing while the leader is still working.
+ *
+ * ## Sync-or-async
+ *
+ * Methods may return `Promise` or sync values; consumers `await`
+ * either way. Memory adapter is sync; SQL/Mongo adapters are async.
+ *
+ * ## Why one file, not a barrel
+ *
+ * Types + the in-memory reference adapter + the instance-id helper
+ * total under 200 LOC and have no internal seams worth a deep
+ * subpath. A barrel would re-export from siblings (memory-adapter,
+ * instance-id, types) and pull every sibling into the consumer
+ * graph — `sideEffects: false` lets modern bundlers tree-shake, but
+ * single-file is the cheaper guarantee.
+ */
+interface LockAdapter {
+  /**
+   * Try to acquire (or extend) a named lock for `holderId`, valid
+   * for `leaseMs` milliseconds.
+   *
+   * Same `holderId` calling twice extends the lease — idempotent.
+   * Adapters MUST atomically check "free OR mine" and update in a
+   * single round-trip; a read-then-write split is racy.
+   */
+  tryAcquire(name: string, holderId: string, leaseMs: number): Promise<boolean> | boolean;
+  /**
+   * Release the lock if held by `holderId`. Returns `true` on actual
+   * release, `false` when the lock isn't held by this holder. Safe
+   * to call without ever having acquired (returns `false`).
+   */
+  release(name: string, holderId: string): Promise<boolean> | boolean;
+  /**
+   * Optional: introspect a lock without trying to acquire it. Useful
+   * for diagnostics ("which replica holds X?") and tests. Returns
+   * `null` when the lock is free or expired.
+   *
+   * Not in the hot path — adapters that can't implement cheaply may
+   * omit it. Consumers must check existence: `adapter.inspect?.(name)`.
+   */
+  inspect?(name: string): Promise<LockState | null> | LockState | null;
+}
+/** Snapshot of a lock's current holder. */
+interface LockState {
+  /** The lock name (mirrored back for convenience). */
+  name: string;
+  /** Holder identifier. Free-form — typically `hostname.pid.uuid`. */
+  holder: string;
+  /** When the current lease expires. UTC. */
+  expiresAt: Date;
+  /** When the current holder first acquired (or last extended) the lock. */
+  acquiredAt: Date;
+}
+/** Adapter-construction options that every backend shares. */
+interface BaseLockAdapterOptions {
+  /**
+   * Default lease length in milliseconds, applied when a caller passes
+   * `leaseMs <= 0` to `tryAcquire`. Most callers pass an explicit
+   * value sized to their cron interval; the default is a safety net.
+   */
+  defaultLeaseMs?: number;
+}
+/**
+ * Reference in-memory `LockAdapter` — single-process only.
+ *
+ * Useful for tests + single-pod deployments that want the same API
+ * as the production adapter without setting up a database. NOT a
+ * coordination primitive — there's no shared state across processes,
+ * so two processes each construct their own `Map` and both think
+ * they hold every lock. For real multi-replica safety use
+ * `@classytic/mongokit/lock`, `@classytic/sqlitekit/lock`, or a
+ * future kit-specific implementation.
+ *
+ * The atomic check-and-set inside `tryAcquire` is genuine — Node's
+ * single-threaded event loop guarantees a synchronous read-then-write
+ * is atomic relative to other JS, the same guarantee a real adapter
+ * gets from its database's atomic upsert.
+ */
+declare function createMemoryLockAdapter(options?: BaseLockAdapterOptions): LockAdapter;
+/**
+ * Returns a stable instance id for this process, generating it once
+ * on first call and caching for the process lifetime. Idempotent.
+ */
+declare function getInstanceId(): string;
+/**
+ * Test helper — overrides the cached id. Call between tests that
+ * simulate multiple replicas in one process. Pass `null` to reset.
+ */
+declare function setInstanceIdForTesting(id: string | null): void;
+//#endregion
+export { BaseLockAdapterOptions, LockAdapter, LockState, createMemoryLockAdapter, getInstanceId, setInstanceIdForTesting };

package/dist/lock/index.mjs

@@ -0,0 +1,162 @@
+import { __require } from "../_virtual/_rolldown/runtime.mjs";
+import { randomUUID } from "node:crypto";
+//#region src/lock/index.ts
+/**
+* Distributed lock contract for the @classytic ecosystem.
+*
+* Coordinates exclusive access to a *named resource* across multiple
+* processes / replicas. The canonical use case: cron leader election.
+* Multi-pod deployments fire every scheduled tick on every replica;
+* without coordination the same sweep runs N times. A lock per cron
+* name lets exactly one replica win each cycle.
+*
+* Distinct from `leasePlugin` (mongokit / sqlitekit) — that one
+* leases existing **rows** (work-queue items) to workers. This
+* adapter leases **names** (no underlying row required), so it
+* doubles as singleton-flag, election-leader, and rate-limit
+* coordination primitive.
+*
+* ## Why this lives in repo-core
+*
+* The contract is driver-free: any K-V or row store with conditional
+* upsert can implement it. Mongokit ships a Mongo-backed adapter
+* (`@classytic/mongokit/lock`); sqlitekit ships a SQLite-backed one
+* (`@classytic/sqlitekit/lock`); future kits (pgkit, prismakit) wire
+* their own. Hosts pick the adapter that matches their primary store
+* and treat the lock as an implementation detail of "we already have
+* a database, use it for coordination too."
+*
+* ## Lease semantics
+*
+* `tryAcquire(name, holderId, leaseMs)` returns `true` when `holderId`
+* now holds the lock — either because it was free, the prior lease
+* expired, or the same holder is extending. `false` means another
+* holder owns an unexpired lease.
+*
+* `release(name, holderId)` releases the lock if held by this holder.
+* Returns `true` on actual release, `false` when the holder didn't
+* own it. Idempotent.
+*
+* Crashed leaders are reclaimed when their lease expires — adapters
+* MUST treat `expiresAt < now` as "free for the taking" inside the
+* atomic acquire path. Hosts size `leaseMs` based on cron interval
+* (typically 80–95%); too long delays failover, too short risks the
+* lease lapsing while the leader is still working.
+*
+* ## Sync-or-async
+*
+* Methods may return `Promise` or sync values; consumers `await`
+* either way. Memory adapter is sync; SQL/Mongo adapters are async.
+*
+* ## Why one file, not a barrel
+*
+* Types + the in-memory reference adapter + the instance-id helper
+* total under 200 LOC and have no internal seams worth a deep
+* subpath. A barrel would re-export from siblings (memory-adapter,
+* instance-id, types) and pull every sibling into the consumer
+* graph — `sideEffects: false` lets modern bundlers tree-shake, but
+* single-file is the cheaper guarantee.
+*/
+/**
+* Reference in-memory `LockAdapter` — single-process only.
+*
+* Useful for tests + single-pod deployments that want the same API
+* as the production adapter without setting up a database. NOT a
+* coordination primitive — there's no shared state across processes,
+* so two processes each construct their own `Map` and both think
+* they hold every lock. For real multi-replica safety use
+* `@classytic/mongokit/lock`, `@classytic/sqlitekit/lock`, or a
+* future kit-specific implementation.
+*
+* The atomic check-and-set inside `tryAcquire` is genuine — Node's
+* single-threaded event loop guarantees a synchronous read-then-write
+* is atomic relative to other JS, the same guarantee a real adapter
+* gets from its database's atomic upsert.
+*/
+function createMemoryLockAdapter(options = {}) {
+	const { defaultLeaseMs = 3e4 } = options;
+	const store = /* @__PURE__ */ new Map();
+	function readLive(name, now) {
+		const entry = store.get(name);
+		if (!entry) return void 0;
+		if (entry.expiresAt <= now) {
+			store.delete(name);
+			return;
+		}
+		return entry;
+	}
+	return {
+		tryAcquire(name, holderId, leaseMs) {
+			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
+			const now = Date.now();
+			const live = readLive(name, now);
+			if (live && live.holder !== holderId) return false;
+			store.set(name, {
+				holder: holderId,
+				expiresAt: now + ms,
+				acquiredAt: live ? live.acquiredAt : now
+			});
+			return true;
+		},
+		release(name, holderId) {
+			const live = readLive(name, Date.now());
+			if (!live || live.holder !== holderId) return false;
+			store.delete(name);
+			return true;
+		},
+		inspect(name) {
+			const live = readLive(name, Date.now());
+			if (!live) return null;
+			return {
+				name,
+				holder: live.holder,
+				expiresAt: new Date(live.expiresAt),
+				acquiredAt: new Date(live.acquiredAt)
+			};
+		}
+	};
+}
+/**
+* Process-wide instance id helper.
+*
+* Lock holders need a stable identifier per process that's unique
+* across replicas. The standard recipe is `hostname.pid.shortuuid`:
+*
+*   - `hostname`: distinguishes containers on the same host.
+*   - `pid`: distinguishes worker processes on the same container.
+*   - short uuid: distinguishes restarts on the same host with
+*     pid-reuse (rare but possible after fast crash-loop).
+*
+* Edge runtimes (Cloudflare Workers, Vercel Edge) lack `os.hostname()`
+* and `process.pid` — the helper falls back to a uuid-only id, which
+* is still unique per worker isolate.
+*/
+let cachedInstanceId = null;
+/**
+* Returns a stable instance id for this process, generating it once
+* on first call and caching for the process lifetime. Idempotent.
+*/
+function getInstanceId() {
+	if (cachedInstanceId) return cachedInstanceId;
+	cachedInstanceId = buildInstanceId();
+	return cachedInstanceId;
+}
+function buildInstanceId() {
+	const shortUuid = randomUUID().slice(0, 8);
+	let hostname = "unknown";
+	let pid = "edge";
+	try {
+		hostname = __require("node:os").hostname();
+		pid = typeof process !== "undefined" && process.pid ? process.pid : "edge";
+	} catch {}
+	return `${hostname}.${pid}.${shortUuid}`;
+}
+/**
+* Test helper — overrides the cached id. Call between tests that
+* simulate multiple replicas in one process. Pass `null` to reset.
+*/
+function setInstanceIdForTesting(id) {
+	cachedInstanceId = id;
+}
+//#endregion
+export { createMemoryLockAdapter, getInstanceId, setInstanceIdForTesting };

package/dist/pagination/canonical.d.mts

@@ -1,4 +1,4 @@
-import { AnyPaginationResult, BareListResponse, PaginatedResponse } from "./types.mjs";
+import { AnyPaginationResult, BareListResult, PaginatedResult } from "./types.mjs";
 
 //#region src/pagination/canonical.d.ts
 /**
@@ -11,7 +11,7 @@ import { AnyPaginationResult, BareListResponse, PaginatedResponse } from "./type
  *
  * Accepts `unknown` (rather than `T[] | AnyPaginationResult<T>`) so wire-
  * boundary callers can guard arbitrary inputs without pre-narrowing — the
- * arc / arc-next response pipeline routinely sees `{ docs: unknown[] }`
+ * arc / arc-next response pipeline routinely sees `{ data: unknown[] }`
  * shapes that are neither a bare array nor a paginated result, and forcing
  * those callers to cast first defeats the guard's purpose.
  */
@@ -20,16 +20,16 @@ declare function isPaginatedResult<TDoc>(input: unknown): input is AnyPagination
  * Normalise a list-shaped value into the canonical wire envelope.
  *
  * Overloads keep the return type tight:
- *   - bare array  → {@link BareListResponse}
- *   - paginated   → {@link PaginatedResponse} (preserves method discriminant)
+ *   - bare array  → {@link BareListResult}
+ *   - paginated   → {@link PaginatedResult} (preserves method discriminant)
  *
  * The mutable-array overload widens to `TDoc[]` because that's the most
  * common server input (kit results return `TDoc[]` for `docs`); the
  * readonly overload covers callers passing `readonly TDoc[]`.
  */
-declare function toCanonicalList<TDoc>(input: TDoc[]): BareListResponse<TDoc>;
-declare function toCanonicalList<TDoc>(input: readonly TDoc[]): BareListResponse<TDoc>;
-declare function toCanonicalList<TDoc, TExtra extends Record<string, unknown>>(input: AnyPaginationResult<TDoc, TExtra>): PaginatedResponse<TDoc, TExtra>;
-declare function toCanonicalList<TDoc>(input: readonly TDoc[] | AnyPaginationResult<TDoc>): PaginatedResponse<TDoc>;
+declare function toCanonicalList<TDoc>(input: TDoc[]): BareListResult<TDoc>;
+declare function toCanonicalList<TDoc>(input: readonly TDoc[]): BareListResult<TDoc>;
+declare function toCanonicalList<TDoc, TExtra extends Record<string, unknown>>(input: AnyPaginationResult<TDoc, TExtra>): PaginatedResult<TDoc, TExtra>;
+declare function toCanonicalList<TDoc>(input: readonly TDoc[] | AnyPaginationResult<TDoc>): PaginatedResult<TDoc>;
 //#endregion
 export { isPaginatedResult, toCanonicalList };

package/dist/pagination/canonical.mjs

@@ -9,7 +9,7 @@
 *
 * Accepts `unknown` (rather than `T[] | AnyPaginationResult<T>`) so wire-
 * boundary callers can guard arbitrary inputs without pre-narrowing — the
-* arc / arc-next response pipeline routinely sees `{ docs: unknown[] }`
+* arc / arc-next response pipeline routinely sees `{ data: unknown[] }`
 * shapes that are neither a bare array nor a paginated result, and forcing
 * those callers to cast first defeats the guard's purpose.
 */
@@ -19,14 +19,8 @@ function isPaginatedResult(input) {
 	return method === "offset" || method === "keyset" || method === "aggregate";
 }
 function toCanonicalList(input) {
-	if (isPaginatedResult(input)) return {
-		...input,
-		success: true
-	};
-	return {
-		success: true,
-		docs: [...input]
-	};
+	if (isPaginatedResult(input)) return { ...input };
+	return { data: [...input] };
 }
 //#endregion
 export { isPaginatedResult, toCanonicalList };

package/dist/pagination/cursor.mjs

@@ -104,7 +104,10 @@ function validateCursorVersion(cursorVersion, expectedVersion, minVersion = 1) {
 function isValidPayload(payload) {
 	if (!payload || typeof payload !== "object") return false;
 	const p = payload;
-	return "v" in p && typeof p["t"] === "string" && typeof p["id"] === "string" && typeof p["idType"] === "string" && typeof p["sort"] === "object" && p["sort"] !== null && typeof p["ver"] === "number";
+	return isSerializedScalar(p["v"]) && typeof p["t"] === "string" && typeof p["id"] === "string" && typeof p["idType"] === "string" && typeof p["sort"] === "object" && p["sort"] !== null && !Array.isArray(p["sort"]) && typeof p["ver"] === "number" && Number.isFinite(p["ver"]);
+}
+function isSerializedScalar(v) {
+	return v === null || typeof v === "string" || typeof v === "number" && Number.isFinite(v) || typeof v === "boolean";
 }
 function serializeValue(value) {
 	if (value === null || value === void 0) return null;

package/dist/pagination/index.d.mts

@@ -1,6 +1,6 @@
-import { AggregatePaginationResponse, AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResponse, CursorPayload, DecodedCursor, KeysetPaginationResponse, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResponse, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResponse, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
+import { AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResult, CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResult, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
 import { isPaginatedResult, toCanonicalList } from "./canonical.mjs";
 import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
 import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
-export { type AggregatePaginationResponse, type AggregatePaginationResult, type AggregatePaginationResultCore, type AnyPaginationResult, type BareListResponse, type CursorPayload, type DecodedCursor, type KeysetPaginationResponse, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResponse, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginatedResponse, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };
+export { type AggregatePaginationResult, type AggregatePaginationResultCore, type AnyPaginationResult, type BareListResult, type CursorPayload, type DecodedCursor, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginatedResult, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };

package/dist/pagination/types.d.mts

@@ -87,7 +87,7 @@ interface DecodedCursor {
  */
 interface OffsetPaginationResultCore<TDoc> {
   method: 'offset';
-  docs: TDoc[];
+  data: TDoc[];
   page: number;
   limit: number;
   total: number;
@@ -119,7 +119,7 @@ type OffsetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> =
  */
 interface KeysetPaginationResultCore<TDoc> {
   method: 'keyset';
-  docs: TDoc[];
+  data: TDoc[];
   limit: number;
   hasMore: boolean;
   /** Cursor token for the next page, or `null` when there is none. */
@@ -145,7 +145,7 @@ type KeysetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> =
  */
 interface AggregatePaginationResultCore<TDoc> {
   method: 'aggregate';
-  docs: TDoc[];
+  data: TDoc[];
   page: number;
   limit: number;
   total: number;
@@ -168,33 +168,23 @@ type AggregatePaginationResult<TDoc, TExtra extends Record<string, unknown> = {}
  * see {@link toCanonicalList}.
  */
 type AnyPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra>;
-/** HTTP success envelope wrapping {@link OffsetPaginationResult}. */
-type OffsetPaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
-  success: true;
-} & OffsetPaginationResult<TDoc, TExtra>;
-/** HTTP success envelope wrapping {@link KeysetPaginationResult}. */
-type KeysetPaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
-  success: true;
-} & KeysetPaginationResult<TDoc, TExtra>;
-/** HTTP success envelope wrapping {@link AggregatePaginationResult}. */
-type AggregatePaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
-  success: true;
-} & AggregatePaginationResult<TDoc, TExtra>;
 /**
- * Bare list envelope — a successful response that wasn't paginated (raw
- * array result). No `method` discriminant; consumers branch on the absence
- * of pagination fields. Most useful when an endpoint sometimes paginates
- * and sometimes returns a fixed-size list.
+ * Bare list shape — an endpoint that doesn't paginate (raw array wrapped
+ * in `{data}` for consistency with paginated shapes). Consumers narrow on
+ * the absence of `method`. The `{data}` wrapper (vs returning the raw
+ * array) leaves room to add pagination metadata later without breaking
+ * the consumer contract.
  */
-interface BareListResponse<TDoc> {
-  success: true;
-  docs: TDoc[];
+interface BareListResult<TDoc> {
+  data: TDoc[];
 }
 /**
- * Union of every wire envelope a paginated/list endpoint can emit. Locked
- * to `success: true` because errors take a separate envelope shape — a
- * client-side type guard checks `success` first, then `method`.
+ * Union of every list shape an endpoint can emit — paginated (offset,
+ * keyset, aggregate) OR bare (`{data}` only). Discriminate via
+ * `'method' in result` — `method === 'offset' | 'keyset' | 'aggregate'`
+ * for paginated, absent for bare lists. Errors live on a separate path
+ * (HTTP status >= 400 → `ErrorContract`).
  */
-type PaginatedResponse<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResponse<TDoc, TExtra> | KeysetPaginationResponse<TDoc, TExtra> | AggregatePaginationResponse<TDoc, TExtra> | BareListResponse<TDoc>;
+type PaginatedResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra> | BareListResult<TDoc>;
 //#endregion
-export { AggregatePaginationResponse, AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResponse, CursorPayload, DecodedCursor, KeysetPaginationResponse, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResponse, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResponse, PaginationConfig, SortDirection, SortSpec, ValueType };
+export { AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResult, CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResult, PaginationConfig, SortDirection, SortSpec, ValueType };

package/dist/plugins/index.d.mts

@@ -0,0 +1,2 @@
+import { TenantPolicyContext, adminBypass, payloadHasTenantField } from "./tenant-helpers.mjs";
+export { type TenantPolicyContext, adminBypass, payloadHasTenantField };

package/dist/plugins/index.mjs

@@ -0,0 +1,2 @@
+import { adminBypass, payloadHasTenantField } from "./tenant-helpers.mjs";
+export { adminBypass, payloadHasTenantField };

package/dist/plugins/tenant-helpers.d.mts

@@ -0,0 +1,63 @@
+import { PolicyKey } from "../operations/types.mjs";
+
+//#region src/plugins/tenant-helpers.d.ts
+/**
+ * Minimal context shape this module reads. Kits' richer
+ * `RepositoryContext` types extend this — by accepting only the slots
+ * we touch, we avoid coupling repo-core to any kit's typing.
+ */
+interface TenantPolicyContext {
+  readonly data?: Record<string, unknown>;
+  readonly dataArray?: readonly Record<string, unknown>[];
+  readonly query?: unknown;
+  readonly filters?: unknown;
+  readonly operations?: unknown;
+}
+/**
+ * True when the op's policy target already has `tenantField` set by
+ * the caller. Used to decide whether the plugin can safely skip
+ * injecting a tenant scope rather than throwing on a missing context.
+ *
+ * - `data`       — `context.data[tenantField]` is present
+ * - `dataArray`  — every row in `context.dataArray` has `tenantField`
+ * - `query`      — `context.query[tenantField]` is present
+ * - `filters`    — `context.filters[tenantField]` is present
+ * - `operations` — every bulkWrite sub-op's filter/document has `tenantField`
+ * - `none`       — unreachable (the hook isn't registered for these ops)
+ *
+ * For multi-row targets (`dataArray`, `operations`) we require EVERY
+ * row to be stamped. Partial stamping is ambiguous (we have no
+ * resolver value to fill in the gaps) and is safer to treat as "not
+ * stamped" so the caller either stamps all rows or supplies a
+ * context/resolver.
+ */
+declare function payloadHasTenantField(context: TenantPolicyContext, policyKey: PolicyKey, tenantField: string): boolean;
+/**
+ * Build a `skipWhen`-compatible callback that bypasses tenant scoping
+ * when the caller's role is in `adminRoles`. Composable with any
+ * kit's multi-tenant plugin shape.
+ *
+ * The factory does an exact-match `Set.has` check — case-sensitive,
+ * no fuzzy matching. Lowercase your role vocabulary upstream.
+ *
+ * @example
+ * ```ts
+ * multiTenantPlugin({
+ *   resolveTenantId: ctx => ctx.organizationId,
+ *   skipWhen: adminBypass({ adminRoles: ['superadmin', 'support'] }),
+ * });
+ * ```
+ *
+ * @param options.roleField  Context key holding the role string (default: `'role'`)
+ * @param options.adminRoles Roles that bypass tenant scope. Frozen on
+ *   factory construction so callers can't mutate the list afterward
+ *   and silently change bypass semantics across plugin instances
+ *   sharing the array reference.
+ * @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+ */
+declare function adminBypass(options: {
+  roleField?: string;
+  adminRoles: readonly string[];
+}): (context: Record<string, unknown>, operation: string) => boolean;
+//#endregion
+export { TenantPolicyContext, adminBypass, payloadHasTenantField };