fastify-auto-sqlapi 0.1.9 → 0.1.11

package/BREAKING_CHANGES.md

@@ -317,3 +317,66 @@ including `joinLeft.filters` / `joinLeft.conditions` and `orderBy`, which previo
 them with 400. They remain rejected in `selectComputed`, `computeMin/Max/Sum/Avg`,
 `joinGroup.aggregations.by` and `defaultOrder`, where the expression precedes the `WHERE`
 values in the parameter order.
+
+# Breaking Change — by-single-id operations disabled for composite primary keys
+
+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:
+
+- `GET /rest/:table/:id` and `DELETE /rest/:table/:id` are **not registered** (404);
+- `POST /bulk/:table/delete` is **not registered** (404);
+- explicitly listing `get`, `delete` or `bulkDelete` in `ITable.operations` for such a table
+  now **throws at startup** with a descriptive error;
+- the programmatic `sqlApi.get/delete/bulkDelete` reject with `400`.
+
+Search, insert, update and bulk upsert are unaffected — they already matched every PK column.
+
+## Why this changed
+
+These operations matched on the **first** PK column alone. On `primary: ['agentId', 'teamId']`:
+
+- `DELETE /rest/t/1` deleted **every** row with `agent_id = 1` — not one record;
+- `GET /rest/t/1` returned an arbitrary row among those sharing `agent_id = 1`;
+- bulk delete removed every row matching each listed first-column value.
+
+A single `:id` cannot address a composite key; silently matching a prefix of the key is data
+loss waiting to happen, so the operations are refused loudly instead.
+
+## Who is affected
+
+Only consumers with composite-PK tables **and** clients calling get/delete/bulk-delete on
+them. If your composite table's first PK column happens to be unique on its own, these
+endpoints previously behaved correctly for you — they are now gone and you must migrate.
+
+## Migration
+
+- **Read one record** → `search` with every PK field in the filters:
+
+  ```typescript
+  await fetch('/auto/search/agent_team', {
+    method: 'POST',
+    body: JSON.stringify({ filters: { agentId: 1, teamId: 2 } }),
+  });
+  ```
+
+- **Delete one record** → a custom route using the low-level `QueryClient`, matching the
+  full key:
+
+  ```typescript
+  import { createQueryClient, pgQueryable } from 'fastify-auto-sqlapi';
+
+  const db = createQueryClient(pgQueryable(app.pg), 'postgres');
+
+  app.delete('/agent-team/:agentId/:teamId', async (req) => {
+    const { agentId, teamId } = req.params;
+    await db.delete('agent_team', { agent_id: agentId, team_id: teamId });
+    return { main: { agentId, teamId } };
+  });
+  ```
+
+- **Row removal as part of an edit flow** → `update` on the parent with `deletions` (write
+  joins), or bulk upsert — both match every PK column.
+
+- **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.

package/CHANGELOG.md

@@ -7,6 +7,106 @@ 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)**.
 
