@edium/halifax 2.2.3 → 2.4.0

package/CHANGELOG.md

@@ -3,6 +3,208 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0]
+
+### Breaking
+
+- **`RouteHandlerContext.resolveRepo` and `GraphQLResourceContext.resolveRepo` now require a
+  third `action: CrudAction` argument** — the resolver function signature has changed from
+  `(req: HttpRequest, auth: AuthContext) => Promise<Repository>` to
+  `(req: HttpRequest, auth: AuthContext, action: CrudAction) => Promise<Repository>`. The
+  `action` parameter carries the name of the CRUD operation being performed (e.g. `'readMany'`,
+  `'create'`) so that action-aware logic (such as the new admin bypass) can branch correctly
+  inside the closure. All built-in handlers and resolvers pass the correct action. Custom
+  integrations that construct a `RouteHandlerContext` or `GraphQLResourceContext` directly must
+  update their `resolveRepo` implementation to accept and handle the third argument.
+
+- **`GraphQLOptions.enabled` must now be explicitly set to `true`** — previously, supplying a
+  `graphql: { ... }` object without `enabled: false` activated the endpoint. The new default is
+  off: the endpoint is registered only when `graphql: { enabled: true, ... }` is passed. This
+  makes GraphQL a deliberate opt-in and avoids importing the optional `graphql` peer dependency
+  unless it is actually used. Existing configurations that relied on the implicit default must
+  add `enabled: true`.
+
+### Added
+
+- **GraphQL endpoint** — Halifax can now expose a full GraphQL API alongside REST. The schema
+  is built at startup from the same resource definitions that drive REST: no separate schema
+  file, no annotations. For each resource Halifax generates `get<T>`, `list<T>`, and
+  `query<T>` query fields plus `create<T>`, `createMany<T>`, `update<T>`, `updateMany<T>`,
+  `upsert<T>`, `delete<T>`, and `deleteMany<T>` mutation fields — only those allowed by
+  `resource.permissions` are included. The same auth strategy, tenant scoping, field-level
+  security (`readRoles`/`writeRoles`), lifecycle hooks, and caching that apply to REST apply
+  identically to GraphQL resolvers. Requires the optional `graphql` (≥ 16.0.0) peer dependency.
+
+  ```ts
+  createExpressCrudRouter(resources, {
+    graphql: { enabled: true, path: '/graphql', graphiql: true }
+  })
+  ```
+
+  - `GET /graphql` serves the GraphiQL browser IDE (disable with `graphiql: false`).
+  - `requireAuth: true` gates even introspection behind `authStrategy.authenticate`.
+  - Set `graphql: false` on any `ResourceDefinition` to exclude it from the schema while
+    keeping it on REST.
+  - See [README_GRAPHQL.md](./README_GRAPHQL.md) for full documentation and examples.
+
+- **Admin tenant bypass** — callers whose `auth.roles` or `auth.permissions` matches any entry
+  in `TenantOptions.bypassRoles` receive an unscoped repository for read operations
+  (`readOne`, `readMany`, `readManyWithQueryBuilder`), allowing them to query across all
+  tenants. Write operations (`create`, `updateOne`, `updateMany`, `upsertOne`, `deleteOne`,
+  `deleteMany`) are never bypassed — the tenant value on writes continues to come from
+  `resolveId`, keeping write provenance tied to authentication rather than client input.
+  Admins who want to read a single tenant's data use the standard filter syntax
+  (`?companyId=42` on REST, `filter: { companyId: 42 }` in GraphQL) rather than any special
+  override mechanism.
+
+  ```ts
+  tenant: {
+    resolveId: ({ auth }) => auth.claims?.companyId,
+    bypassRoles: ['super_admin', 'support:read-all'],   // role OR permission slug
+  }
+  ```
+
+  Per-resource override via `ResourceDefinition.bypassTenantRoles` takes precedence over the
+  API-wide list. Set it to `[]` on a resource to prevent bypass entirely for that model even
+  when a global `bypassRoles` is configured.
+
+- **`README_GRAPHQL.md`** — new reference document covering GraphQL opt-in setup, the
+  auto-generated schema (queries, mutations, types), per-resource opt-out, the GraphiQL IDE,
+  authentication, tenant bypass behaviour, and annotated query/mutation examples.
+
+## [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

package/README.md

