@edium/halifax 2.2.3 → 2.4.0

package/README_GRAPHQL.md

@@ -0,0 +1,352 @@
+# Halifax GraphQL
+
+Halifax can automatically expose a GraphQL API alongside your REST endpoints. The schema is generated at startup from the same resource definitions that drive REST — no extra annotation or separate schema file required.
+
+GraphQL is **opt-in**: nothing happens unless you explicitly set `enabled: true`.
+
+## Contents
+
+- [Installation](#installation)
+- [Enabling GraphQL](#enabling-graphql)
+- [What gets generated](#what-gets-generated)
+- [Per-resource opt-out](#per-resource-opt-out)
+- [GraphiQL IDE](#graphiql-ide)
+- [Authentication](#authentication)
+- [Tenant scoping and admin bypass](#tenant-scoping-and-admin-bypass)
+- [Query examples](#query-examples)
+- [Mutation examples](#mutation-examples)
+- [Types reference](#types-reference)
+
+---
+
+## Installation
+
+The `graphql` package is a peer dependency — install it alongside Halifax:
+
+```bash
+npm install graphql
+# or
+pnpm add graphql
+```
+
+Halifax is tested against `graphql` v16.
+
+---
+
+## Enabling GraphQL
+
+Pass `graphql: { enabled: true }` to `registerCrudApi` (or `createExpressCrudRouter`):
+
+```ts
+import { createExpressCrudRouter } from '@edium/halifax'
+
+const app = createExpressCrudRouter(resources, {
+  graphql: {
+    enabled: true,          // required — GraphQL is off by default
+    path: '/graphql',       // default: '/graphql'
+    graphiql: true,         // default: true — serve the GraphiQL IDE at GET /graphql
+    requireAuth: false,     // default: false — set true to require auth before any operation
+    title: 'My API'         // browser tab title in GraphiQL
+  }
+})
+```
+
+Two routes are registered:
+
+| Route | Purpose |
+|---|---|
+| `POST /graphql` | Execute GraphQL queries and mutations |
+| `GET /graphql` | GraphiQL browser IDE (disable with `graphiql: false`) |
+
+---
+
+## What gets generated
+
+For every resource Halifax generates:
+
+**Query fields**
+
+| Field | REST equivalent | Description |
+|---|---|---|
+| `get<Resource>(id: ID!)` | `GET /<resource>/:id` | Fetch one record by ID |
+| `list<Resource>(filter, limit, offset, orderBy, include)` | `GET /<resource>` | Paginated list with equality filters |
+| `query<Resource>(where, fields, distinct, limit, offset, orderBy, include)` | `POST /<resource>/query` | Advanced query with full filter expressions |
+
+**Mutation fields**
+
+| Field | REST equivalent | Description |
+|---|---|---|
+| `create<Resource>(input)` | `POST /<resource>` | Create one record |
+| `createMany<Resource>(input)` | `POST /<resource>` (array body) | Create multiple records |
+| `update<Resource>(id, input)` | `PATCH /<resource>/:id` | Partial update |
+| `updateMany<Resource>(where, update)` | `PATCH /<resource>` | Bulk update |
+| `upsert<Resource>(id, input)` | `PUT /<resource>/:id` | Create or replace |
+| `delete<Resource>(id)` | `DELETE /<resource>/:id` | Delete one record |
+| `deleteMany<Resource>(where)` | `DELETE /<resource>` | Bulk delete |
+
+Only operations allowed by `resource.permissions` are included. If `allowDeleteMany: false`, no `deleteMany<Resource>` mutation is generated.
+
+---
+
+## Per-resource opt-out
+
+Set `graphql: false` on any resource to exclude it from the GraphQL schema entirely:
+
+```ts
+const resources = [
+  {
+    routePrefix: 'users',
+    repository: userRepo,
+    // visible in REST and GraphQL (default)
+  },
+  {
+    routePrefix: 'audit-logs',
+    repository: auditRepo,
+    graphql: false,  // REST only — excluded from GraphQL
+  }
+]
+```
+
+---
+
+## GraphiQL IDE
+
+When `graphiql: true` (the default), visiting `GET /graphql` in a browser opens the GraphiQL IDE. You can explore the auto-generated schema using introspection, run queries interactively, and inspect the full type system.
+
+To disable the IDE (e.g. in production):
+
+```ts
+graphql: { enabled: true, graphiql: false }
+```
+
+---
+
+## Authentication
+
+GraphQL uses the same `authStrategy` as REST. Every resolver calls `authenticate` before executing, so your JWT/API-key validation fires automatically.
+
+To require authentication before even responding to introspection queries, set `requireAuth: true`:
+
+```ts
+graphql: { enabled: true, requireAuth: true }
+```
+
+Fine-grained permissions (`resource.requiredPermissions`) apply per resolver, identical to REST. Per-field `readRoles`/`writeRoles` restrictions are also enforced — restricted fields are stripped from resolver results.
+
+---
+
+## Tenant scoping and admin bypass
+
+The GraphQL endpoint respects the same tenant isolation that REST does. Each resolver resolves the tenant from the caller's auth context (JWT claims, session, etc.) and scopes the repository automatically — regular users can only see their own tenant's data. The tenant value is **always derived from auth**, never from client-supplied input.
+
+### Admin bypass
+
+Admins who need to query across all tenants can be granted bypass access by listing their roles or permission slugs in `TenantOptions.bypassRoles` (API-wide default) or `ResourceDefinition.bypassTenantRoles` (per-resource override).
+
+```ts
+createExpressCrudRouter(resources, {
+  tenant: {
+    resolveId: (ctx) => ctx.auth.claims?.companyId,
+    bypassRoles: ['super_admin', 'support:read-all'],  // role OR permission slug
+  }
+})
+```
+
+**How it works:**
+
+- **Bypass role → all records.** An admin whose `auth.roles` or `auth.permissions` matches any entry in `bypassRoles` gets an unscoped read — all rows across all tenants.
+- **No bypass role → normal scoping.** Regular users are always scoped to their tenant. The bypass path is unreachable for them.
+- **Writes are never bypassed.** Write operations always resolve the tenant through `resolveId`. An admin whose token carries a `companyId` writes to that company; one without a tenant receives 403 (unless `strict: false`). The tenant field on writes always comes from auth — never from the client.
+
+**Narrowing to a single tenant (admin reads):**
+
+When an admin wants to see just one tenant's data, they use the same filter mechanism as any other caller — the tenant field is just another filterable column:
+
+```graphql
+# All tenants (bypass active, no filter)
+{ listOrders { count results { id companyId total } } }
+
+# One specific tenant — admin narrows with a filter
+{ listOrders(filter: { companyId: 42 }) { count results { id companyId total } } }
+
+# Or with the full query builder
+{
+  queryOrders(where: [
+    { field: "companyId", comparison: "=", value1: 42 }
+  ]) { count results { id companyId total } }
+}
+```
+
+On REST it works the same way:
+```
+# All tenants
+GET /orders
+
+# One tenant
+GET /orders?companyId=42
+```
+
+No special header or query parameter needed — the normal filter API handles it.
+
+#### Per-resource bypass override
+
+Override the global `bypassRoles` for a single resource — or disable bypass entirely for sensitive models:
+
+```ts
+const resources = [
+  {
+    routePrefix: 'orders',
+    repository: orderRepo,
+    // inherits bypassRoles from TenantOptions
+  },
+  {
+    routePrefix: 'payment-methods',
+    repository: paymentRepo,
+    bypassTenantRoles: [],           // no one bypasses tenant on this resource
+  },
+  {
+    routePrefix: 'users',
+    repository: userRepo,
+    bypassTenantRoles: ['super_admin'],  // only super_admin, not support:read-all
+  }
+]
+```
+
+---
+
+## Query examples
+
+### Fetch one record
+
+```graphql
+query {
+  getUser(id: "42") {
+    id
+    name
+    email
+  }
+}
+```
+
+### Paginated list with filters
+
+```graphql
+query {
+  listUsers(
+    filter: { status: "active" }
+    limit: 20
+    offset: 0
+    orderBy: [{ field: "createdAt", direction: desc }]
+  ) {
+    count
+    results {
+      id
+      name
+      email
+    }
+  }
+}
+```
+
+### Advanced query (full filter expressions)
+
+```graphql
+query {
+  queryUsers(
+    where: [
+      { field: "status", comparison: "IN", value1: ["active", "trial"] },
+      { operator: "AND" },
+      { field: "createdAt", comparison: ">=", value1: "2025-01-01" }
+    ]
+    orderBy: [{ field: "name", direction: asc }]
+    limit: 50
+  ) {
+    count
+    results {
+      id
+      name
+      email
+    }
+  }
+}
+```
+
+### With variables
+
+```graphql
+query ListActiveUsers($status: String!, $limit: Int) {
+  listUsers(filter: { status: $status }, limit: $limit) {
+    count
+    results { id name }
+  }
+}
+```
+
+Variables payload:
+```json
+{ "status": "active", "limit": 10 }
+```
+
+---
+
+## Mutation examples
+
+### Create
+
+```graphql
+mutation {
+  createUser(input: { name: "Alice", email: "alice@example.com" }) {
+    id
+    name
+    email
+  }
+}
+```
+
+### Partial update
+
+```graphql
+mutation {
+  updateUser(id: "42", input: { name: "Alice Smith" }) {
+    id
+    name
+  }
+}
+```
+
+### Bulk update
+
+```graphql
+mutation {
+  updateManyUser(
+    where: [{ field: "status", comparison: "=", value1: "trial" }]
+    update: { status: "active" }
+  ) {
+    updated
+  }
+}
+```
+
+### Delete
+
+```graphql
+mutation {
+  deleteUser(id: "42")
+}
+```
+
+---
+
+## Types reference
+
+| Type | Description |
+|---|---|
+| `GraphQLOptions` | Configuration object passed to `registerCrudApi` / `createExpressCrudRouter` |
+| `GraphQLResourceContext` | Internal per-resource context (available if building custom integrations) |
+| `GraphQLResolverContext` | The `contextValue` available in every resolver: `{ req: HttpRequest }` |
+
+All types are re-exported from `@edium/halifax`:
+
+```ts
+import type { GraphQLOptions, GraphQLResourceContext, GraphQLResolverContext } from '@edium/halifax'
+```

package/README_INTERFACES.md

@@ -24,9 +24,11 @@ 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.                                                                                                                                |
+| `graphql`             | `boolean`                               | no       | When `false`, excludes this resource from the auto-generated GraphQL schema while keeping it on REST. Defaults to `true` when GraphQL is enabled.                                                                                           |
+| `bypassTenantRoles`   | `string[]`                              | no       | Roles or permission slugs whose holders bypass tenant scoping for read operations on this resource. Overrides `TenantOptions.bypassRoles`. Set to `[]` to prevent bypass on this resource even when a global list is configured.            |
 
 ---
 
@@ -232,9 +234,10 @@ Configures multi-tenant isolation API-wide. Set on `CrudApiOptions.tenant`.
 
 | Property    | Type                                                         | Default      | Description                                                                                                                                                         |
 | ----------- | ------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveId` | `(ctx: TenantResolveContext) => unknown \| Promise<unknown>` | required     | Resolves the tenant key from the auth context and request. Must come from the token/session — never from client input. Return `null`/`undefined` when none applies. |
-| `field`     | `string`                                                     | `'tenantId'` | Default column name for auto-detection: resources with a field of this name are automatically scoped on it.                                                         |
-| `strict`    | `boolean`                                                    | `true`       | When `true`, a tenant-scoped resource whose `resolveId` returns no value rejects with 403 rather than serving unscoped.                                             |
+| `resolveId`   | `(ctx: TenantResolveContext) => unknown \| Promise<unknown>` | required     | Resolves the tenant key from the auth context and request. Must come from the token/session — never from client input. Return `null`/`undefined` when none applies. |
+| `field`       | `string`                                                     | `'tenantId'` | Default column name for auto-detection: resources with a field of this name are automatically scoped on it.                                                         |
+| `strict`      | `boolean`                                                    | `true`       | When `true`, a tenant-scoped resource whose `resolveId` returns no value rejects with 403 rather than serving unscoped.                                             |
+| `bypassRoles` | `string[]`                                                   | —            | Roles or permission slugs (matched against `auth.roles` OR `auth.permissions`) whose holders receive unscoped reads across all tenants. Writes are never bypassed. Per-resource `ResourceDefinition.bypassTenantRoles` takes precedence. |
 
 ---
 
@@ -404,11 +407,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 +437,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_MULTITENANCY.md

@@ -84,6 +84,11 @@ interface TenantOptions {
   field?: string
   /** Fail-closed when no tenant resolves. Defaults to true. */
   strict?: boolean
+  /**
+   * Roles or permission slugs whose holders bypass tenant scoping on read operations.
+   * See "Admin bypass" below.
+   */
+  bypassRoles?: string[]
 }
 ```
 
@@ -113,6 +118,88 @@ createPrismaResources(prisma, models, {
 })
 ```
 
+## Admin bypass
+
+Sometimes a super-admin or support role needs to read across all tenants — for reporting,
+debugging, or backoffice tooling — without being confined to a single company's data.
+
+### Enabling bypass
+
+Add `bypassRoles` to `TenantOptions`. Any caller whose `auth.roles` **or** `auth.permissions`
+matches at least one entry is granted an unscoped read:
+
+```ts
+createExpressCrudRouter(resources, {
+  tenant: {
+    resolveId: ({ auth }) => auth.claims?.companyId,
+    bypassRoles: ['super_admin', 'support:read-all'],
+  }
+})
+```
+
+Values are matched against both `auth.roles` and `auth.permissions` — either paradigm works.
+
+### What bypass does (and does not do)
+
+| Operation | Behaviour with bypass |
+| --- | --- |
+| `GET /resource` — list | Returns rows from **all** tenants (unscoped) |
+| `GET /resource/:id` | Returns the record regardless of which tenant owns it |
+| `POST /resource/query` (query builder) | Returns rows from all tenants |
+| `POST /resource` (create) | **Not bypassed** — tenant value still comes from `resolveId` |
+| `PATCH`, `PUT`, `DELETE` | **Not bypassed** — tenant value still comes from `resolveId` |
+
+Writes are deliberately excluded. Tenant on writes comes from the authenticated session —
+never from the client and never from the bypass path. An admin writing through the API either has a `companyId` in their token (and writes to that company) or receives 403.
+
+### Narrowing a bypass read to one tenant
+
+When a super-admin wants data for a specific company they use the **normal filter mechanism**
+— the tenant field is just another filterable column from their perspective. No special header or query parameter is needed:
+
+```
+# All tenants (bypass active, no filter)
+GET /orders
+
+# One specific tenant
+GET /orders?companyId=42
+```
+
+In GraphQL:
+
+```graphql
+# All tenants
+{ listOrders { count results { id companyId total } } }
+
+# One tenant
+{ listOrders(filter: { companyId: 42 }) { count results { id companyId total } } }
+```
+
+### Per-resource bypass override
+
+`ResourceDefinition.bypassTenantRoles` overrides the global `bypassRoles` for one resource.
+Set it to `[]` to prevent bypass on a particularly sensitive model:
+
+```ts
+const resources = [
+  {
+    routePrefix: 'orders',
+    repository: orderRepo,
+    // inherits bypassRoles from TenantOptions → super_admin gets all
+  },
+  {
+    routePrefix: 'payment-methods',
+    repository: paymentRepo,
+    bypassTenantRoles: [],           // always scoped — even super_admin sees only their tenant
+  },
+  {
+    routePrefix: 'users',
+    repository: userRepo,
+    bypassTenantRoles: ['super_admin'],  // only super_admin bypasses; support:read-all does not
+  }
+]
+```
+
 ## Security model
 
 Tenant scoping is designed to **fail closed**. The guarantees:

package/README_OPENAPI.md

@@ -240,7 +240,7 @@ The body combines `QueryOptions` fields (to select records) with an `update` key
 
 ```json
 {
-  "where": [{ "field": "status", "comparison": "=", "value": "draft" }],
+  "where": [{ "field": "status", "comparison": "=", "value1": "draft" }],
   "update": { "status": "archived" }
 }
 ```
@@ -274,17 +274,17 @@ The query builder endpoint accepts a `QueryOptions` body for full-featured filte
 ```json
 {
   "where": [
-    { "field": "published", "comparison": "=", "value": true },
-    { "field": "createdAt", "comparison": ">=", "value": "2024-01-01T00:00:00Z" },
+    { "field": "published", "comparison": "=", "value1": true },
+    { "field": "createdAt", "comparison": ">=", "value1": "2024-01-01T00:00:00Z" },
     {
       "operator": "OR",
       "children": [
-        { "field": "title", "comparison": "CONTAINS", "value": "Halifax" },
-        { "field": "title", "comparison": "STARTS WITH", "value": "Hello" }
+        { "field": "title", "comparison": "CONTAINS", "value1": "Halifax" },
+        { "field": "title", "comparison": "STARTS WITH", "value1": "Hello" }
       ]
     }
   ],
-  "orderBy": [{ "field": "createdAt", "direction": "desc" }],
+  "orderBy": [{ "field": "createdAt", "order": "DESC" }],
   "limit": 20,
   "offset": 0,
   "fields": ["id", "title", "createdAt"],
@@ -318,12 +318,12 @@ Flat `where` arrays use **AND-precedence over OR** (same as SQL). Use `children`
 ```json
 {
   "where": [
-    { "field": "active", "comparison": "=", "value": true },
+    { "field": "active", "comparison": "=", "value1": true },
     {
       "operator": "OR",
       "children": [
-        { "field": "role", "comparison": "=", "value": "admin" },
-        { "field": "role", "comparison": "=", "value": "moderator" }
+        { "field": "role", "comparison": "=", "value1": "admin" },
+        { "field": "role", "comparison": "=", "value1": "moderator" }
       ]
     }
   ]

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

@@ -68,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) {
@@ -237,6 +239,12 @@ export class DrizzleAdapter {
         }
     }
     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);
@@ -285,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