fastify-auto-sqlapi 0.2.1 → 0.2.3

package/BREAKING_CHANGES.md

@@ -1,5 +1,7 @@
 # Breaking Changes — Join API redesign
 
+*Landed in **0.1.3**.*
+
 The join API was rewritten to be explicit, alias-based, and to add a real `LEFT JOIN` mode (`joinLeft`) for N:1 relationships. **No backward compatibility** — old names are rejected with 400. Both backend (table configuration) and frontend (request/response shapes) are affected. This document is the single source of truth for migrating either side.
 
 ## Why this changed
@@ -265,6 +267,8 @@ The engine rejects, with `statusCode: 400`, any of:
 
 # Breaking Change — computed field placeholders use `?` markers
 
+*Landed in **0.1.6**.*
+
 `ComputedFieldExpr.expr` must now mark each bound value with `?`. The engine assigns the
 placeholder positions. Writing `$1` (or `db.ph(n)`) inside the expression no longer works and
 is rejected with a descriptive error.
@@ -320,6 +324,8 @@ values in the parameter order.
 
 # Breaking Change — by-single-id operations disabled for composite primary keys
 
+*Landed in **0.1.11**.*
+
 Since **0.1.11**, tables whose `primary` is an array of more than one field no longer expose
 the operations that address a record by a single PK value:
 
@@ -385,6 +391,8 @@ endpoints previously behaved correctly for you — they are now gone and you mus
 
 # Breaking Change — unknown filter keys are rejected
 
+*Landed in **0.1.14**.*
+
 `filters` keys that match nothing are now a `400`, on the main table and on every join family.
 Previously they were dropped without a word.
 
@@ -458,8 +466,103 @@ delegates to the target's own `filters()` and does run `extendedCondition`.
 
 ---
 
