@kequtech/tenon-orm 0.1.0 → 0.1.2

package/dist/safeql/mutations.js

@@ -0,0 +1,74 @@
+import ts from 'typescript';
+import { assignmentLayout, insertLayout, mutationColumns } from '../mutations.js';
+import { CompositionError, isUndefined, literalString, unwrap } from './static.js';
+const parameter = 0;
+function fields(input) {
+    const node = unwrap(input);
+    if (!ts.isObjectLiteralExpression(node)) {
+        throw new CompositionError('Mutation inputs need inline object literals or an explicit literal column list.');
+    }
+    const result = new Map();
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) {
+            throw new CompositionError('Mutation object spreads, accessors, and methods need an explicit literal column list.');
+        }
+        const name = property.name;
+        if (!ts.isIdentifier(name) && !ts.isStringLiteral(name) && !ts.isNumericLiteral(name)) {
+            throw new CompositionError('Mutation keys must be literal names; use an explicit literal column list.');
+        }
+        if (name.text === '__proto__')
+            throw new CompositionError('Prototype-setting object literals are unsupported mutation inputs.');
+        if (result.has(name.text))
+            throw new CompositionError('Duplicate mutation object keys are unsupported.');
+        result.set(name.text, ts.isPropertyAssignment(property) ? property.initializer : property.name);
+    }
+    return result;
+}
+/** Understand the official mutation contract, never the implementation of a JavaScript helper. */
+export function renderMutation(kind, node, checker) {
+    if (node.questionDotToken ||
+        node.arguments.some(ts.isSpreadElement) ||
+        node.arguments.length < 1 ||
+        node.arguments.length > 2) {
+        throw new CompositionError(`sql.${kind} requires an input and an optional literal column list.`);
+    }
+    try {
+        const [argument, selected] = node.arguments;
+        let columns;
+        let rows;
+        if (selected && !isUndefined(selected, checker)) {
+            const list = unwrap(selected);
+            if (!ts.isArrayLiteralExpression(list))
+                throw new CompositionError('Mutation columns must be an inline literal array.');
+            columns = mutationColumns(list.elements.map((item) => {
+                const column = literalString(item, checker);
+                if (column === undefined)
+                    throw new CompositionError('Mutation columns must be literal strings or const strings.');
+                return column;
+            }));
+            // A fixed column contract covers any nonempty batch and every omitted/default cell.
+            // Check all selected columns conservatively; no runtime data or JS types become SQL.
+            rows = [columns.map(() => parameter)];
+        }
+        else {
+            const value = unwrap(argument);
+            const objects = kind === 'insertValues' && ts.isArrayLiteralExpression(value)
+                ? value.elements.map(fields)
+                : [fields(value)];
+            columns = [
+                ...new Set(objects.flatMap((row) => [...row].filter(([, value]) => !isUndefined(value, checker)).map(([key]) => key))),
+            ];
+            rows = objects.map((row) => columns.map((column) => {
+                const cell = row.get(column);
+                return !cell || isUndefined(cell, checker) ? undefined : parameter;
+            }));
+        }
+        const parts = kind === 'insertValues' ? insertLayout(columns, rows) : assignmentLayout(columns, rows[0]);
+        return parts.map((part) => (typeof part === 'string' ? part : '$N')).join('');
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new CompositionError(`sql.${kind}: ${error instanceof CompositionError ? error.detail : error.message}`);
+    }
+}

package/dist/safeql/static.d.ts

@@ -0,0 +1,10 @@
+import ts from 'typescript';
+export declare class CompositionError extends Error {
+    readonly detail: string;
+    readonly name = "TenonCompositionError";
+    constructor(detail: string);
+}
+export declare function unwrap(node: ts.Node): ts.Node;
+export declare function initializer(node: ts.Identifier, checker: ts.TypeChecker): ts.Expression | undefined;
+export declare function literalString(node: ts.Node, checker: ts.TypeChecker): string | undefined;
+export declare function isUndefined(node: ts.Node, checker: ts.TypeChecker): boolean;

package/dist/safeql/static.js

