@edium/halifax 2.2.2 → 2.3.0

package/CHANGELOG.md

@@ -3,12 +3,172 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0]
+
+### Security
+
+- **`PrismaAdapter.upsertOne` cross-tenant write vulnerability eliminated** — the previous scoped
+  upsert path performed `findFirst({ where: { id } })` without a tenant filter, then called
+  `delegate.upsert({ where: { id } })` also without a tenant filter. The application-level
+  ownership check between the two statements created a TOCTOU window: if another tenant's record
+  appeared at that ID between the check and the upsert, Prisma's `upsert` would fire its `update`
+  branch and write into that other tenant's row. The scoped path no longer uses `delegate.upsert`.
+  It now uses a scoped `findFirst(scopedWhere)` to detect existence, `updateMany(scopedWhere)` for
+  the update branch (atomic, same fix applied to `updateOne`), and `create(stampTenant)` for the
+  create branch. The `delegate.upsert` call is retained only for the unscoped path.
+
+- **`PrismaAdapter.updateOne` and `deleteOne` unsafe fallbacks removed** — when `updateMany`
+  (for `updateOne`) or `deleteMany` (for `deleteOne`) were unavailable on the delegate, the code
+  fell back to a two-step scoped-check + unscoped-write sequence. Both halves now throw
+  `ServerError` immediately rather than proceeding with an unsafe path. Standard Prisma delegates
+  always expose both methods, so this only affects non-standard or mock delegates.
+
+- **`requiredPermissions` now uses OR semantics consistently** — all three auth strategies
+  (`JwtClaimsAuthStrategy`, `PassportJwtStrategy`, `PassportSessionStrategy`) previously used
+  `.every()` (ALL permissions required), while the fallback path in `handlerUtils.ts` correctly
+  used `.some()` (ANY single permission grants access). The strategies were wrong. All four paths
+  now delegate to a shared `checkRequiredPermissions()` utility that applies `.some()` semantics:
+  a caller who holds *any one* of the listed permissions is authorized. This matches the documented
+  behavior of `readRoles`/`writeRoles` at the field level and is a consistent read of "required
+  permissions" as an OR list. **If you relied on the undocumented ALL-must-match behavior,
+  tighten your permission model accordingly.**
+
+- **TOCTOU race in `PrismaAdapter.updateOne` under tenant scope eliminated** — the previous
+  scoped-update path did a `findFirst` ownership check and then a separate `update` call. Between
+  the two statements, a concurrent request could transfer the record to a different tenant,
+  allowing the update to land on a record the caller no longer owns. The fix uses
+  `updateMany({ where: scopedWhere })` as the primary path when the Prisma delegate supports it —
+  the tenant field is enforced atomically in a single SQL statement. A safe `findFirst`-then-update
+  fallback remains only for delegates that lack `updateMany`.
+
+### Performance
+
+- **O(n²) → O(n) field validation** — `validateSelectableFields` and `validateSortableFields`
+  previously called `.find()` inside a `.filter()`, giving O(n²) complexity per request. Both now
+  pre-build a `Map` from field names to definitions and do O(1) lookups in the filter pass.
+
+- **`makeReadableFieldFilter` factory for bulk-response field stripping** — `filterReadableFields`
+  previously rebuilt the `fieldMap` `Map` and `userRoles` `Set` for every record in a batch. A
+  new exported factory `makeReadableFieldFilter(resource, auth)` builds both structures once and
+  returns a reusable `(record) => record` function. The `readMany`, `query`, and `updateMany`
+  handlers now call the factory once before `.map()` and pass the compiled function directly,
+  eliminating O(n) redundant Map constructions for responses with up to 5000 records.
+
+- **`parseGetOneOptions` for lean GET /:id parsing** — `readOne` previously called
+  `parseListOptions`, which parses and validates `?fields=`, `?include=`, `?limit=`, `?offset=`,
+  `?order=`, and all filter fields — all of which are irrelevant to a single-record GET. A new
+  exported `parseGetOneOptions(query, resource)` in `queryString.ts` only parses and validates
+  `?fields=` and `?include=`, removing the wasted work and the silent discard of inapplicable
+  parameters on that route.
+
+### Fixed
+
+- **OpenAPI `distinct` type corrected** — the query-builder endpoint's `distinct` parameter was
+  documented as `{ type: 'boolean' }` in the generated spec. The actual type is `string[]` (an
+  array of field names to de-duplicate on). The spec now documents it as
+  `{ type: 'array', items: { type: 'string' } }` with an accurate description.
+
+- **`normalizeEnvelope` and `mergeRelationDefinitions` extracted to `fields.ts`** — both
+  utilities existed in identical form in `crudRouter.ts` and `specGenerator.ts`. They are now
+  exported from `src/core/fields.ts` alongside `mergeFieldDefinitions`, and both files import
+  from there. Behavior is unchanged.
+
+- **`checkRequiredPermissions` extracted to `src/auth/strategies/types.ts`** — the permission
+  check logic was duplicated (with incompatible `.every()` vs `.some()` semantics) across all
+  three strategy files and `handlerUtils.ts`. It is now a single exported function and all four
+  call sites use it. See the Security section above for the semantics fix.
+
+- **`DrizzleAdapter` reports `supportsIncludes: false`** — the adapter has always silently ignored
+  `?include=` requests because Drizzle has no built-in relation eager-loading surface compatible
+  with Halifax's interface. The `capabilities` property now explicitly sets `supportsIncludes:
+  false`, which causes the router to reject `?include=` with `422 Unprocessable Entity` instead
+  of silently returning records with no related data.
+
+- **`InMemoryCacheStore` memory growth bounded** — the store previously only evicted expired
+  entries lazily on reads, so a write-heavy workload with few reads could accumulate stale entries
+  without bound. The `set()` method now runs a full expired-entry sweep every 200 writes
+  (configurable via the `sweepEvery` constructor parameter). No external timers or additional
+  dependencies.
+
+- **`CacheStore.increment` — atomic cache version bumps** — `createCachingRepository` previously
+  incremented the version key with a non-atomic `GET` + `SET`, creating a race window under
+  concurrent writes on Redis. The `CacheStore` interface gains an optional `increment(key):
+  Promise<number> | number` method. `RedisCacheStore` implements it with Redis `INCR` (atomic
+  by design). `InMemoryCacheStore` implements it synchronously (race-free in Node.js's
+  single-threaded event loop). `createCachingRepository` uses `store.increment` when available
+  and falls back to the non-atomic path only for custom stores that do not implement it.
+
+- **`DrizzleAdapter.upsertOne` non-atomicity documented** — the method does a `getOne` check
+  followed by a `createOne` or `updateOne`, which is non-atomic under concurrent load. A JSDoc
+  comment now explains the race condition and recommends implementing a custom repository with a
+  database-native `INSERT … ON CONFLICT` clause when true atomicity is required.
+
+- **`PrismaAdapter` import order** — all imports were moved above function definitions and
+  consolidated into a single, alphabetized block. No behavior change.
+
+- **`parseId` dead code removed** — after `validateId(raw)` narrows `raw` to `string`, the
+  previous `typeof raw === 'string' ? parseInt(raw, 10) : raw` branch was unreachable. The
+  function now calls `parseInt(raw, 10)` directly, and the redundant type guard before the
+  UUID/ObjectId check is also removed.
+
+- **`LIKE` interior-wildcard limitation documented** — `likeToPrisma` in
+  `src/adapters/orm/prisma/astToPrisma.ts` now carries a JSDoc comment explaining that patterns
+  with an interior wildcard (e.g. `'foo%bar'`) cannot be expressed via Prisma's string operators
+  and fall through to an exact `equals` match, not a wildcard match. Use `CONTAINS`, `STARTS
+  WITH`, or `ENDS WITH` comparisons instead of `LIKE` when possible.
+
+### Documentation
+
+- **`QueryBuilder` mutability warning** — the class JSDoc now clearly states that all chaining
+  methods mutate `this` and return the same instance. A before/after code example demonstrates
+  the correct pattern (create a new `QueryBuilder` per branch) and the incorrect pattern (sharing
+  one instance and calling `.limit()` twice).
+
+- **`andGroup` / `orGroup` API design explained** — both methods require a `field`/`comparison`/
+  `value1` parent condition because the Halifax query AST attaches children to a parent filter
+  node. The JSDoc now explains this constraint, describes what the resulting predicate looks like
+  (`cond AND (children)` vs `cond OR (children)`), and suggests a workaround for expressing a
+  pure parenthesized group with no meaningful parent condition.
+
+- **`specGenerator` raw-vs-normalized resource note** — a comment in `generateOpenApiSpec`
+  explains that the function operates on raw `ResourceDefinition` objects (not the normalized
+  forms produced by `crudRouter.normalizeResource`) and therefore re-derives merged fields and
+  relations independently. This is intentional — the spec generator is also usable as a
+  standalone function outside the router.
+
+## [2.2.3]
+
+### Added
+
+- **`ConflictError`** — new `HttpError` subclass with HTTP status `409`. Exported from
+  the main package entry-point so application code can `throw new ConflictError()` in
+  hooks or custom repositories and have it serialised correctly.
+
+### Fixed
+
+- **409 Conflict on duplicate unique-key violations** — `PrismaAdapter` and `DrizzleAdapter`
+  now catch unique-constraint errors from the underlying ORM and re-throw them as
+  `ConflictError` (HTTP 409) instead of letting the raw ORM error propagate as an
+  unhandled 500.
+  - **Prisma**: catches `P2002` (unique constraint failed) on `createOne`, `createMany`,
+    `updateOne`, and both branches of `upsertOne`.
+  - **Drizzle**: catches PostgreSQL `23505`, MySQL `1062` / `ER_DUP_ENTRY`, and SQLite
+    `UNIQUE constraint failed` on `createOne`, `createMany`, and `updateOne`.
+- **`statusCodeMap` now includes `409 → 'CONFLICT'`** — previously, any `HttpError`
+  thrown with status `409` would have been serialised with `code: "INTERNAL_ERROR"`.
+
+### Changed
+
+- **OpenAPI spec** — write operations (`POST /{resource}`, `PATCH /{resource}`,
+  `PATCH /{resource}/{id}`, `PUT /{resource}/{id}`) now include a `409 Conflict` response
+  definition documenting that unique-constraint violations return this status.
+
 ## [2.2.2]
 
 ### Fixed
 
 - Removed the `preinstall` script from both `@edium/halifax` and `@edium/halifax-client`. The
-  script was a developer-convenience guard that enforced pnpm usage inside the monorepo, but because it shipped in the published package it caused npm (v7+) to prompt consumers with an  "approve build scripts" confirmation on every install. End-users no longer need to approve anything to install either package.
+  script was a developer-convenience guard that enforced pnpm usage inside the monorepo, but because it shipped in the published package it caused npm (v7+) to prompt consumers with an "approve build scripts" confirmation on every install. End-users no longer need to approve anything to install either package.
 
 ## [2.2.1]
 

package/README.md

@@ -157,21 +157,21 @@ app.listen(3000)
 
 ## Documentation
 
-| Guide                                                | Contents                                                                                                 |
-| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| [README_CLIENT.md](./README_CLIENT.md) · [npm](https://www.npmjs.com/package/@edium/halifax-client) | `@edium/halifax-client` — install, transports, query builder, React & Vue TanStack Query examples |
-| [README_AUTOCRUD.md](./README_AUTOCRUD.md)           | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes            |
-| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) | Prisma 7 (and 6) setup, `PrismaAdapter`, `DrizzleAdapter`, capabilities, custom repositories             |
-| [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md) | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters                     |
-| [README_AUTH.md](./README_AUTH.md)                   | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, per-field `readRoles`/`writeRoles` |
-| [README_MULTITENANCY.md](./README_MULTITENANCY.md)   | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour            |
-| [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)   | Query-builder payload, comparisons, nested filters, portable execution                                   |
-| [README_CACHE.md](./README_CACHE.md)                 | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header                          |
-| [README_HOOKS.md](./README_HOOKS.md)                 | Lifecycle hooks: `beforeCreate`, `afterCreate`, `beforeReadMany`, `beforeQuery`, and every other hook    |
-| [README_OPENAPI.md](./README_OPENAPI.md)             | OpenAPI 3.1 spec generation, Swagger UI, type introspection, security schemes, programmatic use          |
-| [README_TYPES.md](./README_TYPES.md)                 | All exported type aliases, enums (`SqlComparison`, `SqlOperator`, `SqlOrder`), and constants             |
-| [README_INTERFACES.md](./README_INTERFACES.md)       | All exported interfaces — resource, auth, HTTP, repository, cache, Prisma, Drizzle, query AST            |
-| [README_CLASSES.md](./README_CLASSES.md)             | All exported classes — auth strategies, HTTP adapters, ORM adapters, cache stores, error types           |
+| Guide                                                                                               | Contents                                                                                                 |
+| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [README_CLIENT.md](./README_CLIENT.md) · [npm](https://www.npmjs.com/package/@edium/halifax-client) | `@edium/halifax-client` — install, transports, query builder, React & Vue TanStack Query examples        |
+| [README_AUTOCRUD.md](./README_AUTOCRUD.md)                                                          | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes            |
+| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md)                                                | Prisma 7 (and 6) setup, `PrismaAdapter`, `DrizzleAdapter`, capabilities, custom repositories             |
+| [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md)                                                | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters                     |
+| [README_AUTH.md](./README_AUTH.md)                                                                  | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, per-field `readRoles`/`writeRoles` |
+| [README_MULTITENANCY.md](./README_MULTITENANCY.md)                                                  | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour            |
+| [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)                                                  | Query-builder payload, comparisons, nested filters, portable execution                                   |
+| [README_CACHE.md](./README_CACHE.md)                                                                | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header                          |
+| [README_HOOKS.md](./README_HOOKS.md)                                                                | Lifecycle hooks: `beforeCreate`, `afterCreate`, `beforeReadMany`, `beforeQuery`, and every other hook    |
+| [README_OPENAPI.md](./README_OPENAPI.md)                                                            | OpenAPI 3.1 spec generation, Swagger UI, type introspection, security schemes, programmatic use          |
+| [README_TYPES.md](./README_TYPES.md)                                                                | All exported type aliases, enums (`SqlComparison`, `SqlOperator`, `SqlOrder`), and constants             |
+| [README_INTERFACES.md](./README_INTERFACES.md)                                                      | All exported interfaces — resource, auth, HTTP, repository, cache, Prisma, Drizzle, query AST            |
+| [README_CLASSES.md](./README_CLASSES.md)                                                            | All exported classes — auth strategies, HTTP adapters, ORM adapters, cache stores, error types           |
 
 ## Examples
 

package/README_AUTH.md

@@ -37,7 +37,7 @@ const authStrategy = new ApiKeyAuthStrategy(process.env.API_KEY ?? '')
 const authStrategy = new ApiKeyAuthStrategy(process.env.API_KEY ?? '', 'x-token')
 ```
 
