fastify-auto-sqlapi 0.1.14 → 0.2.1

package/AGENTS_BACKEND.md

@@ -275,6 +275,8 @@ export const TableCustomer = defineTable({
   //   column: 'organization_id',
   //   through: { schema: SchemaCustomer, localField: 'customerId', foreignField: 'id' },
   // },
+  // OR anyOf: several owner columns, the row is visible to any of them
+  // tenantScope: { anyOf: ['requester_agent_id', 'target_agent_id'] },
 
   // SCHEMA OVERRIDES — tighten auto-generated schema validation without editing Schema files
   schemaOverrides: {
@@ -462,7 +464,7 @@ export const TableCustomer = defineTable({
 
 ## Computed Fields (extension system)
 
-`computedFields` lets you declare **virtual fields** as SQL expressions on a per-table basis. Each computed becomes usable like a regular schema field across the search API: `filters` (equality), `conditions` (operators), `orderBy` (1-parte), `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main response. Same machinery serves JSON column extraction, derived strings, dialect-aware date/calendar bucketing — without growing the library case-by-case.
+`computedFields` lets you declare **virtual fields** as SQL expressions on a per-table basis. Each computed becomes usable like a regular schema field across the search API: `filters` (equality), `conditions` (operators), `orderBy` (1-part), `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main response. Same machinery serves JSON column extraction, derived strings, dialect-aware date/calendar bucketing — without growing the library case-by-case.
 
 ```typescript
 import { defineTable, exportTableInfo, Type } from 'fastify-auto-sqlapi';
@@ -546,7 +548,7 @@ For `joinLeft` specifically, the computed expr is automatically alias-prefixed b
 
 - **Bound `values` in computed expressions** work anywhere the expression lands in the `WHERE` clause or in `ORDER BY`: `filters` and `conditions` (main, `joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`) and `orderBy`. The ConditionBuilder assigns the placeholder positions there, so no coordination is needed from the caller.
 - They are still rejected with 400 on `selectComputed`, `computeMin/Max/Sum/Avg`, `joinGroup.aggregations.by` and `defaultOrder`. Those expressions are emitted in the `SELECT` / `GROUP BY` list, which precedes the `WHERE` values in the parameter order — there is no correct position for them there. Most use cases (JSON extraction, concat, dateTrunc, simple ops) need no bound values at all.
-- **Computed CAN be used in `joinGroup.aggregations.by`** (just pass the computed name as a string). Bound `values` are not supported in this position (rejected with 400 — it is emitted in the `SELECT`/`GROUP BY` list). The existing FK-correlation rule for `orderBy <alias>.<fn>.<field>` still applies: 3-parti aggregation orderBy on a `by` that isn't the correlation FK is rejected — by definition a computed-by produces multiple groups per main row, so this is never valid.
+- **Computed CAN be used in `joinGroup.aggregations.by`** (just pass the computed name as a string). Bound `values` are not supported in this position (rejected with 400 — it is emitted in the `SELECT`/`GROUP BY` list). The existing FK-correlation rule for `orderBy <alias>.<fn>.<field>` still applies: 3-part aggregation orderBy on a `by` that isn't the correlation FK is rejected — by definition a computed-by produces multiple groups per main row, so this is never valid.
 - **Computed cannot be used as aggregation function** (`sum`/`min`/`max`/...). The values inside `aggregations.sum: ['<name>']` must be schema field names. To aggregate on a derived expression, declare the derivation as a computed and pass the computed name as the field, BUT only via `computeMin/Max/Sum/Avg` (top-level main aggregates), not the joinGroup ones.
 - **No chained computed** (a computed referencing another computed). Flat-only.
 - **Read-only**. Computed fields are not usable in insert/update bodies — the consumer's `expr` is for SELECT/WHERE/ORDER BY, never for writes.
@@ -635,8 +637,8 @@ const sqlApi = createSqlApi(db, dbTables, { dialect: 'mysql' });
 ```typescript
 // Search — full filter, join, pagination, aggregation support
 // orderBy supports two dotted notations:
-//   - 3-parti `<alias>.<fn>.<field>` for joinGroup aggregations (must be declared in the request body)
-//   - 2-parti `<alias>.<field>` for joinLeft parent fields
+//   - 3-part `<alias>.<fn>.<field>` for joinGroup aggregations (must be declared in the request body)
+//   - 2-part `<alias>.<field>` for joinLeft parent fields
 // See AGENTS_FRONTEND.md and BREAKING_CHANGES.md for the full reference.
 sqlApi.search(tableName, {
   filters?, conditions?,
@@ -771,6 +773,46 @@ Behavior:
 - **Update**: pre-check via SELECT with INNER JOIN (404 if not found). If the payload also changes the through-FK (`localField`), the new value is re-validated against the tenant — moving a record into another tenant's scope is rejected (403).
 - **Delete**: subquery `DELETE WHERE pk IN (SELECT ... INNER JOIN ... WHERE tenant IN (...))`
 
+### Shared tenant (`anyOf`: several owner columns)
+
+For a row owned by two parties and visible to either — a message (`sender_id` / `recipient_id`),
+a transfer (`from_account_id` / `to_account_id`), a shift swap:
+
+```typescript
+const TableShiftSwapRequest = defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaShiftSwapRequest),
+  tenantScope: { anyOf: ['requester_agent_id', 'target_agent_id'] },
+});
+```
+
+Behavior:
+- **Read** (search, get, delete, bulk-delete): adds
+  `AND (requester_agent_id IN ($N) OR target_agent_id IN ($M))`. A `NULL` column does not match
+  and does not stop the other column from matching. A row with every listed column `NULL` is
+  visible to nobody but an admin.
+- **Joins**: the predicate crosses every join family — `joinMultiple`, `joinGroup`,
+  `joinMustExist`, and `joinLeft` (in the `ON` clause, alias-qualified, so `LEFT` semantics
+  survive) — exactly as a single-column scope does, including from a host table that declares no
+  scope of its own.
+- **Insert**: no auto-injection. The payload must **anchor** the row: at least one listed column
+  present and holding a tenant id → `400` if none is present, `403` if present but all foreign.
+  The other parties are stored exactly as sent. A multi-id caller is never ambiguous here,
+  because nothing is being guessed.
+- **Update**: strips **every** listed column from the `SET` — neither party can be re-assigned —
+  and adds the OR predicate to the `WHERE`. A row outside the scope answers `404`.
+- **Bulk upsert**: the anchor rule applies to every item (so an upsert must name a party even
+  when it only means to update), and the listed columns are excluded from the `DO UPDATE SET`,
+  so an upsert onto an existing row cannot take over the other party's slot. The conflict guard
+  rejects (`403`) a conflict key matching a row visible to neither party — including a row whose
+  parties are `NULL`.
+- **Secondaries**: a table with an `anyOf` scope written through another table's
+  `allowedWriteJoins` follows the same anchor rule. The parent's FK is auto-filled but is not an
+  owner, so the child payload must still name a party.
+
+Not combinable with `column` or `through` — `defineTable` throws at startup. An `anyOf` entry
+reached through a parent FK is not supported; declare the scope on the parent instead.
+
 ### Multi-tenant users
 
 ```typescript
@@ -793,8 +835,10 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 ### Error codes
 
 - **403** — Record doesn't belong to tenant, or explicit tenant value doesn't match
-- **400** — Multi-tenant user on insert without explicit tenant value (ambiguous)
-- **404** — Update with indirect tenant, record not found for this tenant
+- **400** — Multi-tenant user on insert without explicit tenant value (ambiguous), or an
+  `anyOf` write naming no owner column at all
+- **404** — Update with indirect tenant, record not found for this tenant; get/update/delete of
+  an `anyOf`-scoped row outside the scope
 
 ---
 
@@ -812,8 +856,9 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 - **All hooks and validators receive camelCase records**: `validate` and the whole hook matrix (`beforeInsert`/`afterInsert`, `beforeUpdate`/`afterUpdate`, `beforeDelete`/`afterDelete`, `beforeBulkDelete`/`afterBulkDelete`) get records keyed by schema field names (camelCase). Mutations propagate to the SQL (plugin converts to DB column format via `colMap` after the hook). The engine internally uses `snakecaseRecord(..., schema)` after user mutations to map field names to actual DB columns.
 - **Filters validation**: TypeBox schemas use `additionalProperties: false`. By default Fastify strips unknown fields silently. For 400 errors on unknown filters: `Fastify({ ajv: { customOptions: { removeAdditional: false } } })`.
 - **Write-body whitelist**: insert/update/bulk-upsert bodies (`main` + secondaries items) are `additionalProperties: false`. Unknown properties are rejected with 400 — only columns in the generated Schema (as narrowed by `schemaOverrides`/`excludeFromCreation`) can be written, so no mass assignment of unexposed columns. Trim the Schema to keep sensitive columns unwritable.
+- **Error responses**: errors the plugin raises itself are `4xx` with messages written for clients (validation, not found, tenant). Anything else — a driver constraint violation, a hook throwing without a `statusCode` — answers a fixed `{"statusCode":500,"error":"Internal Server Error","message":"Internal Server Error"}`: driver messages name tables, columns and constraints, and they stay on the server. **No status code is remapped** (a unique violation is a `500`, not a `409` — that mapping is product logic). The body carries `requestId` (the `reqId` Fastify logs on every line) so the real error is one grep away in the log, where it is also written via `request.log.error` — and attached as `err.cause`, so a consumer `setErrorHandler` can map `err.cause.code === '23505'` to `409` itself. **`exposeDebugInfo: true` is the only way to get the driver detail on the wire** — set it while developing, where a client building against the API cannot always read your log: the `500` then also carries `debugInfo` (`message`, `code`, `constraint`, `detail`, `stack`), additively, so the four fields above keep their production shape. Nothing else flips it: not `debug` (server-side only, and it belongs to whoever registers the plugin), not `NODE_ENV`. Errors thrown by `onRequests` hooks run before the handler and are unaffected.
 - **Request limits**: `maxItemsPerPage` (default 1000) caps the search page size and is applied as the `LIMIT` even when no paginator is sent (so an empty-body search can't dump a whole table); over-limit `itemsPerPage` → 400. `maxBulkItems` (default 1000) caps the bulk array length via schema `maxItems` → 400. Programmatic `sqlApi.*` calls are uncapped.
-- **Tenant filtering**: when `tenantScope` is set on a table and `getTenantId` is provided in plugin options, all CRUD operations are automatically scoped to the tenant. `getTenantId` returning `null`/`undefined` = admin (no filter). Returning an array = multi-tenant user (IN clause).
+- **Tenant filtering**: when `tenantScope` is set on a table and `getTenantId` is provided in plugin options, all CRUD operations are automatically scoped to the tenant. `getTenantId` returning `null`/`undefined` = admin (no filter). Returning an array = multi-tenant user (IN clause). The tenant belongs to the *request*, not to the table it addresses: a scoped table is filtered even when reached as a join target or written as a secondary of an unscoped host, so `getTenantId` must tolerate a request with no authenticated user (`req.user?.x ?? null`).
 
 ---
 

package/BREAKING_CHANGES.md

@@ -144,7 +144,7 @@ Real `LEFT JOIN` for N:1 (parent) relationships. The parent rows are returned in
 
 The engine attaches a real `LEFT JOIN <parentTable> AS <alias>` to the main query **only when needed**:
 - when the request includes `filters` or `conditions` on the parent (effectively turns into INNER JOIN behavior on those aliases — main rows whose parent doesn't match are excluded);
-- when `orderBy` uses 2-parti dotted notation referring to a parent field (`alias.field`).
+- when `orderBy` uses 2-part dotted notation referring to a parent field (`alias.field`).
 
 Otherwise only a side query `WHERE pk IN (distinct fk values)` is issued — no LEFT JOIN, no row duplication. Either way, the response shape is the same.
 
@@ -158,7 +158,7 @@ Otherwise only a side query `WHERE pk IN (distinct fk values)` is issued — no
 | `<alias>.<field>` | `joinLeft` (`unique: true` aliases) | orders main query by a parent field via LEFT JOIN |
 | `<alias>.<fn>.<field>` | `joinGroup` (declared in the same body) | orders main query by an aggregation via correlated scalar subquery |
 
-Ambiguity: 2-parti and 3-parti are disambiguated by counting dots. The 2-parti is rejected unless the alias is in `joinLeft` allowlist; 3-parti is rejected unless the alias is in the request `joinGroup` declaration.
+Ambiguity: 2-part and 3-part are disambiguated by counting dots. The 2-part is rejected unless the alias is in `joinLeft` allowlist; 3-part is rejected unless the alias is in the request `joinGroup` declaration.
 
 ## Response shape
 
@@ -248,7 +248,7 @@ If you used the join table's name as the secondaries key, change it to the new a
 
 `<table>.<fn>.<field>` still works for joinGroup, but `<table>` must now be the alias declared in `buildRelation`. If the alias differs from the old `tableName`, update the string.
 
-If you need to order by a parent field, **add a `joinLeft`-eligible relation** (with `unique: true`) and use 2-parti notation `alias.field` (NEW capability — not available before).
+If you need to order by a parent field, **add a `joinLeft`-eligible relation** (with `unique: true`) and use 2-part notation `alias.field` (NEW capability — not available before).
 
 ## Validation summary (400 responses)
 
@@ -257,8 +257,8 @@ The engine rejects, with `statusCode: 400`, any of:
 - `joinLeft` referencing an alias declared with `unique: false`
 - `joinMultiple`/`joinMustExist`/`joinGroup` referencing an alias declared with `unique: true`
 - request keys referencing an alias not declared in `allowedReadJoins`
-- `orderBy` 2-parti `<alias>.<field>` whose alias is not in `joinLeft`-eligible (i.e. `unique:true`) declarations
-- `orderBy` 3-parti `<alias>.<fn>.<field>` whose alias or `(fn, field)` pair is not declared in `joinGroup` for the same request
+- `orderBy` 2-part `<alias>.<field>` whose alias is not in `joinLeft`-eligible (i.e. `unique:true`) declarations
+- `orderBy` 3-part `<alias>.<fn>.<field>` whose alias or `(fn, field)` pair is not declared in `joinGroup` for the same request
 - `defineTable` with two `allowedReadJoins`/`allowedWriteJoins` entries resolving to the same alias (thrown at startup, not at request time)
 
 ---
@@ -455,3 +455,84 @@ returns a `400` naming the reason.
 
 Use `joinMustExist` on the same relation when you need an extra filter on the parent — that path
 delegates to the target's own `filters()` and does run `extendedCondition`.
+
+---
+
+# Breaking Change — the tenant follows the request, not the table it addresses
+
+`tenantScope` on a table is now enforced even when the request was addressed to a **different**
+table that reaches it through a relation. Previously the tenant was resolved from the addressed
+table alone: if that table declared no `tenantScope`, no predicate was applied anywhere — not to
+it, and not to the scoped tables it joined or wrote into.
+
+## Why this changed
+
+A relation in `allowedReadJoins` is a read grant on its target, and one in `allowedWriteJoins` is
+a write grant (see [ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md)). `tenantScope`
+was documented as the one request-derived protection that crosses a join — the cap that makes a
+relation safe to declare. It did not cross when the *host* was open:
+
+```typescript
+// shift is public on purpose: everyone may see who works when.
+shift: {
+  ...exportTableInfo(SchemaShift),
+  allowedReadJoins: [buildRelation(SchemaShift, 'id', SchemaSwapRequest, 'shiftId', { alias: 'swap' })],
+},
+// …but why somebody wants to change the roster is not public.
+shift_swap_request: {
+  ...exportTableInfo(SchemaSwapRequest),
+  tenantScope: { column: 'agent_id' },
+},
+```
+
+```sql
+-- POST /search/shift  { "joinMultiple": { "swap": {} } }   — before
+SELECT … FROM shift_swap_request WHERE (shift_id IN ($1))
+-- after
+SELECT … FROM shift_swap_request WHERE (shift_id IN ($1) AND (agent_id IN ($2)))
+```
+
+Every scoped row of the neighbour was readable through the open host, and writable through it as
+a secondary. The declaration said "scoped"; the deployment was not. Nothing in the response said
+so, which is the dangerous direction — the same reasoning as unknown filter keys above.
+
+## What changed
+
+- `TenantContext.scope` is now **optional**. `ids` is request-level and travels with the request;
+  `scope` is table-level and absent when the addressed table declares none. Absent `scope` means
+  "no filter on *this* table", never "no tenant" — related tables still enforce their own.
+- `getTenantId` is now called for a request addressed to an unscoped table **when one of that
+  table's declared relations points at a scoped table**. It is still not called when nothing
+  scoped is in reach, so genuinely tenant-free routes are unaffected. Reach is one level: joins
+  and secondaries resolve from the addressed table's own relations and never chain further.
+
+## Who is affected
+
+- **You declare `tenantScope` on a table that another table joins or writes into, where that
+  other table has no scope of its own.** Those requests now return fewer rows and can now answer
+  `403`. This is the fix: the rows were never yours to serve. Check any UI that displayed them.
+- **Your `getTenantId` assumes an authenticated request.** It now runs on routes that previously
+  skipped it — a public host with a scoped neighbour. A body like
+  `(request) => request.user.organizationId` throws there, turning a `200` into a `500`.
+- **You read `tenant.scope` in TypeScript** (custom routes using the exported `TenantContext`).
+  Its type is now `TenantScope | undefined`.
+
+Not affected: tables with no `tenantScope` anywhere in reach, deployments without `getTenantId`,
+admins (`getTenantId` → `null`), and every table that already declared its own scope — their SQL
+is unchanged.
+
+## Migration
+
+Make `getTenantId` total. It already had to return `null` for admins, so the null case exists:
+
+```typescript
+// Before — throws on a route that never had a user
+getTenantId: (request) => request.user.organizationId,
+
+// After — an absent user is simply an unscoped caller
+getTenantId: (request) => request.user?.organizationId ?? null,
+```
+
+Then decide, for each open table that relates to a scoped one, whether the relation was meant to
+be a read grant at all. If it was not, remove it from `allowedReadJoins` — a relation is the
+grant, and the scope is only the cap on it.

package/CHANGELOG.md

@@ -9,8 +9,65 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
 
 ## [Unreleased]
 
+### Added
+
+- **`tenantScope` over several owner columns — `{ anyOf: [...] }`.** A row that belongs to two
+  parties and is visible to either — a message (`sender_id` / `recipient_id`), a transfer
+  (`from_account_id` / `to_account_id`), a shift swap — could not be expressed before, leaving
+  the table open or the route hand-written. Reads add
+  `AND (colA IN (…) OR colB IN (…))`, alias-qualified, and the predicate crosses every join
+  family including `joinLeft`, where it lands in the `ON` clause so `LEFT` semantics survive.
+  A `NULL` column does not match and does not stop the other one from matching.
+  Writes cannot auto-inject an owner, so the payload **anchors** the row instead: at least one
+  listed column present and holding a tenant id, otherwise `400` (nothing to anchor to) or `403`
+  (present but foreign); the other party is stored exactly as sent. Updates strip every listed
+  column from the `SET`, and upserts exclude them from the `DO UPDATE` — neither party can be
+  re-assigned. The upsert conflict guard is null-safe for this shape: a row whose parties are
+  all `NULL` is visible to nobody, where a plain `NOT IN` would have read "unknown" as "not
+  foreign" and handed it over. Purely additive: `{ column }` and `{ column, through }` produce
+  byte-identical SQL. The three forms do not mix — `defineTable` throws at startup on `anyOf`
+  combined with `column` or `through`, on an empty or malformed `anyOf`, and on a scope
+  declaring no owner column at all.
+- `QueryClient.bulkInsertOrUpdate` takes an optional trailing `immutableCols`: columns written
+  on insert but left untouched when the statement lands on an existing row. Additive.
+
 ### Changed
 
+- **BREAKING: the tenant follows the request, not the table it addresses.** `tenantScope` on a
+  table is now enforced even when the request was addressed to a different table that reaches it
+  through a relation. Previously the tenant was resolved from the addressed table alone, so a
+  host declaring no scope of its own carried no predicate into the scoped tables it joined or
+  wrote into — every scoped row of the neighbour was readable through the open host, and writable
+  through it as a secondary, while the declaration said otherwise. A relation is a read grant and
+  a write join a write grant ([ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md)), and
+  `tenantScope` is documented as the cap that makes them safe to declare; it now actually is.
+  `TenantContext.scope` becomes optional — `ids` is request-level, `scope` is table-level and
+  absent means "no filter on this table", never "no tenant". `getTenantId` is now consulted for a
+  request addressed to an unscoped table when one of its declared relations points at a scoped
+  one; it is still never called when nothing scoped is in reach. Tables that already declared
+  their own scope emit unchanged SQL. Migration — including the `getTenantId` body that now needs
+  to tolerate an unauthenticated request — in
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--the-tenant-follows-the-request-not-the-table-it-addresses).
+- **Database errors no longer reach clients verbatim.** Any error escaping an auto-generated
+  route that the plugin did not raise itself now answers `{"statusCode":500,"error":"Internal
+  Server Error","message":"Internal Server Error"}` instead of the driver message, which names
+  tables, columns and constraints (`duplicate key value violates unique constraint
+  "users_email_key"`). Errors the plugin raises are deliberate `4xx` written for clients and
+  are untouched; **no status code is remapped** — a unique violation is still a `500`, per
+  [ADR 0006](./docs/adr/0006-raw-db-errors.md). The original error is logged through
+  `request.log.error` and attached as `err.cause`, so a consumer `setErrorHandler` can still
+  apply its own policy (`23505` → `409`). The guard covers route plugins registered standalone
+  as well. The sanitized body carries `requestId` — the `reqId` Fastify logs on every line — so
+  the entry holding the real error is one grep away. While developing — where a client building
+  against the API (an agent especially) may have no way to read the server log — the new
+  **`exposeDebugInfo: true`** attaches the driver error (message, `code`, `constraint`, stack)
+  as a `debugInfo` payload. It is additive: `statusCode`, `error`, `message` and `requestId`
+  keep their production shape, so client-side error handling does not fork between
+  environments. Nothing else flips it — not `debug`, not `NODE_ENV`: `debug` belongs to the
+  consumer, who may wire it to an environment variable, and it governs the log (access
+  controlled) rather than the response body (not, and these routes are open by default). See
+  [ADR 0013](./docs/adr/0013-sanitized-db-errors.md).
+
 - **Unknown `filters` keys are now rejected with `400 Unknown filter field: <key>`** instead
   of being dropped in silence — on the main table and on every join family. The engine only
   ever visited keys matching a schema field, an `extraFilters` entry or a computed field, so a

package/README.md

@@ -37,7 +37,7 @@ Writes read the same way — *"sync these clients and their tags: update the one
 
 Conflict keys are declared server-side (`upsertMap`: here customer on `email`, tag on `(customerId, tag)`), so re-sending the same payload updates rows instead of duplicating them — client-side sync without hand-written diffing.
 
-And multi-tenancy is one plugin option (`getTenantId: (req) => req.user.organizationId`), enforced on reads *and* writes with zero code in handlers. Rows of other tenants are simply invisible (`404`); here a caller in org B tries to re-point one of their own orders to a customer belonging to org A:
+And multi-tenancy is one plugin option (`getTenantId: (req) => req.user?.organizationId ?? null`), enforced on reads *and* writes with zero code in handlers. Rows of other tenants are simply invisible (`404`); here a caller in org B tries to re-point one of their own orders to a customer belonging to org A:
 
 ```jsonc
 // PUT /api/rest/order — order 7 is mine, customer 41 belongs to another tenant
@@ -368,7 +368,8 @@ await app.register(fastifyAutoSqlApi, {
 | `getTenantId` | `(req) => id \| null` | No | Tenant resolver for multi-tenant |
 | `maxItemsPerPage` | `number` | No | Max search page size, and the row `LIMIT` applied when no paginator is sent (default: `1000`) |
 | `maxBulkItems` | `number` | No | Max number of items accepted by the bulk endpoints (default: `1000`) |
-| `debug` | `boolean` | No | Log all SQL queries to console |
+| `debug` | `boolean` | No | Log all SQL queries to console (server-side only — it never changes a response) |
+| `exposeDebugInfo` | `boolean` | No | **Development only.** Attach the driver error (message, `code`, `constraint`, stack) to `500` responses as `debugInfo` (default: `false`) |
 
 The plugin picks up the connection from the Fastify instance: `fastify.pg` for PostgreSQL
 (what `@fastify/postgres` decorates) or `fastify.mysql` for MySQL/MariaDB. For MySQL,
@@ -476,6 +477,69 @@ malicious resource exhaustion — relevant precisely because the API is open by
 Both are configurable in the plugin options. The programmatic `fastify.sqlApi.*` methods are not
 capped — they run your own trusted code.
 
+### Error responses don't describe your schema
+
+Driver messages name tables, columns and constraints (`duplicate key value violates unique
+constraint "users_email_key"`). Any error the plugin did not raise itself is replaced with a
+bare `500` before it reaches the client:
+
+```json
+{ "statusCode": 500, "error": "Internal Server Error", "message": "Internal Server Error", "requestId": "req-3" }
+```
+
+`requestId` is the `reqId` Fastify logs on every line, so the entry holding the real error is
+one grep away — without the error itself travelling to the client.
+
+Errors the plugin raises are deliberate `4xx` with messages written for clients (validation,
+not found, tenant violations) and are untouched. **No status code is remapped**: a unique
+violation is still a `500`, not a `409` — deciding otherwise is product logic, and this is
+where you do it:
+
+```typescript
+app.setErrorHandler((err, request, reply) => {
+  if (err.cause?.code === '23505') {
+    return reply.status(409).send({ statusCode: 409, error: 'Conflict', message: 'Already exists' });
+  }
+  reply.send(err);
+});
+```
+
+The original error is never lost: it is logged through `request.log.error` and attached as
+`err.cause`. Errors thrown by your own `onRequests` hooks run before the handler and are
+unaffected.
+
+**While developing, you probably want the detail on the wire** — an agent or a frontend
+building against the API cannot always read your server log, and one round trip per failure
+adds up. Say so explicitly:
+
+```typescript
+await app.register(fastifyAutoSqlApi, {
+  DbTables: dbTables,
+  exposeDebugInfo: true,   // development only — see below
+});
+```
+
+```json
+{
+  "statusCode": 500, "error": "Internal Server Error", "message": "Internal Server Error",
+  "requestId": "req-3",
+  "debugInfo": {
+    "message": "duplicate key value violates unique constraint \"users_email_key\"",
+    "code": "23505", "constraint": "users_email_key", "stack": "…"
+  }
+}
+```
+
+It is **additive**: `statusCode`, `error`, `message` and `requestId` keep the shape they have
+in production, so your client-side error handling doesn't fork between environments.
+
+Nothing else flips it — not `debug`, not `NODE_ENV`. `debug` is yours to wire (a constant in
+one deployment, an environment variable in another), so the plugin cannot let it decide what
+leaves the server: it writes to your log, which is access-controlled, while a response body is
+not — and these routes are open by default. What a client sees is readable from the
+registration call alone. See [ADR 0013](./docs/adr/0013-sanitized-db-errors.md) and
+[ADR 0006](./docs/adr/0006-raw-db-errors.md).
+
 ### Write whitelist
 
 Insert/update/bulk-upsert bodies are `additionalProperties: false`: only columns present in the
@@ -590,7 +654,7 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 - **`joinMustExist`** — EXISTS-based filter: "main rows where at least one related row matches". Accepts `{ filters, conditions }` (both optional). Aliases must come from `allowedReadJoins` declarations with `unique: false`.
 - **`joinMultiple`** — fetches related child rows in a side query. Accepts `{ filters, conditions, selection }`. Same `unique: false` aliases.
 - **`joinGroup`** — aggregations on the related table. Supports `sum`, `min`, `max`, `avg`, `count`, `distinctCount`, and optional `by` for GROUP BY (a schema field name or a computed-field name declared on the join table — e.g. for date bucketing declare a computed using `db.dateTrunc('month', qiCol('orderDate'))`). Accepts `{ filters, conditions }`. Same `unique: false` aliases.
-- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-parti `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`. Its `filters` accept schema and computed fields only: the parent's `extraFilters` need an alias-aware `extendedCondition`, so they are rejected with a `400` here instead of being silently ignored — use `joinMustExist` on the same relation when you need one.
+- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-part `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`. Its `filters` accept schema and computed fields only: the parent's `extraFilters` need an alias-aware `extendedCondition`, so they are rejected with a `400` here instead of being silently ignored — use `joinMustExist` on the same relation when you need one.
 
 **Dot-notation in `orderBy` and `conditions`**:
 
@@ -717,6 +781,18 @@ Both schema-level (TypeBox/Ajv) and custom (`validate` / `validateBulk`) errors
 
 Custom validators return tuples `[field, code]` or `[field, code, message]` — `message` defaults to `code` if omitted. `validateBulk` replaces per-item `validate` in bulk-upsert requests.
 
+### Server errors (500)
+
+Anything the plugin did not raise itself — a constraint violation, a hook failing — answers
+with a fixed body carrying no database detail; `requestId` points at the log line with the
+real error. Constraint names and driver messages stay on the server unless the deployment
+opts in with `exposeDebugInfo: true`: see
+[Error responses don't describe your schema](#error-responses-dont-describe-your-schema).
+
+```json
+{ "statusCode": 500, "error": "Internal Server Error", "message": "Internal Server Error", "requestId": "req-3" }
+```
+
 ## Multi-Tenant
 
 Automatic row-level isolation on all CRUD operations. Configure once, no code in handlers.
@@ -730,6 +806,12 @@ await app.register(fastifyAutoSqlApi, {
 
 When `getTenantId` returns `null`, no filtering is applied (admin mode).
 
+The tenant belongs to the **request**, not to the table it addresses: a scoped table is filtered
+even when it is reached as a join target, or written as a secondary, of a host table that
+declares no scope of its own — a relation is a read grant, and `tenantScope` is the cap on it. So
+`getTenantId` must tolerate a request with no authenticated user; return `null` there. It is not
+called at all when neither the addressed table nor anything it relates to is scoped.
+
 ### Direct tenant (column on the table)
 
 ```typescript
@@ -753,6 +835,31 @@ defineTable({
 });
 ```
 
+### Shared tenant (several owner columns)
+
+Some rows belong to two parties and either may see them — a message (`sender_id` /
+`recipient_id`), a transfer (`from_account_id` / `to_account_id`), a shift swap. `anyOf`
+declares that shape:
+
+```typescript
+defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaShiftSwapRequest),
+  tenantScope: { anyOf: ['requester_agent_id', 'target_agent_id'] },
+});
+```
+
+Reads add `AND (requester_agent_id IN (…) OR target_agent_id IN (…))`. A `NULL` column simply
+does not match; the other party still decides. Writes cannot auto-inject an owner — the plugin
+cannot know which party the caller is — so the payload must **anchor** the row: at least one
+listed column present and holding a tenant id, otherwise `400` (nothing to anchor to) or `403`
+(present but foreign). The other party is left exactly as sent, which is the point: a swap
+request names a colleague by definition. Updates strip every listed column from the `SET` and
+upserts leave them out of the `DO UPDATE` — neither party can be re-assigned.
+
+The three forms do not mix: `defineTable` throws at startup on `anyOf` combined with `column`
+or `through`.
+
 Tables without `tenantScope` are unaffected.
 
 ### Isolation guarantees on writes