+## [0.1.11]
+
+### Breaking
+
+- **⚠️ By-single-id operations are disabled for composite-PK tables.** `GET /rest/:id`,
+  `DELETE /rest/:id` and `POST /bulk/:table/delete` matched on the **first** PK column alone:
+  on a table with `primary: ['agentId', 'teamId']`, `DELETE /rest/t/1` deleted **every** row
+  with `agentId = 1`, not one record. These routes are no longer registered for composite-PK
+  tables (404); explicitly listing one of them in `operations` now throws at startup, and the
+  programmatic `sqlApi.get/delete/bulkDelete` reject with 400. Search, insert, update and
+  bulk upsert are unaffected — they already handled every PK column. If your composite table's
+  first PK column happens to be unique, these endpoints previously worked for you and are now
+  gone — see
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--by-single-id-operations-disabled-for-composite-primary-keys)
+  for the migration paths.
+
+### Fixed
+
+- **⚠️ NULL values were serialized as `0` / `""` in read responses.** The generator mapped
+  nullable columns to `Type.Optional(T)`, which means "key may be absent" — not "value may
+  be null" — so fast-json-stringify coerced every NULL to the type's zero value (a NULL FK
+  was served as `0`). Nullable columns are now generated as `Type.Optional(Nullable(T))`,
+  where the new exported `Nullable()` helper emits the JSON-Schema type-array form
+  (`type: ['integer', 'null']`). **Regenerate your schemas** (`sqlapi-generate-schema`) to
+  pick up the fix. Note: the type-array form is deliberate — a `Type.Union([T, Type.Null()])`
+  would NOT fix it, because Fastify's default Ajv `coerceTypes` corrupts values through
+  union branches (`null` → `0` with the Null branch last, `0`/`""` → `null` with it first);
+  with a type array no coercion happens. As a side effect, writes now accept an explicit
+  `null` to set a column to NULL.
+- **`maxItemsPerPage` below 500 broke every request without an explicit `itemsPerPage`.**
+  The search querystring schema declared a fixed `default: 500`; Ajv injects defaults before
+  the cap check runs, so any lower cap rejected the injected default with 400. The schema is
+  now parameterized: `default = min(500, maxItemsPerPage)` and the cap doubles as the schema
+  `maximum` (structured 400 instead of a plain error). The `SearchTableQuery(cap)` builder is
+  exported; `SearchTableQueryString` remains as the default-cap variant.
+
+### Changed
+
+- **`filters` with an explicit `null` now filter by `IS NULL`.** Previously a null filter
+  was silently dropped — a request asking "field is null" returned unfiltered results. An
+  explicit `null` on a schema field now builds `WHERE col IS NULL` (undefined/absent keys
+  are still ignored). `conditions` + `isNull` keeps working as before.
+
+### Added
+
+- **LLM / agent client support.** The plugin doubles as the enforcement layer for a chat
+  agent operating on your data (tenant scoping, `readExclude`, `operations`, caps apply to
+  whatever the model invents). New pieces:
+  - `AGENTS_FRONTEND.md` rewritten as a compact LLM-oriented request grammar (search with
+    all join families, ordering, pagination, writes, error shapes) — usable both by coding
+    agents and as the system prompt of a runtime agent client. Same filename and package
+    path as before, so existing references keep working; the verbose tutorial-style
+    content it replaces is fully covered by the grammar plus Swagger.
+  - `agentManifest: true` plugin option → `GET {prefix}/agent/manifest` (JSON) and
+    `/agent/manifest.md` (markdown for the system prompt): per-table fields with
+    type/required/nullable, enabled operations, join aliases with direction, computed
+    fields, extra filters — always in sync with the running config, behind the same
+    global `onRequests`. Also exported programmatically (`buildAgentManifest`,
+    `renderAgentManifestMd`) and as a granular route plugin (`agentManifestRoutes`).
+  - `agentToolSchemas(dbTables, table)` — the exact JSON Schemas the routes validate
+    with, per enabled operation, for strict provider-side tool definitions.
+  - README "LLM / agent clients" section and AGENTS_BACKEND.md pattern: read-only agent
+    surface via granular composition, loose-tool + structured-400 retry loop vs strict
+    tools.
+- `Nullable(schema)` export: marks a TypeBox schema nullable via the JSON-Schema type-array
+  form — the only representation safe under Fastify's default Ajv/fast-json-stringify on
+  both input validation and response serialization.
+- ADR 0007: table generation is explicit — `--all` is a migration helper, not the default.
+
+## [0.1.10]
+
+### Added
+
+- **Architecture Decision Records** in `docs/adr/` (shipped in the npm package so agents
+  consuming the library can read them): no-ORM/raw-SQL, open-by-default, non-transactional
+  bulk operations, always-updatable fields (no `excludeFromUpdate`), insert-pipeline
+  ordering, raw DB errors. Linked from README ("Design Decisions") and AGENTS.md.
+
+### Fixed
+
+- **`excludeFromCreation` no longer strips values set by `beforeInsert`.** The exclusion list
+  was applied after the hook, so a server-generated value assigned in `beforeInsert` (the
+  documented pattern for TEXT primary keys, `createdAt`, audit columns) was silently removed
+  from the INSERT — a table with `excludeFromCreation: ['id']` and an id-generating hook
+  failed with a not-null violation. The client payload is now sanitized *before* the hook
+  runs, in both the single insert and the bulk upsert path: client-supplied values on
+  excluded fields are still ignored, hook-assigned ones reach the SQL. For the same reason,
+  secondary records now drop excluded fields *before* the engine's FK auto-fill, so listing
+  the FK column in a secondary table's `excludeFromCreation` no longer erases the injected
+  parent key.
+
+### Documentation
+
+- Clarified that `excludeFromCreation` is an ergonomics tool for creation, not a field-level
+  security mechanism: it deliberately does not apply to updates, where every Schema field is
+  writable by default. Field-level update rules (sensitive flags, roles, ownership/tenant
+  columns) are product logic to enforce via `beforeUpdate`/`validate` or dedicated endpoints —
+  see the new "Field-level update rules" section in the README and the matching pattern in
+  AGENTS_BACKEND.md.
+
 ## [0.1.7]
 
 ### Fixed