-Wrong or missing key → 403.
+Missing header → 401 Unauthorized. Wrong key → 403 Forbidden.
 
 ### `JwtClaimsAuthStrategy`
 
@@ -194,7 +194,7 @@ class RoleBasedStrategy implements AuthStrategy {
 
   authorize({ auth, action, resource, requiredPermissions }) {
     if (auth.roles.includes('admin')) return true
-    return requiredPermissions.every((p) => auth.permissions.includes(p) || auth.roles.includes(p))
+    return requiredPermissions.some((p) => auth.permissions.includes(p) || auth.roles.includes(p))
   }
 }
 ```

package/README_AUTOCRUD.md

@@ -100,9 +100,9 @@ Each entry in `fields` accepts four optional boolean flags. All default to `true
 
 | Flag         | Effect when `false`                                                   |
 | ------------ | --------------------------------------------------------------------- |
-| `filterable` | Rejects the field as a query-string filter (`?fieldName=value`) → 400 |
-| `sortable`   | Rejects the field in `?order=` and query-builder `orderBy` → 400      |
-| `selectable` | Rejects the field in `?fields=` and query-builder `fields` → 400      |
+| `filterable` | Rejects the field as a query-string filter (`?fieldName=value`) → 422 |
+| `sortable`   | Rejects the field in `?order=` and query-builder `orderBy` → 422      |
+| `selectable` | Rejects the field in `?fields=` and query-builder `fields` → 422      |
 | `writable`   | Silently strips the field from POST / PATCH / PUT request bodies      |
 
 Example — `role` is fully locked down; `createdAt` can be read and sorted but never written or filtered:
