fastify-auto-sqlapi 0.1.12 → 0.1.14

package/AGENTS_BACKEND.md

@@ -357,6 +357,8 @@ buildRelation(mainSchema, mainField, joinSchema, joinField, options?)
 //   unique?: boolean;         // default false.
 //                             //   false → 1:N (child→main). Allowed in joinMustExist/joinMultiple/joinGroup.
 //                             //   true  → N:1 (parent→main). Allowed in joinLeft only.
+//   fields?: string[];        // allowlist of the target's fields reachable through this relation.
+//                             // Read joins only. Must include joinField. Everything else is 400.
 // }
 ```
 
@@ -367,6 +369,27 @@ buildRelation(mainSchema, mainField, joinSchema, joinField, options?)
 
 **When to declare an explicit `alias`**: only when (a) you join the same table multiple times in the same `allowedReadJoins`/`allowedWriteJoins`, or (b) you want a friendlier name in the public API surface than the SQL table name (e.g. `'orders'` instead of `'customer_order'`). Otherwise omit it — the default is `joinSchema.tableName`.
 
+**⚠️ A relation in `allowedReadJoins` is a read grant on the target table.** The join runs inside the query of the *host* table's route, so the target's `onRequests` never fire and its `operations` whitelist does not apply — a table with `operations: []` is still fully readable through any relation pointing at it. What does cross a join: `readExclude`, `tenantScope`, and the schema the relation was declared with.
+
+To expose a table broadly but keep some of its columns narrow, give the relation a `fields` allowlist:
+
+```typescript
+allowedReadJoins: [
+  buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true, fields: ['id', 'name'] }),
+],
+```
+
+The relation is declared against a schema narrowed to that list, so every read surface validates against it — `selection`, `filters`, `conditions`, `orderBy`, aggregations, and the generated request/response schemas. A field outside the list is `400 Unknown field` everywhere, not just missing from the projection, and the default `'*'` selection is spelled out into the allowed columns rather than emitting a real `SELECT *`.
+
+Rules, all enforced at declaration time:
+
+- **Must include the join field** — it is what correlates the fetched rows with the main ones.
+- **Not allowed on `allowedWriteJoins`** — the allowlist restricts reading only; write paths resolve `upsertMap` by schema identity and must write every column the caller sent. Declare two relations if the same pair is joined for reading and for writing.
+- **Computed fields on the target resolve against the narrowed schema** — one that reads a field outside the list is a `400`, so a computed cannot be used to reach past the allowlist. One that stays inside keeps working.
+- **Fail-closed** — a column added to the target later is not reachable through the relation until it is added to `fields`.
+
+`fields` is not a replacement for `readExclude` (which hides a column from the owning table's own routes too). See [ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md) and [ADR 0011](./docs/adr/0011-join-fields-allowlist.md).
+
 **Choosing `unique`**: if `joinField` is the PK (or part of the composite PK) of `joinSchema`, the relation is N:1 — you almost certainly want `unique: true` so the alias is usable in `joinLeft`.
 
 **Owned child tables (translations, `*_info` details): use a writeJoin, not a standalone table.** A table that only exists as a child of a parent — e.g. `product_info` with composite PK `(product_id, lang)` — should be an `allowedWriteJoins` on the parent, not its own `DbTables` entry. The engine auto-fills the FK (`product_id`); add it to `upsertMap` (conflict key = the composite PK) to upsert children passing only their own fields. Avoids redundant endpoints/validators.
@@ -431,6 +454,10 @@ export const TableCustomer = defineTable({
 
 `extraFilters` accepts either a `Type.Object({...})` or a plain `Record<string, TSchema>`. Extra filter fields appear in Swagger but are NOT auto-applied as `WHERE col = value` — they are handled exclusively by the `extendedCondition` callback. The `filters` parameter in the callback is fully typed with autocomplete for all schema fields + extra filter keys.
 
+**Not available on `joinLeft`.** `extendedCondition` writes its own column references, which cannot be qualified with the `LEFT JOIN` alias the parent gets there, so `buildLeftJoinClauses` handles schema and computed fields only. The generated body schema does not advertise the parent's `extraFilters` under `joinLeft.<alias>.filters`, and sending one is a `400` rather than a silent no-op. Use `joinMustExist` on the same relation when you need an extra filter on the parent.
+
+**Unknown filter keys are a `400`** (`Unknown filter field: <key>`), on the main table and on every join. A filter that does not match a schema field, an `extraFilters` key or a computed field is rejected instead of dropped: silently ignoring it would return *more* rows than the caller asked for. The check lives in the engine, so it applies to `sqlApi.search()` too, and it runs before any query — the outcome never depends on whether the main query matched rows.
+
 ---
 
 ## Computed Fields (extension system)
@@ -777,7 +804,7 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 - **All fields Optional in response**: `RETURNING *` may return any subset. Response schemas use `Type.Partial`.
 - **Nullable columns use `Nullable(T)` (type-array form)**: the generator emits `Type.Optional(Nullable(T))` for nullable columns — `Nullable` (exported by the package) produces `{ type: ['integer', 'null'] }`. Do NOT replace it with `Type.Union([T, Type.Null()])`: under Fastify's default Ajv `coerceTypes` a union corrupts values through its branches (`null` → `0` with the Null branch last, `0`/`""` → `null` with it first), while the type array validates and serializes NULL correctly. A bare `Type.Optional(T)` is also wrong: NULL serializes as `0`/`""`. In `filters`, an explicit `null` on a schema field builds `WHERE col IS NULL`.
 - **`excludeFromCreation`**: **IMPORTANT** — auto-increment PKs (e.g. `id` serial/auto_increment) MUST be listed here, otherwise INSERT will try to send them and fail. The CLI auto-detects this and adds it by default. Also useful for `createdAt`/`updatedAt` columns managed by DB defaults or hooks. It strips **client-supplied** values only: the payload is sanitized before `beforeInsert` runs, so a value the hook assigns to an excluded field (e.g. a server-generated TEXT id) DOES reach the INSERT. Same for the engine's FK auto-fill on secondaries — an excluded FK column does not suppress it. It is an **ergonomics tool for creation, NOT a field-level security mechanism**: it does not apply to updates — every Schema field is updatable by default, by design. Field-level update rules (`isAdmin`, roles, owner/tenant columns, state fields) are product logic: enforce them in `beforeUpdate` (silent strip) or `validate` (loud 400), or move the privileged transition to a dedicated endpoint and keep it off the auto routes via `operations`.
-- **`readExclude`**: fields hidden from every read — not projected by search/get, omitted from read response schemas and from this table's default (`*`) join selection when it is a join target. Referencing one from `filters`, `conditions`, `orderBy`, `joinGroup` aggregations or an explicit join `selection` returns 400: hiding a field from output while allowing it to be filtered would leak its value by bisection. **Writes are unaffected** — insert/update/bulk still accept the field, so a column can be writable but never readable (password hash, access token). Primary keys cannot be excluded. Complementary to trimming the Schema, which removes the column from reads *and* writes.
+- **`readExclude`**: fields hidden from every read — not projected by search/get, omitted from read response schemas and from this table's default (`*`) join selection when it is a join target. Referencing one from `filters`, `conditions`, `orderBy`, `joinGroup` aggregations or an explicit join `selection` returns 400: hiding a field from output while allowing it to be filtered would leak its value by bisection. **Writes are unaffected** — insert/update/bulk still accept the field, so a column can be writable but never readable (password hash, access token). Primary keys cannot be excluded. Complementary to trimming the Schema, which removes the column from reads *and* writes. It is **per table and static**: a column hidden here is hidden from every caller, including admins. To keep a column readable on the table's own routes but not through a relation, trim the Schema the *relation* is declared with instead — see the read-grant warning under [buildRelation](#buildrelation-signature).
 - **`upsertMap`**: when present for a schema, INSERT becomes upsert. PostgreSQL: `ON CONFLICT (...) DO UPDATE`. MySQL/MariaDB: `ON DUPLICATE KEY UPDATE`. Applies to both main and secondary tables.
 - **`schemaOverrides`**: override auto-generated schema fields with stricter TypeBox types (e.g. `{ email: Type.String({ format: 'email' }) }`). Overrides are merged into the body schema for insert, update, and bulk-upsert. The original Schema file is never modified. In updates, overridden fields are still wrapped in Optional (validates only when present). Overrides appear in Swagger.
 - **Validation receives camelCase**: `validate` receives the original camelCase record (as sent by the client) and secondaries. Field names match the schema definition, with full TypeScript inference (`main.startDate`, not `main.start_date`). It returns `ValidationError[]` — tuples of `[field, code]` or `[field, code, message]`. If any errors are returned, the request is rejected with 400 before hooks or SQL execute.

package/BREAKING_CHANGES.md

@@ -380,3 +380,78 @@ endpoints previously behaved correctly for you — they are now gone and you mus
 - **First PK column is truly unique on its own?** Then the composite declaration was
   redundant: declare `primary: 'id'` (single) and keep the second column as a plain field —
   every by-id operation comes back.
+
+---
+
+# Breaking Change — unknown filter keys are rejected
+
+`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.
+
+## Why this changed
+
+The engine only ever visited filter keys matching a schema field, an `extraFilters` entry or a
+computed field. Anything else — a typo, a renamed column, a field that exists on the table but
+not on the trimmed Schema a relation was declared with — was never looked at, and the query ran
+as if the filter had not been sent.
+
+That fails in the dangerous direction. A rejected filter returns *more* rows than the caller
+asked for, and nothing in the response says so; in an application where filters are also how
+visibility is narrowed, a typo becomes a data exposure. It was also the odd one out: an unknown
+field in `selection`, `conditions`, `orderBy` or a `joinGroup` aggregation has always been a
+400.
+
+## What changed
+
+| Request | Before | After |
+|---|---|---|
+| `filters: { nosuchfield: 'x' }` | `200`, filter ignored | `400 Unknown filter field: nosuchfield` |
+| `joinMultiple.<alias>.filters: { nosuchfield: 1 }` | `200`, filter ignored | `400 Unknown filter field: nosuchfield` |
+| `joinLeft.<alias>.filters: { <extraFilter> }` | `200`, filter ignored | `400 Filter '<key>' is an extraFilter: …` |
+| `filters: { knownField: undefined }` | ignored | ignored (unchanged) |
+| `filters: { knownField: null }` | `IS NULL` | `IS NULL` (unchanged) |
+
+Two related fixes ship with it:
+
+- The check runs in the engine, not in the route schema, so `sqlApi.search()` behaves the same
+  as the HTTP routes. (A closed `additionalProperties: false` schema would not have worked:
+  Fastify runs Ajv with `removeAdditional: true`, so it would have *stripped* the key and
+  reproduced the same silent behaviour one layer up.)
+- Join filters are validated **before any query runs**. They used to be validated inside the
+  side query, which is skipped entirely when the main result set is empty — so the same request
+  answered 400 or 200 depending on the data it matched.
+
+## Who is affected
+
+Callers that send filter keys the target table does not declare. Over-sending is the common
+case: a frontend that spreads a whole form state into `filters`, or reuses one filter object
+across two tables.
+
+## Migration
+
+Send only keys the table declares. `GET /agent/manifest` and the Swagger body schema both list
+them per table (schema fields + `extraFilters` + computed fields).
+
+For a form-state object, filter it before sending rather than relying on the server to ignore
+the extras:
+
+```typescript
+const ALLOWED = ['name', 'status', 'createdFrom'] as const;
+const filters = Object.fromEntries(
+  Object.entries(formState).filter(([k, v]) => ALLOWED.includes(k) && v !== '')
+);
+```
+
+Passing `undefined` for an absent value is still safe and needs no filtering: only keys with a
+defined value are validated.
+
+## joinLeft and extraFilters
+
+`joinLeft.<alias>.filters` used to advertise the parent table's `extraFilters` in Swagger and
+accept them at runtime, applying nothing: `buildLeftJoinClauses` builds its condition inline and
+never runs the target's `extendedCondition`, whose column references cannot be qualified with
+the `LEFT JOIN` alias the parent gets there. They are no longer advertised, and sending one
+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`.

package/CHANGELOG.md

@@ -7,6 +7,61 @@ 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]
+
+### 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
+  mistyped filter name came back as an unfiltered (wider) result set with no error: the
+  dangerous direction to fail in, and inconsistent with `selection`, `conditions`, `orderBy`
+  and aggregations, which have always answered 400. The check lives in the engine, so it
+  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
+  `LEFT JOIN` alias), so the filter applied nothing. They are now rejected with a `400` naming
+  the reason and pointing at `joinMustExist` on the same relation.
+
+### Fixed
+
+- **Join validation no longer depends on the main result set.** `joinMultiple` / `joinLeft` /
+  `joinGroup` skip their side query entirely when the main query matched no rows, so everything
+  validated inside it was skipped with it — the same request answered 400 or 200 depending on
+  the data. This covered filter keys and `readExclude` on join filters, an explicit `selection`
+  naming an unknown field, and `joinGroup` aggregation fields including `aggregations.by`. Join
+  filters are now validated up front, and the selection and aggregation lists are resolved
+  before the empty-result bail-out.
+
+### 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).
+
+- **`excludeTables` config option** — blacklist for `sqlapi-generate-schema`. Tables
+  listed in `excludeTables` in `sqlapi.config.ts` (exact names or `*` globs, e.g.
+  `knex_*`) are skipped during schema generation; their previously generated schema files
+  are removed as orphans on the next full run, like those of dropped tables (ADR 0009).
+  Does not apply to `sqlapi-generate-tables`, which is already explicit (ADR 0007).
+
 ## [0.1.12]
 
 ### Fixed

package/README.md

@@ -1,14 +1,63 @@
 # fastify-auto-sqlapi
 
-Automatic CRUD API generation from PostgreSQL, MySQL, and MariaDB tables for [Fastify](https://fastify.dev/). No ORM, no magic — just raw SQL, with TypeBox validation and Swagger docs out of the box.
+**Your database already knows its tables, columns and relations. This plugin turns that knowledge into a complete REST API inside your [Fastify](https://fastify.dev/) app.**
 
-Point it at your database, and get a full REST API with search, advanced conditions, pagination, joins, aggregations, bulk operations, multi-tenant isolation, validation, and hooks.
+Two CLI commands introspect PostgreSQL / MySQL / MariaDB and generate typed schemas; one `register()` call turns each table *you choose to expose* into seven endpoints: search with filters, advanced conditions, relation joins and aggregations; validated writes with nested child records; bulk upsert/delete; multi-tenant isolation; Swagger docs. Related tables don't need endpoints of their own — reads reach them through joins, writes through nested children — so a whole subgraph can live behind a single exposed table. What's left to write is what makes your product yours — auth, business rules, custom logic — as plain TypeScript hooks next to your other routes.
+
+One request, to show the point — *"active customers with over 500 total in completed orders, with their order stats, biggest spenders first"*:
+
+```jsonc
+// POST /api/search/customer?orderBy=orders.sum.total DESC&page=1&itemsPerPage=20
+{
+  "filters": { "status": "active" },
+  "joinGroup": {
+    "orders": {
+      "filters": { "status": "completed" },
+      "aggregations": { "sum": ["total"], "count": ["id"] }
+    }
+  },
+  "conditions": [{ "field": "orders.sum.total", "method": "isGreater", "params": [500] }]
+}
+```
+
+Under the hood this is a fixed, request-shaped number of set-based queries — the main select plus one per requested join alias (EXISTS clauses and correlated subqueries ride inside them), **never one per returned row**. There are no lazy relations to accidentally loop over: the N+1 problem is structurally absent, not something you remember to avoid.
+
+Writes read the same way — *"sync these clients and their tags: update the ones that exist, insert the missing ones, don't duplicate a tag"*:
+
+```jsonc
+// PUT /api/bulk/customer — all mains in one SQL; child FKs auto-filled from each parent
+[
+  { "main": { "email": "mario@acme.it", "name": "Mario" },
+    "secondaries": { "tags": [{ "tag": "vip" }, { "tag": "newsletter" }] } },
+  { "main": { "email": "luigi@acme.it", "name": "Luigi" } }
+]
+// → 200 [{ "main": { "id": 1 }, "secondaries": { "tags": [{ "id": 10 }, { "id": 11 }] } },
+//        { "main": { "id": 2 } }]
+```
+
+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:
+
+```jsonc
+// PUT /api/rest/order — order 7 is mine, customer 41 belongs to another tenant
+{ "main": { "id": 7, "customerId": 41 } }
+// → 403 Forbidden — cross-tenant references are rejected server-side
+```
+
+No endpoint written by hand, no resolvers, no query language on the server — and these requests are schema-validated, Swagger-documented, size-capped and tenant-isolated like every other one.
+
+## Not an ORM, not GraphQL — a third thing
+
+- **Not an ORM.** An ORM is a library *your* code uses to talk to the database — you still hand-write every endpoint on top of it. This plugin generates the endpoints themselves. And there is no ORM underneath either: no models, no migrations, no second schema to keep in sync. The database is the single source of truth (the CLI reads it from `information_schema`), and every request runs as plain parameterized SQL you can read with `debug: true`.
+- **Not GraphQL.** GraphQL buys client-driven flexibility with a heavy toolchain: a schema layer, hand-written resolvers (and their N+1 traps), mutations written one by one, client libraries, and query-cost analysis to stop hostile requests. This plugin covers what most projects actually reach for GraphQL for — filter, paginate, join related data, aggregate, in one round trip — with a fixed JSON grammar over plain REST: curl-able, Swagger-documented, bounded by design (join depth is fixed, page and bulk sizes are capped). The write side — nested children, upserts, bulk — is generated too, which GraphQL never gives you for free. What you give up: arbitrarily deep nesting, per-field selection on the main table, subscriptions. If you need those, you need GraphQL; most CRUD backends don't.
+- **Not a hosted black box.** PostgREST / Hasura / Supabase give you an instant API as a separate service, configured from the outside. This is a plugin inside your own app: hooks, validation and auth are TypeScript functions in your codebase, and you can always drop down to `app.sqlApi.*` or raw SQL in a custom route — same engine, no lock-in.
 
 ## Features
 
+- **Zero boilerplate** — 7 endpoints per exposed table; related tables can stay behind joins and nested writes instead of getting endpoints of their own
+- **No ORM** — raw SQL via `pg` + parameterized queries; set-based joins, so no N+1 by construction
 - **Agent-ready** — `AGENTS.md` and the ADRs ship *inside* the npm package, so a coding agent can configure the library without reading the source or guessing intent
-- **Zero boilerplate** — define your tables, get 7 endpoints each
-- **No ORM** — raw SQL via `pg` + parameterized queries
 - **TypeBox validation** — request/response schemas auto-generated from your DB
 - **Joins** — four explicit families (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`) with alias support
 - **Computed fields** — declare virtual fields as SQL expressions in `defineTable`; usable like schema fields in filters/orderBy/conditions, and opt-in projected in the response via `selectComputed`. Covers JSON extraction, derived columns, dialect-aware date bucketing