@@ -17,9 +17,10 @@ The package is split into small, replaceable layers — nothing is imported into
 - 🗄️ **Two ORM adapters, six databases** — `PrismaAdapter` covers PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, and SQLite; `DrizzleAdapter` (sub-path `@edium/halifax/drizzle`) covers PostgreSQL, MySQL, SQLite, and LibSQL. Both compile to ORM calls (never raw SQL) so the same query behaves identically across engines.
 - 🔎 **Dynamic query-builder endpoint** — let the front-end compose rich filtered/sorted/paginated queries "for free" (`AND`/`OR`/nesting, `IN`, `BETWEEN`, `CONTAINS`, …) without hand-writing endpoints. Fully validated — bad fields/operators return structured `4xx` errors, never leaked DB internals.
 - 📄 **OpenAPI 3.1 generation** — zero-annotation spec generated from your resource definitions at startup. Prisma and Drizzle types are introspected automatically; custom repos annotate individual fields. Swagger UI at `/docs`, raw spec at `/openapi.json`. Disable with `enabled: false` for zero production overhead.
-- 🏢 **Multi-tenancy built in** — per-resource tenant scoping with fail-closed guarantees; one tenant can never read or write another's rows.
+- 🏢 **Multi-tenancy built in** — per-resource tenant scoping with fail-closed guarantees; one tenant can never read or write another's rows. Privileged roles (admin, super-admin) can optionally bypass scoping to read across all tenants, with per-resource granularity. See [README_MULTITENANCY.md](./README_MULTITENANCY.md).
 - ⚡ **Pluggable read-through caching** — in-memory or Redis, per-resource TTLs, never-expire mode, automatic write-invalidation, tenant-safe keys, and a `Cache-Control` bust header.
-- 🔐 **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action permissions; `filterable`/`sortable`/`selectable`/`writable` field flags; and per-field `readRoles`/`writeRoles` for role-based column visibility.
+- 🔐 **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action permissions (matched against roles OR permission slugs); `filterable`/`sortable`/`selectable`/`writable` field flags; and per-field `readRoles`/`writeRoles` for role-based column visibility.
+- 🔷 **GraphQL endpoint** — opt-in GraphQL API auto-generated from the same resource definitions as REST. Every query, mutation, filter, sort, and field-level permission works identically. Includes a GraphiQL IDE, per-resource opt-out, and full tenant bypass support. See [README_GRAPHQL.md](./README_GRAPHQL.md).
 - 🪝 **Lifecycle hooks** — inject custom logic before or after any CRUD operation per resource (`beforeCreate`, `afterCreate`, `beforeReadMany`, `beforeQuery`, …). Stamp audit fields, emit events, enforce ownership, or transform results without writing a custom repository. See [README_HOOKS.md](./README_HOOKS.md).
 - 📦 **Companion browser client** — [`@edium/halifax-client`](https://www.npmjs.com/package/@edium/halifax-client) is a typed, zero-dependency client with a fluent query builder and built-in TanStack Query helpers (queries + mutation auto-invalidation). Bring your own HTTP library (fetch, axios, ky, ofetch, superagent).
 - 🧪 **Type-safe & battle-tested** — strict TypeScript, ESM, ships full `.d.ts`; hundreds of unit tests plus the full integration suite run against six real databases + Redis in CI.
@@ -30,9 +31,10 @@ The package is split into small, replaceable layers — nothing is imported into
 | -------------- | -------------------------------------------------------------------------------------------------------------------- |
 | HTTP server    | Express 4/5, Fastify, HyperExpress, Ultimate Express                                                                 |
 | ORM / database | Prisma 6 or 7 (Postgres, MySQL, MariaDB, SQL Server, CockroachDB, SQLite); Drizzle (Postgres, MySQL, SQLite, LibSQL) |
-| Auth           | API key, JWT/Bearer, Passport + JWT; per-field `readRoles`/`writeRoles`                                              |
+| Auth           | API key, JWT/Bearer, Passport + JWT; per-field `readRoles`/`writeRoles`; role or permission slug                     |
 | Caching        | Pluggable read-through cache (in-memory default; bring Redis, etc.)                                                  |
 | API docs       | OpenAPI 3.1 spec + Swagger UI (optional, zero overhead when disabled)                                                |
+| GraphQL        | Auto-generated schema from resource definitions; opt-in; GraphiQL IDE; requires `graphql` ≥ 16 peer dep             |
 
 Every HTTP adapter is interchangeable and behaves identically — same routes, status codes,
 error-body shape, and content negotiation — so you can switch frameworks without touching
@@ -168,6 +170,7 @@ app.listen(3000)
 | [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_GRAPHQL.md](./README_GRAPHQL.md)                                                            | GraphQL endpoint: opt-in setup, auto-generated schema, GraphiQL IDE, auth, tenant bypass for admins      |
 | [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            |

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).                                 |