+# Breaking Change — request limits, condition arity and tenant scope inside subqueries
+
+*Landed in **0.2.0**.*
+
+## Why this changed
+
+Four ways a single search request could do more than the plugin admitted, and one where the
+declared scope was not the enforced one.
+
+- `maxItemsPerPage` bounds the **rows a search returns**, not the work done to find them. Every
+  dotted `conditions` entry and every 3-part `orderBy` token becomes its own correlated subquery,
+  so an uncapped list turned one request into arbitrarily many.
+- `paginator.page` and `paginator.itemsPerPage` are rendered straight into `LIMIT`/`OFFSET`.
+  `Paginator` is a compile-time type only, and `sqlApi.search()` is a documented public API a
+  consumer may hand an unvalidated querystring — the integer check has to exist at runtime.
+- `key in map` and `map[key]` walk `Object.prototype`, so `constructor`, `toString`, `valueOf`,
+  `hasOwnProperty` and `__proto__` satisfied every "is this a known field" check and reached the
+  SQL builders, where they rendered as `undefined` or as a column that does not exist.
+- A condition method was dispatched with whatever `params` carried. A missing or wrongly shaped
+  one threw a `TypeError` inside the builder, which the error handler can only report as a 500.
+- `tenantScope` was applied to the main query and to the tables a request addressed directly. The
+  subqueries and child writes the same request produced carried no scope, so a scoped table was
+  still readable and writable through its own relations.
+
+## What changed
+
+Every row below answers **400** where it previously did something else.
+
+| Input | Rule now | Before |
+|---|---|---|
+| `conditions` | at most **100** entries, per section (top level and each join family) — schema `maxItems` plus an engine backstop | unbounded |
+| `orderBy` | at most **20** comma-separated parts; the request schema also caps the string at **1024** characters | unbounded |
+| `paginator` | `page` and `itemsPerPage` must both be integers `>= 1`, checked before any query runs | any value, rendered into `LIMIT`/`OFFSET` as-is |
+| condition `params` | must be an array; single-value methods need 1 entry, `isBetween`/`isNotBetween` 2, `isIn`/`isNotIn` an array as the first entry | passed to the builder as-is → `TypeError` → 500 |
+| field names | inherited `Object.prototype` keys are not fields, in `filters`, condition fields, `orderBy` and `selectComputed` | resolved as known fields and reached the SQL |
+
+The two caps are exported as `MAX_CONDITIONS` and `MAX_ORDER_BY_PARTS`. Both checks live in the
+**engine**, not in the route, which is what covers `sqlApi.search()` — no schema validates a
+programmatic caller. `isNull`/`isNotNull` still take no params, and an explicit `undefined` handed
+to `isIn` remains the documented no-op.
+
+And `tenantScope` now follows the request into everything it touches:
+
+- **secondaries** — a child row written alongside a main row is scoped and anchored by the child
+  table's own `tenantScope`;
+- **`joinLeft`** — the predicate lands in the `ON` clause, so `LEFT` semantics survive;
+- **`joinGroup` aggregation subqueries**, and the 3-part aggregation `orderBy` built on them —
+  they counted and summed every tenant's child rows, which disagreed with the scoped
+  `result.joinGroup` for the same alias and leaked the existence of the rest.
+
+## Who is affected
+
+- **A client that sends more than 100 `conditions` or more than 20 `orderBy` parts.** Generated
+  filter UIs are the realistic case: a "select all" that emits one condition per row.
+- **A caller that forwards a raw querystring to `sqlApi.search()`.** `itemsPerPage: '10'` is a
+  string and is now a 400: parse the querystring before you forward it.
+- **Conditions assembled programmatically.** One built with a missing `params` used to reach the
+  builder; it is now refused up front, with the method named.
+- **Any deployment using `tenantScope` with `secondaries`, `joinLeft` or `joinGroup`.**
+  Aggregates that used to count across tenants return smaller numbers, and an ordering built on
+  them changes with it. A secondary write that used to land in another tenant's rows is now
+  refused. This is the fix, not a regression — but a dashboard whose numbers were computed
+  cross-tenant will move.
+
+Not affected: requests within the caps, a well-formed integer `paginator`, and any deployment
+without `tenantScope`.
+
+## Migration
+
+Split an oversized `conditions` list rather than raising anything — the caps are not configurable:
+
+```typescript
+// Before: one request with 400 conditions
+{ conditions: ids.map((id) => ({ field: 'id', method: 'isEqual', params: [id] })) }
+
+// After: one condition, one bound array
+{ conditions: [{ field: 'id', method: 'isIn', params: [ids] }] }
+```
+
+Parse a querystring before it reaches `sqlApi.search()`:
+
+```typescript
+const paginator = {
+  page: Number.parseInt(req.query.page ?? '1', 10),
+  itemsPerPage: Number.parseInt(req.query.itemsPerPage ?? '50', 10),
+};
+```
+
+Then re-read any number your product computes from `joinGroup`: if it was collected under a
+tenant scope, it was counting rows that tenant cannot see, and it changes with this release.
+
+---
+
 # Breaking Change — the tenant follows the request, not the table it addresses
 
