@prismakit/cli 3.2.1 → 4.0.0

package/skills/prismakit/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 
 Framework-agnostic Prisma repository kit. Not a Prisma fork. Only repositories talk to Prisma.
 
-NestJS apps: also load skill `prismakit-nestjs` after this contract.
+**Line:** 4.0 (pre-stable). NestJS apps: also load skill `prismakit-nestjs` after this contract.
 
 ## Non-negotiables
 
@@ -29,10 +29,10 @@ Violations are bugs. Enforce with `@prismakit/eslint-plugin` + this skill.
 
 | Required | How |
 |----------|-----|
-| Reads/writes | `*Repository` from `createRepository` / Nest factories |
+| Reads/writes | `*Repository` from `createRepository` / Nest `createDefineRepo` |
 | Tx writes | `invalidate: 'none'` then `invalidateCache` after commit |
 | User-facing reads | `setCache: true` when the repo has cache config |
-| Relations in `select` | `model` + `scalarFields` or loaded Prisma meta |
+| Relations in `select` | `model` + Prisma meta loaded (`loadPrismaMetaFromSchema` / `loadPrismaMetaFromDmmf` or Nest `schemaPath` / `dmmf`) |
 | ESLint | `prismakit.configs.recommended` |
 
 ## Layers
@@ -47,7 +47,7 @@ Helpers may inject repositories — never the Prisma client.
 
 | Task | Use |
 |------|-----|
-| New repository | `createRepository` (core) or Nest `defineRepo` — see `prismakit-nestjs` |
+| New repository | `createRepository` (core) or Nest `defineAppRepo` — see `prismakit-nestjs` |
 | User-facing get by id | `getThrowById` / `getById` + `setCache: true` |
 | Existence / uniqueness / auth | `getFirst` — **no** `setCache` |
 | List | `getMany` + `setCache: true` + optional `cacheTags` |
@@ -65,15 +65,18 @@ Helpers may inject repositories — never the Prisma client.
 
 ```typescript
 import { PrismaClient } from '@prisma/client';
-import { createRepository } from '@prismakit/core';
+import { createRepository, loadPrismaMetaFromSchema } from '@prismakit/core';
 import { RedisCacheAdapter } from '@prismakit/redis';
 
+loadPrismaMetaFromSchema('prisma/schema.prisma');
+// Prisma 5/6: loadPrismaMetaFromDmmf(Prisma.dmmf)
+
 const DAY = 86_400;
 
 const UserRepoClass = createRepository({
   model: 'user',
   cache: { ttl: DAY, nullTtl: 60, sensitiveFields: ['password'] },
-  lock: true, // table + columns resolved from Prisma schema meta
+  lock: true, // table + columns from Prisma meta
 });
 
 const prisma = new PrismaClient();
@@ -81,19 +84,16 @@ const cache = new RedisCacheAdapter({ prefix: 'myapp' });
 export const users = new UserRepoClass({ prisma, cache });
 ```
 
-`defineRepository` and `createPrismaRepository` are aliases of `createRepository`.
+Public factory: **`createRepository` only** (no `defineRepository` / `createPrismaRepository` aliases).
 
-**NestJS apps:** use `createDefineRepo` / `defineAppRepo` with app-wide cache defaults instead — see skill `prismakit-nestjs`.
+**NestJS apps:** use `createDefineRepo` / `defineAppRepo` — see skill `prismakit-nestjs`.
 
 | Option | Description |
 |--------|-------------|
-| `model` | Prisma client key (`prisma.user` → `'user'`). Needed for cache + compose. |
-| `scalarFields` | Usually `Prisma.XScalarFieldEnum`. **Optional** when `schemaPath` / DMMF meta is loaded (default since 3.1). |
+| `model` | Prisma client key (`prisma.user` → `'user'`). **Required.** |
 | `cache` | `CacheOptions` or `true` (uses app defaults when bound via `createDefineRepo`). |
-| `lock` | `true` / client key / `@@map` table / `{ tableName, columns }`. |
-| `primaryKey` | Override only. Defaults to schema `@id` / `@@id` (composite `string[]`) or `id`. |
-| `schemaPath` | Path to `schema.prisma` when meta is not loaded globally. Default: `prisma/schema.prisma`. |
-| `getDelegate` | Optional. Defaults to `(c) => c[model]`. |
+| `lock` | `true` (from meta) or `{ tableName, columns? }`. |
+| `toPayload` | Optional payload mapper (default identity). |
 
 Put files under `**/repositories/**`. Keep Prisma client construction under `**/infrastructure/prisma/**`.
 
