@classytic/repo-core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+### Added
+- Phase 0 scaffold: package.json, tsconfig, tsdown, biome, vitest (4-tier), knip
+- `@classytic/repo-core/hooks` — `HOOK_PRIORITY` constants + `HookPriority` type
+- `@classytic/repo-core/operations` — `CORE_OP_REGISTRY`, `extendRegistry`, `listOperations`, `mutatingOperations`, `readOperations`, `operationsByPolicyKey`, `describe`; 17 core ops, driver-free
+- `@classytic/repo-core/errors` — `HttpError`, `createError`, `isHttpError`, `conservativeMongoIsDuplicateKey`, `toDuplicateKeyHttpError`
+- `@classytic/repo-core/pagination` — `encodeCursor`/`decodeCursor` (URL-safe base64, mongokit ≤3.x compat), `validateCursorSort`, `validateCursorVersion`, `normalizeSort`, `validateKeysetSort`, `invertSort`, `getPrimaryField`, `validateLimit`, `validatePage`, `shouldWarnDeepPagination`, `calculateSkip`, `calculateTotalPages`
+- INFRA.md tracking doc + 4-tier test structure per monorepo testing-infrastructure.md
+- 74 unit tests across 6 files, full suite runs in ~360 ms
+- `@classytic/repo-core/filter` — Filter IR types (`Filter` discriminated union), combinators (`eq`, `ne`, `gt`/`gte`/`lt`/`lte`, `in_`/`anyOf`, `nin`/`noneOf`, `like`, `regex`, `exists`, `and`, `or`, `not`/`invert`), constants (`TRUE`, `FALSE`), runtime guard (`isFilter`), traversal (`walkFilter`, `mapFilter`, `collectFields`), in-memory evaluator (`matchFilter`, `asPredicate`). Boolean absorbing/identity elimination baked in.
+- `@classytic/repo-core/repository` — arc-aligned contract types: `MinimalRepo<TDoc>` (5-method floor), `StandardRepo<TDoc>` (recommended surface), option/result types (`QueryOptions`, `WriteOptions`, `DeleteOptions`, `FindOneAndUpdateOptions`, `DeleteResult`, `DeleteManyResult`, `UpdateManyResult`, `PaginationParams`), `RepositorySession`, `InferDoc<R>`.
+- 43 additional unit tests (builders, walk, match) bringing total to 117.
+- **Filter IR expansion** — sugar builders: `between`, `startsWith`, `endsWith`, `contains`, `iEq`, `isNull`, `isNotNull` (desugar to existing ops); new `raw` escape-hatch op for driver-native fragments (e.g. pgvector `<=>`, SQLite JSON1 path, Mongo `$geoWithin`).
+- `@classytic/repo-core/query-parser` — URL → `ParsedQuery<Filter>` driver-agnostic parser. Bracket grammar (`field[gte]=18`, `field[in]=a,b`, `field[contains]=text`). Shared types (`ParsedQuery`, `ParsedSort`, `ParsedSelect`, `ParsedPopulate`, `QueryParserOptions`, `BracketOperator`) consumed identically by every kit and both frontends (arc-next, fluid).
+- 36 more unit tests covering sugar builders + QueryParser. Total: **153 tests, 11 files, green on vitest 4**.
+- Upgraded to **vitest 4.1**, **typescript 6.0**, **biome 2.4.12**. Vitest config migrated to new `pool` / `fileParallelism` top-level API.
+- **M3 landed: `RepositoryBase` abstract class** at `@classytic/repo-core/repository`. Owns `HookEngine`, plugin installation, context builder, `_emitAfter` / `_emitError`, and the `_cachedValue` cache-short-circuit helper. Kits extend it instead of reinventing the hook layer.
+- **M4 landed: 5 portable plugins** — `@classytic/repo-core/plugins/timestamp`, `/multi-tenant`, `/soft-delete`, `/audit`, `/cache`. All Filter-IR-native. Multi-tenant + soft-delete inject scope via `and(existing, eq(...))` / `and(existing, isNull(...))` — no Mongo-specific `$`-operators. Cache includes pluggable `CacheAdapter` interface + reference `createMemoryCacheAdapter`.
+- **Tightened the scope rule for plugins** — skipped observability / validation-chain / field-filter / cascade / custom-id. Rule: a plugin lives in repo-core only if every backend needs it AND no backend provides it natively. The skipped ones are either arc's job (field-filter), host cookbook (observability, custom-id), zod's job (validation-chain), or SQL-native (cascade).
+- **`StandardRepo.withTransaction` signature fixed** — was `(session) => T`, mongoose leak. Now `(txRepo: this) => T` — caller writes `await txRepo.create(...)`, never touches session. SQL / Prisma kits bind the tx connection to a new repo; mongokit returns a session-threaded proxy.
+- `QueryOptions.session` re-documented as mongoose-specific.
+- `RepositoryBase.on` / `off` now generic over listener-data type so typed plugins (`(ctx: RepositoryContext) => void`) don't need casts.
+- **HookEngine** exposed at `@classytic/repo-core/hooks` — `DEFAULT_LISTENER_PRIORITY`, `HookEngine` class, `HookListener`, `HookMode`, `PrioritizedHook`, `EventPhase` types.
+- **Context subpath** at `@classytic/repo-core/context` — `RepositoryContext` type exposed independently for plugin authors.
+- **`HookEngine.listeners()`** — read-only snapshot of the listener registry (frozen buckets). Lets kits expose a back-compat `_hooks: Map<event, PrioritizedHook[]>` getter without handing out mutable internal state. Used by mongokit 3.10's read-through `_hooks` shim.
+- **`RepositoryBase._buildContext` always awaits `before:*` hooks** regardless of engine mode — policy plugins must mutate context synchronously before the driver call fires. After- and error-hooks still honor `hooks: 'sync'` for fire-and-forget observability. Previous behavior (fire-and-forget in sync mode) would let driver calls race ahead of tenant/soft-delete scope injection; tracked as a latent bug surfaced by the mongokit 3.10 migration.
+
+### Changed — plugins move out, primitives move in
+
+- **All 5 plugins deleted from `@classytic/repo-core/plugins/*`** — `timestamp`, `soft-delete`, `multi-tenant`, `audit`, `cache` no longer ship from this package. Rationale: end-users install a kit, never repo-core directly, so plugins belong in the namespace users actually import. Each kit (mongokit, sqlitekit, pgkit, prismakit) owns its own plugin implementations, which lets each use driver-native features (mongoose native timestamps, SQLite triggers, Postgres `now()`, Prisma `@default`) instead of a lowest-common-denominator JS emulation.
+- **New `@classytic/repo-core/cache` subpath** — the plugin-composition primitives that every kit's cachePlugin shares:
+  - `CacheAdapter` interface (get / set / del / delByPattern)
+  - `stableStringify` — deterministic JSON keying for cache buckets
+  - `createMemoryCacheAdapter` — reference in-memory adapter for tests + single-process apps
+- **New scope helpers in `@classytic/repo-core/filter`** — `buildTenantScope(existing, tenantField, tenantId)` and `mergeScope(existing, scope)`. Every policy plugin (multi-tenant / soft-delete / org-boundary) AND-s a predicate into an existing filter while handling three shapes (undefined / Filter IR / flat record). Lifted into `/filter` so each kit's plugin composes the same merge semantics.
+- **Architectural principle codified** — "Repo-core is invisible infrastructure. End-users install a kit; repo-core exists for kit authors." See INFRA.md §3.
+
+### Arc integration review — 2026-04-19
+
+Changes landed in response to the Arc 2.10 maintainer's end-to-end integration report (see `ARC_INTEGRATION_REPORT.md`). All three non-blocking enhancements adopted; sqlitekit-side blockers are tracked on the sqlitekit package, not here.
+
+- **`OffsetPaginationResult<TDoc, TExtra>` + `KeysetPaginationResult<TDoc, TExtra>`** — added an optional second generic so kits can surface typed extras alongside the core envelope (mongokit emits `warning?: string` on deep-page reads, pgkit could surface `queryPlan`, sqlitekit could surface vacuum hints). Defaults to `Record<string, never>` so existing consumers (`OffsetPaginationResult<User>`) see zero behavioral change. Both types also export their core interface (`OffsetPaginationResultCore` / `KeysetPaginationResultCore`) for StandardRepo contract references. The `method` discriminant carries through the intersection so `if (result.method === 'offset')` narrowing keeps working.
+- **`HOOK_EVENTS` constant + `HookEventName` type** at `@classytic/repo-core/hooks` — canonical string-constant registry for every `before:* / after:* / error:*` event across the MinimalRepo + StandardRepo op set (17 ops × 3 phases = 51 events). Plugin authors subscribe via `HOOK_EVENTS.BEFORE_CREATE` instead of raw strings so typos become compile errors instead of silent no-ops. Kits with additional native ops (mongokit's `aggregate` / `bulkWrite`) compose their own extended constant on top. Cross-kit plugins written against `HOOK_EVENTS` work identically on every kit for the shared op set.
+- **`CacheAdapter.clear?(pattern?)`** replaces the previous `delByPattern?(pattern)` — aligns with mongokit's `CacheAdapter` and Arc's `CacheStore` so one Redis / KV / Memcached implementation plugs into every consumer. `clear()` with no argument wipes everything; `clear('prefix:*')` is glob-matched. `createMemoryCacheAdapter` reference impl updated. Breaking change for anything calling `adapter.delByPattern` directly — sqlitekit's cache plugin (the only in-tree caller) migrated in the same commit.
+- **`CacheAdapter.delete(key)`** — renamed from `del(key)` for consistency with JavaScript's native `Map.delete` / `Set.delete`, `MinimalRepo.delete(id)` in this same package, arc's `RepositoryLike.delete`, and every higher-level cache library (Keyv, etc.). Redis clients keep their own `.del()` — the adapter implementation translates. Applied across `@classytic/repo-core/cache` (interface + `createMemoryCacheAdapter`) and `@classytic/mongokit` (its own `CacheAdapter` type + `createMemoryCache` reference impl + every test adapter). The rename arrived **before first publish**, so no migration cost for external consumers — it's simply the shipping name.
+- **TTL unit stays seconds** (`ttlSeconds`) — matches Redis `SET EX seconds` and mongokit's existing `ttl` semantics. Arc's `ttlMs` was the outlier; the Arc team agreed to align on seconds.
+- **Sync-or-async return types preserved** on `CacheAdapter` — memory-backed adapters return synchronously without a microtask hop; Redis adapters return Promises. Consumers `await` either way at no runtime cost.
+
+**Test delta**: 153 → 177 tests (24 new covering HOOK_EVENTS exhaustiveness, pagination TExtra narrowing, and CacheAdapter + stableStringify round-trip).
+
+### Unified `withTransaction` contract — mongokit caught up
+
+The `StandardRepo.withTransaction` contract at `@classytic/repo-core/repository` has always specified `fn: (txRepo: this) => Promise<T>` — the bound-tx shape sqlitekit has implemented since 0.1. Mongokit 3.9 deviated from the contract and passed a raw `ClientSession` instead. Mongokit 3.10 fixes that: its `withTransaction` now hands over a session-threaded proxy repository matching the canonical signature. Cross-kit plugins and apps that depend on `StandardRepo.withTransaction` now work identically against mongokit and sqlitekit — one contract, no kit-specific branches.
+
+The contract docstring in `src/repository/types.ts` was already accurate; this is the mongokit-side implementation catching up. See `@classytic/mongokit` 3.10 release notes for the migration diff — this is a **breaking change for mongokit 3.x users** but repo-core's shape is unchanged.
+
+### Consumed by
+
+- **`@classytic/mongokit`** — `Repository extends RepositoryBase`; hook engine, plugin-order validator, and `HOOK_PRIORITY` sourced from repo-core. Ships its own Mongo-optimized plugins (unchanged from 3.9).
+- **`@classytic/sqlitekit`** — extends `RepositoryBase`; ships its own SQLite-optimized plugins at `@classytic/sqlitekit/plugins/{timestamp,soft-delete,multi-tenant,audit,cache}`. Imports `CacheAdapter` + `stableStringify` + `buildTenantScope` from repo-core.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Classytic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @classytic/repo-core
+
+**Driver-agnostic repository primitives.** Hooks, Filter IR, operations registry, pagination, URL query parsing, cache contract — the shared foundation for `@classytic/mongokit`, `@classytic/sqlitekit`, and future `@classytic/pgkit` / `@classytic/prismakit`.
+
+Repo-core is **infrastructure for kit authors.** End-users install a kit (mongokit / sqlitekit) and import their full API from that one namespace. Repo-core is what each kit's runtime is built on — you typically won't import it directly in application code.
+
+## Design principles
+
+- **ESM only.** `.mjs` + `.d.mts` output. Node 22+.
+- **No root barrel.** Every public surface is its own subpath in `exports`. Import directly from where the symbol lives; unused modules never enter your dep graph.
+- **Zero runtime dependencies.** No driver imports anywhere in `src/`.
+- **Tree-shakeable by construction.** `unbundle: true` in tsdown — 1:1 src→dist, no shared chunks.
+- **No plugins ship here.** Each kit owns its own plugin implementations so they can use driver-native features (mongoose's built-in timestamps, SQLite triggers, Postgres `now()`, Prisma `@default`). Repo-core provides the primitives kits compose: `CacheAdapter`, `stableStringify`, `buildTenantScope`, `HOOK_PRIORITY`, the hook engine, Filter IR.
+
+## Subpaths
+
+```ts
+// Hook engine + priority constants + canonical event names. HOOK_EVENTS turns
+// raw strings into compile-checked constants so typos fail at build time.
+import { HOOK_EVENTS, HOOK_PRIORITY, HookEngine } from '@classytic/repo-core/hooks';
+
+// Abstract repository base + MinimalRepo / StandardRepo contracts + plugin types.
+import { RepositoryBase, type MinimalRepo, type Plugin } from '@classytic/repo-core/repository';
+
+// Driver-agnostic filter AST — combinators (eq/and/or/in/like/between/...) + walk/match + scope helpers.
+import { and, eq, gte, in_, like, buildTenantScope, matchFilter } from '@classytic/repo-core/filter';
+
+// URL → ParsedQuery grammar. Backend frameworks (Express/Arc/Fastify) parse req.query here.
+import { parseUrl } from '@classytic/repo-core/query-parser';
+
+// Pagination primitives — cursor codec, keyset helpers, offset math.
+import { encodeCursor, decodeCursor, validateKeysetSort } from '@classytic/repo-core/pagination';
+
+// Cache plumbing — the CacheAdapter interface every kit's cachePlugin writes against.
+import { type CacheAdapter, stableStringify, createMemoryCacheAdapter } from '@classytic/repo-core/cache';
+
+// HTTP error envelope + duplicate-key contract.
+import { createError, conservativeMongoIsDuplicateKey } from '@classytic/repo-core/errors';
+
+// Operation registry (for arc-level policy dispatch + doc generation).
+import { CORE_OP_REGISTRY, describe } from '@classytic/repo-core/operations';
+
+// Repository hook context type (for plugin authors).
+import type { RepositoryContext } from '@classytic/repo-core/context';
+```
+
+**There is no `.` / root entry.** Import from the exact subpath — that's the contract that keeps tree-shaking honest.
+
+## Example: a kit's repository extends `RepositoryBase`
+
+```ts
+import { RepositoryBase } from '@classytic/repo-core/repository';
+import { compileFilter } from './my-kit-compiler.js';
+
+export class MyKitRepository<T> extends RepositoryBase {
+  // Kit-specific CRUD methods. Each routes through `_buildContext` → plugins
+  // → native driver call → `_emitAfter` so every plugin (timestamp, cache,
+  // multi-tenant, audit) composes identically across kits.
+  async getAll(params: {...}) {
+    const context = await this._buildContext('getAll', params);
+    const cached = this._cachedValue(context);
+    if (cached) return cached;
+    const where = compileFilter(context.filters);
+    const result = await this.driver.query(where);
+    await this._emitAfter('getAll', context, result);
+    return result;
+  }
+}
+```
+
+## Example: URL → ParsedQuery → any kit
+
+The URL grammar is identical across every kit. Frontends emit one URL; swapping the backend DB doesn't change a single query string.
+
+```ts
+import { parseUrl } from '@classytic/repo-core/query-parser';
+
+app.get('/users', async (req, res) => {
+  const parsed = parseUrl(req.query, {
+    allowedFilterFields: ['email', 'role', 'active', 'createdAt'],
+    fieldTypes: { active: 'boolean', createdAt: 'date' },
+    maxLimit: 200,
+  });
+  // Works identically against any kit's repository:
+  //   const page = await sqliteUserRepo.getAll(parsed);
+  //   const page = await mongoUserRepo.getAll(parsed);
+  res.json(await userRepo.getAll(parsed));
+});
+```
+
+URL grammar:
+
+| URL                                   | Filter IR produced                             |
+|---------------------------------------|-----------------------------------------------|
+| `?status=active`                      | `eq('status', 'active')`                       |
+| `?age[gte]=18&age[lt]=65`             | `and(gte('age', 18), lt('age', 65))`           |
+| `?role[in]=admin,editor`              | `in_('role', ['admin', 'editor'])`             |
+| `?name[contains]=john`                | `like('name', '%john%')`                       |
+| `?price[between]=10,100`              | `and(gte(...), lte(...))`                      |
+| `?deletedAt[exists]=false`            | `isNull('deletedAt')`                          |
+| `?sort=-createdAt,name`               | `{ createdAt: -1, name: 1 }` (on `.sort`)      |
+| `?select=name,email,-password`        | `{ name: 1, email: 1, password: 0 }`           |
+| `?page=2&limit=50`                    | pagination fields on ParsedQuery               |
+| `?after=eyJ2Ij...`                    | opaque keyset cursor                           |
+
+## Plugin-friendly event names
+
+```ts
+import { HOOK_EVENTS, HOOK_PRIORITY } from '@classytic/repo-core/hooks';
+
+// Cross-kit plugin — works identically on mongokit, sqlitekit, pgkit, prismakit.
+export function stampOrgId(orgId: string): Plugin {
+  return {
+    name: 'stamp-org-id',
+    apply(repo) {
+      repo.on(HOOK_EVENTS.BEFORE_CREATE, (ctx) => {
+        if (!ctx.data?.organizationId) ctx.data = { ...ctx.data, organizationId: orgId };
+      }, { priority: HOOK_PRIORITY.POLICY });
+    },
+  };
+}
+```
+
+Typos like `'before:craete'` become compile errors. Subscribing to an event a given kit doesn't emit is a silent no-op (that's how the hook engine works), so a plugin can safely wire listeners for the full standard set.
+
+## Typed result extras
+
+```ts
+import type { OffsetPaginationResult } from '@classytic/repo-core/pagination';
+
+// Kit adds a typed surface-level extra without breaking cross-kit substitutability.
+type MongokitPage<T> = OffsetPaginationResult<T, { warning?: string }>;
+
+function render(page: MongokitPage<User>) {
+  if (page.warning) showBanner(page.warning);
+  return page.docs.map(userRow);
+}
+```
+
+Default `TExtra` is `Record<string, never>` — `OffsetPaginationResult<User>` behaves identically before and after; the generic is free to ignore.
+
+## Status
+
+**v0.1.0 — initial release.**
+
+Consumed by:
+- `@classytic/mongokit` ≥ 3.10 — `Repository extends RepositoryBase`; hook engine, plugin-order validator, `HOOK_PRIORITY` sourced from repo-core. Mongokit's own `QueryParser` remains standalone (emits Mongo `$`-objects) but implements the same URL grammar by convention.
+- `@classytic/sqlitekit` (in development) — `SqliteRepository extends RepositoryBase`; Filter IR compiled to Drizzle / raw SQL natively. Uses `parseUrl` directly for URL parsing.
+
+See [INFRA.md](./INFRA.md) for the architectural principles, subpath map, build/tooling decisions, and the roadmap for pgkit / prismakit.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cache/index.d.mts

@@ -0,0 +1,4 @@
+import { CacheAdapter } from "./types.mjs";
+import { createMemoryCacheAdapter } from "./memory-adapter.mjs";
+import { stableStringify } from "./stable-stringify.mjs";
+export { type CacheAdapter, createMemoryCacheAdapter, stableStringify };

package/dist/cache/index.mjs

@@ -0,0 +1,3 @@
+import { createMemoryCacheAdapter } from "./memory-adapter.mjs";
+import { stableStringify } from "./stable-stringify.mjs";
+export { createMemoryCacheAdapter, stableStringify };

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

@@ -0,0 +1,7 @@
+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;
+//#endregion
+export { createMemoryCacheAdapter };

package/dist/cache/memory-adapter.mjs

@@ -0,0 +1,37 @@
+//#region src/cache/memory-adapter.ts
+/** Minimal in-memory `Map`-backed adapter with per-key TTL + prefix invalidation. */
+function createMemoryCacheAdapter() {
+	const store = /* @__PURE__ */ new Map();
+	const now = () => Date.now();
+	return {
+		get(key) {
+			const entry = store.get(key);
+			if (!entry) return void 0;
+			if (entry.expiresAt !== 0 && entry.expiresAt < now()) {
+				store.delete(key);
+				return;
+			}
+			return entry.value;
+		},
+		set(key, value, ttlSeconds = 60) {
+			const expiresAt = ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3;
+			store.set(key, {
+				value,
+				expiresAt
+			});
+		},
+		delete(key) {
+			store.delete(key);
+		},
+		clear(pattern) {
+			if (pattern === void 0) {
+				store.clear();
+				return;
+			}
+			const prefix = pattern.endsWith("*") ? pattern.slice(0, -1) : pattern;
+			for (const key of store.keys()) if (key.startsWith(prefix)) store.delete(key);
+		}
+	};
+}
+//#endregion
+export { createMemoryCacheAdapter };

package/dist/cache/stable-stringify.d.mts

@@ -0,0 +1,15 @@
+//#region src/cache/stable-stringify.d.ts
+/**
+ * Deterministic JSON stringify — equivalent values produce identical output.
+ *
+ * Used by kits that build cache keys from hook contexts so
+ * `{ b: 1, a: 2 }` and `{ a: 2, b: 1 }` hash to the same bucket. Arrays
+ * preserve order (order is part of array identity).
+ *
+ * Extracted from the mongokit / sqlitekit cache plugins into repo-core so
+ * every kit's cachePlugin uses the same keying rule — cross-kit caches
+ * remain bucket-compatible.
+ */
+declare function stableStringify(value: unknown): string;
+//#endregion
+export { stableStringify };

package/dist/cache/stable-stringify.mjs

@@ -0,0 +1,19 @@
+//#region src/cache/stable-stringify.ts
+/**
+* Deterministic JSON stringify — equivalent values produce identical output.
+*
+* Used by kits that build cache keys from hook contexts so
+* `{ b: 1, a: 2 }` and `{ a: 2, b: 1 }` hash to the same bucket. Arrays
+* preserve order (order is part of array identity).
+*
+* Extracted from the mongokit / sqlitekit cache plugins into repo-core so
+* every kit's cachePlugin uses the same keying rule — cross-kit caches
+* remain bucket-compatible.
+*/
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+//#endregion
+export { stableStringify };

package/dist/cache/types.d.mts

@@ -0,0 +1,59 @@
+//#region src/cache/types.d.ts
+/**
+ * Portable cache adapter contract.
+ *
+ * Kits (mongokit / sqlitekit / pgkit / prismakit) ship their own
+ * `cachePlugin` compositions; arc's `cache/QueryCache` composes on top of
+ * the same interface. One concrete Redis / KV / Memcached / in-memory
+ * implementation plugs into every consumer — no 95%-identical duplicates.
+ *
+ * ## What this contract covers
+ *
+ * Just the key-value transport layer — `get` / `set` / `del` / optional
+ * `clear`. Higher-level semantics (tag-based invalidation, SWR,
+ * stale-while-revalidate, hit-rate metrics, serialization) belong in the
+ * *consumer*, not the adapter. That keeps one adapter implementation
+ * re-usable across consumers with different cache strategies.
+ *
+ * ## TTL unit
+ *
+ * `ttlSeconds` — seconds, not milliseconds. Matches Redis (`SET key value
+ * EX seconds`), which is the dominant backend. `0` or `undefined` means no
+ * expiry; adapters are free to apply a default.
+ *
+ * ## Sync-or-async return types
+ *
+ * Both accepted. An in-memory `Map` adapter returns values synchronously; a
+ * Redis adapter returns Promises. Consumers `await` either way — awaiting
+ * a non-Promise value is a no-op at runtime.
+ */
+interface CacheAdapter {
+  /** Get a value by key. Returns `undefined` when not found or expired. */
+  get(key: string): Promise<unknown | undefined> | unknown | undefined;
+  /** Store a value with optional TTL (seconds). */
+  set(key: string, value: unknown, ttlSeconds?: number): Promise<void> | void;
+  /**
+   * Delete a single key. No-op when the key doesn't exist.
+   *
+   * Named `delete` (not `del`) to match the rest of the ecosystem:
+   * `MinimalRepo.delete(id)` in this same package, JavaScript's native
+   * `Map.delete` / `Set.delete`, arc's `RepositoryLike.delete`, and every
+   * higher-level cache library (Keyv, etc.). Redis clients keep their
+   * own `.del()` method — adapter implementations translate.
+   */
+  delete(key: string): Promise<void> | void;
+  /**
+   * Invalidate keys matching a glob pattern (typically `prefix:*`), or
+   * every key when `pattern` is omitted.
+   *
+   * Optional — simpler adapters that can't enumerate keys (some KV stores)
+   * may omit this and rely on TTL for eventual consistency. Consumers that
+   * need strict invalidation must check for its presence: `adapter.clear?.(pattern)`.
+   *
+   * Named `clear` (matching mongokit + arc) rather than `delByPattern` so
+   * one interface flows across every layer.
+   */
+  clear?(pattern?: string): Promise<void> | void;
+}
+//#endregion
+export { CacheAdapter };

package/dist/context/index.d.mts

@@ -0,0 +1,2 @@
+import { RepositoryContext } from "./types.mjs";
+export { type RepositoryContext };

package/dist/context/types.d.mts

@@ -0,0 +1,24 @@
+import { Filter } from "../filter/types.mjs";
+
+//#region src/context/types.d.ts
+/** The canonical lifecycle-hook context. */
+interface RepositoryContext {
+  /** Operation name (`'create'`, `'getAll'`, `'update'`, ...). */
+  operation: string;
+  /** Repository / model identifier. Set by `RepositoryBase` from its constructor. */
+  model: string;
+  /** Primary key for id-bearing ops. */
+  id?: string | number | unknown;
+  /** Raw filter — Filter IR or plain record. Used by most read/write ops. */
+  query?: Filter | Record<string, unknown>;
+  /** Paginated-list filter sub-bag (distinct from `query` — see docstring). */
+  filters?: Filter | Record<string, unknown>;
+  /** Single-doc create/update payload. */
+  data?: Record<string, unknown>;
+  /** Multi-doc create payload. */
+  dataArray?: Record<string, unknown>[];
+  /** Arbitrary plugin-owned fields (cache markers, soft-delete flags, ...). */
+  [key: string]: unknown;
+}
+//#endregion
+export { RepositoryContext };

package/dist/errors/create-error.d.mts

@@ -0,0 +1,19 @@
+import { HttpError } from "./types.mjs";
+
+//#region src/errors/create-error.d.ts
+/**
+ * Create an error with an HTTP status code attached.
+ *
+ * Pure helper. No driver knowledge. Used by every kit at its error boundary:
+ *
+ * ```ts
+ * throw createError(404, 'Document not found');
+ * throw createError(400, 'Invalid input');
+ * throw createError(409, 'Conflict');
+ * ```
+ */
+declare function createError(status: number, message: string): HttpError;
+/** Runtime predicate — true when `value` already carries an `HttpError` shape. */
+declare function isHttpError(value: unknown): value is HttpError;
+//#endregion
+export { createError, isHttpError };

package/dist/errors/create-error.mjs

@@ -0,0 +1,23 @@
+//#region src/errors/create-error.ts
+/**
+* Create an error with an HTTP status code attached.
+*
+* Pure helper. No driver knowledge. Used by every kit at its error boundary:
+*
+* ```ts
+* throw createError(404, 'Document not found');
+* throw createError(400, 'Invalid input');
+* throw createError(409, 'Conflict');
+* ```
+*/
+function createError(status, message) {
+	return Object.assign(new Error(message), { status });
+}
+/** Runtime predicate — true when `value` already carries an `HttpError` shape. */
+function isHttpError(value) {
+	if (!(value instanceof Error)) return false;
+	const status = value.status;
+	return typeof status === "number" && Number.isFinite(status);
+}
+//#endregion
+export { createError, isHttpError };

package/dist/errors/duplicate-key.d.mts

@@ -0,0 +1,38 @@
+import { DuplicateKeyMeta, HttpError } from "./types.mjs";
+
+//#region src/errors/duplicate-key.d.ts
+/** Predicate shape kits implement and repositories expose as `isDuplicateKeyError`. */
+type IsDuplicateKeyErrorFn = (err: unknown) => boolean;
+/**
+ * Conservative fallback predicate. Used by arc ONLY when the repository
+ * doesn't expose `isDuplicateKeyError` — preserves back-compat with
+ * mongokit ≤3.8 which didn't export the predicate. Matches ONLY MongoDB's
+ * narrow signals so it never swallows a transactional retry error.
+ *
+ * Non-Mongo kits MUST implement their own `isDuplicateKeyError` — the
+ * fallback returns `false` for their native signals (P2002, 23505, etc.).
+ */
+declare const conservativeMongoIsDuplicateKey: IsDuplicateKeyErrorFn;
+/** Options for `toDuplicateKeyHttpError`. */
+interface ToDuplicateKeyHttpErrorOptions {
+  /**
+   * Include offending values inline in the error message and under
+   * `error.duplicate.values`. Default `false` — values can be PII and
+   * end up in logs/crash reports. Enable in dev or trusted internal tools.
+   */
+  exposeValues?: boolean;
+}
+/**
+ * Build a 409 `HttpError` from already-extracted duplicate-key metadata.
+ *
+ * Kits call their driver-specific extractor (`extractMongoE11000`,
+ * `extractPrismaP2002`, ...) and pass the resulting `{ fields, values }`
+ * bundle here. Repo-core stays driver-free — it only knows the shape of
+ * the canonical 409 error.
+ *
+ * PII-safe by default: the message names fields only. Values are attached
+ * only when `exposeValues: true`.
+ */
+declare function toDuplicateKeyHttpError(meta: DuplicateKeyMeta, options?: ToDuplicateKeyHttpErrorOptions): HttpError;
+//#endregion
+export { IsDuplicateKeyErrorFn, ToDuplicateKeyHttpErrorOptions, conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError };

package/dist/errors/duplicate-key.mjs

@@ -0,0 +1,57 @@
+import { createError } from "./create-error.mjs";
+//#region src/errors/duplicate-key.ts
+/**
+* Duplicate-key detection — driver-agnostic contract.
+*
+* Every backend signals unique-constraint violations differently:
+*
+* | Backend    | Signal                                                |
+* |------------|-------------------------------------------------------|
+* | MongoDB    | `err.code === 11000` / `codeName === 'DuplicateKey'`  |
+* | Prisma     | `err.code === 'P2002'`                                |
+* | Postgres   | `err.code === '23505'`                                |
+* | SQLite     | message contains `'UNIQUE constraint failed'`         |
+*
+* Classification belongs in the kit that knows its driver. Arc's
+* idempotency / outbox adapters depend only on the boolean outcome of
+* `repository.isDuplicateKeyError(err)`, so this module defines the
+* shared contract — the `IsDuplicateKeyErrorFn` type and a safe default
+* fallback — and leaves the concrete predicate to each kit.
+*/
+/**
+* Conservative fallback predicate. Used by arc ONLY when the repository
+* doesn't expose `isDuplicateKeyError` — preserves back-compat with
+* mongokit ≤3.8 which didn't export the predicate. Matches ONLY MongoDB's
+* narrow signals so it never swallows a transactional retry error.
+*
+* Non-Mongo kits MUST implement their own `isDuplicateKeyError` — the
+* fallback returns `false` for their native signals (P2002, 23505, etc.).
+*/
+const conservativeMongoIsDuplicateKey = (err) => {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	return e.code === 11e3 || e.codeName === "DuplicateKey";
+};
+/**
+* Build a 409 `HttpError` from already-extracted duplicate-key metadata.
+*
+* Kits call their driver-specific extractor (`extractMongoE11000`,
+* `extractPrismaP2002`, ...) and pass the resulting `{ fields, values }`
+* bundle here. Repo-core stays driver-free — it only knows the shape of
+* the canonical 409 error.
+*
+* PII-safe by default: the message names fields only. Values are attached
+* only when `exposeValues: true`.
+*/
+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");
+	httpError.duplicate = {
+		fields: meta.fields,
+		...exposed && meta.values ? { values: { ...meta.values } } : {}
+	};
+	return httpError;
+}
+//#endregion
+export { conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError };

package/dist/errors/index.d.mts

@@ -0,0 +1,4 @@
+import { DuplicateKeyMeta, HttpError, ValidationErrorMeta } from "./types.mjs";
+import { createError, isHttpError } from "./create-error.mjs";
+import { IsDuplicateKeyErrorFn, ToDuplicateKeyHttpErrorOptions, conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
+export { type DuplicateKeyMeta, type HttpError, type IsDuplicateKeyErrorFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, conservativeMongoIsDuplicateKey, createError, isHttpError, toDuplicateKeyHttpError };

package/dist/errors/index.mjs

@@ -0,0 +1,3 @@
+import { createError, isHttpError } from "./create-error.mjs";
+import { conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
+export { conservativeMongoIsDuplicateKey, createError, isHttpError, toDuplicateKeyHttpError };

package/dist/errors/types.d.mts

@@ -0,0 +1,37 @@
+//#region src/errors/types.d.ts
+/**
+ * HTTP-shaped error contract used across every driver kit.
+ *
+ * An `HttpError` is a plain `Error` with a `status` field and optional
+ * structured fields for duplicate-key and validation conflicts. Kits
+ * classify their driver-specific errors into this shape at the boundary,
+ * so the framework layer (arc) never needs to know whether the error
+ * originated from MongoDB `E11000`, Postgres `23505`, or Prisma `P2002`.
+ */
+/** Structured metadata for duplicate-key (unique-constraint) errors. */
+interface DuplicateKeyMeta {
+  /** Offending field names. Always safe to log. */
+  fields: string[];
+  /**
+   * Offending values. ONLY populated when the kit's duplicate-key parser
+   * was explicitly called with `{ exposeValues: true }`. Values may contain
+   * PII (emails, tokens, phone numbers) — never log unconditionally.
+   */
+  values?: Record<string, unknown>;
+}
+/** Structured metadata for validation errors. */
+interface ValidationErrorMeta {
+  validator: string;
+  error: string;
+}
+/** HTTP-shaped error — the envelope every repository error resolves to. */
+interface HttpError extends Error {
+  /** HTTP status code (400, 404, 409, 500, ...). */
+  status: number;
+  /** Structured validation failures when `status` is 400. */
+  validationErrors?: ValidationErrorMeta[];
+  /** Structured duplicate-key metadata when `status` is 409. */
+  duplicate?: DuplicateKeyMeta;
+}
+//#endregion
+export { DuplicateKeyMeta, HttpError, ValidationErrorMeta };