@prismakit/cli 3.2.2 → 4.0.1

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` + Prisma meta loaded (or `scalarFields` when meta unavailable) |
+| 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` is an alias of `createRepository` in core. Note: `createPrismaRepository` is also an alias in core, but in `@prismakit/nestjs` it aliases `createInjectableRepository` instead — avoid using it to prevent confusion.
+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/**`.
 
@@ -167,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.
 
@@ -200,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
 
@@ -244,9 +244,10 @@ Allowed Prisma usage: `**/repositories/**`, `**/infrastructure/prisma/**`. Rules
 
 ## Observability
 
-- Core: `setTelemetry({ enabled, onEvent, slowThreshold })` or Nest `telemetry` / `queryLog.slowThreshold`.
-- Optional: `@prismakit/opentelemetry` → `createPrismaKitTelemetry({ slowThreshold })`.
-- Events: `cache.hit` / `cache.miss` / `cache.bypass` / `cache.invalidate` / `cache.error`, `compose.*`, `lock.*`, `stampede.*`, `query.complete` / `query.slow`.
+- 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

@@ -23,7 +23,6 @@ export const userSelectPresets = {
 
 export const UserRepoClass = createRepository({
   model: 'user',
-  // scalarFields: optional when schemaPath/DMMF meta is loaded (default since 3.1)
   cache: {
     ttl: DAY,
     nullTtl: 60,
@@ -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)
 ```
 
-Alias: `defineRepository`. (`createPrismaRepository` is also an alias in core but maps to `createInjectableRepository` in `@prismakit/nestjs` — avoid it to prevent confusion.)
+Public factory: **`createRepository` only**.
 
 `RepositoryDeps`: `{ prisma, cache?, registry?, autoCompose? }`.
 
@@ -37,14 +37,12 @@ Alias: `defineRepository`. (`createPrismaRepository` is also an alias in core bu
 
 | 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> }`.
 
@@ -120,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`, `getThrowFirst`, `getMany`, `getManyPaginate`, `getManyCursor`, `count`, `exists`, `aggregate`, `groupBy`. |
+| `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`
 
@@ -133,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
 
@@ -150,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`. Pass `decimalFactory: (s) => new Prisma.Decimal(s)` on `RedisCacheAdapter` (and/or Nest `PrismaKitModule.forRoot`) so compose clone and cache hits return native Prisma scalars — `JSON.stringify` otherwise turns `Date`/`Decimal` into strings via `toJSON`.
 
 ### Debug
 
@@ -170,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`):
@@ -184,6 +175,7 @@ new RedisCacheAdapter({
   prefix: 'myapp',            // default 'prismakit'
   compression: 'gzip',        // 'none' | 'gzip'
   compressionThresholdBytes: 1024,
+  decimalFactory: (s) => new Prisma.Decimal(s),
 });
 ```
 
@@ -193,11 +185,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:
 
@@ -208,8 +200,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`)
@@ -219,7 +209,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`.
 
@@ -235,7 +224,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
 
@@ -265,10 +254,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
@@ -276,8 +261,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 |
@@ -285,23 +268,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,
@@ -311,7 +286,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) });
 

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
@@ -28,10 +30,18 @@ import { RedisCacheAdapter } from '@prismakit/redis';
   imports: [
     PrismaKitModule.forRoot({
       prisma: prismaClient,
-      cache: new RedisCacheAdapter({ prefix: 'myapp' }),
+      cache: new RedisCacheAdapter({
+        prefix: 'myapp',
+        decimalFactory: (s) => new Prisma.Decimal(s),
+      }),
       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),
+      },
     }),
   ],
 })
@@ -40,7 +50,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)
 
@@ -95,14 +105,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
 
@@ -200,7 +209,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.
 
@@ -219,12 +228,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

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`);

package/skills/prismakit-nestjs/reference.md

@@ -1,6 +1,6 @@
 # PrismaKit NestJS reference
 
-API surface for `@prismakit/nestjs` 3.x. Repository methods, cache, compose, and locks are documented in skill `prismakit` (`reference.md` in that skill). This file covers the Nest adapter only.
+API surface for `@prismakit/nestjs` **4.0** (pre-stable). Repository methods, cache, compose, and locks are documented in skill `prismakit` (`reference.md` in that skill). This file covers the Nest adapter only.
 
 ## `PrismaKitModuleOptions`
 
@@ -13,13 +13,11 @@ API surface for `@prismakit/nestjs` 3.x. Repository methods, cache, compose, and
 | `validateCompose` | no | When `true`, `assertSelectComposeValid` on module init. |
 | `strictCachedRepos` | no | Fail boot when a cached repo is missing from `providers`, or listed in two modules. Default `true`. |
 | `modulesRoot` | no | Directory scanned by `strictCachedRepos`. Default `src/modules`. |
-| `cacheModels` | no | Optional extra allowlist. Omit — repo `cache` is the source of truth. |
-| `compose` | no | `ComposeOptions`: `maxDepth` (default 10), `parallel` (default true), `setCache` (default true). `tx` is per-call only. |
-| `telemetry` | no | `{ enabled?: boolean; onEvent?: (event) => void }`. |
-| `queryLog` | no | `{ slowThreshold?: number; onSlowQuery?: (e) => void }`. Default threshold 500ms. Setting this enables telemetry. |
+| `compose` | no | `ComposeOptions`: `maxDepth` (default 10), `parallel` (default true), `setCache` (default true). |
+| `telemetry` | no | `{ enabled?, slowThreshold?, onSlowQuery?, onEvent? }`. |
 | `autoRegisterModels` | no | `true` = stub repos for all schema/DMMF models; `string[]` = those client keys only. |
 
-`queryLog.onSlowQuery` receives `{ model?, method?, durationMs, thresholdMs }` for `query.complete` events at/above the threshold.
+`onSlowQuery` receives `{ model?, method?, durationMs, thresholdMs }` for slow queries. Setting `slowThreshold` / `onSlowQuery` enables telemetry unless `enabled: false`.
 
 ## Async config
 
@@ -42,6 +40,10 @@ PrismaKitModule.forRootAsync({
       prefix: config.get('CACHE_PREFIX') ?? 'myapp',
     }),
     schemaPath: 'prisma/schema.prisma',
+    telemetry: {
+      enabled: true,
+      slowThreshold: 500,
+    },
   }),
 });
 ```
@@ -68,67 +70,25 @@ execTx<T, TClient = unknown>(
 
 `TransactionOptions`: `{ maxWait?: number; timeout?: number; isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable' | string }`.
 
-Type the client when useful:
-
-```typescript
-await this.tx.execTx<User, Prisma.TransactionClient>(async (tx) => { /* ... */ });
-```
-
 `afterCommit` runs only after `prisma.$transaction` resolves successfully.
 
 ## Repository factories
 
 | Factory | When |
 |---------|------|
-| `createDefineRepo<Prisma.TypeMap>()` then local `defineRepo({ model, ... })` | **Default** for apps. Zero phantoms; `model` + `scalarFields` + `cache` / `lock`. |
-| `defineInjectableRepository({ model, select, create, update, where, orderBy, payload, ... })` | TypeMap unavailable. Package aliases: `defineRepository`. |
-| `createInjectableRepository({ model, ... })` | Thin / untyped. Results `unknown` unless `toPayload` is supplied. Alias: `createPrismaRepository`. |
+| `createDefineRepo<Prisma.TypeMap>()` then app `defineAppRepo({ model, ... })` | **Default** for apps. Zero phantoms; `model` + `cache` / `lock` / `toPayload`. |
+| `createInjectableRepository({ model, ... })` | Low-level escape hatch. Results thinly typed unless `toPayload` is supplied. |
 
-`createDefineRepo` accepts app-wide defaults (`cache`, `schemaPath`) and per-repo options: `model`, `scalarFields?` (optional since 3.1), `primaryKey?`, `cache?` (`true` inherits app defaults), `lock?`, `schemaPath?`.
+`createDefineRepo` accepts app-wide defaults (`cache`) and per-repo options: `model`, `cache?` (`true` inherits app defaults), `lock?`, `toPayload?`.
 
 When `cache` is set, the returned API includes `setCache` / `cacheTags` / `invalidate` / `tags` / `invalidateCache`. Otherwise those fields are omitted from the type (`HasCacheFromOptions`).
 
-`createDefineRepo` / `RepositoryApiFromTypeMap` includes the full runtime surface: `create`, `createMany`, `createManyAndReturn`, `update`, `updateById`, `updateMany`, `updateManyAndReturn`, `upsert`, `upsertMany`, `delete`, `deleteById`, `deleteMany`, `getThrowFirst`, `count`, `exists`, `aggregate`, `groupBy`, `getManyCursor`, `queryRaw`, `executeRaw`, `lock` + `orderBy` on `getFirst`, `lock` on `getMany`, and composite-PK `id` on `*ById`. `primaryKey` is optional — composite `@@id` is read from schema meta.
-
-Export the instance type with interface merging so `cache` on options gates `setCache` (a same-name `type` alias collapses to `any`):
+Export the instance type with interface merging so `cache` on options gates `setCache`:
 
 ```typescript
 export interface UserRepository extends InstanceType<typeof UserRepository> {}
 ```
 
-## `defineInjectableRepository` shape (escape hatch)
-
-```typescript
-import { Prisma } from '@prisma/client';
-import { defineInjectableRepository } from '@prismakit/nestjs';
-
-type Of<S> = S extends Prisma.UserSelect
-  ? Prisma.UserGetPayload<{ select: S }>
-  : never;
-
-export const UserRepository = defineInjectableRepository({
-  model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum, // required for this escape hatch (meta not typed)
-  select: null! as Prisma.UserSelect,
-  create: null! as Prisma.UserCreateInput,
-  update: null! as Prisma.UserUpdateInput,
-  where: null! as Prisma.UserWhereInput,
-  orderBy: null! as Prisma.UserOrderByWithRelationInput,
-  payload: class {
-    declare readonly _select: unknown;
-    declare type: () => Of<this['_select']>;
-  },
-  cache: { ttl: 86_400, sensitiveFields: ['password'] },
-  lock: true,
-});
-```
-
-## Re-exports from core
-
-`@prismakit/nestjs` re-exports: `AutoComposer`, `RepositoryRegistry`, `CacheAdapter`, repository option/instance types, `RepoPayloadHKT`, `ComposeOptions`, `TelemetryOptions`, `TelemetryEvent`, `loadPrismaMetaFromDmmf`, `loadPrismaMetaFromSchema`, `setComposeOptions`, `setTelemetry`.
-
-Prefer importing Nest-only APIs from `@prismakit/nestjs` and core-only helpers from `@prismakit/core`.
-
 ## Layout
 
 ```