@@ -0,0 +1,59 @@
+import ts from 'typescript';
+export class CompositionError extends Error {
+    detail;
+    name = 'TenonCompositionError';
+    constructor(detail) {
+        super(`Tenon cannot statically check this composition: ${detail} Use a static query/fragment, or an explicit lint suppression with database tests for every runtime variant.`);
+        this.detail = detail;
+    }
+}
+export function unwrap(node) {
+    while (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isTypeAssertionExpression(node))
+        node = node.expression;
+    return node;
+}
+export function initializer(node, checker) {
+    let symbol = checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+        symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    return declaration &&
+        ts.isVariableDeclaration(declaration) &&
+        ts.isVariableDeclarationList(declaration.parent) &&
+        declaration.parent.flags & ts.NodeFlags.Const
+        ? declaration.initializer
+        : undefined;
+}
+/** Follow immutable const aliases only. Never inspect functions or evaluate expressions. */
+function constant(node, checker) {
+    const seen = new Set();
+    node = unwrap(node);
+    while (ts.isIdentifier(node)) {
+        if (seen.has(node))
+            throw new CompositionError('Circular const reference.');
+        if (seen.size >= 1000)
+            throw new CompositionError('Const resolution exceeds 1000 references.');
+        seen.add(node);
+        const value = initializer(node, checker);
+        if (!value)
+            break;
+        node = unwrap(value);
+    }
+    return node;
+}
+export function literalString(node, checker) {
+    const value = constant(node, checker);
+    return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+        ? value.text
+        : undefined;
+}
+export function isUndefined(node, checker) {
+    const value = constant(node, checker);
+    return (ts.isIdentifier(value) &&
+        value.text === 'undefined' &&
+        !checker.getSymbolAtLocation(value)?.declarations?.length);
+}

package/docs/adoption-guide.md

@@ -11,10 +11,10 @@ queries or generate types; keep the existing migration runner if that is the int
 1. Locate the old ORM's connection setup, schema, migrations, and call sites. Identify behavior
    supplied by the ORM: validation, IDs, timestamps, hooks, defaults, relation loading,
    serialization, and transaction boundaries.
-2. If table row types will help your application, generate them from the existing database:
+2. If row and mutation input types will help your application, generate them from the existing database:
 
    ```sh
-   npx tenon generate --out src/generated-schema.ts
+   npx tenon generate --out src/generated-schema.d.ts
    ```
 
    Use `--namespace name` for a non-public schema. Generation reads the actual database and requires
@@ -25,14 +25,107 @@ queries or generate types; keep the existing migration runner if that is the int
    Generated types describe pg values: check bigint/numeric strings, dates, JSON, and arrays when
    the old ORM transformed them.
 4. If using optional SQL checking, configure the