@@ -25,37 +74,6 @@ Point it at your database, and get a full REST API with search, advanced conditi
 > with bound values, read the 0.1.6 entry — earlier versions could return wrong rows.
 
 
-## Working with coding agents
-
-The library is documented for two readers. Humans get this README; agents get task-oriented
-files that ship in the published package, so they are already on disk after `npm install`:
-
-| File                                   | Contents                                                          |
-| -------------------------------------- | ----------------------------------------------------------------- |
-| `AGENTS.md`                            | Entry point: what the library does, which file to read for what   |
-| `AGENTS_BACKEND.md`                    | `defineTable` reference, hooks, tenancy, computed fields, CLI      |
-| `AGENTS_FRONTEND.md`                   | Request/response shapes for every endpoint                        |
-| `docs/adr/`                            | Why the non-obvious behaviours are what they are                  |
-
-Point your agent at them once:
-
-> Read `node_modules/fastify-auto-sqlapi/AGENTS.md` before touching anything under `src/db/`.
-
-Three design choices make the generated code predictable enough for an agent to write it
-unsupervised:
-
-- **Configuration is declarative and local.** A table is one `defineTable()` call — nothing to
-  wire across files, so a diff is reviewable at a glance.
-- **One naming convention.** camelCase in requests, responses, hooks and validators; the
-  mapping to DB columns is automatic. There is no second convention to remember, and no
-  layer where the agent has to guess which one applies.
-- **Errors are machine-readable.** A 400 carries `fields: [{ path, code, message }]`, so a
-  failing request tells the agent exactly what to fix instead of requiring a guess.
-
-The ADRs matter more than they look: they answer the "why is it like this?" questions
-(open-by-default, non-transactional bulk, always-updatable fields) that an agent would
-otherwise resolve by inventing a workaround — or by proposing to change intentional behaviour.
-
 ## Quick Start
 
 ### 1. Install