@@ -295,7 +295,7 @@ The `?where` / query-builder `children` filter lets callers nest conditions. To
 }
 ```
 
-Requests that exceed the limit receive **400 VALIDATION_ERROR**.
+Requests that exceed the limit receive **422 UNPROCESSABLE_ENTITY**.
 
 ## Error Response Shape
 
@@ -320,6 +320,7 @@ All errors follow the same envelope — an `errors` array where each item has a
 | 404    | `NOT_FOUND`              | `NotFoundError`             | Record not found                                                                                     |
 | 405    | `METHOD_NOT_ALLOWED`     | `MethodNotAllowedError`     | HTTP method not enabled for this resource                                                            |
 | 406    | `NOT_ACCEPTABLE`         | `NotAcceptableError`        | `Accept` header excludes `application/json`                                                          |
+| 409    | `CONFLICT`               | `ConflictError`             | Write rejected due to a unique constraint violation                                                  |
 | 415    | `UNSUPPORTED_MEDIA_TYPE` | `UnsupportedMediaTypeError` | Request body is not `application/json`                                                               |
 | 422    | `UNPROCESSABLE_ENTITY`   | `UnprocessableEntityError`  | Semantic validation failure — unknown field, invalid filter, sort/select restriction, depth exceeded |
 | 500    | `INTERNAL_ERROR`         | `ServerError`               | Repository misconfigured or unhandled internal error                                                 |

package/README_CACHE.md

@@ -149,6 +149,12 @@ class MyCacheStore implements CacheStore {
   async delete(key: string): Promise<void> {
     /* … */
   }
+  // Optional — implement for atomic version bumps under concurrent writes.
+  // When omitted, Halifax falls back to a non-atomic GET + SET (safe for
+  // single-process stores like InMemoryCacheStore, but not for Redis).
+  async increment(key: string): Promise<number> {
+    /* … return new integer value */
+  }
 }
 ```
 

