fastify-auto-sqlapi 0.2.0 → 0.2.2

package/docs/adr/0006-raw-db-errors.md

@@ -1,6 +1,7 @@
 # 0006. Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping
 
-- **Status**: accepted
+- **Status**: accepted on the mapping; message exposure narrowed by
+  [0013](./0013-sanitized-db-errors.md)
 - **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
 
 ## Context

package/docs/adr/0010-joins-do-not-run-route-guards.md

@@ -97,4 +97,7 @@ programmatic `sqlApi.search()` path.
   narrow. Not decided here.
 - `tenantScope` remains the one request-derived protection that crosses joins, and is the
   precedent for the shape any future one should take: table configuration plus a plugin-level
-  resolver, not a route hook.
+  resolver, not a route hook. It crosses joins **unconditionally** only since the tenant stopped
+  being resolved from the addressed table alone; before that, a host declaring no scope of its
+  own carried none into its join targets, which made the row above true only when the host
+  happened to be scoped too (see BREAKING_CHANGES.md).

package/docs/adr/0013-sanitized-db-errors.md

@@ -0,0 +1,114 @@
+# 0013. Database error messages are sanitized on the wire by default
+
+- **Status**: accepted — narrows [0006](./0006-raw-db-errors.md)
+- **Date**: 2026-08-05
+
+## Context
+
+[ADR 0006](./0006-raw-db-errors.md) rejected two distinct proposals in one decision: mapping
+SQLSTATE codes to HTTP semantics, and sanitizing driver messages. The first rejection holds
+— the mapping is dialect-specific and encodes product decisions the plugin should not make.
+The second rested on "hiding details is an environment policy, and Fastify already gives
+consumers the hook for it", and three facts undermine it:
+
+- The plugin installs its own `setErrorHandler` in the routes' child scope
+  (`src/routes/auto/plugin.ts`), and it sends `error.message` verbatim for any status code.
+  A consumer handler registered on the parent scope never sees these errors, so the escape
+  route 0006 points at does not exist for the main-plugin path.
+- The posture is inconsistent with the rest of the codebase. `maxItemsPerPage`,
+  `maxBulkItems`, prototype-key filtering and the join field allowlist are all guards the
+  plugin applies by default where the cost is zero. A constraint name describing the schema
+  to whoever triggered a duplicate is the same class of free hardening.
+- [ADR 0002](./0002-open-by-default.md) amplifies the exposure: the scenario the plugin
+  optimizes for — internal scaffolding wired up in five minutes — is exactly the one where
+  nobody wrote an error handler.
+
+The failure mode is silent. A consumer who never thinks about it ships the leak and gets no
+signal.
+
+## Decision
+
+Errors escaping an auto-generated route handler are replaced with a bare
+`500 Internal Server Error` carrying no database detail. Errors the plugin raises itself are
+deliberate `4xx` with messages written for clients (`httpError`, `validationErrors`) and pass
+through untouched — the rule is `statusCode` in `[400, 500)`, nothing else.
+
+No status code is remapped: a `500` stays a `500`. ADR 0006 stands on that point.
+
+Nothing is lost. The original error is logged through `request.log.error` and attached as the
+`cause` of the error the consumer's `setErrorHandler` receives, so unique-violation → `409`
+remains implementable, and remains the consumer's decision. The sanitized body carries
+`requestId` — the same value Fastify binds as `reqId` on the request logger — so the client
+can name the log line holding the real error instead of describing a `500` that happened
+"around then".
+
+Developing against the API is a real need the log does not serve — a client building on it,
+an agent especially, may have no way to read the server's log, and a round trip per failure
+is expensive. `exposeDebugInfo: true` answers it by **adding** a `debugInfo` payload (driver
+message, `code`, `constraint`/`detail`, stack) beside the fields above, which keep the shape
+they have in production. Client-side error handling therefore does not fork between
+environments — the difference is extra data, not different data.
+
+`exposeDebugInfo` derives from nothing. Not `debug`, not `NODE_ENV`, not the log level. The
+deciding argument is that **`debug` belongs to the consumer**: whoever registers the plugin
+decides how it is wired — a constant in one deployment, an environment variable flipped
+during an incident in another — so the library cannot assume its lifecycle, and an option
+whose value the library does not control must not decide what leaves the server. Beyond that,
+`debug` writes to the log, an access-controlled internal channel; the response body is
+external, and under ADR 0002 often unauthenticated. And the posture wanted during a
+production incident — log everything, tell clients nothing — stops being expressible the
+moment one switch drives both.
+
+The guard sits in the handler built by `registerForAllTables`
+(`src/routes/auto/route-helpers.ts`) — the single choke point every auto route passes
+through, including route plugins registered standalone without the main plugin. The
+`debugInfo` payload is copied from the driver error by allowlist, never spread: an error
+object that starts carrying the connection config must not reach a client through it.
+
+## Alternatives considered
+
+- **`fastify.setErrorHandler` in the plugin** — rejected: the plugin is registered through
+  `fp()`, so a handler installed at that level would hijack error rendering for the
+  consumer's entire application, not just the auto routes.
+- **Sanitizing inside the existing child-scope handler in `plugin.ts`** — rejected: route
+  plugins registered standalone (`searchRoutes` alone, per AGENTS_BACKEND.md "Register only
+  specific routes") never reach that handler, and would keep leaking.
+- **Leaving it to the consumer, as 0006 decided** — rejected for the three reasons in
+  Context; the deciding one is that the plugin's own child-scope handler makes the
+  prescribed consumer remedy unreachable.
+- **Deriving the behaviour from `debug`** — rejected, for the reasons in Decision: the
+  consumer owns that option and may wire it to an environment variable, it currently governs
+  an internal channel only, and coupling makes "verbose log, silent response" unexpressible.
+  An override (`debug: true` + an explicit opt-out) would keep the combination reachable but
+  leaves the default pointing the dangerous way, which is the failure mode this ADR exists to
+  close.
+- **Keying it on `NODE_ENV`** — rejected. `NODE_ENV !== 'production'` is fail-open: the
+  variable is unset often enough in real deployments (a bare `node dist/server.js`, many
+  container images, systemd units) that the leak would come back precisely where nothing was
+  configured. `NODE_ENV === 'development'` would at least fail closed, but a security-relevant
+  response decided by the shell instead of by the registration call is action at a distance.
+- **Replacing `message` with the driver text instead of adding `debugInfo`** — rejected: it
+  makes one field mean different things in different environments, so client error handling
+  has to be written twice. The additive payload costs nothing and carries more, structured.
+- **Echoing only the SQLSTATE code** (`23505`, no names) — rejected: a third middle mode is
+  harder to reason about than a boolean, and reading meaning into SQLSTATE is the direction
+  0006 closed.
+- **Sending the detail only to localhost callers** — rejected: it makes the response depend
+  on network topology, which reverse proxies routinely flatten.
+
+## Consequences
+
+- Constraint violations reach clients as `{"statusCode":500,"error":"Internal Server
+  Error","message":"Internal Server Error","requestId":"…"}`. Diagnosing one requires the
+  server log — which is where the error was already going, under that same id.
+- Behavioural breaking change for consumers who parsed driver messages out of `500` bodies.
+  They read `debugInfo` instead, and only where the deployment opted in.
+- Development needs one more line (`exposeDebugInfo: true`) than it did. That is the price of
+  the option meaning exactly one thing: what a client sees is readable from the registration
+  call alone, without knowing how `debug` or the environment happen to be wired.
+- A deployment that leaves `exposeDebugInfo` on by mistake is back to disclosing schema
+  detail. The name is the mitigation: `expose` is the word that makes a reader stop, which
+  `debug` is not.
+- Errors thrown by consumer `onRequests` hooks are outside the handler and unaffected: that
+  is consumer code running before the plugin's SQL surface, and its messages are the
+  consumer's to write.

package/docs/adr/0014-what-follows-a-write-join.md

@@ -0,0 +1,84 @@
+# 0014. A secondary runs the child table's transform, not its verdicts
+
+- **Status**: accepted
+- **Date**: 2026-08-23
+
+## Context
+
+[ADR 0010](./0010-joins-do-not-run-route-guards.md) drew the line for reads: route-level
+controls (`onRequests`, `operations`) do not follow a join, configuration-level ones
+(`readExclude`, `tenantScope`, the relation's schema) do. The write side never had that line
+drawn, and it had drifted into an inconsistent middle.
+
+`processSecondaries` already consulted the child's configuration for two things — it stripped
+the child's `excludeFromCreation` and enforced the child's `tenantScope` — while its
+`beforeInsert` was silently skipped. The gap was invisible until a table started using that
+hook to change a value's *representation* rather than to add a value: a column encrypted on
+the way in was stored as ciphertext through `POST /rest/patient`, and as plaintext through
+`POST /rest/visit` with the same row sent under `secondaries.patient`. Nothing failed; the
+data was simply wrong in a way only a later read would show, and `afterRead` would then
+"decrypt" a value that was never encrypted.
+
+The reverse extension is not obviously right either. `validate` and `afterInsert` are also
+per-table configuration, and running them for children would be the symmetric move — but they
+do not transform a record, they *decide* about it: `validate` rejects the request, and
+`afterInsert` fires side effects. Both would change when and how a host's write fails, for
+consumers that never opted in.
+
+## Decision
+
+**A secondary is a write like any other for everything that shapes the record, and not for
+anything that renders a verdict on it.** The child's configuration is applied in this order,
+mirroring the single-insert pipeline of [ADR 0005](./0005-insert-pipeline-sanitize-before-hooks.md):
+
+1. the child's `excludeFromCreation` strip (client-input whitelist);
+2. the child's `beforeInsert` (may mutate, including on excluded fields);
+3. conversion to DB column format;
+4. the engine's FK auto-fill, which is authoritative over both the payload and the hook;
+5. the child's `tenantScope` enforcement.
+
+The child's `validate`, `validateBulk`, `afterInsert`, `beforeDelete` and `afterDelete` do not
+run. `processDeletions` is unchanged: it removes rows, it does not shape them.
+
+| Child-table config | Applies to a secondary |
+|---|---|
+| `excludeFromCreation` | yes |
+| `beforeInsert` | yes |
+| `tenantScope` | yes |
+| `upsertMap` | yes (via the host's `upsertMap`) |
+| `validate` / `validateBulk` | no |
+| `afterInsert` | no |
+| `onRequests` / `operations` | no (ADR 0010) |
+
+The host's own `validate` receives the secondaries and is the place to reject them.
+
+## Alternatives considered
+
+- **Leave `beforeInsert` skipped and document it** — rejected: the failure is silent and
+  writes bad data. A hook that assigns `createdBy` merely produced a null column when skipped;
+  a hook that encodes a value produced a row that reads back as garbage, and no error marks
+  the moment it happened.
+- **Run the child's full pipeline (`validate` + `afterInsert`)** — rejected for now, not on
+  principle. `validate` would make a host's insert start failing on child rows that were
+  accepted the day before, and `afterInsert` would fire N side effects inside the host's
+  transaction with no ordering contract against the host's own `afterInsert`. Both are
+  behaviour changes that need their own decision; the host's `validate` already receives the
+  secondaries.
+- **A separate `beforeSecondaryInsert` hook on the host** — rejected: a second name for
+  "prepare a row of this table", declared on the wrong table. The transform belongs to the
+  table that owns the column, which is the same rule `afterRead` follows on the read side.
+- **Run the child hook before the exclusion strip** — rejected: it inverts ADR 0005 and lets
+  a client value survive on an excluded field.
+
+## Consequences
+
+- Behaviour change (CHANGELOG + BREAKING_CHANGES): a child table's `beforeInsert` now runs for
+  rows written as secondaries, where it was silently skipped. A hook that was written assuming
+  it only ever saw the table's own route — one that reads `req.params`, or increments a counter
+  per call — now runs in a context it did not expect.
+- The hook receives the **transaction** connection, not the pool: what it writes rolls back
+  with the host's write.
+- `beforeInsert` is now the one place where "how this table's rows are shaped on the way in"
+  is written, on both entry paths — the dual of `afterRead` on the way out.
+- The asymmetry between transform and verdict is now a stated boundary, so the next reader
+  finds a decision instead of what looks like the same oversight in a different hook.

package/docs/adr/0015-non-writable-columns.md

@@ -0,0 +1,86 @@
+# 0015. A column the database computes is not writable — `writeExclude` (narrows 0004)
+
+- **Status**: accepted
+- **Date**: 2026-08-28
+
+## Context
+
+[ADR 0004](./0004-updates-always-open.md) rejected `excludeFromUpdate`: a static per-field
+write block, proposed to protect `isAdmin`, `createdAt` and ownership columns. It lost on one
+argument — those cases are **session-dependent**, a static list cannot express them, and
+offering one would give a false sense of security to consumers who used it for exactly that.
+That reasoning stands unchanged.
+
+It does not, however, cover a case the plugin met later: a column the database itself refuses
+to be told about.
+
+```sql
+subtotal INTEGER GENERATED ALWAYS AS (qty * price) STORED
+```
+
+Both engines reject the whole statement — not the field — when a write so much as names such a
+column: `428C9 cannot insert a non-DEFAULT value into column "subtotal"` on PostgreSQL,
+`ER_NON_DEFAULT_VALUE_FOR_GENERATED_COLUMN` on MySQL. Yet nothing in the generated schema said
+so, so the column was offered as an ordinary writable field, and a client that sent it back
+what a read had just returned got a **500** — a raw driver error, per
+[ADR 0006](./0006-raw-db-errors.md) — for a payload nobody could have made valid.
+
+The same blind spot hid `GENERATED ... AS IDENTITY`, which has no `column_default` to reveal
+that the database fills it in: the generated field came out mandatory and the table could not
+be inserted into at all.
+
+## Decision
+
+Fields the database computes are excluded from every write path. The CLI records them in the
+generated Schema's `generatedFields`, and the runtime removes them from the insert, update and
+bulk-upsert bodies (main and secondaries) and again inside the engines, which `sqlApi.*`
+reaches without those schemas.
+
+`ITable.writeExclude` exposes the same mechanism for the columns introspection cannot know
+about — one a trigger owns, one a migration is about to drop.
+
+This narrows 0004 rather than reversing it, and the boundary is what the exclusion is *about*:
+
+- **a fact about the column** — the database rejects the value whoever assigned it, so there is
+  no configuration in which offering the field helps anyone. This ADR.
+- **a rule about the caller** — who may change what, when. Still product logic, still
+  `beforeUpdate` / `validate` / a dedicated endpoint. Still ADR 0004.
+
+Three consequences follow from that boundary and are enforced:
+
+- `writeExclude` runs **after** the write hooks — the opposite of `excludeFromCreation`, which
+  is sanitized before them so a hook can assign the field ([ADR 0005](./0005-insert-pipeline-sanitize-before-hooks.md)).
+  A hook cannot put back a value the database will refuse.
+- `defineTable` rejects a field that is also in `readExclude`: neither readable nor writable is
+  what removing it from the Schema means.
+- `defineTable` rejects the primary key, which the update body needs to identify the row.
+
+## Alternatives considered
+
+- **`Schema.generatedFields` only, no public key** — rejected: it covers the introspected case
+  and nothing else, and a consumer whose schema is hand-written or whose column is owned by a
+  trigger would be back to a driver error with no way out.
+- **Let the write through and map the driver error to a 400** — rejected: it contradicts
+  [ADR 0006](./0006-raw-db-errors.md) (no SQLSTATE→HTTP mapping), it costs a round trip to the
+  database to learn what the schema already knew, and the field would still be advertised as
+  writable in Swagger and in the agent manifest.
+- **Trim the column out of the generated Schema** — rejected: that removes it from reads too,
+  and a computed column is precisely the one a client wants to read.
+- **Reopen 0004 and add a general `excludeFromUpdate`** — rejected: the false-sense-of-security
+  argument is untouched by anything here. The documentation for `writeExclude` says what it is
+  not for, and the key deliberately has no per-caller or per-role dimension that would invite
+  the misuse 0004 warned about.
+
+## Consequences
+
+- Under Fastify's default `removeAdditional: true`, a computed column in a write body is
+  **stripped silently** rather than rejected; the row is written with the value the database
+  computed. With `removeAdditional: false` the closed body schema answers 400. Either way the
+  driver error is gone — which was the point.
+- A consumer upgrading gets the fix from **regenerating the Schema files alone**: the exclusion
+  travels in `generatedFields`, not in the `Table*.ts` the generator never overwrites.
+- The generated `Table*.ts` names the computed columns in a comment and leaves `writeExclude`
+  commented out, and `sqlapi-generate-schema` prints them per table — a generated source file
+  is not always read, its command's output is.
+- Reads are untouched: a computed column stays projected, filterable, orderable and
+  aggregatable, because it is a real column with a real value.

package/docs/adr/0016-a-view-is-a-table-config.md

@@ -0,0 +1,92 @@
+# 0016. A view is a table config — the generator refuses to invent its primary key
+
+- **Status**: accepted
+- **Date**: 2026-08-28
+
+## Context
+
+Views were never designed for, and they worked anyway: both introspections read
+`information_schema.columns`, which lists view columns exactly like table columns, so
+`sqlapi-generate-schema` produced a Schema and searching the result worked with no special
+support. Three things underneath that were wrong.
+
+**The primary key was invented in silence.** A view carries no `PRIMARY KEY` constraint, so
+`is_primary` is false on every column and the generated Schema had no `primaryKey`. The table
+generator then fell through to its heuristic for hand-written schemas: `id` if present,
+otherwise **the first integer column**, otherwise the first column of any kind. On
+`SELECT status, count(*) AS order_count ... GROUP BY status` that hands back `order_count` — a
+count — as the key, and `get/:id`, `update` and `delete` then address rows by it. Nothing said
+so, in the file or on the console.
+
+**Nothing validated `primary` at all.** `defineTable` checked `tenantScope`, `readExclude`,
+`computedFields` and alias uniqueness, but a `primary` naming a field the schema does not have
+passed straight through and became a raw SQL error on the first request — a 500, per
+[ADR 0006](./0006-raw-db-errors.md).
+
+**PostgreSQL materialized views were invisible.** They are not in `information_schema` at all;
+they live only in `pg_catalog`. They were skipped without a word — and a materialized view is
+precisely the kind of expensive read one wants to expose.
+
+## Decision
+
+A view **is** a table config. No `ViewName` file, no `View*` type, no `readOnly` flag: the
+plugin has one concept for "a relation with columns you can query" and a view is that one. A
+second name would fork the `dbTables` keys, the generator, the docs and the manifest to express
+nothing the existing vocabulary cannot.
+
+What changes is what may be **assumed**, and all of it lives in the generator and in startup
+validation, not in the runtime semantics:
+
+- Introspection reports `is_view` on both engines, and PostgreSQL materialized views are read
+  from `pg_catalog` and reported the same way. The generated Schema carries `isView: true`.
+- For a view the generator **never guesses a key from a column type**. It accepts `id` when the
+  view has one — a strong enough signal — and says in the file that the key was *inferred, not
+  read from the database*. With no `id`, it writes a `TODO_pick_a_unique_column` placeholder
+  rather than a wrong answer.
+- A view's generated config starts read-only: `operations: ['search', 'get']`, or
+  `['search']` when the key is unresolved. `defaultOrder` names a real column, so search never
+  falls back to the placeholder, and the config **works as generated** — the TODO is a note for
+  whoever wants to widen it, not a defect.
+- `defineTable` now validates `primary` against the schema fields. The exception is exact and
+  narrow: a table exposing **only** `search` and naming its own `defaultOrder` never reads
+  `primary`, so it is allowed. Anything else fails at startup.
+- `sqlapi-generate-schema` prints the views it found and both assumptions it had to make. A
+  generated source file is not always read; the output of the command that produced it is.
+
+Writes through a view are **not** blocked at runtime. A view simple enough for the engine to
+make updatable accepts INSERT and UPDATE on both PostgreSQL and MySQL, and using one as a
+projection or permission layer is a legitimate pattern the plugin has no business refusing. The
+read-only start is the *generated template* — a file the developer then owns — which is a
+different thing from the runtime default that [ADR 0002](./0002-open-by-default.md) settles.
+That default is untouched: a hand-written view config with no `operations` still exposes
+everything.
+
+## Alternatives considered
+
+- **`ViewName` files / a distinct type** — rejected: it forks a concept for no expressive gain
+  and breaks the one-name-per-concept rule the glossary exists to enforce.
+- **A `readOnly: true` flag on `defineTable`** — rejected: a second spelling of
+  `operations: ['search', 'get']`.
+- **Blocking writes to views at runtime** — rejected: simple views are genuinely updatable on
+  both engines (verified), and the plugin cannot tell which ones from the schema alone. It
+  would remove a working feature to prevent an error the database already reports.
+- **Keep guessing the key, just add a comment** — rejected: the wrong-key failure is silent and
+  addresses *rows*, which is the worst kind. A placeholder that refuses to start is the loud
+  version of the same information.
+- **Skip views entirely, or leave materialized views unsupported and document it** — rejected:
+  they already worked for reads, which is the case that matters, and silence about a relation
+  the database has is the least defensible of the options.
+
+## Consequences
+
+- A view without an `id` column needs one manual edit before it can serve anything but
+  `search`. That is the point: the edit is a decision about uniqueness that only the author of
+  the view can make.
+- `defineTable` now throws at startup on a `primary` that names no schema field. A config that
+  relied on that tolerance — a primary key deliberately kept out of the Schema — has to name a
+  schema field or restrict itself to `operations: ['search']`.
+- Materialized views appear in generation runs where they did not before, so a project that
+  regenerates with `--all` will find new `Table*.ts` files for them.
+- The `is_view` flag is generator-facing. Nothing in the request path branches on it: a view
+  searches, filters, orders, paginates, joins and (when the database allows) writes through the
+  same code as a base table.

package/docs/adr/0017-the-schema-is-the-contract.md

@@ -0,0 +1,85 @@
+# 0017. The database schema is the API contract — by default, and only by default
+
+- **Status**: accepted
+- **Date**: 2026-08-28
+
+## Context
+
+The first objection this plugin meets is always the same: *it couples the API to the database.*
+Change a column and you change the API, and through it every client.
+
+The objection is real and worth answering precisely, because the imprecise answer ("it's fine
+for internal tools") concedes more than it has to and defends less than it should.
+
+## Decision
+
+The database schema is the API contract **by default**. That is the mechanism, not a shortcut,
+and it rests on three things.
+
+**The coupling is exposed, not created.** A hand-written CRUD layer over the same tables is
+coupled to exactly the same schema — it just retypes it. Rename a column there and you edit the
+model, the DTO, the mapper, the validator, the Swagger annotation and the client, in six places
+instead of one. What that layer genuinely buys is different: an indirection that lets the
+contract stay still while the schema moves. That is a real thing to want, and it is paid for
+continuously and cashed in rarely. This plugin makes the opposite bet, and states it.
+
+**It is checked, not implied.** The Schema files are generated from `information_schema`, so a
+schema change that breaks the API breaks it when you regenerate and compile — for TypeScript
+consumers, at build time. A hand-written mapper that nobody remembered to update fails in
+production instead. (Untyped clients — a browser fetch — still find out at runtime; the
+generated Swagger and `GET {prefix}/agent/manifest.md` are what they check against.)
+
+**It is a default, and every part of it is overridable.** The exposed shape is not forced to be
+the stored shape:
+
+| To decouple | Use |
+|---|---|
+| a column exists but must never be read | `readExclude` |
+| a column exists but must never be written | `writeExclude` ([ADR 0015](./0015-non-writable-columns.md)) |
+| a column must not exist for the API at all | trim it out of the Schema |
+| the API type must be stricter than the column | `schemaOverrides` |
+| the API value is derived, not stored | `computedFields` |
+| the stored representation is not the API one | `afterRead` (decrypt, unpack, rescale) |
+| a table must not have all seven routes | `operations` |
+| a relation must be named for the API, not the DB | the relation `alias`, plus its `fields` allowlist |
+| a filter has no column behind it | `extraFilters` + `extendedCondition` |
+| different callers need different surfaces | register the plugin more than once, under different prefixes |
+
+And when none of that fits, the operation is not a CRUD operation: write the route by hand and
+call `app.sqlApi.*` inside it. That is not the fallback path — it is the design. The custom
+route keeps filters, joins, tenant scoping, hooks and validation; what it does not keep is the
+assumption that the endpoint looks like a table.
+
+**Where the objection is right.** A public or third-party API — consumers you cannot redeploy
+alongside your schema, a contract with a version number and a deprecation policy — is a surface
+whose stability has to outlive refactors. There an indirection that survives schema movement
+earns its cost, and generating that surface from the schema is the wrong default. Do not
+auto-expose it: keep those tables off the auto routes with `operations`, or behind their own
+hand-written endpoints, and let the plugin serve the surface it is for.
+
+That surface is the internal one: back-office and admin tools where superadmin, admin and
+tenant-admin roles need full control over the domain, the schema *is* the domain model, and the
+people who change a column are the people who change the screen that shows it. There, the
+translation layer has no reader — it exists only to be kept in sync with the thing it
+translates.
+
+## Alternatives considered
+
+- **A mapping/DTO layer inside the plugin** — rejected: that is the hand-written layer again,
+  re-expressed as configuration instead of code, with the same maintenance cost and less
+  freedom. The per-concern levers above cover what most projects actually need to hide or
+  reshape, and a custom route covers the rest without inventing a second schema language.
+- **Frozen schema snapshots, versioned independently of the database** — rejected: a second
+  source of truth to keep in sync, which is precisely what [ADR 0001](./0001-no-orm-raw-sql.md)
+  refused when it refused an ORM's models and migrations.
+- **Saying nothing and letting readers work it out** — rejected: it is the first question every
+  reviewer asks, and an unanswered one reads as an unconsidered one.
+
+## Consequences
+
+- Renaming a column changes the API field. Accepted: it is one regeneration, and typed
+  consumers fail to compile rather than failing quietly.
+- The plugin is not the right tool for a versioned public API, and says so in the README rather
+  than leaving it to be discovered.
+- Every "the API should not look like the table" request has a specific answer in the table
+  above, or is a custom route. Neither is a gap in the plugin.

package/docs/adr/0018-one-seam-to-the-http-framework.md

@@ -0,0 +1,68 @@
+# 0018. The HTTP framework is reachable through one seam — `ApiRequest`
+
+- **Status**: accepted
+- **Date**: 2026-08-29
+
+## Context
+
+The question was what it would take to serve the same engine over something other than Fastify.
+Measuring first turned up a codebase that was already almost free of one:
+
+- of 74 files under `src/`, 26 named a Fastify type and **not one imported a value from it**;
+- **nothing under `src/lib/` ever read a property off the request** — no `body`, no `params`, no
+  `log`. It arrives from the route, is forwarded to `getTenantId`, `validate` and the hooks, and
+  is otherwise untouched;
+- `httpError` produces a plain `Error` carrying `statusCode`. Fastify happens to read that; the
+  plugin does not produce it *for* Fastify.
+
+So the engine, the schema builders and the write pipeline depend on a web framework for exactly
+one thing: the **name of a type they never dereference**. That dependency was spread across
+thirteen files, where every new hook signature quietly widened it, and nothing prevented an
+engine from starting to read `request.headers` tomorrow.
+
+## Decision
+
+The request type is declared once, in `src/types/request.ts`, and everything in the core refers
+to that name:
+
+```ts
+export type ApiRequest = FastifyRequest;
+```
+
+`.dependency-cruiser.mjs` enforces it: `http-framework-behind-one-seam` fails the build on a
+`fastify` import — **including a type-only one** — anywhere under `src/lib/`, `src/types/` or
+`src/bin/` other than that file. The two Fastify bridge helpers that lived in `lib/`
+(`setup-swagger`, `sql-api-decorator`) moved to `src/routes/`, which is where the adapter is, so
+the rule needs no exceptions.
+
+A plain alias, not a generic parameter on `ITable`. `ITable` appears as a bare type in over a
+hundred places; threading `<Req>` through all of them — and through `DbTables`, and every
+`*Params` — changes the public type surface today to buy a property that only pays off once the
+core ships as a package of its own. The alias makes the seam **one file**, which is the whole
+requirement, and leaves the generic available later without having spent anything on it now.
+
+This decision is about where the dependency lives, not about supporting a second framework. It
+records what the measurement found, and stops it from silently degrading.
+
+## Alternatives considered
+
+- **`ITable<F, Req = FastifyRequest>`** — rejected for now, as above: the churn is large, it
+  changes the public types, and mixed `DbTables` maps get awkward. It is the right shape for a
+  three-package split and can be done then, from this seam, in one file's worth of decisions.
+- **Leave `FastifyRequest` inline and write the constraint in the docs** — rejected: a property
+  that thirteen files must remember is a property that lasts until the next hook is added.
+  Gates, not documentation (ADR 0012).
+- **Make the core read nothing by typing the request as `unknown`** — rejected: it would break
+  every consumer's typed hook to express something the consumer does not need to know.
+
+## Consequences
+
+- Consumers see no change: `ApiRequest` *is* `FastifyRequest`, and it is exported from the
+  package for anyone declaring a hook outside a `defineTable` call.
+- The core cannot regress. An engine that starts naming a Fastify type fails `npm run verify`.
+- A second HTTP adapter is now a question about `src/routes/` (582 lines) plus what Fastify does
+  for free — request validation against the generated schemas, and response serialization, which
+  is part of the contract rather than plumbing — and not a question about the engine at all.
+- Fixing the rule so it could fire revealed that `no-static-optional-peer` had never been able
+  to: `includeOnly: '^src/'` dropped every npm edge from the graph. It is live now, qualified to
+  what its name says (static, value-level imports of optional peers).

package/docs/adr/README.md

@@ -27,6 +27,12 @@ not by editing history.
 | [0010](./0010-joins-do-not-run-route-guards.md) | A declared join is a read grant — joins do not run the target table's route guards |
 | [0011](./0011-join-fields-allowlist.md) | Per-relation field restriction is an allowlist, not a blocklist |
 | [0012](./0012-anti-duplication-tooling.md) | Repository rules are enforced by executable gates, not by documentation |
+| [0013](./0013-sanitized-db-errors.md) | Database error messages are sanitized on the wire by default (narrows 0006) |
+| [0014](./0014-what-follows-a-write-join.md) | A secondary runs the child table's transform, not its verdicts |
+| [0015](./0015-non-writable-columns.md) | A column the database computes is not writable — `writeExclude` (narrows 0004) |
+| [0016](./0016-a-view-is-a-table-config.md) | A view is a table config — the generator refuses to invent its primary key |
+| [0017](./0017-the-schema-is-the-contract.md) | The database schema is the API contract — by default, and only by default |
+| [0018](./0018-one-seam-to-the-http-framework.md) | The HTTP framework is reachable through one seam — `ApiRequest` |
 
 ## When to write one
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",

package/dist/lib/setup-swagger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"setup-swagger.d.ts","sourceRoot":"","sources":["../../src/lib/setup-swagger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAkB,MAAM,aAAa,CAAC;AAEvE,wBAAsB,YAAY,CAChC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CA6Bf"}

package/dist/lib/sql-api-decorator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sql-api-decorator.d.ts","sourceRoot":"","sources":["../../src/lib/sql-api-decorator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,MAAM,EAAE,MAAM,CAAC;KAChB;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,IAAI,CA2BN"}