-   [SafeQL integration](reference.md#sql-checking-with-safeql) to generate query annotations and
-   check them against the intended schema. Run tests against a dedicated test database. Verify
+   [SafeQL integration](reference.md#sql-checking-with-safeql) and follow the
+   [incremental audit workflow](#adopt-sql-checking-incrementally) below before accepting generated
+   annotations. Run tests against a dedicated test database. Verify
    writes and rollback, relationships, validation, and any hooks you moved into application code or
    SQL. A schema-preserving first release makes application rollback easier.
 5. Remove the old runtime dependency and unused generated code after its callers are gone. Keep the
    migration tooling until the migration transition below is complete, if that transition is part of
    the work.
 
+## Replace local write helpers
+
+Use `sql.insertValues(rows)` and `sql.assignments(patch)` in place of local object-to-SQL utilities:
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+
+const insert = sql`INSERT INTO profiles ${sql.insertValues(rows)} RETURNING id`;
+const update = sql`UPDATE profiles SET ${sql.assignments(patch)} WHERE id = ${id}`;
+```
+
+Compare omission, defaults, nulls, and empty-input behavior with the old helpers. Keep expressions
+in SQL and remove the local utilities after their callers move. Generated `Rows.Insert` and
+`Rows.Update` types can replace handwritten table inputs; retain application-specific refinements
+and validation. Run the existing write and rollback workflows. See the [mutation cookbook](mutations.md).
+
+## Adopt SQL checking incrementally
+
+For an existing application, including Next.js, SQL checking can run as a separate audit while the
+normal lint/build commands keep their existing database requirements. Extend the existing flat
+ESLint configuration rather than replacing it. After installing the
+[checking dependencies](reference.md#install-and-configure), a single-database setup can use:
+
+```js
+// eslint.sql.config.mjs
+import { defineConfig } from 'eslint/config';
+import baseConfig from './eslint.config.mjs';
+import safeql from '@ts-safeql/eslint-plugin/config';
+import tseslint from 'typescript-eslint';
+import { safeqlPlugin, eslintPlugin } from '@kequtech/tenon-orm/safeql';
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) throw new Error('DATABASE_URL is required for SQL checking');
+
+export default defineConfig(baseConfig, {
+  files: ['src/**/*.ts', 'src/**/*.tsx'],
+  languageOptions: {
+    parser: tseslint.parser,
+    parserOptions: { projectService: true },
+  },
+  plugins: { tenon: eslintPlugin },
+  rules: { 'tenon/check-composition': 'error' },
+  extends: [
+    safeql.configs.connections({
+      databaseUrl,
+      plugins: [safeqlPlugin],
+      targets: [{ tag: { regex: '.*' } }],
+    }),
+  ],
+});
+```
+
+Preserve existing type-aware parser settings where configured. The broad target above lets Tenon
+recognize aliases; use distinct targets for [multiple databases](reference.md#configuration-choices-and-multiple-databases).
+The example does not load environment files. Use the application's existing environment loader
+and URL selection to supply its migrated development/test database through `DATABASE_URL`.
+
+```json
+{
+  "scripts": {
+    "lint:sql": "eslint --config eslint.sql.config.mjs \"src/**/*.{ts,tsx}\""
+  }
+}
+```
+
+Start with `npm run lint:sql`. Keep both checking rules enabled and distinguish the findings:
+
+- SQL errors identify problems in reconstructed SQL; review them before accepting inferred types.
+- Missing/mismatched annotations may reflect an outdated type, a deliberate application refinement,
+  or a checker limitation. They are not all demonstrated application bugs.
+- `tenon/check-composition` means SQL analysis was skipped. Add inline selected columns for opaque
+  mutation inputs where useful. Keep reusable authorization policy centralized when its fragments
+  remain unsupported, with database tests for runtime variants.
+
+Preview fixes on a small module first, without writing source. Invoke ESLint directly to select
+one file, since the script above already supplies a source glob:
+
+```sh
+npx eslint --config eslint.sql.config.mjs src/database/profiles.ts --fix-dry-run --format json
+```
+
+Review the proposed annotations, apply selected changes deliberately, and run TypeScript and
+database tests. Broader inferred types may require validation where raw database values enter the
+application. For example, require a finite `Date` before calling `.getTime()`, validate structured
+JSON from `unknown`, and justify CHECK-constrained string refinements with matching schema checks
+or a reviewed column override. Do not globally map timestamps to `Date`: pg can return numeric
+infinities. See [checker mappings](reference.md#supported-sql-and-limitations).
+
+Unsupported queries have not had their SQL verified. Keep database tests for their runtime variants
+and use explained suppressions only where appropriate. Once the intended scope passes, make SQL
+checking a required CI step. Fix commands can also apply other enabled ESLint rules.
+
 ## Move migration ownership to Tenon
 
 Choose one final schema checkpoint for the old runner and bring existing target databases to it.

package/docs/agent-guide.md

@@ -1,7 +1,7 @@
 # Tenon agent guide
 
 Tenon executes PostgreSQL SQL through `pg`, with parameter binding, transactions, optional write
-limits, SQL migrations, and generated table row types. Use ordinary functions for reusable queries.
+limits, SQL migrations, and generated row and mutation input types. Use ordinary functions for reusable queries.
 This guide contains the setup and contracts needed for routine implementation; the
 [reference](reference.md) covers additional options.
 
@@ -108,12 +108,33 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
 
 `pattern` and `limit` are validated application inputs. To compose existing predicates, use
 `sql.join([first, second], 'AND')`. The checker supports literal join arrays, constant fragments,
-and literal/const-string separators. It rejects mutable, conditional, function-generated, or
-runtime-built composition. Prefer fixed SQL for simple optional filters, e.g.
+literal/const-string separators, and [official mutation helpers](reference.md#object-based-mutation-fragments).
+It rejects mutable or runtime-dependent SQL structure. Prefer fixed SQL for simple optional filters, e.g.
 `(${email}::text IS NULL OR email = ${email})`. If runtime composition is required, retain an
 explicit result type, suppress `tenon/check-composition` only on that query with a reason, and test
 each branch. Parameter binding alone does not establish result correctness.
 
+## Object-based writes
+
+Use official `sql.insertValues(rowOrRows, columns?)` and `sql.assignments(patch, columns?)` fragments
+instead of application helpers that enumerate object keys. Keep tables, authorization predicates,
+expressions, conflict behavior and `RETURNING` visible in SQL. Insert missing/undefined fields use
+PostgreSQL defaults; update missing/undefined fields are omitted. Explicit null stays null. Empty
+batches/updates throw; a single default-only insert works. Omit generated columns and batch large
+writes explicitly below the query-wide limit of 65,535 parameters. Expressions and queries are
+rejected as cell values; write arithmetic, `DEFAULT`, and `excluded.column` in the surrounding SQL.
+
+Use generated `Rows.Insert['table']` and `Rows.Update['table']` for mutation inputs when available;
+narrow editable fields with `Pick`. They account for defaults, nullability, domains, and generated
+columns. Write mappings differ from returned rows: timestamps use `Date | string`, bigint uses
+`string | bigint`, and JSON uses serialized text. See the [input types](reference.md#insert-and-update-inputs).
+
+SafeQL reads inline object/array literals directly. Runtime inputs, spreads and data-builder results
+need explicit inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`. Checking
+uses all selected columns conservatively, without interpreting application JavaScript. It verifies
+SQL and result annotations, not input values, constraints, or nonempty runtime input. See the
+[mutation contract](reference.md#object-based-mutation-fragments) and [cookbook](mutations.md).
+
 ## Configure and run SQL checking
 
 SafeQL checks SQL against the development/test schema and generates or verifies result annotations.
@@ -124,10 +145,8 @@ Configure it normally and add both exports from `@kequtech/tenon-orm/safeql`:
 - `eslintPlugin` goes in ESLint's `plugins`, with `tenon/check-composition` enabled. It reports
   unsupported forms that the adapter skips. It does not wrap SafeQL's rule.
 
-These tools are optional development tooling; the database runtime does not import them. SafeQL,
-ESLint, and TypeScript are optional peers. The application owns the TypeScript parser configuration
-and imports SafeQL and typescript-eslint itself. Use a TypeScript version supported by the lint
-toolchain. Generated table types are optional and not required by SafeQL.
+These tools run during development and CI. Reuse the application's TypeScript parser settings and
+use a TypeScript version supported by the lint toolchain. Generated table types are optional.
 
 Reuse existing configuration and scripts. For a new setup:
 
@@ -186,6 +205,9 @@ Reuse existing lint scripts or add:
 SQL and annotation errors come from `@ts-safeql/check-sql`; unsupported composition errors come from
 `tenon/check-composition`. Keep both rules enabled.
 
+For existing applications, use the [incremental audit workflow](adoption-guide.md#adopt-sql-checking-incrementally)
+to preview fixes and review database types versus application refinements.
+
 1. Run the development `db:migrate` script below against the intended development/test database.
 2. Run `npm run lint`. Fix SQL mistakes before accepting generated types.
 3. Run `npm run lint:fix` for missing/stale annotations. It can add
@@ -193,33 +215,14 @@ SQL and annotation errors come from `@ts-safeql/check-sql`; unsupported composit
    enabled ESLint rules may also fix files.
 4. Run the application's typecheck and database tests. CI runs `lint` without `--fix`.
 
-For multiple databases, replace the connection object with an array. Each connection has its own
-URL, `plugins: [safeqlPlugin]`, and distinct `targets`, for example `{ tag: 'usersSql' }` and
-`{ tag: 'billingSql' }`. Import `sql as usersSql` and `sql as billingSql` to select them, even
-within one file. Alternatively, scope separate SafeQL configurations with non-overlapping ESLint
-`files` patterns and keep the `sql` tag. Runtime connections remain independent: execute each query
-with the right database instance. The checker does not trace `db.query` destinations.
-
-Qualify tables with their schema when names repeat across schemas in a database. SafeQL can infer
-the wrong type for an unqualified table despite the connection's `search_path`; explicit schema
-names avoid that ambiguity.
-
-The checker recognizes Tenon imports, aliases, and typed object properties. It resolves constant
-fragments and literal/const identifier names without executing application code. Imported fragments
-need inspectable source initializers. Use literal newlines and bound string values: outer-template
-JavaScript escapes are rejected because SafeQL reads raw text while Tenon executes decoded text.
-Bound values and constant fragments are decoded consistently.
-
-Checking verifies SQL and result annotations, not JavaScript input compatibility, authorization, or
-JSON contents. PostgreSQL owns parameter inference; the checker adds no casts based on JavaScript
-types. `unsafeSql` is unchecked. Never use `any` to hide an unsupported query.
-
-Default scalar mappings: bigint/numeric are strings; JSON is `unknown`; temporal values are
-`Date | number` because infinities are numbers. Generated `PgArray<T>` supports recursive dimensions
-and null elements. Numeric arrays contain numbers and can lose precision. Custom pg parsers and
-recursive array projections need matching checker overrides and tests, for example
-`overrides: { columns: { 'User.tags': 'PgArray<string>' } }` on the SafeQL connection. Import
-`PgArray` from the generated definitions when using that annotation.
+For multiple databases, give each connection distinct tag targets or ESLint file scopes. Qualify
+same-named tables with their schemas. See the [connection reference](reference.md#configuration-choices-and-multiple-databases).
+
+Checking verifies SQL and result annotations. Input validation, authorization, JSON contents, and
+runtime query variants still need application checks and database tests. Keep shared policy in
+ordinary functions even when its fragments cannot be checked statically. Use literal newlines in
+SQL templates and bind string values. The [reference](reference.md#supported-sql-and-limitations)
+covers supported composition and parser overrides.
 
 ## Transactions and writes
 
@@ -252,7 +255,7 @@ development script in `package.json`:
 ```json
 {
   "scripts": {
-    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.ts"
+    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.d.ts"
   }
 }
 ```
@@ -261,7 +264,7 @@ development script in `package.json`:
 npx tenon new create_users
 # Fill the generated up/down SQL before migrating.
 npm run db:migrate
-npx tenon generate --out src/generated-schema.ts --check
+npx tenon generate --out src/generated-schema.d.ts --check
 npx tenon status
 npx tenon rollback --steps 1
 ```

package/docs/human-guide.md

@@ -59,12 +59,12 @@ CREATE TABLE public."User" (
 DROP TABLE public."User";
 ```
 
-For development, add a script to `package.json` that applies migrations and updates table row types:
+For development, add a script to `package.json` that applies migrations and updates generated types:
 
 ```json
 {
   "scripts": {
-    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.ts"
+    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.d.ts"
   }
 }
 ```
@@ -162,6 +162,32 @@ outside a callback transaction. The guard checks a count; you still need the cor
 and application authorization. Checking returned rows with `returns` alone does not undo an
 autocommitted write.
 
+## Write objects without building column lists by hand
+
+Use `sql.insertValues(rowOrRows)` inside an authored `INSERT` and `sql.assignments(patch)` after
+`SET`. Inserts use database defaults for missing/undefined fields; updates omit those fields.
+Explicit `null` stays null. Empty batches and updates throw. Heterogeneous insert rows remain
+aligned, with `DEFAULT` for missing cells.
+
+```ts
+import type { Rows } from './generated-schema.js';
+
+const input: Rows.Insert['User'] = { email: 'another@example.test' };
+await db.query(sql`INSERT INTO public."User" ${sql.insertValues(input, ['email'])}`);
+
+const patch: Pick<Rows.Update['User'], 'active'> = { active: false };
+await db.query(sql`UPDATE public."User" SET ${sql.assignments(patch, ['active'])}
+  WHERE email = ${input.email}`);
+```
+
+Generated insert types distinguish required fields from defaults and nullable fields. Update types
+make writable fields optional; use `Pick` to limit what an action may edit. See the
+[input-type reference](reference.md#insert-and-update-inputs) for write-value mappings.
+
+Keep expressions, authorization, conflict handling and `RETURNING` in SQL. The selected column lists
+above also let the optional SQL checker inspect runtime-built inputs. They select fields rather
+than validate the complete object. See the [mutation cookbook](mutations.md) for batches and upserts.
+
 ## Check your SQL and result types
 
 There are three different jobs here:
@@ -170,13 +196,9 @@ There are three different jobs here:
 - TypeScript checks the application code and the result types you declare.
 - SafeQL checks the SQL against your database and verifies or generates those types.
 
-SafeQL is optional development tooling run by ESLint. Configure it normally, with Tenon's
-`safeqlPlugin` adapter to translate queries and constant fragments. A small companion ESLint rule,
-`tenon/check-composition`, flags queries that cannot be checked statically. SafeQL performs the
-database analysis and annotation fixes. Your application's ESLint configuration imports these tools;
-Tenon's database runtime does not need them. Generated table types are a separate convenience and
-are not required by SafeQL. Follow the one-time
-[SQL checking setup](reference.md#sql-checking-with-safeql).
+SafeQL is optional development tooling run by ESLint. Tenon's adapter supports queries, constant
+fragments, and mutation helpers; `tenon/check-composition` reports queries it cannot inspect.
+Follow the one-time [SQL checking setup](reference.md#sql-checking-with-safeql).
 
 Use the application's existing lint commands. If it has none, the setup shows `lint` and `lint:fix`.
 They run ESLint, including all other enabled rules. Once configured, the normal workflow is:
@@ -237,9 +259,10 @@ works, but it does not prove that every variant is valid SQL or returns the decl
 const filters = [sql.fragment`active = ${true}`];
 if (email !== undefined) filters.push(sql.fragment`email = ${email}`);
 
-// eslint-disable-next-line tenon/check-composition -- Runtime filters are covered by database tests.
+/* eslint-disable tenon/check-composition -- Runtime filters are covered by database tests. */
 const query = sql<UserSummary>`SELECT id, email FROM public."User"
   WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
+/* eslint-enable tenon/check-composition */
 ```
 
 The initial condition keeps this list nonempty. Empty lists throw so that missing filters cannot

package/docs/mutations.md

@@ -0,0 +1,157 @@
+# Mutation cookbook
+
+Keep SQL structure visible and let the official helpers handle object fields. See the
+[reference](reference.md#object-based-mutation-fragments) for the complete contract. Examples use
+application-owned inputs and clients; add the authorization predicates required by your product.
+
+## Defaults, undefined, and null in batches
+
+```ts
+await db.query(
+  sql`INSERT INTO profiles ${sql.insertValues([
+    { name: 'Ada', bio: null },
+    { name: 'Lin', score: 4, bio: undefined },
+  ])} RETURNING id`,
+);
+```
+
+The first row uses the score default. The second uses the bio default. Explicit null in the first
+row stays null. Columns are aligned across rows. Omit generated columns and let PostgreSQL enforce
+required fields and constraints.
+
+For runtime-built rows, supply an inline column list for SafeQL:
+
+```ts
+import type { Rows } from './generated-schema.js';
+
+const rows: Rows.Insert['profiles'][] = buildRows();
+await db.query(sql`INSERT INTO profiles ${sql.insertValues(rows, ['name', 'bio', 'score'])}`);
+```
+
+This list selects and orders fields; unlisted fields are ignored. It does not assert that the
+entire input object contains only allowed keys. Keep narrower application input validation.
+
+`tenon generate` also provides `Rows.Update['profiles']`. Use `Pick` to limit a patch to fields
+the caller may edit, for example `Pick<Rows.Update['profiles'], 'name' | 'bio'>`. Generated inputs
+understand defaults, nullability, domains, and generated columns. They use write representations:
+timestamps accept `Date | string`, bigint accepts `string | bigint`, and JSON uses serialized text.
+See the [input-type reference](reference.md#insert-and-update-inputs) for the complete mapping.
+
+## Input types, SQL checking, and runtime validation
+
+Apply input types with an annotation, `satisfies`, or a helper generic argument. Generating the
+file alone does not check every write. Narrow the fields each operation accepts:
+
+```ts
+import { sql, type QueryClient } from '@kequtech/tenon-orm';
+import type { Rows } from './generated-schema.js';
+
+type ProfileInput = Pick<Rows.Insert['profiles'], 'name' | 'score'>;
+
+function createProfile(client: QueryClient, input: ProfileInput) {
+  return client.query(sql<{ id: number }>`INSERT INTO profiles
+    ${sql.insertValues(input, ['name', 'score'])} RETURNING id`);
+}
+```
+
+Here `id` and `score` are assumed to be integers. TypeScript rejects an incompatible typed input
+such as `{ name: 'Ada', score: true }`. SafeQL checks selected columns and `RETURNING`; it does not
+inspect runtime values. Validate external inputs before calling this function and keep database
+constraints and application authorization in place.
+
+**Selected columns can discard required fields.** For a table requiring integer `id` and text
+`name` and `location`, this input is valid but the query fails:
+
+```ts
+const row: Rows.Insert['profiles'] = { id: 1, name: 'Ada', location: 'London' };
+const query = sql`INSERT INTO profiles ${sql.insertValues(row, ['id', 'name'])}`;
+// PostgreSQL rejects the insert: location was dropped and has no default.
+```
+
+A column list selects fields; it does not prove that all required fields will be written.
+
+## Patches mixed with SQL expressions
+
+```ts
+await db.query(sql`UPDATE profiles
+  SET ${sql.assignments({ name, bio })}, revision = revision + 1, score = DEFAULT
+  WHERE id = ${id}`);
+```
+
+Undefined fields are omitted; null clears a field. Expressions, `DEFAULT`, and references to
+`excluded.column` belong in SQL, not in mutation objects.
+
+An empty patch throws even if the surrounding statement has other assignments. Choose an
+expression-only query explicitly when that is the intended behavior:
+
+```ts
+const patch: { name?: string; bio?: string | null } = readPatch();
+if (patch.name !== undefined || patch.bio !== undefined) {
+  await db.query(sql`UPDATE profiles
+    SET ${sql.assignments(patch, ['name', 'bio'])}, revision = revision + 1
+    WHERE id = ${id}`);
+} else {
+  await db.query(sql`UPDATE profiles SET revision = revision + 1 WHERE id = ${id}`);
+}
+```
+
+## Preserve an omitted field during an upsert
+
+Use complete query variants when an option changes conflict behavior. Both templates can be
+checked independently; the checker need not choose a JavaScript branch:
+
+```ts
+if (email !== undefined) {
+  await db.query(sql`INSERT INTO preferences ${sql.insertValues({ profile_id, in_app, email })}
+    ON CONFLICT (profile_id) DO UPDATE
+    SET in_app = excluded.in_app, email = excluded.email`);
+} else {
+  await db.query(sql`INSERT INTO preferences ${sql.insertValues({ profile_id, in_app })}
+    ON CONFLICT (profile_id) DO UPDATE SET in_app = excluded.in_app`);
+}
+```
+
+The second query leaves an existing email value unchanged. Missing an insert field uses its
+database default; that alone does not decide what an upsert should overwrite.
+
+## JSONB arrays and PostgreSQL arrays
+
+Tenon preserves pg's value conversion. A JavaScript array binds as a PostgreSQL array. To write an
+array into a JSON/JSONB column, serialize it explicitly:
+
+```ts
+const handles = ['ada', 'lin'];
+await db.query(
+  sql`INSERT INTO deliveries ${sql.insertValues({
+    recipients_json: JSON.stringify(handles), // jsonb column
+    recipient_handles: handles, // text[] column
+  })}`,
+);
+```
+
+Objects used as JSON values retain pg's ordinary JSON conversion. The helper does not infer JSON
+versus array encoding from the table schema. Generated JSON input types use serialized text for
+consistent handling of objects and arrays. Validate JSON contents in the application.
+
+## Batches in one transaction
+
+Choose the batch size in the caller and keep all writes on the transaction client:
+
+```ts
+await db.transaction(async (tx) => {
+  for (let offset = 0; offset < rows.length; offset += 300) {
+    const batch = rows.slice(offset, offset + 300);
+    await tx.query(sql`INSERT INTO profiles ${sql.insertValues(batch, ['name', 'bio', 'score'])}`);
+  }
+});
+```
+
+A failure rolls back all batches. The helper rejects an empty batch; this loop makes no insert
+calls for empty input. The query-wide limit is 65,535 bound parameters, including parameters outside
+the mutation fragment. An oversized query reports its actual count, for example
+`at most 65535 bound parameters; received 65536`. Defaults consume no parameters. Account for the
+selected columns and surrounding query when choosing a batch size; Tenon never splits queries automatically.
+
+Reusable authorization fragments remain valid at runtime. Keep shared policy in application
+functions and test it rather than duplicating it for static coverage. Function-generated SQL,
+conditional fragments, and dynamic filter lists remain outside static checking.