package/README_CLASSES.md

@@ -28,13 +28,14 @@ Import: `@edium/halifax`
 Reads a request header and compares it against a static shared secret.
 
 ```ts
-new ApiKeyAuthStrategy(expectedApiKey: string, headerName?: string)
+new ApiKeyAuthStrategy(expectedApiKey: string, headerName?: string, roles?: string[])
 ```
 
-| Parameter        | Default       | Description                         |
-| ---------------- | ------------- | ----------------------------------- |
-| `expectedApiKey` | required      | The secret key callers must supply. |
-| `headerName`     | `'x-api-key'` | Header to read the key from.        |
+| Parameter        | Default       | Description                                                              |
+| ---------------- | ------------- | ------------------------------------------------------------------------ |
+| `expectedApiKey` | required      | The secret key callers must supply.                                      |
+| `headerName`     | `'x-api-key'` | Header to read the key from.                                             |
+| `roles`          | `[]`          | Role strings attached to `auth.roles` on every successfully authed call. |
 
 - Missing header → 401 Unauthorized
 - Wrong key → 403 Forbidden
@@ -208,7 +209,12 @@ new PrismaAdapter<TRecord, TCreate, TUpdate>(options: PrismaAdapterOptions)
 
 See `PrismaAdapterOptions` in [README_INTERFACES.md](./README_INTERFACES.md).
 