+*Landed in **0.2.1**.*
+
 `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
@@ -536,3 +639,56 @@ 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.
+
+---
+
+# Breaking Change — secondaries run the child table's `beforeInsert`
+
+*Landed in **0.2.2**.*
+
+## Why this changed
+
+`processSecondaries` consulted the child table's configuration for its `excludeFromCreation` and
+its `tenantScope`, but skipped its `beforeInsert`. A child table whose hook *transformed* a value
+rather than adding one — encrypting a column, normalising a unit — therefore stored the raw
+client value whenever its rows arrived as another table's secondaries, and correctly only through
+its own route. Nothing failed at write time; the row read back as garbage later. See
+[ADR 0014](./docs/adr/0014-what-follows-a-write-join.md).
+
+## What changed
+
+- A child table's **`beforeInsert` now runs** for rows written as `secondaries`, after that
+  table's `excludeFromCreation` strip and before the engine's FK auto-fill (which stays
+  authoritative). The child's `validate` and `afterInsert` still do not run.
+- The **get response schema honours `readExclude`**: it previously advertised fields the engine
+  never selects. `schemaOverrides` is unchanged — still write bodies only.
+- The **update body now requires the primary key**. It identifies the row (`PUT /rest/:table`
+  carries it in `main`), but the generated PK field is `Optional` and that modifier reached the
+  update body unchanged, so a request omitting `main.id` built its `WHERE` on `undefined`
+  instead of being rejected with a 400.
+
+## Who is affected
+
+- **A table of yours declares `beforeInsert` and is also a write-join target.** The hook now runs
+  on that path. If it was written assuming the table's own route — reading `req.params`, counting
+  invocations, calling an external service per record — it now runs where it did not before. It
+  receives the transaction connection, so what it writes rolls back with the host's write.
+- **You send an update without `main.<pk>`.** It never identified a row — the `WHERE` was built
+  on `undefined` — and is now a 400.
+- **A client of yours read a `readExclude`d field out of the get route's Swagger.** It was never
+  returned; only the documentation claimed it.
+
+Not affected: tables with no `beforeInsert`, or none that are write-join targets. Nothing about
+`schemaOverrides` changes.
+
+## Migration
+
+For a `beforeInsert` that must keep running on the table's own route only, guard on the context
+it needs rather than on the path:
+
+```typescript
+beforeInsert: async (db, req, record) => {
+  record.slug = slugify(record.name);           // shaping: correct on both paths, leave it
+  if (req.routeOptions?.url?.startsWith('/rest/')) await notify(record);  // side effect: narrow it
+},
+```

package/CHANGELOG.md

@@ -7,7 +7,179 @@ All notable changes to this project are documented here. This project follows
 
 Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)**.
 
-## [Unreleased]
+## [0.2.3]
+
+### Fixed
+
+- **MySQL read every default *expression* as a database-computed column.** The generator
+  matched `information_schema.columns.EXTRA` on the substring `generated`, and MySQL writes
+  `DEFAULT_GENERATED` there for **any** column whose default is an expression —
+  `DEFAULT CURRENT_TIMESTAMP` above all, but also `DEFAULT (UUID())`, `DEFAULT (CURRENT_DATE)`,
+  a JSON default. Every one of those columns came out of `sqlapi-generate-schema` listed under
+  `generatedFields`, which the runtime strips from the insert, update and bulk-upsert bodies and
+  again inside the engines: the column stopped being writable, silently, with no error anywhere —
+  a client sending it had the value dropped and read back whatever the default had produced. On a
+  schema that timestamps its tables, that is every table. Only `GENERATION_EXPRESSION` separates
+  the two cases — it is non-empty for a real `GENERATED ALWAYS AS (<expr>)` column and empty for a
+  default expression — and it is now what the flag reads, with the `EXTRA` markers
+  (`VIRTUAL GENERATED`, `STORED GENERATED`, `PERSISTENT GENERATED`) kept as a fallback for a
+  server or driver that does not return it. MySQL and MariaDB only; PostgreSQL was never
+  affected. **Regenerate your schemas** (`sqlapi-generate-schema`) to get the columns back.
+
+- **The agent manifest's markdown never rendered `readOnly`.** The JSON manifest has carried the
+  flag since 0.2.2, but `/agent/manifest.md` — the rendering built to go into a system prompt —
+  dropped it, so the one consumer that reads the markdown, a model, kept putting non-writable
+  columns in write payloads and kept having them dropped. The notation now carries `(readOnly)`
+  alongside `(writeOnly)`, and the legend explains it.
+
+- **`ApiRequest` was documented as exported and was not.** [ADR 0018](./docs/adr/0018-one-seam-to-the-http-framework.md)
+  and the 0.2.2 entry below both say the type is exported from the package; `src/index.ts` never
+  re-exported it, so a consumer typing a hook or a `getTenantId` against it had to import from a
+  `dist/` internal path. It is now part of the public type exports.
+
+- **The upsert conflict guard failed open on a `NULL` owner in single-column tenant scopes.**
+  `col NOT IN (...)` evaluates to `NULL`, not `TRUE`, when the column is `NULL`, so a conflicting
+  row belonging to nobody slipped past the probe and could be claimed and overwritten by any
+  tenant's upsert. The single-column branch now reads `(col IS NULL OR col NOT IN (...))` —
+  an unowned row is foreign — which is what the `anyOf` branch and the read side already did.
+
+- **Documentation corrections.** `AGENTS_BACKEND.md` stated that programmatic `sqlApi.*` calls
+  are uncapped. The two *configurable* caps do belong to the routes (`maxItemsPerPage`,
+  `maxBulkItems` — `sqlApi.search()` takes `maxRows` for the first), but the complexity caps
+  (100 `conditions`, 20 `orderBy` parts) and the `paginator` integer guard live in the engine and
+  have always applied to `sqlApi.search()` too. `AGENTS_BACKEND.md` and `README.md` now say which
+  cap sits where, and the fixed caps are documented at all.
+
+## [0.2.2]
+
+### Added
+
+- **`ApiRequest` — one seam between the core and the HTTP framework.** The engines, the schema
+  builders and the write pipeline never read a property off the request: it arrives from the
+  route, is forwarded to `getTenantId`, `validate` and the hooks, and is otherwise untouched. That
+  dependency was spread over thirteen files as a `FastifyRequest` type import; it is now declared
+  once in `src/types/request.ts` and exported from the package. `ApiRequest` *is* `FastifyRequest`,
+  so nothing changes for consumers — hooks keep their exact types. A new dependency-cruiser rule
+  fails the build on a `fastify` import (type-only included) anywhere under `src/lib/`,
+  `src/types/` or `src/bin/` but that file, and the two Fastify bridge helpers that lived in
+  `lib/` (`setupSwagger`, the `sqlApi` decorator) moved to `src/routes/` so the rule needs no
+  exceptions. See [ADR 0018](./docs/adr/0018-one-seam-to-the-http-framework.md).
+
+- **Views are supported explicitly, and PostgreSQL materialized views at all.** A view was
+  already usable — both introspections read `information_schema.columns`, which lists view
+  columns like any other — but the generator treated it as a base table and **invented a
+  primary key from the column types**: on an aggregating view that takes a count as the key,
+  and `get/:id`, `update` and `delete` then address rows by it, silently. Introspection now
+  reports `is_view` on both engines, the generated Schema carries `isView`, and the table
+  generator refuses to guess: it uses `id` when the view has one and says the key was *inferred,
+  not read from the database*, and otherwise writes a `TODO_pick_a_unique_column` placeholder
+  with `operations: ['search']` and a real `defaultOrder` — a config that works as generated,
+  since search never reads the primary key. Writes start off in the template but are **not**
+  blocked at runtime: a view the engine can make updatable is a legitimate projection layer.
+  PostgreSQL **materialized views** are now introspected from `pg_catalog`; they are absent from
+  `information_schema` and were being skipped without a word. `sqlapi-generate-schema` prints
+  the views it found and the assumptions it had to make. See
+  [ADR 0016](./docs/adr/0016-a-view-is-a-table-config.md).
+
+- **Columns the database computes are no longer offered as writable.** A
+  `GENERATED ALWAYS AS (<expr>)` column — PostgreSQL STORED, MySQL VIRTUAL or STORED — is
+  rejected by both engines when a write so much as names it, and the whole statement fails.
+  The plugin used to advertise those columns as ordinary writable fields, so a client sending
+  back what a read had just returned got a `500` for a payload nobody could have made valid.
+  `sqlapi-generate-schema` now detects them and records them in the generated Schema's
+  `generatedFields`; the runtime drops them from the insert, update and bulk-upsert bodies
+  (main and secondaries) and again inside the engines, which `sqlApi.*` reaches without those
+  schemas. **Regenerating the Schema files is enough** — the exclusion does not live in the
+  `Table*.ts` the generator never overwrites. The CLI also prints the columns it found, per
+  table, since a generated source file is not always read. See
+  [ADR 0015](./docs/adr/0015-non-writable-columns.md).
+
+- **`writeExclude` on `defineTable`** — the write-side counterpart of `readExclude`, for the
+  non-writable columns introspection cannot know about (one a trigger owns, one a migration is
+  about to drop). Reads are untouched: the field stays projected, filterable and orderable. It
+  runs **after** the write hooks, unlike `excludeFromCreation` which is sanitized before them
+  (ADR 0005): a hook cannot put back a value the database will refuse. `defineTable` rejects an
+  unknown field, the primary key, and a field that is also `readExclude`d. It is static and
+  applies to everyone — a rule that depends on *who* is asking is still product logic (ADR 0004).
+
+- **The agent manifest marks non-writable fields** `readOnly`, alongside the existing
+  `writeOnly` for `readExclude`.
+
+- **`afterRead` — the read-side hook.** The counterpart of `beforeInsert`/`beforeUpdate`, for
+  turning a stored representation back into the API one: decrypting a column, unpacking a blob,
+  rescaling a unit. Called **once per result set** with camelCase rows mutated **in place** and
+  awaited, so a hook that calls a remote KMS gets one invocation per page instead of one per row.
+  Declared on the table that **owns** the column and it follows a join: the hook runs wherever
+  that table's rows surface — `get`, `search`, and a `joinMultiple`/`joinLeft` declared on
+  another table, with `ctx.source` and `ctx.alias` saying which — so a relation elsewhere needs
+  no extra wiring, the way `readExclude` and `tenantScope` already work (ADR 0010). It does not
+  run on `joinGroup` (aggregates, not table rows) nor on an empty result, and rows cannot be
+  added or removed: the pagination `COUNT` has already run. On the main table it runs *after* the
+  join side queries, which correlate on the values the database returned, so a hook rewriting the
+  column a relation joins on cannot break the correlation. `SearchParams`/`GetParams` now carry
+  the optional `request`, which `sqlApi.search()`/`sqlApi.get()` forward when given one.
+
+### Changed
+
+- **The update body requires the primary key**, which identifies the row it updates
+  (`PUT /rest/:table` carries it in `main`). The generated PK field is `Optional` — it is
+  absent on insert — and that modifier reached the update body unchanged, so a request omitting
+  `main.id` built its `WHERE` on `undefined` instead of being rejected. The code comment said
+  "PK required" all along.
+
+- **A secondary now runs the child table's `beforeInsert`.** `processSecondaries` already applied
+  the child's `excludeFromCreation` and its `tenantScope` but skipped its `beforeInsert`, so a
+  table whose hook *transformed* a value — encrypting a column, normalising a unit — stored the
+  raw client value whenever its rows arrived as another table's children, and the correct one
+  through its own route. Nothing failed at write time; the row read back as garbage later. The
+  hook runs after the exclusion strip and before the engine's FK auto-fill, which stays
+  authoritative, and receives the transaction connection. The child's `validate` and
+  `afterInsert` deliberately still do not run — see
+  [ADR 0014](./docs/adr/0014-what-follows-a-write-join.md). **Breaking** for a `beforeInsert`
+  written assuming it only ever ran on its own table's route.
+
+- **The get response schema honours `readExclude`**, like the search response already did; it
+  previously advertised fields the engine never selects. It now lives in `lib/schema/get.ts`
+  (`GetTableResponse`) instead of inline in the route, which is how it had drifted.
+  `schemaOverrides` stays where it was — write bodies only: an override rules what the API
+  accepts from now on, while the rows already stored predate it, so narrowing the response
+  would promise something no one can retroactively make true.
+
+### Fixed
+
+- **A `tenantScope` naming a schema field instead of a column now fails at startup.**
+  `tenantScope` names real DB columns — the scope is applied to the SQL, after the payload has
+  been converted, and `through.foreignField` belongs to a parent table that may have no config of
+  its own. Nothing checked it, so writing `organizationId` where the column is `organization_id`
+  passed `defineTable` and surfaced as `column "organizationId" does not exist` on every request
+  to the table: an opaque `500`, failing closed but saying nothing. All four positions are now
+  checked (`column`, each `anyOf` entry, `through.localField`, and `through.foreignField` against
+  the parent schema). The check is narrow by design — it fires only when the name *is* a schema
+  field whose column differs, so a column absent from the schema raises nothing and a camelCase
+  database, where `col()` is the identity, raises nothing either.
+
+- **The `no-static-optional-peer` gate had never been able to fire.** `includeOnly: '^src/'` in
+  `.dependency-cruiser.mjs` dropped every npm edge from the dependency graph, so the rule meant to
+  stop a static import of `pg` / `mysql2` / `@fastify/*` — which breaks installs that use the other
+  dialect — matched nothing, ever. The graph now keeps npm dependencies as leaves, and the rule is
+  qualified to what its name says: static, value-level imports only, since a type-only import is
+  erased at compile time and a dynamic one is what the rule asks for. Both gates were verified by
+  introducing a violation and watching them fail.
+
+- **`defineTable` never validated `primary`.** A primary key naming a field the schema does not
+  have passed startup untouched and became a raw SQL error on the first request — a `500`. It
+  now throws at `defineTable` time, naming the field and the operations that need it. The one
+  exception is exact: a table exposing only `search` and declaring its own `defaultOrder` never
+  reads `primary`, which is the shape generated for a view whose key could not be inferred.
+
+- **PostgreSQL identity columns made a table impossible to insert into.**
+  `GENERATED ... AS IDENTITY` reports no `column_default`, which is what the generator read to
+  decide that the database fills a column in — so the primary key came out **mandatory** in the
+  write body while PostgreSQL rejected any explicit value for it (`Column "id" is an identity
+  column defined as GENERATED ALWAYS`). Identity columns are now flagged like MySQL's
+  `AUTO_INCREMENT`: the field is Optional and the CLI lists it under `excludeFromCreation`.
+
+## [0.2.1]
 
 ### Added
 
@@ -28,6 +200,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
   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.
 
@@ -48,6 +221,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
   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
@@ -68,6 +242,93 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
   controlled) rather than the response body (not, and these routes are open by default). See
   [ADR 0013](./docs/adr/0013-sanitized-db-errors.md).
 
+## [0.2.0]
+
+### Added
+
+- `QueryClient.update` and `QueryClient.delete` take an optional trailing `extraCondition`
+  (a `ConditionBuilder`) merged into the `WHERE` with its values bound in order — how the tenant
+  row guard reaches a write. Additive.
+
+### Changed
+
+- **BREAKING: `conditions` and `orderBy` are capped.** `maxItemsPerPage` bounds the rows a
+  search returns, not the work done to find them: every dotted `conditions` entry and every
+  3-part `orderBy` token becomes its own correlated subquery, so an uncapped list turned one
+  request into arbitrarily many. `conditions` now takes at most **100** entries per section — the
+  top level and each join family — and `orderBy` at most **20** comma-separated parts; over
+  either, the answer is a **400**. The request schemas carry the same numbers (`maxItems`, plus a
+  1024-character cap on the `orderBy` string), so Swagger advertises exactly what the engine
+  enforces. Both are exported as `MAX_CONDITIONS` and `MAX_ORDER_BY_PARTS`, and both are checked
+  **in the engine**, which is what covers `sqlApi.search()` — no schema validates a programmatic
+  caller. See [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--request-limits-condition-arity-and-tenant-scope-inside-subqueries).
+
+- **BREAKING: `paginator` is validated at runtime.** `page` and `itemsPerPage` are rendered
+  straight into `LIMIT`/`OFFSET`, and `Paginator` is a compile-time type only: nothing stopped a
+  string, a fraction, a zero or a `NaN` — or a SQL fragment, on the documented path where a
+  consumer hands `sqlApi.search()` an unvalidated querystring. Both must now be integers `>= 1`,
+  checked before any query runs; anything else is a **400**. A numeric *string* (`itemsPerPage:
+  '10'`) is rejected too, so a querystring must be parsed before it is forwarded.
+
+- **BREAKING: a malformed condition `params` answers 400 instead of 500.** The method was
+  dispatched with whatever `params` carried, so a missing or wrongly shaped one threw a
+  `TypeError` inside the builder — which the error handler could only report as an
+  `Internal Server Error`. Arity is now checked once, at dispatch, for every call site:
+  `params` must be an array, the single-value methods need one entry, `isBetween`/`isNotBetween`
+  need two, and `isIn`/`isNotIn` need an array as their first entry. `isNull`/`isNotNull` still
+  take none, and an explicit `undefined` to `isIn` stays the documented no-op.
+
+- **BREAKING: inherited `Object.prototype` keys are no longer field names.** `key in map` and
+  `map[key]` walk the prototype chain, so `constructor`, `toString`, `valueOf`, `hasOwnProperty`
+  and `__proto__` satisfied every "is this a known field" check and reached the SQL builders,
+  where they rendered as `undefined` or as a column that does not exist. Every allowlist and every
+  field lookup in the search engine now tests own properties, so an inherited name is simply
+  unknown — a **400** in `filters`, condition fields, `orderBy` and `selectComputed`.
+
+- **BREAKING: `tenantScope` reaches the subqueries and the child writes of a request.** The
+  scope was applied to the main query and to the tables addressed directly, and nowhere else, so
+  the same request could still read and write other tenants' rows through its own joins:
+  **secondaries** were written without the child table's scope, **`joinLeft`** embedded the parent
+  unscoped, and the **`joinGroup` aggregation subqueries** — with the 3-part aggregation
+  `orderBy` built on them — counted and summed every tenant's child rows, disagreeing with the
+  scoped `result.joinGroup` for the same alias and leaking the existence of the rest. All four
+  now carry the scope of the table they touch; on `joinLeft` the predicate lands in the `ON`
+  clause, so `LEFT` semantics survive. Aggregates that used to count across tenants return
+  smaller numbers, and an ordering built on them changes with it.
+
+### Internal
+
+- The quality gates became executable and zero-tolerance (eslint, jscpd, knip,
+  dependency-cruiser, lefthook, CI), `search.ts` was split into seven layered modules with an
+  acyclic graph, and `docs/INDEX.md` plus `npm run find-similar` were added as the anti-duplication
+  surface. No runtime behaviour changes with any of it. See
+  [ADR 0012](./docs/adr/0012-anti-duplication-tooling.md).
+
+## [0.1.14]
+
+### Added
+
+- **`fields` allowlist on `buildRelation`** — restricts which of the target table's fields are
+  reachable through one relation, without hiding them from the table's own routes the way
+  `readExclude` would. The relation is declared against a schema narrowed to the list, so
+  `selection`, `filters`, `conditions`, `orderBy`, aggregations and the generated
+  request/response schemas all reject anything outside it with `400 Unknown field`; the default
+  `'*'` selection is spelled out into the allowed columns instead of emitting a real `SELECT *`;
+  and computed fields on the target resolve against the narrowed schema, so one reading an
+  excluded column is a 400 rather than a way around the list. Declaration-time checks: the list
+  must include the join field, and is rejected on `allowedWriteJoins` (write paths resolve
+  `upsertMap` by schema identity and must write every column the caller sent). Fail-closed by
+  design — see [ADR 0011](./docs/adr/0011-join-fields-allowlist.md) for allowlist vs blocklist.
+
+- **[ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md)** — a declared join is a read
+  grant: `onRequests` and `operations` are route-level and do not follow a join, so
+  `allowedReadJoins` grants read access to the target table under the *host* table's
+  authorization. Documents what does cross a join (`readExclude`, `tenantScope`, the relation's
+  schema), the trimmed-schema + explicit-`selection` pattern for column-level narrowing, and
+  the rejected alternatives (`canBeJoined` hook, `selection` as a ceiling).
+
+### Changed
+
 - **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
@@ -77,6 +338,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
   covers `sqlApi.search()` as well as the HTTP routes. `undefined` values still mean "filter
   not supplied" and are ignored; an explicit `null` still filters by `IS NULL`. See
   [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--unknown-filter-keys-are-rejected).
+
 - **`joinLeft.<alias>.filters` no longer advertises the parent's `extraFilters`.** They were
   present in the generated body schema and in Swagger, but `buildLeftJoinClauses` never runs
   the target's `extendedCondition` (its column references cannot be qualified with the
@@ -93,25 +355,9 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
   filters are now validated up front, and the selection and aggregation lists are resolved
   before the empty-result bail-out.
 
-### Added
+## [0.1.13]
 
-- **`fields` allowlist on `buildRelation`** — restricts which of the target table's fields are
-  reachable through one relation, without hiding them from the table's own routes the way
-  `readExclude` would. The relation is declared against a schema narrowed to the list, so
-  `selection`, `filters`, `conditions`, `orderBy`, aggregations and the generated
-  request/response schemas all reject anything outside it with `400 Unknown field`; the default
-  `'*'` selection is spelled out into the allowed columns instead of emitting a real `SELECT *`;
-  and computed fields on the target resolve against the narrowed schema, so one reading an
-  excluded column is a 400 rather than a way around the list. Declaration-time checks: the list
-  must include the join field, and is rejected on `allowedWriteJoins` (write paths resolve
-  `upsertMap` by schema identity and must write every column the caller sent). Fail-closed by
-  design — see [ADR 0011](./docs/adr/0011-join-fields-allowlist.md) for allowlist vs blocklist.
-- **[ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md)** — a declared join is a read
-  grant: `onRequests` and `operations` are route-level and do not follow a join, so
-  `allowedReadJoins` grants read access to the target table under the *host* table's
-  authorization. Documents what does cross a join (`readExclude`, `tenantScope`, the relation's
-  schema), the trimmed-schema + explicit-`selection` pattern for column-level narrowing, and
-  the rejected alternatives (`canBeJoined` hook, `selection` as a ceiling).
+### Added
 
 - **`excludeTables` config option** — blacklist for `sqlapi-generate-schema`. Tables
   listed in `excludeTables` in `sqlapi.config.ts` (exact names or `*` globs, e.g.