package/skills/prismakit-nestjs/review-checklist.md

@@ -22,7 +22,6 @@ Task Progress:
 - [ ] `prisma` is the shared client instance
 - [ ] Prisma meta is loaded: `dmmf: Prisma.dmmf` (Prisma 5/6) or `schemaPath: 'prisma/schema.prisma'` (Prisma 7)
 - [ ] Production cache uses `RedisCacheAdapter` with a stable `prefix`
-- [ ] `cacheModels` is omitted (repo `cache` is source of truth), or lists every cached model if an allowlist is used
 - [ ] `validateCompose: true` is on for apps that nest relations in `select`
 - [ ] Cached repo classes are in feature `providers` (`strictCachedRepos` fails boot otherwise)
 
@@ -32,7 +31,7 @@ Task Progress:
 - [ ] Feature repos call that binder — not `createInjectableRepository` unless types are intentionally thin
 - [ ] `export interface XRepository extends InstanceType<typeof XRepository> {}` (infers cache from options; do not use a same-name `type` alias)
 - [ ] Repo class is in `providers` and `exports` of the feature module
-- [ ] `lock: true` (or table/client key) is set when any call uses `lock`
+- [ ] `lock: true` (or `{ tableName, columns }`) is set when any call uses `lock`
 
 ## DI
 