-**Static method:** `PrismaAdapter` has no static methods. For auto-generating resources from all Prisma models, use `createPrismaResources` (a standalone function).
+**Static methods:**
+
+- `PrismaAdapter.fieldsFromModel(model: ModelSchema): FieldDefinition[]` — derives a Halifax field schema from a Prisma DMMF model. Used internally by the constructor when `options.model` is provided; also callable standalone when you want to inspect or override fields before constructing the adapter.
+- `PrismaAdapter.relationsFromModel(model: ModelSchema): RelationDefinition[]` — derives relation definitions from object-kind fields in the model.
+
+For auto-generating resources from all Prisma models at once, use `createPrismaResources` (a standalone function).
 
 **Capabilities reported:**
 
@@ -314,6 +320,7 @@ Base class for all Halifax HTTP errors. Not instantiated directly.
 | `NotFoundError`             | 404    | Record with the given ID does not exist. Throw from a custom `Repository.getOne`.                              |
 | `MethodNotAllowedError`     | 405    | HTTP method not enabled for this resource. Used internally by Halifax.                                         |
 | `NotAcceptableError`        | 406    | Client `Accept` header excludes `application/json`. Used internally by Halifax.                                |
+| `ConflictError`             | 409    | Write rejected due to a unique constraint violation. Thrown by `PrismaAdapter` and `DrizzleAdapter` automatically; throw it from a custom repository for the same semantics. |
 | `UnsupportedMediaTypeError` | 415    | Body-carrying request with non-JSON `Content-Type`. Used internally by Halifax.                                |
 | `UnprocessableEntityError`  | 422    | Unknown fields in body, missing required filter, empty update payload.                                         |
 | `NotImplementedError`       | 501    | Repository does not support this operation (e.g. `upsertOne` not implemented).                                 |

