@classytic/repo-core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,369 @@ 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.4.0] - 2026-05-04
+
+### Added — kit-shared building blocks (consolidation)
+
+- **`@classytic/repo-core/aggregate`** (new subpath) — kit-neutral aggregate IR helpers that every backend's compiler consumes identically: `normalizeGroupBy`, `validateMeasures`, `encodeAggCursor`, `decodeAggCursor`, `isKeysetMode`, `DecodedCursor`. mongokit + sqlitekit shipped byte-identical copies of these for the prior several releases; promoting them here keeps the IR contract honest. The driver-specific predicate builders (`buildKeysetPredicate` in mongokit, `buildKeysetHaving` in sqlitekit) stay kit-local.
+- **`@classytic/repo-core/plugins`** (new subpath) — kit-neutral plugin building blocks. Currently exports `payloadHasTenantField` (handles all 5 policy keys: data, dataArray, query, filters, operations) and `adminBypass` (skipWhen-compatible role-bypass factory). Both kits now consume these instead of shipping their own copies. Sqlitekit gains `adminBypass` for free as a side effect.
+
+### ⚠️ BREAKING — `cache/deferred.ts` removed (use `Promise.withResolvers()`)
+
+- **`createDeferred()` and `Deferred<T>` no longer exported from `@classytic/repo-core/cache`.** Both were thin wrappers around `Promise.withResolvers()`, which Node 22+ ships natively (the package's platform floor). The cache engine's single-flight map now uses the native primitive directly with zero indirection.
+- **Migration:** if you imported them, replace `import { createDeferred } from '@classytic/repo-core/cache'` with `Promise.withResolvers<T>()`. Same shape (`{ promise, resolve, reject }`); behavior is identical.
+
+### Fixed — security & robustness hardening
+
+- **DoS surface in URL parser**: `parseUrl` now drops parameter keys longer than 256 chars before bracket-regex parsing. Without the cap, a hostile 1MB key forced repeated full-string regex scans. Legitimate URL params don't approach the bound. (`src/query-parser/parse-url.ts`)
+- **Cursor payload type validation**: `decodeCursor` now type-checks every payload field, not just presence. A corrupted token shaped `{ v: { evil: true } }` previously slipped past the `'v' in p` guard and produced opaque errors downstream. (`src/pagination/cursor.ts`)
+- **Regex compile-per-doc on in-memory filter**: `matchFilter`'s `like` and `regex` cases now use a bounded LRU cache (256 entries) keyed by `(pattern, flags)`. Prior implementation compiled a fresh `RegExp` on every call — measurable cost when `asPredicate(filter)` runs over 100k docs. (`src/filter/match.ts`)
+
+### Cache hash upgrade (djb2 → FNV-1a 64-bit)
+
+- **`buildCacheKey` now uses FNV-1a 64-bit** (was djb2 32-bit). At multi-tenant fleet scale (10k tenants × dozens of cached aggregations each), djb2's 32-bit space hit ~50% birthday-paradox collision around 65k distinct keys. FNV-1a 64-bit pushes that threshold to ~4B keys. Same call site, same key shape, same regex-compatible base-36 output.
+- **Operational note for deployment:** existing Redis entries hash differently after the swap, so cold cache for one TTL cycle post-deploy. The collection-version orphan path already handles this for write-driven invalidation.
+
+### Cache layer — atomic counters, parallel invalidation, prefetch, timeout
+
+- **`CacheAdapter.increment(key, by, ttl)`** — optional atomic counter primitive. When the adapter ships it (Redis `INCRBY`, in-memory `Map`, future driver-native impls), `bumpModelVersion` produces strictly-monotonic versions across concurrent multi-pod writes — no lost bumps. Adapters without `increment` (Cloudflare KV, etc.) fall back to `get → max → set`; correct in single-pod, accepts a tiny race window in multi-pod (mitigated by `Date.now()` floor).
+- **Parallelized `invalidateByTags`** — fan-out reads + fan-out deletes via `Promise.all`. For Redis-backed adapters with pipelining, 5 tags × 100 keys completes in ~2 RTTs instead of 510. ~10× speedup on hot tags.
+- **`CacheEngine.prefetch(key, opts, fetcher)`** — TanStack-equivalent cache warming. Single-flight semantics: 100 concurrent prefetches for the same key run the fetcher exactly once. Returns cached on hit, fetches + stores on miss, dedupes via the engine's pending map.
+- **`withTimeout(adapter, { ms, onTimeout, onSlow })`** — adapter decorator that fail-fasts on slow backends. `onTimeout: 'miss'` (default) makes slow gets behave as cache misses (kit serves uncached); `'throw'` propagates `CacheTimeoutError`. `onSlow` callback for observability.
+- **`scheduleBackground`** is now a public export from `@classytic/repo-core/cache` — hosts can use the same cross-runtime primitive for their own post-response work.
+
+### Cache layer — production hardening (TanStack-aligned) + cross-runtime
+
+Six gaps in the v1 unified cache layer fixed before any prod traffic:
+
+1. **Single-flight on miss** — `CacheEngine.claimPending()` / `getPending()` / `resolvePending()` / `rejectPending()`. Concurrent misses for the same key wait on the first claimer's promise instead of running N redundant fetches. Cache-stampede prevention; TanStack `QueryClient`-equivalent.
+2. **Per-scope version-bump** — `bumpModelVersion(model, scopeKey?)` and `getModelVersion(model, scopeKey?)`. Writes inside `org:abc` no longer invalidate `org:xyz`'s cached reads. Targeted invalidation; matches TanStack's "exact match" semantics.
+3. **Cross-runtime SWR scheduling** — new `runtime.ts` exposes `scheduleBackground` that picks `setImmediate` on Node / Bun and `setTimeout(0)` on Cloudflare Workers / Deno Deploy / browser. Either way the callback fires after the current sync block + microtask queue, ensuring the user's response writes to the socket BEFORE the bg fetch's first await. (Old impl used `setImmediate` directly — `ReferenceError` on edge runtimes.)
+4. **TTL-bounded tag index** — index entries inherit their cached entries' TTLs (capped at 24h). Old impl used `ttlSeconds: 0` ("never expire" in Redis); side-index grew unboundedly on hot tags.
+5. **`error:<op>` rejects pending** — when the claimer's executor errors, the plugin's `error:<op>` hook rejects the deferred so single-flight waiters fail-fast. No hanging promises, no double-fetch on transient backend failures.
+6. **Allowlist-per-op shape keys** — `DEFAULT_SHAPE_KEYS_BY_OP` maps each read op to the fields that actually affect result shape. Only those fields participate in the cache key. Replaces the prior denylist (which would silently include any new context field a kit added — exploding miss rates if e.g. `requestId` slipped through). Hosts can override per-op via `cachePlugin({ shapeKeysByOp })`.
+
+### Code organization
+
+The unified plugin (`@classytic/repo-core/cache`) is now split into focused modules:
+
+```
+cache/
+  plugin/
+    index.ts                  # cachePlugin factory + types + handle (~200 LOC)
+    context.ts                # typed context slots + extraction + shape-keys (~170 LOC)
+    read-hooks.ts             # before/after/error for read ops (~180 LOC)
+    invalidation-hooks.ts     # after for write ops (~60 LOC)
+    swr.ts                    # background-refresh scheduler (~50 LOC)
+  engine.ts                   # TTL + SWR + tag + version + single-flight (~220 LOC)
+  runtime.ts                  # cross-runtime scheduleBackground (~50 LOC)
+  ...
+```
+
+Each module has one purpose. Replaces the prior 564-LOC `plugin.ts` mega-file.
+
+### Added — `Deferred<T>` utility
+
+`createDeferred<T>()` exported from `@classytic/repo-core/cache` — a Promise plus its `resolve`/`reject` handles, externalized. Same primitive `Promise.withResolvers()` provides natively in Node 22+; we ship our own to keep the contract explicit and support older runtimes.
+
+### Added — Unified cache layer (`@classytic/repo-core/cache`)
+
+One `cachePlugin({ adapter })` for every kit + arc + Express/Nest hosts. Replaces three independent SWR/TTL/tag implementations (mongokit's CRUD `cachePlugin` + aggregate `withAggCache`, sqlitekit's local `cachePlugin`, arc's `QueryCache`) with one canonical hook integration.
+
+#### Public surface (`@classytic/repo-core/cache`)
+
+```ts
+import {
+  cachePlugin,                  // hook integration — plugs into RepositoryBase
+  CacheEngine,                   // direct SWR + TTL + tag flow over a CacheAdapter
+  buildEnvelope, inspectEnvelope, type CacheEnvelope,
+  buildCacheKey, extractScopeTags, type BuildKeyInput,
+  appendKeyToTags, invalidateByTags as invalidateByTagsImpl,
+  bumpModelVersion, getModelVersion,
+  resolveCacheOptions, type CacheOptions, type ResolvedCacheOptions, type CacheReadResult,
+  // already shipped:
+  type CacheAdapter, createMemoryCacheAdapter, stableStringify,
+} from '@classytic/repo-core/cache';
+```
+
+#### TanStack Query-shaped per-call options
+
+Same shape across CRUD + aggregate, kit-agnostic:
+
+```ts
+{
+  staleTime?: number;     // seconds fresh
+  gcTime?: number;        // seconds retained past stale (default 60)
+  swr?: boolean;          // serve-stale + bg refresh
+  tags?: readonly string[];
+  bypass?: boolean;
+  enabled?: boolean;
+  key?: string;           // explicit override
+}
+```
+
+#### What the plugin does
+
+1. Subscribes to `before:<op>` / `after:<op>` for every read op (`getById`, `getAll`, `getOne`, `getByQuery`, `count`, `exists`, `distinct`, `aggregate`, `aggregatePaginate`) — configurable via `enabled: [...]`.
+2. Subscribes to `after:<op>` for every mutating op (`create`, `update`, `delete`, `claim`, ...) — configurable via `invalidating: [...]`. Bumps the model's version (orphans every cached read in O(1)) AND invalidates the model-tag (cross-aggregation invalidation).
+3. Auto-injects scope tags (`org:<id>`, `user:<id>`) from `context.filter` so cross-tenant cache poisoning is structurally impossible.
+4. Hooks register at `HOOK_PRIORITY.CACHE` (200) — multi-tenant + soft-delete (POLICY = 100) run first so their filter mutations land in the cache key.
+5. Attaches `repo.cache` handle exposing `invalidateByTags(tags)`, `bumpModelVersion(model)`, `clear()`.
+
+#### Strictly-monotonic version bumps
+
+`bumpModelVersion` uses `max(Date.now(), previous + 1)` so same-millisecond writes (cache prime + write hit at the same ms) don't collide, fixing a real correctness gap the prior `Date.now()`-only impl had.
+
+#### `AggCacheOptions` is now an alias for `CacheOptions`
+
+Same shape across CRUD + aggregate. Old field names (`ttl`, `staleWhileRevalidate`) removed — migrate to `staleTime`, `swr`. Ecosystem packages (mongokit, sqlitekit, arc) all consume the unified type.
+
+#### Removed
+
+- `/aggregate-cache` subpath — superseded by the unified `/cache` plugin (which handles aggregate ops natively via the `before:aggregate` hook).
+
+#### Migration (kit + host)
+
+```ts
+// Before — kit-specific cache plugins + constructor option
+new Repository(model, [cachePlugin({ adapter, ttlSeconds: 60 })], {}, {
+  aggregateCache: adapter,  // separate constructor option
+});
+repo.aggregate({ measures, cache: { ttl: 60, staleWhileRevalidate: true } });
+
+// After — one plugin, one shape
+new Repository(model, [
+  multiTenantPlugin({ tenantField: 'orgId' }),
+  cachePlugin({ adapter, defaults: { staleTime: 60, gcTime: 300, swr: true } }),
+]);
+repo.aggregate({ measures, cache: { staleTime: 60, swr: true, tags: ['orders'] } });
+repo.getAll(filter, { cache: { staleTime: 30 } });
+await repo.cache?.invalidateByTags(['orders']);
+```
+
+### Added — `StandardRepo.claim()` and `claimVersion()` (atomic CAS, REQUIRED on the contract)
+
+Standardizes the canonical state-machine write that every domain package was hand-rolling on top of `findOneAndUpdate`:
+
+```ts
+const claimed = await repo.claim?.(runId, { from: 'waiting', to: 'running' }, {
+  lastHeartbeat: new Date(),
+  workerId: 'worker-12',
+});
+if (!claimed) return; // someone else got it
+```
+
+**Cross-kit portable.** Mongokit compiles to `findOneAndUpdate({ _id, status: from }, { $set: { status: to, ...patch } })`. SQL kits compile to `UPDATE x SET ... WHERE id = ? AND status = <from> RETURNING *`. Prismakit compiles to `prisma.x.updateMany({ where: { id, status: from }, data: ... })` followed by a `findUnique` when `count > 0`. Same input, same null-on-race semantics across every backend.
+
+**Pairs with `@classytic/primitives/state-machine`** — different layers:
+- `defineStateMachine()` answers "is `from → to` legal in the model?" (compile-time table + early throw)
+- `claim()` answers "did we win the transition vs concurrent writers?" (runtime null on race)
+
+The state field defaults to `'status'` (matches the convention across `streamline`, `@classytic/order`, `revenue`, `invoice`); pass `{ field: 'phase', from, to }` for state machines keyed off a different column.
+
+#### New types exported from `@classytic/repo-core/repository`
+
+- `ClaimTransition` — `{ field?, from, to, where? }` argument shape for `claim` (`where` is the compound-CAS predicate slot — see below).
+- `ClaimVersionTransition` — `{ field?, from: number | undefined, by?, where? }` argument shape for `claimVersion`. `from === undefined` is admitted for first-write CAS (matches docs whose version field is null OR missing).
+
+#### Added to `StandardRepo<TDoc>` — REQUIRED methods (not optional)
+
+```ts
+claim(
+  id: string,
+  transition: ClaimTransition,
+  patch?: Partial<TDoc>,
+  options?: WriteOptions,
+): Promise<TDoc | null>;
+
+claimVersion(
+  id: string,
+  transition: ClaimVersionTransition,
+  update: Record<string, unknown>,
+  options?: WriteOptions,
+): Promise<TDoc | null>;
+```
+
+**Required, not optional.** During pre-release dev iterations, `claim?` was optional as scaffolding while kits implemented. Both mongokit and sqlitekit ship them as concrete class primitives, and downstream domain packages (~10 in the classytic codebase) carry FSM verbs depending on them — none gracefully degrade. Required-on-the-contract removes the `if (repo.claim) { ... }` boilerplate at every call site and surfaces missing implementations at the conformance gate instead of at runtime.
+
+#### `ClaimTransition.where` — compound-CAS predicate
+
+Real-world audit (streamline, commission, yard, revenue, order, invoice): the bare `{ [idField]: id, [field]: from }` filter shape fits ~5% of atomic-claim sites in production. The other 95% carry compound predicates — paused guards, retry-time guards, heartbeat-staleness, sub-document `$elemMatch`, `$or` for missing-or-stale fields. Without a way to express those, `claim()` covered the textbook example but couldn't replace the hand-rolled CAS calls in production.
+
+`ClaimTransition.where` AND-merges arbitrary predicates alongside the canonical id + state-field match:
+
+```ts
+const claimed = await repo.claim?.(runId, {
+  from: 'waiting',
+  to: 'running',
+  where: {
+    paused: { $ne: true },
+    'scheduling.retryAfter': { $lte: new Date() },
+  },
+}, { lastHeartbeat: new Date() });
+```
+
+Cross-kit notes:
+- Mongokit: ANDed into the `findOneAndUpdate` filter.
+- SQL kits: ANDed into the `WHERE` clause (raw column literals accepted; portable Filter IR is compiled).
+- Prismakit: merged as additional keys on the `where` object.
+
+Null-on-race semantics unchanged — if no doc matches the full compound filter (state OR any `where` predicate), `claim` returns `null`. The caller can't distinguish "lost race" from "guard predicate failed"; both mean "don't proceed."
+
+Driven by streamline's audit (1 of 21 sites fit the bare shape; 21 of 21 fit the compound shape). Same pattern across the other audited packages.
+
+#### `ClaimTransition.from` widened to `unknown | readonly unknown[]` — multi-source CAS
+
+Single-value `from` covers the textbook one-source transition (`waiting → running`). Real-world state machines also need to claim from one of multiple source states — commission's `voidRecord` / `markClawedBack` / `endAgreement` / `_transition` (4 sites), media-kit's `pending|processing → error` catch-block. `from` now accepts an array; kit compilers emit `[stateField] IN (...)` (SQL) or `[stateField]: { $in: [...] }` (mongo).
+
+```ts
+// "From any non-terminal state to voided"
+await repo.claim?.(id, { from: ['pending', 'approved', 'sent'], to: 'voided' });
+```
+
+Single-value `from` is unchanged (back-compatible). Array form is opt-in — pass an array to enable.
+
+**`from === to` is allowed** — the documented idempotent re-claim semantic. Yard's `reviseDeparture` writes `departed → departed` to atomically refresh the row's payload while asserting it hasn't moved on. The CAS still returns `null` if the row left the source state, so race-loss semantics hold.
+
+#### Migration
+
+Pre-0.4.0 callers wrote:
+
+```ts
+const claimed = await repo.findOneAndUpdate(
+  { _id: id, status: 'waiting' },
+  { $set: { status: 'running', lastHeartbeat: new Date() }, },
+);
+```
+
+Post-0.4.0:
+
+```ts
+const claimed = await repo.claim?.(id, { from: 'waiting', to: 'running' }, { lastHeartbeat: new Date() });
+```
+
+The old form keeps working — `claim()` is an additive optional method, not a rename.
+
+## [0.3.0] - 2026-04-29
+
+### Added — Aggregate pagination shapes
+
+- `AggregatePaginationResultCore<TDoc>` and `AggregatePaginationResult<TDoc, TExtra>` join `Offset*` / `Keyset*` as the third pagination shape every kit reports. Mirrors offset (page / total / pages / hasNext / hasPrev) with `method: 'aggregate'` discriminant. Mongokit's existing local `AggregatePaginationResult` (3.10.x) becomes redundant — to be deleted in mongokit 4.0.
+- `AnyPaginationResult<TDoc, TExtra>` — union over the three result shapes. Use as the input type to anything that converts repo results into HTTP envelopes.
+
+### Added — HTTP wire envelopes
+
+The repository result shapes (`OffsetPaginationResult`, etc.) carry the `method` discriminant, so the corresponding HTTP wire envelope is just `{ success: true } & Result`. Adding the literal here closes the **server/client envelope mismatch** — arc's HTTP server was emitting flattened paginated responses without the `method` field while arc-next's typed responses required it.
+
+- `OffsetPaginationResponse<TDoc, TExtra>` = `{ success: true } & OffsetPaginationResult<TDoc, TExtra>`
+- `KeysetPaginationResponse<TDoc, TExtra>` = same for keyset
+- `AggregatePaginationResponse<TDoc, TExtra>` = same for aggregate
+- `BareListResponse<TDoc>` = `{ success: true; docs: TDoc[] }` for endpoints that don't paginate
+- `PaginatedResponse<TDoc, TExtra>` = union over all four. The discriminated-union contract is `success: true` literal first, `method` second — typed clients (arc-next, SDKs) narrow with `if (res.success && 'method' in res && res.method === 'offset')`.
+
+### Added — `toCanonicalList()` runtime normalizer
+
+```ts
+import { toCanonicalList } from '@classytic/repo-core/pagination';
+
+const result = await userRepo.getAll(query);
+reply.send(toCanonicalList(result));   // → PaginatedResponse<User>
+
+reply.send(toCanonicalList([u1, u2])); // → BareListResponse<User>
+```
+
+The single point where an internal `Result` becomes an external `Response`. Three overloads route bare arrays / paginated results to the right wire shape; `TExtra` fields (mongokit's `warning?: string`, etc.) flow through.
+
+**Subtle behavior**: `success: true` is stamped *after* the spread, so a stale `success: false` accidentally present on the input cannot override the literal — paginated success path is always `success: true`. Tested.
+
+### Added — `isPaginatedResult()` type guard
+
+Branches on the `method` discriminant rather than `Array.isArray`, so an empty paginated result still routes through the paginated branch. Used internally by `toCanonicalList`; exported for consumers writing custom envelope logic.
+
+### Test delta
+
+230 → 303 tests across 0.3.0. New coverage includes `tests/unit/pagination/canonical.test.ts` and the type-level coverage extensions in `result-types.test.ts` (35 tests landed with the aggregate / wire-envelope / `toCanonicalList` work), plus `tests/unit/repository/base-plugin-validation.test.ts` (6 tests for the `assertValidPlugin` guard).
+
+### Added — `SchemaGenerator<TModel>` interface in `/schema`
+
+Canonical contract for repository kits' CRUD-schema generators. Mongokit's `buildCrudSchemasFromModel` and sqlitekit's `buildCrudSchemasFromTable` (and any future kit's equivalent) `satisfies SchemaGenerator<TKitModel>` at the call site, so arc's `MongooseAdapter.schemaGenerator` / `DrizzleAdapter.schemaGenerator` accept them by structural typing — no glue, no inheritance, no inline function signatures duplicated in every adapter.
+
+- `SchemaGenerator<TModel = unknown>` — `(model, options?, context?) => CrudSchemas | Record<string, unknown>`.
+- `SchemaGeneratorContext` — resource-level context threaded at boot (`idField`, `resourceName`).
+- `isSchemaGenerator(value)` — runtime predicate (arity 1-3 functions). Conservative — doesn't invoke.
+
+Each kit ships a compile-time conformance check (same playbook as mongokit's `RepositoryLike` conformance gate):
+
+```ts
+const _conformance: SchemaGenerator<Model<unknown>> = buildCrudSchemasFromModel;
+```
+
+Drift surfaces in the kit's typecheck immediately, before any consumer sees it.
+
+10 new tests in `tests/unit/schema/generator.test.ts`. Total repo-core: 293 → 303.
+
+### Added — `errors` module: canonical wire + throwable error contract
+
+`@classytic/repo-core/errors` is now the single source of truth for error contracts across the org. Two complementary shapes:
+
+- **`HttpError extends Error`** — the *throwable* shape. Plain `Error` with `status`, optional `code`, `meta`, `validationErrors`, `duplicate`. Kits classify their driver-specific errors into this shape; framework layers (arc) catch and serialize. Existing `HttpError` extended in 0.3 with `code?: string` and `meta?: Record<string, unknown>` (mongokit had these locally pre-3.12).
+- **`ErrorContract`** — the *wire* shape (RFC 7807 / Stripe-style). What gets serialized to JSON responses, dead-letter records, audit trails, inter-service envelopes. Flat top-level `code` / `message` / `status` matches the org-wide `{ success, ... }` envelope convention.
+- **`ErrorDetail`** — single field-scoped error (path / code / message). `ErrorContract.details` is `ReadonlyArray<ErrorDetail>`.
+- **`ERROR_CODES` + `ErrorCode`** — canonical lowercase + snake_case codes (`'validation_error'`, `'not_found'`, `'conflict'`, `'unauthorized'`, `'forbidden'`, `'rate_limited'`, `'idempotency_conflict'`, `'precondition_failed'`, `'internal_error'`, `'service_unavailable'`, `'timeout'`). Domain packages extend hierarchically (`'order.validation.missing_line'`).
+- **`toErrorContract(error)`** — converts any `Error` / `HttpError` / non-`Error` value to the canonical wire `ErrorContract`. `code` cascade: explicit `error.code` → status-derived → `'internal_error'`. Flattens mongokit-shaped `validationErrors` and `duplicate.fields` into the canonical `details[]` array.
+- **`statusToErrorCode(status)`** — well-known HTTP status → canonical code. Conservative mapping; unknown statuses fall through to `'internal_error'` so domain handlers explicitly opt in.
+
+Consumed by mongokit (drops local `HttpError`), arc (`ArcError implements HttpError` with `status` getter), and any future kit / service. Relocated from `@classytic/primitives/errors` (which had `ErrorContract` + `ERROR_CODES` but not the throwable contract) — same playbook as the pagination, tenant, and events relocations: errors are infrastructure-shaped, not domain primitives.
+
+14 new tests in `tests/unit/errors/contract.test.ts`. Total repo-core: 279 → 293.
+
+### Added — `tenant` subpath (canonical home for tenant scope contract)
+
+New subpath `@classytic/repo-core/tenant` ships:
+- `TenantConfig` — static config (`strategy`, `enabled`, `tenantField`, `fieldType`, `ref`, `contextKey`, `required`, `resolve`).
+- `TenantStrategy = 'field' | 'none' | 'custom'`, `TenantFieldType = 'objectId' | 'string'`.
+- `ResolvedTenantConfig` — the resolved-with-defaults shape returned by `resolveTenantConfig`.
+- `DEFAULT_TENANT_CONFIG` — sensible org-wide defaults (`tenantField: 'organizationId'`, `fieldType: 'objectId'`, `ref: 'organization'`, `required: true`).
+- `resolveTenantConfig(config?)` — normaliser; validates `'custom'` strategy requires `resolve`.
+
+Relocated from `@classytic/primitives/tenant` (which has been removed in primitives 0.3 cleanup). Tenant scope is **infrastructure-shaped** — describes how queries get scoped, not a domain primitive like Money or Address. Repo-core is its proper home: it sits next to `context`, `filter`, `hooks`, `schema`, `cache` — every other repository contract — and lets mongokit / sqlitekit / future kits consume it through the existing `@classytic/repo-core` peer dep without pulling primitives just for one type.
+
+**Custom tenancy escape hatch** unchanged: `strategy: 'custom'` + `resolve: (ctx) => filterShape` covers multi-field composites, region+partner shards, hash-derived filters, anything that doesn't fit `field === id`.
+
+14 new tests in `tests/unit/tenant/resolve.test.ts` (ported from primitives' suite). Total repo-core: 265 → 279 tests.
+
+### Added — schema-builder vocabulary
+
+- **`SchemaBuilderOptions.excludeFields`** — global field exclusion. Fields listed here are dropped from create / update / response schemas in one place. Equivalent to setting `create.omitFields`, `update.omitFields`, AND `response.omitFields` to the same list. Use for fields that should never appear in any HTTP-facing schema.
+- **`SchemaBuilderOptions.response`** with `omitFields?: string[]` — response-schema overrides. Drops extra fields from the response shape without marking them globally hidden.
+- **`CrudSchemas.response?: JsonSchema`** — optional response-shape schema. Includes server-set fields (`createdAt`, `updatedAt`, `_id`, immutable / readonly / systemManaged) since those ARE returned to clients. Only `fieldRules[field].hidden: true` strips automatically. Set `additionalProperties: true` so virtuals / computed fields pass through.
+- **`FieldRule.hidden?: boolean`** — strips the field from the response shape. Distinct from `systemManaged` (request-body concern). Use for passwords, secrets, internal scoring.
+- **`collectFieldsToOmit(options, 'response')`** — third purpose alongside `'create'` / `'update'`. Implements the response policy (only `hidden` + `excludeFields` + `response.omitFields`).
+
+These are the contracts mongokit 3.12 implements, arc 2.12's MongooseAdapter consumes, and any future kit (sqlitekit, prismakit) inherits for free.
+
+### Hardened — `RepositoryBase` plugin-shape validation
+
+`RepositoryBase.use()` and the constructor's plugin loop now reject malformed plugin entries up front via `assertValidPlugin()`. The motivating field bug: `new Repository(Model, ['organizationId'], opts)` — passing a tenant-field string array where the constructor expected `plugins[]` — used to crash deep in the call site with `TypeError: plugin.apply is not a function`, cascade-failing every test that booted the app. The validator now throws a single descriptive `TypeError` at construction with the offending index and a hint about the common `tenantField`-in-the-wrong-slot mistake:
+
+```
+[repo-core] Repository "Foo": plugin at index 0 has wrong type.
+Expected a function or { name, apply(repo) } object — got string 'organizationId'.
+Common cause: `new Repository(Model, [tenantField], opts)` — second argument must be a plugins array.
+```
+
+Lock-in: `tests/unit/repository/base-plugin-validation.test.ts` (6 cases covering string/null/object-without-apply/function/object/post-construction `use()` paths).
+
+### Migration — mongokit 4.0, arc 2.12, arc-next 0.6
+
+Three downstream changes drop their local copies and import directly:
+
+1. **mongokit 4.0** — deletes its local `AggregatePaginationResult` declaration and `PaginationResult` union; consumers that imported them from `@classytic/mongokit` must switch to `@classytic/repo-core/pagination`. (Breaking.)
+2. **arc 2.12** — `fastifyAdapter` calls `toCanonicalList()` once instead of inline-flattening offset and falling through keyset/aggregate as nested `data`. Closes a real wire-envelope-mismatch bug.
+3. **arc-next 0.6** — adds `@classytic/repo-core` as peer dep, deletes its local `OffsetPaginationResponse` / `KeysetPaginationResponse` / `AggregatePaginationResponse` / `PaginatedResponse` types. Server and client now share one declaration — the `method` field asymmetry is impossible by construction.
+
+No breaking changes inside `@classytic/repo-core` itself — purely additive.
+
 ## [0.2.0] - 2026-04-22
 
 ### Added — Update IR (portable write-side primitive)

package/README.md

@@ -28,14 +28,34 @@ import { and, eq, gte, in_, like, buildTenantScope, matchFilter } from '@classyt
 // 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';
+// Pagination primitives — cursor codec, keyset helpers, offset math, the canonical
+// result types (`OffsetPaginationResult`, `KeysetPaginationResult`,
+// `AggregatePaginationResult`, `PaginationResult`) and the wire helper
+// `toCanonicalList()`. Single source of truth — primitives' duplicate dropped,
+// mongokit/sqlitekit re-export from here.
+import { encodeCursor, decodeCursor, validateKeysetSort, toCanonicalList } from '@classytic/repo-core/pagination';
+import type { OffsetPaginationResult, KeysetPaginationResult, AggregatePaginationResult, PaginationResult } from '@classytic/repo-core/pagination';
+
+// Tenant config — the canonical `TenantConfig`, `TenantStrategy`, `TenantFieldType`,
+// `resolveTenantConfig`, `DEFAULT_TENANT_CONFIG`, `ResolvedTenantConfig`. Kits'
+// `MultiTenantOptions extends Pick<TenantConfig, ...>`.
+import { resolveTenantConfig, DEFAULT_TENANT_CONFIG } from '@classytic/repo-core/tenant';
+import type { TenantConfig, ResolvedTenantConfig } from '@classytic/repo-core/tenant';
 
 // 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';
+// Error contracts — `HttpError` throwable + `ErrorContract` wire shape +
+// `ErrorDetail` + `ErrorCode` + `ERROR_CODES` + `toErrorContract()` +
+// `statusToErrorCode()`. Single source of truth — primitives' errors module dropped,
+// mongokit's local `HttpError` dropped, `ArcError implements HttpError`.
+import { toErrorContract, statusToErrorCode, ERROR_CODES, createError, conservativeMongoIsDuplicateKey } from '@classytic/repo-core/errors';
+import type { HttpError, ErrorContract, ErrorDetail, ErrorCode } from '@classytic/repo-core/errors';
+
+// Schema generator interface — kits ship `SchemaGenerator<TModel>` + the
+// compile-time conformance assertion; arc adapters are typed against it.
+import type { SchemaGenerator, SchemaGeneratorContext } from '@classytic/repo-core/schema';
+import { isSchemaGenerator } from '@classytic/repo-core/schema';
 
 // Operation registry (for arc-level policy dispatch + doc generation).
 import { CORE_OP_REGISTRY, describe } from '@classytic/repo-core/operations';
@@ -141,11 +161,12 @@ Default `TExtra` is `Record<string, never>` — `OffsetPaginationResult<User>` b
 
 ## Status
 
-**v0.1.0 — initial release.**
+**v0.3.0 — canonical contracts release.** Pagination types + wire envelope, tenant config, error contracts, and the `SchemaGenerator<TModel>` interface relocated from primitives / mongokit / arc to single sources of truth here.
 
 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.
+- `@classytic/mongokit` ≥ 3.12 — `Repository extends RepositoryBase`; hook engine, plugin-order validator, `HOOK_PRIORITY` sourced from repo-core. Pagination + `HttpError` types now flow from repo-core (mongokit's local copies dropped). `MultiTenantOptions extends Pick<TenantConfig, ...>`. `buildCrudSchemasFromModel` ships a compile-time `SchemaGenerator<TModel>` conformance assertion. Mongokit's own `QueryParser` remains standalone.
+- `@classytic/sqlitekit` ≥ 0.2 — `SqliteRepository extends RepositoryBase`; Filter IR compiled to Drizzle / raw SQL natively. `MultiTenantOptions extends Pick<TenantConfig, ...>`. `buildCrudSchemasFromTable` ships the same `SchemaGenerator` conformance assertion.
+- `@classytic/arc` ≥ 2.12 — adapters typed against `SchemaGenerator<TModel>`; `ArcError implements HttpError`; pagination wire envelope (`method` discriminant) emitted via `toCanonicalList()` with `reply.sendList()`.
 
 See [INFRA.md](./INFRA.md) for the architectural principles, subpath map, build/tooling decisions, and the roadmap for pgkit / prismakit.
 

package/dist/adapter/index.d.mts

@@ -0,0 +1,3 @@
+import { AdapterFactory, AdapterRepositoryInput, AdapterSchemaContext, AdapterValidationResult, DataAdapter, FieldMetadata, OpenApiSchemas, RelationMetadata, RepositoryLike, SchemaMetadata } from "./types.mjs";
+import { asRepositoryLike, isRepository } from "./widen.mjs";
+export { type AdapterFactory, type AdapterRepositoryInput, type AdapterSchemaContext, type AdapterValidationResult, type DataAdapter, type FieldMetadata, type OpenApiSchemas, type RelationMetadata, type RepositoryLike, type SchemaMetadata, asRepositoryLike, isRepository };

package/dist/adapter/index.mjs

@@ -0,0 +1,2 @@
+import { asRepositoryLike, isRepository } from "./widen.mjs";
+export { asRepositoryLike, isRepository };