package/src/__tests__/naming.spec.ts

@@ -20,10 +20,13 @@ describe('cli generate templates', () => {
     expect(files).toHaveLength(1);
     expect(files[0].relativePath).toContain('repositories/product.repository.ts');
     expect(files[0].content).toContain("model: 'product'");
-    expect(files[0].content).toContain('cache: {');
+    expect(files[0].content).toContain('cache: true');
     expect(files[0].content).not.toContain('getDelegate');
     expect(files[0].content).not.toContain('scalarFields');
-    expect(files[0].content).toContain("from '@prismakit/nestjs'");
+    expect(files[0].content).toContain('defineAppRepo');
+    expect(files[0].content).toContain(
+      "from 'src/infrastructure/prisma/define-app-repo'",
+    );
   });
 
   it('emits full Nest module when full: true', () => {

package/src/commands/skills.ts

@@ -44,7 +44,6 @@ export function findSkillsRoot(startDir: string): string | undefined {
     for (const candidate of [
       path.join(dir, 'skills'),
       dir,
-      path.join(dir, 'templates', 'cursor-skills'),
     ]) {
       if (isSkillsRoot(candidate)) return candidate;
     }

package/src/templates.ts

@@ -40,19 +40,16 @@ function renderRepository(
   prismaImport: string,
   base: string,
 ): GeneratedFile {
-  const cacheBlock = cacheEnabled
-    ? `  cache: {
-    ttl: 86400,
-    sensitiveFields: ['password'],
-    defaultSetCache: true,
-  },
-`
-    : '';
+  const cacheBlock = cacheEnabled ? `  cache: true,\n` : '';
 
   const content = apply(
-    `import { createInjectableRepository } from '@prismakit/nestjs';
+    `import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
 
-export class {{pascal}}Repository extends createInjectableRepository({
+/**
+ * Bind once in infrastructure:
+ * export const defineAppRepo = createDefineRepo<Prisma.TypeMap>({ cache: { ... } });
+ */
+export class {{pascal}}Repository extends defineAppRepo({
   model: '{{repoModel}}',
 {{cacheBlock}}}) {}
 `,