@@ -76,6 +94,7 @@ export default {
   schema: 'public',            // PostgreSQL schema to introspect (default: 'public')
   // dialect: 'mysql',         // 'postgres' (default) | 'mysql' | 'mariadb'
   // envFile: '.env.local',    // env file to load (default: '.env')
+  // excludeTables: ['knex_*'], // tables to skip in schema generation ('*' = wildcard)
 };
 ```
 
@@ -113,6 +132,12 @@ This introspects your tables and generates one TypeBox schema file per table in
 `<outputDir>/schemas/` (e.g. `SchemaCustomer.ts`, `SchemaOrder.ts`). These files are
 auto-generated — don't edit them; re-run the command after a DB change.
 
+To keep some tables out of schema generation (migration bookkeeping, PostGIS internals, …)
+list them in `excludeTables` in the config — exact table names or `*` globs (e.g.
+`knex_*`). Excluded tables are invisible to the generator: their schemas are not created,
+and any previously generated schema file is removed as an orphan on the next full run,
+like that of a dropped table.
+
 ### 4. Generate the tables template
 
 ```bash
@@ -161,6 +186,37 @@ That's it. For a table called `customer`, you now have:
 
 > **Note:** Search uses `POST` because filters are passed as JSON in the request body.
 
+## Working with coding agents
+
+The library is documented for two readers. Humans get this README; agents get task-oriented
+files that ship in the published package, so they are already on disk after `npm install`:
+
+| File                                   | Contents                                                          |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| `AGENTS.md`                            | Entry point: what the library does, which file to read for what   |
+| `AGENTS_BACKEND.md`                    | `defineTable` reference, hooks, tenancy, computed fields, CLI      |
+| `AGENTS_FRONTEND.md`                   | Request/response shapes for every endpoint                        |
+| `docs/adr/`                            | Why the non-obvious behaviours are what they are                  |
+
+Point your agent at them once:
+
+> Read `node_modules/fastify-auto-sqlapi/AGENTS.md` before touching anything under `src/db/`.
+
+Three design choices make the generated code predictable enough for an agent to write it
+unsupervised:
+
+- **Configuration is declarative and local.** A table is one `defineTable()` call — nothing to
+  wire across files, so a diff is reviewable at a glance.
+- **One naming convention.** camelCase in requests, responses, hooks and validators; the
+  mapping to DB columns is automatic. There is no second convention to remember, and no
+  layer where the agent has to guess which one applies.
+- **Errors are machine-readable.** A 400 carries `fields: [{ path, code, message }]`, so a
+  failing request tells the agent exactly what to fix instead of requiring a guess.
+
+The ADRs matter more than they look: they answer the "why is it like this?" questions
+(open-by-default, non-transactional bulk, always-updatable fields) that an agent would
+otherwise resolve by inventing a workaround — or by proposing to change intentional behaviour.
+
 ## Table Configuration
 
 Tables are configured with `defineTable()`. The only required fields are `primary` and the output of `exportTableInfo()`:
@@ -210,6 +266,8 @@ const TableCustomer = defineTable({
     buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
     buildRelation(SchemaSession, 'userId', SchemaUser, 'id', { unique: true }),           // alias = 'user', N:1
     buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true }),
+    // `fields` restricts what this relation exposes of the target — read joins only
+    buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true, fields: ['id', 'name'] }),
   ],
   allowedWriteJoins: [
     buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
@@ -367,6 +425,43 @@ are always available to your own code.
 **3. Multi-tenancy** — `getTenantId` + `tenantScope` filter every query by tenant (see
 [Multi-Tenant](#multi-tenant)).
 
+### A declared join is a read grant
+
+⚠️ **Neither of the first two layers follows a join.** `onRequests` and `operations` are
+properties of the routes generated *for* a table; a join is resolved inside the query of the
+**host** table's route, so the target's hooks never run and its `operations` whitelist does not
+apply. A table with `operations: []` — no HTTP routes at all — is still fully readable through
+any relation pointing at it.
+
+So `allowedReadJoins` is a security decision: declaring a relation grants read access to the
+target table under the **host** table's authorization.
+
+What does follow a join: `readExclude`, `tenantScope`, and the schema the relation was declared
+with. To expose a table broadly while keeping some columns narrow, give the relation a `fields`
+allowlist:
+
+```typescript
+allowedReadJoins: [
+  buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', {
+    unique: true,
+    fields: ['id', 'name'],   // everything else on `user` is unreachable here
+  }),
+],
+```
+
+Every read surface validates against it — `selection`, `filters`, `conditions`, `orderBy`,
+aggregations, and the generated request/response schemas — so `email` is `400 Unknown field`
+everywhere, not just missing from the projection. It is fail-closed: a column added to `user`
+later is not reachable through this relation until it is added to the list.
+
+`fields` restricts **reading** only, and only through that relation. It is not a replacement for
+`readExclude` (which hides a column from the table's own routes too) or for `onRequests` (which
+decides who may call them).
+
+Full rationale and the rejected alternatives in
+[ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md) and
+[ADR 0011](./docs/adr/0011-join-fields-allowlist.md).
+
 ### Request limits
 
 Two hard caps bound how much work a single request can trigger (defense against accidental or
@@ -383,11 +478,14 @@ capped — they run your own trusted code.
 
 ### Write whitelist
 
-Insert/update/bulk-upsert bodies reject **unknown properties** (`additionalProperties: false`):
-only columns present in the generated Schema (as narrowed by `schemaOverrides` /
-`excludeFromCreation`) can be written. An unexpected field is a `400`, never a silently-written
-column — the Schema is the write whitelist. Trim the generated Schema (or use `excludeFromCreation`)
-to keep sensitive columns out of it.
+Insert/update/bulk-upsert bodies are `additionalProperties: false`: only columns present in the
+generated Schema (as narrowed by `schemaOverrides` / `excludeFromCreation`) can be written. The
+Schema is the write whitelist. Trim the generated Schema (or use `excludeFromCreation`) to keep
+sensitive columns out of it.
+
+An unexpected field is **stripped, not rejected**: Fastify runs Ajv with `removeAdditional: true`,
+so the request succeeds and the column is simply never written. Mass assignment is prevented
+either way, but do not expect a `400` to tell a client its extra field was ignored.
 
 ### Field-level update rules are product logic — use the hooks
 
@@ -487,12 +585,12 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 }
 ```
 
-- **`filters`** — equality-based, flat key/value. Supports schema fields + `extraFilters`.
+- **`filters`** — equality-based, flat key/value. Supports schema fields, `extraFilters` and computed fields. A key that is none of those is a `400 Unknown filter field: <key>` — a mistyped filter must never come back as a wider result set. An explicit `null` filters by `IS NULL`; `undefined` means "not supplied" and is ignored.
 - **`conditions`** — array of `{ field, method, params }`. Methods: `isEqual`, `isNotEqual`, `isGreater`, `isGreaterOrEqual`, `isLess`, `isLessOrEqual`, `isLike`, `isILike`, `isIn`, `isNotIn`, `isBetween`, `isNotBetween`, `isNull`, `isNotNull`.
 - **`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 }`.
+- **`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.
 
 **Dot-notation in `orderBy` and `conditions`**:
 

package/dist/bin/generate-schema.js

@@ -4,7 +4,7 @@ import * as path from 'node:path';
 import { loadConfig } from '../lib/cli/config.js';
 import { buildConnectionString, introspectTables } from '../lib/cli/pg-introspect.js';
 import { buildMysqlConnectionConfig, introspectMysqlTables } from '../lib/cli/mysql-introspect.js';
-import { buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
+import { applyExcludeTables, buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
 import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, parseArgs, runCli } from './utils.js';
 await runCli('fastify-auto-sqlapi: generating schemas', async () => {
     const cliArgs = parseArgs({
@@ -36,6 +36,14 @@ await runCli('fastify-auto-sqlapi: generating schemas', async () => {
         return;
     }
     const tableMap = buildTableMap(rows);
+    // Config blacklist: excluded tables are invisible to the generator, so their
+    // schema files (if any) fall through to the orphan cleanup below.
+    const excluded = applyExcludeTables(tableMap, config.excludeTables);
+    if (excluded.length) {
+        display(`Excluded by config (excludeTables): ${excluded.join(', ')}`, CONSOLE_COLORS.gray);
+    }
+    // Note: no early return when everything is excluded — the orphan cleanup below
+    // must still run to remove the schema files of freshly excluded tables.
     // Filter tables if --tables flag is provided
     const tableNames = cliArgs.tables;
     if (tableNames.length) {

package/dist/lib/agent/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/lib/agent/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAgCD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA2CrE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/lib/agent/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAgCD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA6CrE"}

package/dist/lib/agent/manifest.js

@@ -114,6 +114,8 @@ export function renderAgentManifestMd(manifest) {
         'serverGenerated fields: omit on insert (values from client are ignored).',
         'readJoins aliases: `1:N` → joinMustExist/joinMultiple/joinGroup; `N:1` → joinLeft.',
         'writeJoins aliases: keys for `secondaries`/`deletions` in writes.',
+        'filters: unknown keys are rejected (400), never ignored. extraFilters do not apply ' +
+            'under joinLeft — use joinMustExist on the same relation.',
         '',
     ];
     for (const t of Object.values(manifest.tables)) {

package/dist/lib/cli/schema-codegen.d.ts

@@ -5,5 +5,12 @@ export declare function convertColType(udtName: string, columnInfo: {
     is_auto_increment?: boolean;
 }): string;
 export declare function buildTableMap(rows: ColumnInfo[]): TableMap;
+/**
+ * Remove from `tableMap` the tables matching any of the `excludeTables` config patterns.
+ * Patterns are matched against the DB table name (not the generated schema name);
+ * `*` is the only wildcard — everything else is literal.
+ * Returns the names of the excluded tables, in map order.
+ */
+export declare function applyExcludeTables(tableMap: TableMap, excludeTables?: string[]): string[];
 export declare function generateSchemaFile(schemaName: string, tableName: string, fields: Record<string, string>, colMap: Record<string, string>, primary?: string[]): string;
 //# sourceMappingURL=schema-codegen.d.ts.map

package/dist/lib/cli/schema-codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/schema-codegen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE3D,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE;IAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,MAAM,CA0DR;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,CAqC1D;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CA8CR"}
+{"version":3,"file":"schema-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/schema-codegen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE3D,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE;IAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,MAAM,CA0DR;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,CAqC1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAoBzF;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CA8CR"}

package/dist/lib/cli/schema-codegen.js

@@ -85,6 +85,31 @@ export function buildTableMap(rows) {
         return acc;
     }, {});
 }
+/**
+ * Remove from `tableMap` the tables matching any of the `excludeTables` config patterns.
+ * Patterns are matched against the DB table name (not the generated schema name);
+ * `*` is the only wildcard — everything else is literal.
+ * Returns the names of the excluded tables, in map order.
+ */
+export function applyExcludeTables(tableMap, excludeTables) {
+    if (excludeTables === undefined)
+        return [];
+    if (!Array.isArray(excludeTables) || excludeTables.some((p) => typeof p !== 'string')) {
+        throw new Error('Invalid config: "excludeTables" must be an array of strings.');
+    }
+    if (excludeTables.length === 0)
+        return [];
+    const regexes = excludeTables.map((pattern) => new RegExp(`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replaceAll('\\*', '.*')}$`));
+    const excluded = [];
+    for (const schemaName of Object.keys(tableMap)) {
+        const tableName = tableMap[schemaName].name;
+        if (regexes.some((re) => re.test(tableName))) {
+            excluded.push(tableName);
+            delete tableMap[schemaName];
+        }
+    }
+    return excluded;
+}
 export function generateSchemaFile(schemaName, tableName, fields, colMap, primary) {
     const fieldsStr = JSON.stringify(fields, null, 2).replace(/"(.*?)"\s*:\s*"Type(.*?)"/g, '$1: Type$2');
     const colMapStr = JSON.stringify(colMap, null, 2);

package/dist/lib/engine/search/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAcb,MAAM,mBAAmB,CAAC;AA8lC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CA4HvB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAeb,MAAM,mBAAmB,CAAC;AAqoC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CAqIvB"}