@@ -123,7 +123,8 @@ await users.getFirst({
 | `getMany` | array (`take` / `skip` / `orderBy`) |
 | `getManyPaginate` | `{ data, meta: { page, pageSize, totalItems, totalPages } }` |
 | `getManyCursor` | `{ data, nextCursor, hasMore }` |
-| `count` / `exists` | `{ count }` / `{ exists }` |
+| `getThrowFirst` | first match; throws if missing |
+| `count` / `exists` | `number` / `boolean` |
 | `aggregate` / `groupBy` | Prisma delegate results |
 
 `id` is `string` or `Record<string, string>` for composite PKs (object form for `@@id([a,b])`).
@@ -134,8 +135,11 @@ await users.getFirst({
 
 | Method | Default `invalidate` |
 |--------|----------------------|
-| `create` / `createMany` | `queries` |
-| `updateById` / `updateMany` / `upsert` / `deleteById` / `deleteMany` | `all` |
+| `create` / `createMany` / `createManyAndReturn` | `queries` |
+| `updateById` / `update` / `updateMany` / `updateManyAndReturn` | `all` |
+| `upsert` / `upsertMany` | `all` |
+| `deleteById` / `delete` / `deleteMany` | `all` |
+| `queryRaw` / `executeRaw` | none (raw SQL — no cache) |
 
 ```typescript
 await users.updateById({
@@ -163,7 +167,7 @@ If Redis is down, `RedisCacheAdapter` **fails open** — queries still hit Prism
 | Auth, uniqueness, JWT lookup | omit / `false` |
 | Inside `tx` | ignored |
 
-Repository `cache` is the source of truth. Omit `cacheModels` (fail-open). An optional allowlist throws if a cached repo's model is missing from the list.
+Repository `cache` is the source of truth. There is no Nest `cacheModels` allowlist in 4.0.
 
 `setCache` / `cacheTags` / `invalidate` / `invalidateCache` exist on the type **only** when the repo has `cache` config. Do not force them on uncached repos.
 
@@ -196,9 +200,9 @@ await posts.getThrowById({
 });
 ```
 
-Requirements: source repo has `model`; `scalarFields` **or** Prisma meta loaded (`loadPrismaMetaFromDmmf(Prisma.dmmf)` on Prisma 5/6, `loadPrismaMetaFromSchema('prisma/schema.prisma')` on Prisma 7); related model repos are registered.
+Requirements: source repo has `model`; Prisma meta loaded; related model repos are registered.
 
-AutoComposer injects the target primary key into nested selects even if omitted. Relation field names resolve from schema / DMMF meta (`schemaPath` defaults to `prisma/schema.prisma`).
+AutoComposer injects the target primary key into nested selects even if omitted. Relation field names resolve from schema / DMMF meta.
 
 ## Row locks
 
@@ -240,8 +244,10 @@ Allowed Prisma usage: `**/repositories/**`, `**/infrastructure/prisma/**`. Rules
 
 ## Observability
 
-- Core: `setTelemetry({ enabled, onEvent })` or Nest `telemetry` / `queryLog.slowThreshold`.
-- Optional: `@prismakit/opentelemetry` → `createPrismaKitTelemetry({ slowThreshold })`.
+- Core: `setTelemetry({ enabled, onEvent, slowThreshold })`
+- Nest: `telemetry: { enabled, slowThreshold, onSlowQuery, onEvent }`
+- Optional: `@prismakit/opentelemetry` → `createPrismaKitTelemetry({ slowThreshold })`
+- Events: `cache.hit` / `cache.miss` / `cache.bypass` / `cache.invalidate` / `cache.error`, `compose.*`, `lock.*`, `stampede.*`, `query.complete` / `query.slow`
 
 ## Clean code
 

package/skills/prismakit/examples.md

@@ -6,7 +6,7 @@ Copy-paste patterns for `@prismakit/core`. Contract: [SKILL.md](SKILL.md).
 
 ```typescript
 // src/modules/users/repositories/user.repository.ts
-import { Prisma } from '@prisma/client';
+import { Prisma } from '@prisma/client'; // or generated client path for Prisma 7
 import { createRepository } from '@prismakit/core';
 
 const DAY = 86_400;
@@ -23,7 +23,6 @@ export const userSelectPresets = {
 
 export const UserRepoClass = createRepository({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
   cache: {
     ttl: DAY,
     nullTtl: 60,
@@ -40,7 +39,7 @@ export type UserRepository = InstanceType<typeof UserRepoClass>;
 
 ```typescript
 // src/infrastructure/prisma/repos.ts
-import { PrismaClient } from '@prisma/client';
+import { PrismaClient } from '@prisma/client'; // or generated client for Prisma 7
 import { RedisCacheAdapter } from '@prismakit/redis';
 import { UserRepoClass } from '../../modules/users/repositories/user.repository';
 
@@ -202,7 +201,6 @@ import { MemoryCacheAdapter } from '@prismakit/memory';
 
 const UserRepo = createRepository({
   model: 'user',
-  scalarFields: { id: 'id', email: 'email', name: 'name' },
   cache: { ttl: 60 },
 });
 

package/skills/prismakit/reference.md

@@ -1,19 +1,19 @@
 # PrismaKit core reference
 
-API surface for `@prismakit/core` 3.x. Read [SKILL.md](SKILL.md) first.
+API surface for `@prismakit/core` **4.0** (pre-stable). Read [SKILL.md](SKILL.md) first.
 
 ## Packages
 
 | Package | Role |
 |---------|------|
 | `@prismakit/core` | `createRepository`, AutoComposer, locks, pagination, `CacheAdapter` |
-| `@prismakit/redis` | `RedisCacheAdapter` |
+| `@prismakit/redis` | `RedisCacheAdapter`, `createRedisJsonReviver` |
 | `@prismakit/memory` | `MemoryCacheAdapter` (tests / local) |
 | `@prismakit/opentelemetry` | Map telemetry → OTel metrics/spans |
 | `@prismakit/cli` | `prismakit generate / validate / skills` |
 | `@prismakit/eslint-plugin` | Repository-only data-access rules |
 
-Node ≥ 20. Line **3.2.x**. Install:
+Node ≥ 20. Install:
 
 ```bash
 pnpm add @prismakit/core
@@ -29,7 +29,7 @@ pnpm add -D @prismakit/eslint-plugin @prismakit/cli
 createRepository(options) → new RepoClass(deps: RepositoryDeps)
 ```
 
-Aliases: `defineRepository`, `createPrismaRepository`.
+Public factory: **`createRepository` only**.
 
 `RepositoryDeps`: `{ prisma, cache?, registry?, autoCompose? }`.
 
@@ -37,14 +37,12 @@ Aliases: `defineRepository`, `createPrismaRepository`.
 
 | Field | Type | Notes |
 |-------|------|-------|
-| `model` | `string` | Client key. Required for cache + compose. |
-| `scalarFields` | `Record<string, string>` | `Prisma.XScalarFieldEnum`; inferred from meta if omitted. |
+| `model` | `string` | Client key. **Required.** |
 | `cache` | `CacheOptions \| true` | `true` → `{ ttl: 86400, sensitiveFields: ['password'] }`. |
-| `lock` | `true \| string \| RepositoryLockConfig` | `true` / client key / Pascal name / `@@map` table. |
-| `schemaPath` | `string` | Lock/schema helpers when global meta is missing. |
-| `primaryKey` | `string \| string[]` | `*ById` + row locks. Default: meta PK or `id`. Composite → Prisma `a_b: { a, b }` where. |
-| `getDelegate` | `(client) => delegate` | Default `(c) => c[model]`. |
-| `toPayload` | `(data) => payload` | Default identity. Prefer typed factories over this. |
+| `lock` | `true \| RepositoryLockConfig` | `true` resolves table/columns from Prisma meta. |
+| `toPayload` | `(data) => payload` | Default identity. |
+
+Scalars, primary key, and relations come from Prisma meta (`loadPrismaMetaFromSchema` / `loadPrismaMetaFromDmmf`).
 
 `RepositoryLockConfig`: `{ tableName: string; columns?: Record<string, string> }`.
 
@@ -58,12 +56,13 @@ All methods accept optional `tx`. Cached repos also accept cache fields (see bel
 |--------|------------|---------|
 | `getById` | `id`, `select?`, `lock?`, `setCache?` | `T \| null` |
 | `getThrowById` | same | `T` (throws if missing) |
-| `getFirst` | `where?`, `select?`, `lock?`, `setCache?`, `cacheTags?` | `T \| null` |
+| `getFirst` | `where?`, `select?`, `lock?`, `setCache?`, `cacheTags?`, `orderBy?` | `T \| null` |
+| `getThrowFirst` | same as `getFirst` | `T` (throws if missing) |
 | `getMany` | `where?`, `select?`, `orderBy?`, `take?`, `skip?`, `lock?`, `setCache?`, `cacheTags?` | `T[]` |
 | `getManyPaginate` | `where?`, `select?`, `orderBy?`, `page?`, `pageSize?`, `setCache?`, `cacheTags?` | `PaginatedResult<T>` |
 | `getManyCursor` | `where?`, `select?`, `orderBy?`, `cursor?`, `take?`, `skip?`, `setCache?`, `cacheTags?` | `CursorPage<T>`; with `cursor`, default `skip: 1` |
-| `count` | `where?`, `select?`, `setCache?`, `cacheTags?` | `{ count: number }` |
-| `exists` | `where?`, `setCache?`, `cacheTags?` | `{ exists: boolean }` |
+| `count` | `where?`, `setCache?`, `cacheTags?` | `number` |
+| `exists` | `where?`, `setCache?`, `cacheTags?` | `boolean` |
 | `aggregate` | Prisma aggregate args + `setCache?`, `cacheTags?` | delegate result |
 | `groupBy` | Prisma groupBy args + `setCache?`, `cacheTags?` | delegate result |
 
@@ -86,6 +85,13 @@ All methods accept optional `tx`. Cached repos also accept cache fields (see bel
 | `upsert` | `where`, `create`, `update`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
 | `deleteById` | `id`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
 | `deleteMany` | `where`, `invalidate?`, `tags?` | `all` | `{ count }` |
+| `update` | `where`, `data`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
+| `delete` | `where`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
+| `createManyAndReturn` | `data[]`, `select?`, `skipDuplicates?`, `invalidate?`, `tags?` | `queries` | `T[]` |
+| `updateManyAndReturn` | `where`, `data`, `select?`, `invalidate?`, `tags?` | `all` | `T[]` |
+| `upsertMany` | `data[]`, `skipDuplicates?`, `invalidate?`, `tags?` | `all` | `{ count }` |
+| `queryRaw` | `sql`, `...params` | — | raw result |
+| `executeRaw` | `sql`, `...params` | — | `number` (affected rows) |
 
 Mutation `tags`: `string[] | null | undefined | ((result) => string[] | null | undefined)`.
 
@@ -112,10 +118,10 @@ await repo.invalidateCache({ id?: string; tags?: string[] });
 | `ttl` | `86400` | Entity TTL (seconds). |
 | `nullTtl` | — | Negative cache for null results. |
 | `sensitiveFields` | `['password']` | Selects containing these never cache. |
-| `methods` | — | Per-method `{ enabled?, ttl? }` for `getById`, `getThrowById`, `getFirst`, `getMany`, `getManyPaginate`. |
+| `methods` | — | Per-method `{ enabled?, ttl? }`. |
 | `defaultSetCache` | `false` | Reads cache unless caller passes `setCache: false`. |
 | `stampede` | see below | Per-repo stampede overrides. |
-| `compression` | — | Hint for adapters (`'none' \| 'zstd' \| 'lz4'`). Redis adapter uses `'none' \| 'gzip'`. |
+| `strictInvalidation` | `false` | When true, invalidation failures rethrow. |
 
 ### `InvalidateMode`
 
@@ -125,11 +131,6 @@ await repo.invalidateCache({ id?: string; tags?: string[] });
 | `entity` | Entity keys only |
 | `queries` | Query index only |
 | `none` | Skip — **required inside transactions** |
-| `stale` | Core treats like entity+queries (adapter may layer SWR) |
-
-### Allowlist
-
-`setRegisteredCacheModels(['user', 'product'])`. Empty/unset = fail-open. When set, a repo with `cache` whose `model` is missing throws at init.
 
 ### Key schema
 
@@ -142,7 +143,7 @@ await repo.invalidateCache({ id?: string; tags?: string[] });
 {prefix}:v2:repo:{model}:t:{tag}:__idx
 ```
 
-Redis payloads use tagged JSON for `Date`, `BigInt`, `Bytes`, and `Decimal` (`__date`, `__bigint`, …). Bump to v2 keys causes a one-time miss after upgrade.
+Redis payloads use tagged JSON for `Date`, `BigInt`, `Bytes`, and `Decimal`. Custom revive: `createRedisJsonReviver` from `@prismakit/redis`.
 
 ### Debug
 
@@ -162,8 +163,6 @@ Hits/misses/bypasses via `cacheDebugStorage` from `@prismakit/core`.
 | `backoff` | `'exponential'` (`'fixed'` also valid) |
 | `totalTimeoutMs` | `3000` |
 
-In-process `singleflight` is also used. If Redis is down, fail open.
-
 ### Adapters
 
 **Redis** (`@prismakit/redis`):
@@ -185,11 +184,11 @@ new RedisCacheAdapter({
 new MemoryCacheAdapter({ prefix: 'test', maxSize: 1000, defaultTtl: 300 });
 ```
 
-Custom: implement `CacheAdapter` (`get`/`set`/`del`/`setNx`/`setWithIndex`/`invalidateByIndex`/`saddAndExpire`/`smembers`/`isReady`/`getPrefix` + `safe*` wrappers). `get`/`safeGet` **must** return a fresh copy (structuredClone / JSON). Prefer fail-open `safe*` semantics.
+Custom: implement `CacheAdapter`. Prefer fail-open `safe*` semantics.
 
 ## Auto-compose
 
-`splitSelect` keeps scalars (+ FK fields from DMMF) for the Prisma query. Relation keys load via the target repository. Target PK is always injected into the nested select.
+`splitSelect` keeps scalars (+ FK fields from meta) for the Prisma query. Relation keys load via the target repository. Target PK is always injected into the nested select.
 
 Load meta once at bootstrap:
 
@@ -200,8 +199,6 @@ loadPrismaMetaFromDmmf(Prisma.dmmf);                 // Prisma 5/6
 loadPrismaMetaFromSchema('prisma/schema.prisma');    // Prisma 7 (no Prisma.dmmf)
 ```
 
-Without meta, AutoComposer cannot resolve renamed relations; pass `schemaPath` or `dmmf`. Relation field → registry key is source-scoped (`Category.products` vs `Tag.products` can target different models).
-
 Validate: `npx prismakit validate --auto-register` or `assertSelectComposeValid`.
 
 ### `ComposeOptions` (global via `setComposeOptions`)
@@ -211,7 +208,6 @@ Validate: `npx prismakit validate --auto-register` or `assertSelectComposeValid`
 | `maxDepth` | `10` | Max relation nesting. |
 | `parallel` | `true` | Same-level relations via `Promise.all`. |
 | `setCache` | `true` | Nested fetches pass `setCache: true` unless parent has `tx` / `setCache: false`. |
-| `tx` | — | Per-call only; forwarded to nested `getMany`. |
 
 Related repos must be registered on `RepositoryRegistry`.
 
@@ -227,7 +223,7 @@ Related repos must be registered on `RepositoryRegistry`.
 | `nowait` | Fail immediately if locked. |
 | `skipLocked` | Skip locked rows. **Cannot** combine with `nowait`. |
 
-`lock: true` / `'wallet'` / `'Wallet'` / `'wallets'` resolve via Prisma meta when available, else `buildLockConfigFromSchema`.
+`lock: true` resolves via Prisma meta. Explicit: `{ tableName, columns? }`.
 
 ## Telemetry
 
@@ -237,12 +233,13 @@ import { setTelemetry } from '@prismakit/core';
 setTelemetry({
   enabled: true,
   onEvent: (event) => { /* metrics */ },
+  slowThreshold: 500, // emits query.slow for queries ≥ this ms
 });
 ```
 
 | Type | When |
 |------|------|
-| `cache.hit` / `cache.miss` / `cache.bypass` / `cache.invalidate` | Cache-aside path |
+| `cache.hit` / `cache.miss` / `cache.bypass` / `cache.invalidate` / `cache.error` | Cache-aside path |
 | `compose.start` / `compose.complete` | Auto-compose (`queryCount`, `durationMs`) |
 | `lock.acquired` / `lock.waited` / `lock.timeout` | Row locks |
 | `stampede.locked` / `stampede.waited` / `stampede.fallthrough` | Stampede protection |
@@ -256,10 +253,6 @@ npx prismakit validate [--schema <path>] [--auto-register] [--no-assert]
 npx prismakit help
 ```
 
-Default generate output: `src/modules/<kebab>/repositories/<kebab>.repository.ts`.
-
-`--full` emits Nest module + controller + service + select/where types. Register `*Module` in `app.module.ts` afterwards.
-
 ## ESLint
 
 ```js
@@ -267,8 +260,6 @@ import prismakit from '@prismakit/eslint-plugin';
 export default [prismakit.configs.recommended];
 ```
 
-`recommended` turns all rules on at **error**.
-
 | Rule | Forbids |
 |------|---------|
 | `prismakit/no-prisma-service-outside-repos` | Inject/reference `PrismaService` / `PrismaClient` outside allowlist |
@@ -276,23 +267,15 @@ export default [prismakit.configs.recommended];
 | `prismakit/require-transaction-service` | `.$transaction` in feature code |
 | `prismakit/require-cached-repo-provider` | Cached repo class missing from Nest `providers` |
 
-Allowed path patterns (forward slashes):
-
-- `**/repositories/**`
-- `**/infrastructure/prisma/**`
-- `**/node_modules/**`
-- `packages/(core|nestjs|redis)/**` (PrismaKit monorepo)
-
-Mirror this layout rather than weakening the plugin.
+Allowed path patterns: `**/repositories/**`, `**/infrastructure/prisma/**`.
 
 ## Bootstrap (plain Node)
 
 ```typescript
-import { Prisma, PrismaClient } from '@prisma/client';
+import { PrismaClient } from '@prisma/client';
 import {
   createRepository,
   loadPrismaMetaFromSchema,
-  setRegisteredCacheModels,
   setComposeOptions,
   setTelemetry,
   RepositoryRegistry,
@@ -302,7 +285,6 @@ import { RedisCacheAdapter } from '@prismakit/redis';
 
 const prisma = new PrismaClient();
 loadPrismaMetaFromSchema('prisma/schema.prisma');
-setRegisteredCacheModels(['user', 'post']);
 setComposeOptions({ maxDepth: 6, parallel: true, setCache: true });
 setTelemetry({ enabled: true, onEvent: (e) => console.debug('[pk]', e.type) });
 
@@ -312,7 +294,6 @@ const autoCompose = new AutoComposer(registry);
 
 const UserRepo = createRepository({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
   cache: { ttl: 86_400 },
 });
 const users = new UserRepo({ prisma, cache, registry, autoCompose });

package/skills/prismakit/review-checklist.md

@@ -26,8 +26,7 @@ Task Progress:
 - [ ] New model access goes through `createRepository` (core) or the app's Nest `defineRepo` binder — not a one-off Prisma call
 - [ ] File lives under `**/repositories/**` as `*.repository.ts`
 - [ ] `model` is the Prisma client key (`'user'`, not `'User'`)
-- [ ] `scalarFields` is set **or** Prisma meta is loaded at bootstrap (`dmmf` / `schemaPath`)
-- [ ] `cacheModels` is omitted unless the app wants an extra allowlist
+- [ ] Prisma meta is loaded at bootstrap (`dmmf` / `schemaPath` / `loadPrismaMetaFrom*`)
 
 ## Selects
 
@@ -54,7 +53,7 @@ Task Progress:
 
 ## Locks
 
-- [ ] Repo declares `lock` (`true`, client key, table name, or config) before any call passes `lock`
+- [ ] Repo declares `lock` (`true` or `{ tableName, columns }`) before any call passes `lock`
 - [ ] Every `lock: { mode }` call also passes `tx`
 - [ ] `skipLocked` is not combined with `nowait`
 - [ ] Locked transactions stay short

package/skills/prismakit-nestjs/SKILL.md

@@ -2,15 +2,17 @@
 name: prismakit-nestjs
 description: >-
   PrismaKit NestJS adapter: PrismaKitModule.forRoot/forRootAsync wiring, injectable repositories via
-  createDefineRepo/defineInjectableRepository, TransactionService.execTx with afterCommit invalidation,
-  and PRISMAKIT_* DI tokens. Use when working with @prismakit/nestjs, Nest feature modules that need
-  Prisma data access, or Nest transactions and cache invalidation.
+  createDefineRepo (default) / createInjectableRepository (escape hatch), TransactionService.execTx
+  with afterCommit invalidation, and PRISMAKIT_* DI tokens. Use when working with @prismakit/nestjs,
+  Nest feature modules that need Prisma data access, or Nest transactions and cache invalidation.
 ---
 
 # PrismaKit NestJS
 
 Adapter for NestJS. The data-access contract (layering, cache, compose, locks, ESLint) lives in skill `prismakit` — follow it. This skill covers module wiring, injectable repos, and `TransactionService`.
 
+**Line:** 4.0 (pre-stable). Default factory: **`createDefineRepo` / app `defineAppRepo`**.
+
 ## Bootstrap
 
 ```bash
@@ -23,7 +25,6 @@ pnpm add -D @prismakit/eslint-plugin @prismakit/cli
 import { Module } from '@nestjs/common';
 import { PrismaKitModule } from '@prismakit/nestjs';
 import { RedisCacheAdapter } from '@prismakit/redis';
-import { Prisma } from '@prisma/client';
 
 @Module({
   imports: [
@@ -33,6 +34,11 @@ import { Prisma } from '@prisma/client';
       schemaPath: 'prisma/schema.prisma', // default; Prisma 5/6: dmmf: Prisma.dmmf
       validateCompose: true,
       compose: { maxDepth: 6, parallel: true, setCache: true },
+      telemetry: {
+        enabled: true,
+        slowThreshold: 500,
+        onEvent: (e) => console.debug(e.type),
+      },
     }),
   ],
 })
@@ -41,7 +47,7 @@ export class AppModule {}
 
 `forRootAsync` when cache/URL come from `ConfigService` — see [examples.md](examples.md).
 
-`schemaPath` defaults to `prisma/schema.prisma`. Always load Prisma meta (`dmmf` or `schemaPath`) so auto-compose and `lock: true` resolve FKs/`@@map` from the schema — no relation-alias map.
+`schemaPath` defaults to `prisma/schema.prisma`. Always load Prisma meta (`dmmf` or `schemaPath`) so auto-compose and `lock: true` resolve FKs/`@@map` from the schema.
 
 ## Factory (one default)
 
@@ -96,14 +102,13 @@ export class AuditLogRepository extends defineAppRepo({
 }) {}
 ```
 
-`scalarFields` is **optional** when `schemaPath` or DMMF meta is loaded (default since 3.1). Omit it in new repos.
+Per-repo options: `model` (required), `cache?`, `lock?: true | RepositoryLockConfig`, `toPayload?`.
 
-Escape hatches (do not use as the app default):
+Escape hatch (do not use as the app default):
 
-- `defineInjectableRepository` from `@prismakit/nestjs` (package alias `defineRepository`) — phantoms + payload HKT when TypeMap is unavailable.
-- `createInjectableRepository` without a types bag — thin, results are `unknown`. Alias: `createPrismaRepository`.
+- `createInjectableRepository` — thin Nest wrapper when TypeMap binding is unavailable (results are thinly typed).
 
-Do not import `defineRepo` from `@prismakit/nestjs` in apps that already bind `createDefineRepo` as `defineAppRepo`.
+Removed in 4.0: `defineInjectableRepository`, `defineRepo`, `defineRepository`, `createPrismaRepository`, Nest `cacheModels`, Nest `queryLog`.
 
 ## Register and inject
 
@@ -201,7 +206,7 @@ await this.tx.execTx(
 
 When the repo options include `cache`, TypeScript exposes `setCache`, `cacheTags`, mutation `invalidate`/`tags`, and `invalidateCache`. Without `cache`, those fields are omitted — do not pass them.
 
-Repository `cache` is the source of truth. Omit `cacheModels` (fail-open). Pass an allowlist only if you want a second check.
+Repository `cache` is the source of truth.
 
 `cache.defaultSetCache: true` makes user-facing reads cache by default; still pass `setCache: false` on auth/uniqueness.
 
@@ -220,12 +225,10 @@ Repository `cache` is the source of truth. Omit `cacheModels` (fail-open). Pass
 
 | Option | Use |
 |--------|-----|
-| `cacheModels` | Optional extra allowlist (omit — repo `cache` is enough) |
 | `validateCompose: true` | Assert compose-safe selects on boot |
 | `strictCachedRepos` | Fail boot if a `cache` repo class is not in Nest `providers` (default `true`) |
 | `compose` | `{ maxDepth, parallel, setCache }` |
-| `telemetry` | `{ enabled: true, onEvent }` or `createPrismaKitTelemetry()` from `@prismakit/opentelemetry` |
-| `queryLog` | `{ slowThreshold, onSlowQuery }` — enables telemetry / `query.slow` |
+| `telemetry` | `{ enabled, slowThreshold, onSlowQuery, onEvent }` or `createPrismaKitTelemetry()` |
 | `autoRegisterModels` | `true` or `string[]` — stub repos for compose-only models |
 
 ## Scaffolding
@@ -244,7 +247,7 @@ Reference app: [starter-prismakit-nestjs](https://github.com/fikiap23/starter-pr
 
 ## Clean code (Nest)
 
-- One `defineRepo` binder under `src/infrastructure/prisma/`. Do not call `createDefineRepo` per feature.
+- One `defineAppRepo` binder under `src/infrastructure/prisma/`. Do not call `createDefineRepo` per feature.
 - Feature modules own their repository providers; do not make every repo global.
 - Controllers stay HTTP-only: map DTO → service method. No repository calls in controllers.
 - Select presets live next to the repository (`minimal` / `general` / `withPassword`).

package/skills/prismakit-nestjs/examples.md

@@ -2,7 +2,7 @@
 
 Production-shaped snippets. Contract: skill `prismakit` + [SKILL.md](SKILL.md).
 
-## 1. App module (Redis, allowlist, slow-query log)
+## 1. App module (Redis, telemetry)
 
 ```typescript
 // src/app.module.ts
@@ -31,7 +31,8 @@ import { UserModule } from './modules/users/user.module';
         validateCompose: true,
         compose: { maxDepth: 6, parallel: true, setCache: true },
         autoRegisterModels: true,
-        queryLog: {
+        telemetry: {
+          enabled: true,
           slowThreshold: 500,
           onSlowQuery: (e) => {
             console.warn(`Slow ${e.model}.${e.method}: ${e.durationMs}ms`);
@@ -47,24 +48,30 @@ export class AppModule {}
 
 Prisma 5/6: pass `dmmf: Prisma.dmmf` instead of (or in addition to skipping) `schemaPath`. Prisma 7: `schemaPath` only.
 
-## 2. TypeMap binder
+## 2. TypeMap binder with app-wide cache defaults
 
 ```typescript
-// src/infrastructure/prisma/define-repo.ts
+// src/infrastructure/prisma/define-app-repo.ts
 import { createDefineRepo } from '@prismakit/nestjs';
-import type { Prisma } from '@prisma/client';
+import type { Prisma } from 'src/infrastructure/prisma/prisma-client';
 
-export const defineRepo = createDefineRepo<Prisma.TypeMap>();
+const DAY = 86_400;
+
+export const defineAppRepo = createDefineRepo<Prisma.TypeMap>({
+  cache: {
+    ttl: DAY,
+    nullTtl: 60,
+    defaultSetCache: true,
+  },
+});
 ```
 
 ## 3. Feature repository + select presets
 
 ```typescript
 // src/modules/users/repositories/user.repository.ts
-import { Prisma } from '@prisma/client';
-import { defineRepo } from '../../../infrastructure/prisma/define-repo';
-
-const DAY = 86_400;
+import { Prisma } from 'src/infrastructure/prisma/prisma-client';
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
 
 export const userSelectPresets = {
   minimal: { id: true } satisfies Prisma.UserSelect,
@@ -80,18 +87,24 @@ export const userSelectPresets = {
   } satisfies Prisma.UserSelect,
 };
 
-export const UserRepository = defineRepo({
+export class UserRepository extends defineAppRepo({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
   cache: {
-    ttl: DAY,
-    nullTtl: 60,
+    defaultSetCache: false,       // auth lookups pass setCache explicitly
     sensitiveFields: ['password'],
     methods: { getFirst: { enabled: false } },
   },
-  lock: true,
-});
-export interface UserRepository extends InstanceType<typeof UserRepository> {}
+}) {}
+```
+
+```typescript
+// Simple cached repo — inherits app-wide defaults
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
+
+export class CategoryRepository extends defineAppRepo({
+  model: 'category',
+  cache: true,
+}) {}
 ```
 
 ## 4. Feature module + thin controller + service