package/README.md

@@ -4,18 +4,9 @@ Automatic CRUD API generation from PostgreSQL, MySQL, and MariaDB tables for [Fa
 
 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.
 
-## What LLMs Are Saying
-
-> API: 5 new read-only tables — and this is where your plugin really shined.
-
-> Yes, it genuinely saved me a lot of work, and the numbers make that obvious: I deleted about 350 lines of hand-written API repository and route code, replacing them with roughly 150 lines of declarative configuration. And it wasn't a one-for-one trade. In return, I gained features I simply didn't have before: complete Swagger documentation, the conditions DSL (previously I only had sorting and fixed filters), pagination with total counts, structured 400 errors, and consistent camelCase conversion. 
-
-> The moment I thought, "Okay, this is well designed," was when I used computedFields: the case of "attributes stored inside a jsonb column that still need to be sortable and filterable" is exactly the kind of problem that usually forces you to step outside the framework, yet it fit in cleanly. It worked end-to-end with the role-based CASE expression, remained sortable, could be projected with selectComputed, and required zero SQL in the routes.
-
-> The AGENTS files deserve a mention: I configured everything without ever opening the source code—CLI schema, defineTable, buildRelation, computed, extraFilters, and the frontend request/response shapes. As "documentation for agents," they genuinely work, and that's more than I can say for most libraries.
-
 ## Features
 
+- **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
@@ -33,54 +24,105 @@ Point it at your database, and get a full REST API with search, advanced conditi
 > **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** for migration guides. If you use `computedFields`
 > 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
 
 ```bash
 npm install fastify-auto-sqlapi fastify @fastify/postgres
+# MySQL/MariaDB: npm install fastify-auto-sqlapi fastify mysql2
 ```
 
 ### 2. Create the config file
 
-Create `sqlapi.config.ts` in your project root. This is used only by the CLI generators, not at runtime.
+Create `sqlapi.config.ts` (or `.mjs`/`.js`) in your project root. This is used only by the
+CLI generators, not at runtime.
 
 ```typescript
 export default {
-  outputDir: './src/schemas',  // where to generate Schema files
-  schema: 'public',            // PostgreSQL schema to introspect
+  outputDir: './src/db',       // base dir for generated files (default: './src/db')
+  schema: 'public',            // PostgreSQL schema to introspect (default: 'public')
+  // dialect: 'mysql',         // 'postgres' (default) | 'mysql' | 'mariadb'
+  // envFile: '.env.local',    // env file to load (default: '.env')
 };
 ```
 
-The DB connection is read from environment variables:
+The DB connection is read from environment variables (a `.env` file in the project root is
+loaded automatically, without overriding variables already set):
 
 ```bash
 # Either a full connection string:
-DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb   # or mysql://...
 
-# Or individual vars:
+# Or individual vars (PostgreSQL):
 POSTGRES_HOST=127.0.0.1
 POSTGRES_PORT=5432
 POSTGRES_USER=myuser
 POSTGRES_PASSWORD=mypassword
 POSTGRES_DB=mydb
+
+# Or individual vars (MySQL/MariaDB):
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=myuser
+MYSQL_PASSWORD=mypassword
+MYSQL_DB=mydb
 ```
 
 ### 3. Generate schemas from your database
 
 ```bash
-npx sqlapi-generate-schema
+npx sqlapi-generate-schema                  # all tables
+npx sqlapi-generate-schema --tables customer,order   # only some
+npx sqlapi-generate-schema --dialect mysql  # override the config dialect
 ```
 
-This introspects your tables and generates one TypeBox schema file per table (e.g. `SchemaCustomer.ts`, `SchemaOrder.ts`). These files are auto-generated — don't edit them.
+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.
 
 ### 4. Generate the tables template
 
 ```bash
-npx sqlapi-generate-tables
+npx sqlapi-generate-tables --all            # or: npx sqlapi-generate-tables customer order
 ```
 
-This creates a `tables.ts` file with a `defineTable()` call for each table. It auto-detects primary keys, foreign key relations, and lays out all available options as commented code. **This file is yours to customize.**
+This creates in `<outputDir>/tables/` one `Table*.ts` file per table — a `defineTable()`
+call with auto-detected primary keys, foreign key relations, and all available options as
+commented code — plus a `dbTables.ts` index. **These files are yours to customize**: the
+generator never overwrites an existing file, so re-running it only adds files for new tables.
 
 ### 5. Register the plugin
 
@@ -88,7 +130,7 @@ This creates a `tables.ts` file with a `defineTable()` call for each table. It a
 import Fastify from 'fastify';
 import fastifyPostgres from '@fastify/postgres';
 import { fastifyAutoSqlApi } from 'fastify-auto-sqlapi';
-import { dbTables } from './src/schemas/tables.js';
+import { dbTables } from './src/db/tables/dbTables.js';
 
 const app = Fastify();
 
@@ -156,7 +198,8 @@ const TableCustomer = defineTable({
 
   // Ordering & filtering
   defaultOrder: 'name',                     // default ORDER BY (camelCase fields map to DB columns)
-  excludeFromCreation: ['id'],              // omit from INSERT (e.g. auto-increment)
+  excludeFromCreation: ['id'],              // client-sent values ignored on INSERT (auto-increment,
+                                            // DB defaults); beforeInsert can still set them
   readExclude: ['passwordHash'],            // hide from all reads (writes unaffected)
   distinctResults: true,                    // SELECT DISTINCT
 
@@ -269,7 +312,20 @@ await app.register(fastifyAutoSqlApi, {
 | `maxBulkItems` | `number` | No | Max number of items accepted by the bulk endpoints (default: `1000`) |
 | `debug` | `boolean` | No | Log all SQL queries to console |
 
-For MySQL/MariaDB, register `mysql2/promise` pool instead of `@fastify/postgres` and pass `dialect: 'mysql'` or `'mariadb'`.
+The plugin picks up the connection from the Fastify instance: `fastify.pg` for PostgreSQL
+(what `@fastify/postgres` decorates) or `fastify.mysql` for MySQL/MariaDB. For MySQL,
+decorate a `mysql2/promise` pool (e.g. via `@fastify/mysql` with `promise: true`, or manually)
+and pass `dialect: 'mysql'` or `'mariadb'`:
+
+```typescript
+import mysql from 'mysql2/promise';
+
+const pool = mysql.createPool({ host: '127.0.0.1', user: 'myuser', password: '...', database: 'mydb' });
+app.decorate('mysql', pool);
+app.addHook('onClose', async () => { await pool.end(); });
+
+await app.register(fastifyAutoSqlApi, { DbTables: dbTables, dialect: 'mysql' });
+```
 
 ## Security
 
@@ -333,6 +389,42 @@ only columns present in the generated Schema (as narrowed by `schemaOverrides` /
 column — the Schema is the write whitelist. Trim the generated Schema (or use `excludeFromCreation`)
 to keep sensitive columns out of it.
 
+### Field-level update rules are product logic — use the hooks
+
+`excludeFromCreation` is an **ergonomics tool for creation**, not a security mechanism: it
+exists so auto-generated values (serial PKs, DB-default timestamps) don't have to be sent —
+or validated — on insert. It deliberately does **not** apply to updates: every field in the
+Schema is updatable by default, because whether a field may change is a product decision the
+plugin cannot make for you (a super admin may legitimately fix an `updatedAt`; in one product
+users may move themselves across tenants, in another nobody may).
+
+So watch out for **sensitive flags and ownership fields** — `isAdmin`, `role`, tenant/owner
+columns, state fields: if they are in the Schema, the auto-generated update route will accept
+them. Encode your rules with the tools made for it:
+
+```typescript
+// Silent strip: non-admins simply cannot touch the flag
+beforeUpdate: async (db, req, fields) => {
+  if (!req.user.isAdmin) delete fields.isAdmin;
+},
+
+// Loud 400: touching the flag without permission is an error
+validate: async (db, req, main) => {
+  if (main.isAdmin !== undefined && !req.user.isAdmin)
+    return [['isAdmin', 'forbidden']];
+  return [];
+},
+```
+
+For privileged state transitions (promoting an admin, moving a record across tenants) consider
+a dedicated endpoint with its own auth and audit instead of the auto-generated CRUD route —
+`operations` lets you keep the sensitive operation off the auto routes entirely.
+
+Note on tenants: when `tenantScope` is active, tenant-scoped callers can never move a record to
+another tenant (the tenant column is enforced server-side); admin callers (`getTenantId` →
+`null`) are unrestricted. That is the isolation contract of the opt-in tenancy feature, not a
+field-level rule.
+
 ### Read visibility
 
 `readExclude` hides columns from every read while leaving writes untouched — the case for a
@@ -444,6 +536,13 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 
 Returns `{ main: { ... } }` or 404.
 
+> **Composite primary keys:** `GET /rest/:id`, `DELETE /rest/:id` and `POST /bulk/:table/delete`
+> address a record by a single PK value, so they are **not registered** for tables whose
+> primary key spans multiple columns (a match on the first column alone could hit many rows —
+> for the deletes, destructively). Explicitly listing one of these operations in `operations`
+> for such a table throws at startup. Use `search` with all PK fields in the filters, `update`
+> (which matches every PK column), or a custom route.
+
 ### POST /rest/{table}
 
 **Body:**
@@ -471,7 +570,7 @@ Returns `{ main: { ... } }` or 404.
 > ),
 > // → PUT /rest/product { "main": {...}, "secondaries": { "translations": [{ "lang": "en", "name": "Bike" }] } }
 > ```
-> Expose a composite-PK table as a standalone CRUD table only when it stands on its own (M:N link tables, natural keys) — composite PKs are fully supported there too.
+> Expose a composite-PK table as a standalone CRUD table only when it stands on its own (M:N link tables, natural keys) — search, insert, update and bulk upsert fully support composite PKs; the by-single-id routes (get, delete, bulkDelete) are skipped for them (see the note under GET).
 
 **Response (201):** `{ main: { ... }, secondaries: { ... } }`
 
@@ -491,7 +590,8 @@ Returns `{ main: { ... } }` or 404.
 
 ### DELETE /rest/{table}/:id
 
-Returns the deleted record or 404.
+**Response (200):** `{ main: { <pk>: ... } }` (PK-only, like all write responses), or `404` if
+the record does not exist.
 
 ### PUT /bulk/{table}
 
@@ -621,6 +721,68 @@ await app.register(async (instance) => {
 }, { prefix: '/admin' });
 ```
 
+## LLM / agent clients
+
+The plugin is a natural enforcement layer for an agent that operates on your data through
+chat: whatever requests the LLM invents, they pass through the same tenant scoping,
+`readExclude`, `operations` whitelist, validation and request caps as any HTTP client —
+direct-DB firepower, backoffice constraints. Three pieces make this practical:
+
+**1. The grammar** — [`AGENTS_FRONTEND.md`](./AGENTS_FRONTEND.md) (ships in the npm package)
+is a compact, LLM-oriented reference of how to call the API: search with all four join
+families, ordering, pagination, writes, error shapes. Put it in the system prompt.
+
+**2. The vocabulary** — enable the manifest endpoint to describe *this deployment's* tables:
+
+```typescript
+await app.register(fastifyAutoSqlApi, {
+  DbTables: dbTables,
+  agentManifest: true,   // GET {prefix}/agent/manifest (JSON) + /agent/manifest.md
+});
+```
+
+`GET /agent/manifest.md` returns a compact markdown block per table — fields with
+type/required/nullable, enabled operations, join aliases (with direction), computed fields,
+extra filters — always in sync with the running config, behind the same `onRequests` auth.
+Fetch it at session start: grammar + vocabulary is everything the model needs. The same data
+is available programmatically via `buildAgentManifest(dbTables)` /
+`renderAgentManifestMd(manifest)`.
+
+**3. The guardrails** — writes are often too dangerous to hand to a model. Register a
+read-only surface with granular composition and give the agent only that:
+
+```typescript
+import { searchRoutes, getRoutes, agentManifestRoutes } from 'fastify-auto-sqlapi';
+
+await app.register(async (instance) => {
+  const opts = { DbTables: dbTables, onRequests: [agentAuth] };
+  await instance.register(searchRoutes, opts);
+  await instance.register(getRoutes, opts);
+  await instance.register(agentManifestRoutes, opts);
+}, { prefix: '/agent' });   // reads only: no insert/update/delete routes exist here
+```
+
+**Validation strategy** — two options, per table or per deployment:
+
+- *Loose tool + retry loop* (recommended default): expose a generic tool
+  (`table` as enum from the manifest, `body` as free object) and let the plugin validate.
+  A failed request returns a structured 400 with `fields: [{path, code, message}]` — feed
+  it back to the model and it self-corrects in one round trip. Cheap prompts, no schema
+  duplication.
+- *Strict tools*: `agentToolSchemas(dbTables, 'customer')` returns the exact JSON Schemas
+  the routes validate with (body + querystring for search, bodies for writes, only for the
+  operations enabled on that table) — plug them into provider-side tool definitions when
+  you want invalid calls rejected before they leave the model. Costs prompt size; best for
+  a few hot tables.
+
+## Design Decisions
+
+Deliberate, non-obvious choices — open-by-default, non-transactional bulk operations,
+always-updatable fields, raw DB errors, insert-pipeline ordering — are recorded as
+[Architecture Decision Records in `docs/adr/`](./docs/adr/README.md), each with its
+rationale and the alternatives that were rejected. Read them before filing an issue that
+proposes changing one of these behaviors.
+
 ## Conventions
 
 - **camelCase everywhere in the API** — requests, responses, `validate`, and all hooks (`beforeInsert`/`afterInsert`, `beforeUpdate`/`afterUpdate`, `beforeDelete`/`afterDelete`, `beforeBulkDelete`/`afterBulkDelete`) use schema field names
@@ -629,6 +791,8 @@ await app.register(async (instance) => {
 - **`joinMustExist` / `joinMultiple` / `joinGroup`** are 1:N (child→main) and use side queries / EXISTS / correlated subqueries — no row duplication
 - **`joinLeft`** is N:1 (parent→main) and adds a real `LEFT JOIN` on demand (only when filtering/ordering by parent)
 - **All response fields are Optional** — response schemas use `Type.Partial` since `RETURNING *` may return any subset
+- **Nullable columns use `Nullable(T)`** — the generator emits the JSON-Schema type-array form (`type: ['integer', 'null']`) via the exported `Nullable()` helper. This is deliberate: a bare `Type.Optional(T)` serializes NULL as `0`/`""`, and a `Type.Union([T, Type.Null()])` gets corrupted by Ajv's default type coercion (`null` ↔ `0`/`""` through the branches). In `filters`, an explicit `null` filters by `IS NULL`
+- **The `pg` driver returns `numeric`/`int8` as strings** and parses timestamps into local-timezone `Date`s — driver defaults the plugin deliberately does not override (global state). See "PostgreSQL driver type parsers" in AGENTS_BACKEND.md for the recommended one-time setup
 
 ## Re-exports
 
@@ -647,6 +811,7 @@ import {
   buildRelation,
   buildUpsertRule,
   buildUpsertRules,
+  Nullable,               // type-array nullable schema (see Conventions)
 
   // DB layer
   QueryClient,            // raw SQL query helper

package/dist/index.d.ts

@@ -4,13 +4,17 @@ export { getDialect, type SqlDialect, type DialectName } from './lib/dialect.js'
 export { pgQueryable } from './lib/adapters/pg-adapter.js';
 export { mysqlQueryable } from './lib/adapters/mysql-adapter.js';
 export { exportTableInfo, defineTable, buildRelation, buildUpsertRule, buildUpsertRules } from './lib/table-helpers.js';
+export { Nullable } from './lib/nullable.js';
+export { buildAgentManifest, renderAgentManifestMd, type AgentManifest, type ManifestTable, } from './lib/agent/manifest.js';
+export { agentToolSchemas, type AgentToolSchemas } from './lib/agent/tool-schemas.js';
+export { default as agentManifestRoutes } from './routes/auto/agent-manifest.routes.js';
 export { resolveTenant } from './lib/tenant.js';
 export { SqlApi, createSqlApi } from './lib/sql-api.js';
 export type { SqlApiOptions, SqlApiSearchParams, SqlApiInsertParams, SqlApiUpdateParams } from './lib/sql-api.js';
 export { default as fastifyAutoSqlApi } from './routes/auto/plugin.js';
 export { setupSwagger } from './lib/setup-swagger.js';
 export { searchEngine } from './lib/engine/search/search.js';
-export { SearchTableBodyPost, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
+export { SearchTableBodyPost, SearchTableQuery, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
 export { default as searchRoutes } from './routes/auto/search.routes.js';
 export { insertEngine } from './lib/engine/rest/insert.js';
 export { InsertTableBody, InsertTableResponse } from './lib/schema/insert.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -9,6 +9,11 @@ export { pgQueryable } from './lib/adapters/pg-adapter.js';
 export { mysqlQueryable } from './lib/adapters/mysql-adapter.js';
 // Table helpers
 export { exportTableInfo, defineTable, buildRelation, buildUpsertRule, buildUpsertRules } from './lib/table-helpers.js';
+export { Nullable } from './lib/nullable.js';
+// Agent / LLM client helpers
+export { buildAgentManifest, renderAgentManifestMd, } from './lib/agent/manifest.js';
+export { agentToolSchemas } from './lib/agent/tool-schemas.js';
+export { default as agentManifestRoutes } from './routes/auto/agent-manifest.routes.js';
 // Tenant
 export { resolveTenant } from './lib/tenant.js';
 // SqlApi — programmatic high-level API
@@ -19,7 +24,7 @@ export { default as fastifyAutoSqlApi } from './routes/auto/plugin.js';
 export { setupSwagger } from './lib/setup-swagger.js';
 // Search
 export { searchEngine } from './lib/engine/search/search.js';
-export { SearchTableBodyPost, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
+export { SearchTableBodyPost, SearchTableQuery, SearchTableQueryString, SearchTableResponse } from './lib/schema/search.js';
 export { default as searchRoutes } from './routes/auto/search.routes.js';
 // Insert
 export { insertEngine } from './lib/engine/rest/insert.js';

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

@@ -0,0 +1,53 @@
+import type { DbTables, ITable, TableOperation } from '../../types.js';
+export interface ManifestField {
+    type: string;
+    /** Present (true) when the field must be sent on insert. */
+    required?: boolean;
+    /** Present (true) when the column accepts null. */
+    nullable?: boolean;
+    /** Present (true) when the field is writable but never returned by reads (readExclude). */
+    writeOnly?: boolean;
+}
+export interface ManifestJoin {
+    alias: string;
+    table: string;
+    /** '1:N' → usable in joinMustExist/joinMultiple/joinGroup; 'N:1' → usable in joinLeft. */
+    kind: '1:N' | 'N:1';
+}
+export interface ManifestTable {
+    /** URL segment for this table's routes. */
+    table: string;
+    primary: string | string[];
+    operations: TableOperation[];
+    fields: Record<string, ManifestField>;
+    /** Fields stripped from client input on insert (server-generated: PKs, timestamps). */
+    serverGenerated?: string[];
+    /** Computed (virtual) fields: usable in filters/conditions/orderBy/selectComputed. */
+    computed?: Record<string, string>;
+    /** Extra filter names accepted in `filters` beyond schema fields. */
+    extraFilters?: Record<string, string>;
+    readJoins?: ManifestJoin[];
+    /** Aliases accepted as `secondaries`/`deletions` keys in writes. */
+    writeJoins?: ManifestJoin[];
+    /** Present (true) when rows are automatically scoped to the caller's tenant. */
+    tenantScoped?: boolean;
+    defaultOrder?: string;
+}
+export interface AgentManifest {
+    tables: Record<string, ManifestTable>;
+}
+export declare function tableOperations(tableConf: ITable): TableOperation[];
+/**
+ * Build the machine-readable description of every table exposed by this deployment:
+ * fields (type/required/nullable), enabled operations, join aliases, computed fields,
+ * extra filters, tenant scoping. Derived entirely from `DbTables`, so it is always in
+ * sync with the running configuration. Pairs with AGENTS_FRONTEND.md (the request grammar)
+ * to give an LLM client everything it needs to drive the API.
+ */
+export declare function buildAgentManifest(dbTables: DbTables): AgentManifest;
+/**
+ * Compact markdown rendering of the manifest, designed for an LLM system prompt.
+ * Notation: `!` required on insert, `?` nullable, `(writeOnly)` never returned by reads.
+ */
+export declare function renderAgentManifestMd(manifest: AgentManifest): string;
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +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"}