package/README_INTERFACES.md

@@ -24,7 +24,7 @@ Full definition of a Halifax resource. Pass an array of these to `createExpressC
 | `requiredPermissions` | `Partial<Record<CrudAction, string[]>>` | no       | Permission strings per action checked by the auth strategy.                                                                                                                                                                                |
 | `defaultLimit`        | `number`                                | no       | Default page size when caller omits `?limit=`. Defaults to `DEFAULT_PAGE_LIMIT` (5000). `0` disables the default bound.                                                                                                                    |
 | `maxLimit`            | `number`                                | no       | Hard cap on page size. Defaults to `MAX_PAGE_LIMIT` (5000). `0` removes the cap.                                                                                                                                                           |
-| `maxFilterDepth`      | `number`                                | no       | Maximum nesting depth for `where` clause children. Defaults to 3.                                                                                                                                                                          |
+| `maxFilterDepth`      | `number`                                | no       | Maximum nesting depth for `where` clause children. Defaults to 4.                                                                                                                                                                          |
 | `cache`               | `ResourceCacheConfig \| false`          | no       | Per-resource cache TTL. `false` disables caching even when an API-wide default is set.                                                                                                                                                     |
 | `envelope`            | `string \| null`                        | no       | Wraps every success response body under this key (e.g. `'data'`). Overrides the API-wide `envelope` option.                                                                                                                                |
 
@@ -404,11 +404,12 @@ Import: `@edium/halifax`
 
 Contract for pluggable cache backends. Implement this to use Redis, Memcached, or any other store.
 
-| Method   | Signature                                            | Description                                                      |
-| -------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
-| `get`    | `(key: string) => Promise<unknown> \| unknown`       | Read a cached value. Returns `undefined` when absent or expired. |
-| `set`    | `(key, value, ttlSeconds?) => Promise<void> \| void` | Write a value. `ttlSeconds` `0` or omitted means no expiry.      |
-| `delete` | `(key: string) => Promise<void> \| void`             | Delete a cached value.                                           |
+| Method      | Signature                                             | Description                                                                                                          |
+| ----------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `get`       | `(key: string) => Promise<unknown> \| unknown`        | Read a cached value. Returns `undefined` when absent or expired.                                                     |
+| `set`       | `(key, value, ttlSeconds?) => Promise<void> \| void`  | Write a value. `ttlSeconds` `0` or omitted means no expiry.                                                          |
+| `delete`    | `(key: string) => Promise<void> \| void`              | Delete a cached value.                                                                                               |
+| `increment` | `(key: string) => Promise<number> \| number` *(opt.)* | Atomically increment an integer key and return the new value. Implement this for safe concurrent version bumps (e.g. Redis `INCR`). When omitted, Halifax falls back to a non-atomic `get`+`set`. |
 
 ---
 
@@ -433,11 +434,12 @@ Import: `@edium/halifax`
 
 Minimal structural type for a Redis client. `RedisCacheStore` uses this interface so no specific Redis package is a hard dependency. `redis` v4's `get`, `set`, and `del` satisfy it directly.
 
-| Method | Signature                                    | Description                                    |
-| ------ | -------------------------------------------- | ---------------------------------------------- |
-| `get`  | `(key: string) => Promise<string \| null>`   | Read a key.                                    |
-| `set`  | `(key, value, options?) => Promise<unknown>` | Write a key. `options.EX` sets TTL in seconds. |
-| `del`  | `(key: string) => Promise<unknown>`          | Delete a key.                                  |
+| Method | Signature                                          | Description                                                                         |
+| ------ | -------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `get`  | `(key: string) => Promise<string \| null>`         | Read a key.                                                                         |
+| `set`  | `(key, value, options?) => Promise<unknown>`       | Write a key. `options.EX` sets TTL in seconds.                                      |
+| `del`  | `(key: string) => Promise<unknown>`                | Delete a key.                                                                       |
+| `incr` | `(key: string) => Promise<number>` *(optional)*    | Atomically increment a key. Used by `RedisCacheStore.increment` for version bumps when the client exposes this method. |
 
 ---
 

package/README_OPENAPI.md

@@ -284,7 +284,7 @@ The query builder endpoint accepts a `QueryOptions` body for full-featured filte
       ]
     }
   ],
-  "orderBy": [{ "field": "createdAt", "direction": "desc" }],
+  "orderBy": [{ "field": "createdAt", "order": "DESC" }],
   "limit": 20,
   "offset": 0,
   "fields": ["id", "title", "createdAt"],

package/README_REPO_ADAPTERS.md

@@ -186,6 +186,8 @@ A resource always needs a field schema — it's the allow-list that powers filte
 
 Halifax's `peerDependencies` allow `@prisma/client >=6.0.0`, so it runs on **Prisma 6 or Prisma 7**. `PrismaAdapter` is database- and version-agnostic: it imports nothing from `@prisma/client` and only calls standard model-delegate methods (`findMany`, `findUnique`, `findFirst`, `create`, `createMany`, `update`, `updateMany`, `delete`, `deleteMany`, `upsert`, `count`) that behave identically across both majors. **You** construct the client and pass `prisma.<model>` as the `delegate` — Halifax never touches the parts that differ between the versions.
 
+**Tenant-scoped paths require `updateMany` and `deleteMany` on the delegate.** When multi-tenant isolation is active, `updateOne` uses `updateMany(scopedWhere)` for an atomic ownership-enforced write, and `deleteOne` uses `deleteMany(scopedWhere)` for the same reason. If the delegate does not expose these methods, both operations throw `ServerError`. Standard Prisma delegates always expose them; this only affects non-standard or mock delegates.
+
 > **Caveats.** Halifax's CI matrix exercises **Prisma 7 only** — Prisma 6 is supported on the strength of that stable delegate surface, not a dedicated CI leg, so treat it as best-effort and pin/test your own app against it. Prisma 7 is the recommended path; the main reason to stay on (or drop to) Prisma 6 today is **MongoDB**, which Prisma 7 does not yet support. When Prisma 7 restores MongoDB, prefer upgrading over remaining on 6.
 
 What you implement differently on Prisma 6 (everything below is your project's Prisma setup — no Halifax code changes):
@@ -306,6 +308,14 @@ new DrizzleAdapter(db, table, config?, scope?)
 | `config.idField` | `string` (optional)   | Primary key field name. Defaults to auto-detecting the first column marked `.primaryKey()`. Set explicitly for composite PKs or non-standard names. |
 | `scope`          | `TenantScope \| null` | Tenant scope. Set by `withScope()` internally — do not pass directly.                                                                               |
 
+### Relation includes
+
+`DrizzleAdapter` does **not** support `?include=` (relation eager-loading). It reports
+`capabilities.supportsIncludes: false`, so the router rejects `?include=` requests with
+`422 Unprocessable Entity` rather than silently returning records with no related data.
+If you need related records, fetch them with a second query or use `PrismaAdapter` for
+the resource that requires includes.
+
 ### Multi-tenancy
 
 `DrizzleAdapter` supports per-resource tenant scoping via `withScope()` exactly like `PrismaAdapter`. See [README_MULTITENANCY.md](./README_MULTITENANCY.md) for how to configure it on the resource.

package/dist/adapters/orm/drizzle/DrizzleAdapter.d.ts

@@ -88,6 +88,11 @@ export declare class DrizzleAdapter<TRecord = Record<string, unknown>, TCreate =
     private readonly table;
     readonly fields: FieldDefinition[];
     readonly idField: string;
+    /** Drizzle uses `.returning()` for inserts/updates, so it always returns created records. */
+    readonly capabilities: {
+        supportsIncludes: boolean;
+        supportsCreateManyReturn: boolean;
+    };
     private readonly columns;
     private readonly scope;
     constructor(db: AnyDrizzleDB, table: Table, config?: DrizzleAdapterConfig, scope?: TenantScope | null);

package/dist/adapters/orm/drizzle/DrizzleAdapter.js

@@ -1,5 +1,19 @@
+import { ConflictError } from '../../../errors/ConflictError.js';
 import { count, eq, getTableColumns, and, inArray, asc, desc } from 'drizzle-orm';
 import { astToDrizzleWhere, astToDrizzleOrderBy } from './astToDrizzle.js';
+/** Detects unique constraint violations across PostgreSQL (23505), MySQL (1062/ER_DUP_ENTRY), and SQLite. */
+function isDuplicateError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const e = error;
+    if (e['code'] === '23505')
+        return true;
+    if (e['errno'] === 1062 || e['code'] === 'ER_DUP_ENTRY')
+        return true;
+    if (typeof e['message'] === 'string' && e['message'].includes('UNIQUE constraint failed'))
+        return true;
+    return false;
+}
 function drizzleTypeToOpenApi(col) {
     switch (col.dataType) {
         case 'string':
@@ -54,6 +68,8 @@ export class DrizzleAdapter {
     table;
     fields;
     idField;
+    /** Drizzle uses `.returning()` for inserts/updates, so it always returns created records. */
+    capabilities = { supportsIncludes: false, supportsCreateManyReturn: true };
     columns;
     scope;
     constructor(db, table, config = {}, scope = null) {
@@ -176,11 +192,18 @@ export class DrizzleAdapter {
         return { count: total, results: rows };
     }
     async createOne(data, _options) {
-        const rows = (await this.db
-            .insert(this.table)
-            .values(this.scope ? { ...data, [this.scope.field]: this.scope.value } : data)
-            .returning());
-        return rows[0];
+        try {
+            const rows = (await this.db
+                .insert(this.table)
+                .values(this.scope ? { ...data, [this.scope.field]: this.scope.value } : data)
+                .returning());
+            return rows[0];
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     async createMany(data, _options) {
         if (!data.length)
@@ -188,20 +211,40 @@ export class DrizzleAdapter {
         const stamped = this.scope
             ? data.map((d) => ({ ...d, [this.scope.field]: this.scope.value }))
             : data;
-        const rows = (await this.db.insert(this.table).values(stamped).returning());
-        return rows;
+        try {
+            const rows = (await this.db.insert(this.table).values(stamped).returning());
+            return rows;
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     async updateOne(id, data) {
         const idWhere = eq(this.columns[this.idField], id);
         const where = this.withScopeWhere(idWhere);
-        const rows = (await this.db
-            .update(this.table)
-            .set(this.stripScope(data))
-            .where(where)
-            .returning());
-        return rows[0] ?? null;
+        try {
+            const rows = (await this.db
+                .update(this.table)
+                .set(this.stripScope(data))
+                .where(where)
+                .returning());
+            return rows[0] ?? null;
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     async upsertOne(id, data) {
+        // Non-atomic: the getOne check and the subsequent write are separate statements.
+        // Under concurrent load, two simultaneous upserts for the same absent ID can both
+        // pass the getOne check and then race on createOne — the loser gets a ConflictError.
+        // Drizzle has no single portable INSERT…ON CONFLICT across all databases, so this
+        // is the safest cross-provider implementation. Callers that need true atomicity
+        // should implement a custom repository using a database-specific ON CONFLICT clause.
         const existing = await this.getOne(id);
         if (existing) {
             const updated = await this.updateOne(id, data);
@@ -250,6 +293,6 @@ export class DrizzleAdapter {
         return { count: total, results: rows };
     }
     withScope(scope) {
-        return new DrizzleAdapter(this.db, this.table, { idField: this.idField }, scope ?? null);
+        return new DrizzleAdapter(this.db, this.table, { idField: this.idField }, scope);
     }
 }

package/dist/adapters/orm/prisma/PrismaAdapter.d.ts

@@ -1,6 +1,5 @@
 import type { IQueryOptions } from '@edium/halifax-types';
-import type { Repository, RepositoryCapabilities, DeleteManyResult, ListOptions, ListResult, QueryResult, TenantScope, UpdateManyResult } from '../../../core/types.js';
-import type { FieldDefinition, RelationDefinition, ModelSchema } from '../../../core/types.js';
+import type { DeleteManyResult, FieldDefinition, ListOptions, ListResult, ModelSchema, QueryResult, RelationDefinition, Repository, RepositoryCapabilities, TenantScope, UpdateManyResult } from '../../../core/types.js';
 import type { PrismaAdapterOptions } from './types.js';
 /**
  * PrismaAdapter is a generic repository implementation that uses Prisma delegates to perform