@rawsql-ts/sql-contract 0.2.0 → 0.3.2

package/README.md

@@ -1,582 +1,617 @@
-
-# @rawsql-ts/sql-contract
-
-## Overview
-
-`@rawsql-ts/sql-contract` is a lightweight library for reducing repetitive, mechanical code around handwritten SQL.  
-It focuses on mapping query results into application-typed models and simplifying common CUD (Create / Update / Delete) statement construction.
-
-## Getting Started
-
-### Installation
-
-```sh
-pnpm add @rawsql-ts/sql-contract
-```
-
-### Minimal CRUD sample
-
-```ts
-import { Pool } from 'pg'
-import {
-  createReader,
-  createWriter,
-  type QueryParams
-} from '@rawsql-ts/sql-contract'
-
-async function main() {
-  const pool = new Pool({
-    connectionString: process.env.DATABASE_URL
-  })
-
-  const executor = async (sql: string, params: QueryParams) => {
-    const result = await pool.query(sql, params as unknown[])
-    return result.rows
-  }
-
-  const reader = createReader(executor)
-  const writer = createWriter(executor)
-
-  const rows = await reader.list(
-    `SELECT customer_id, customer_name FROM customers WHERE status = $1`,
-    ['active']
-  )
-
-  await writer.insert('customers', { name: 'alice', status: 'active' })
-  await writer.update(
-    'customers',
-    { status: 'inactive' },
-    { id: 42 }
-  )
-  await writer.remove('customers', { id: 17 })
-
-  await pool.end()
-
-  void rows
-}
-```
-
-## Features
-
-* Zero runtime dependencies
-* Zero DBMS and driver dependencies
-* Works with any SQL-executor returning rows
-* Minimal mapping helpers for SELECT results
-* Simple builders for INSERT / UPDATE / DELETE
-
-## Philosophy
-
-### SQL as Domain Specification
-
-SQL is the primary language for expressing domain requirements—precise, unambiguous, and directly verifiable against the database.
-
-Mapping returned rows to typed domain models is mechanical and repetitive.
-This library removes that burden, letting domain logic remain in SQL.
-
-Write operations (INSERT/UPDATE/DELETE) are usually repetitive and predictable.
-So the library offers simple builders for common cases only.
-
-## Concepts
-
-### Executor: DBMS / Driver Integration
-
-To integrate with any database or driver, define a single executor:
-
-```ts
-const executor = async (sql: string, params: QueryParams) => {
-  const result = await pool.query(sql, params as unknown[])
-  return result.rows
-}
-```
-
-Connection pooling, retries, transactions, and error handling belong inside the executor.
-
-### Reader: Query Execution and Result Mapping
-
-Reader executes SELECT queries and maps raw database rows into application-friendly structures.
-
-It supports multiple levels of mapping depending on your needs,
-from quick projections to fully validated domain models.
-
-### Catalog executor: QuerySpec contract and observability
-
-Catalog executor executes queries through a `QuerySpec` instead of running raw
-SQL directly.
-
-A `QuerySpec` defines a stable query contract that couples an SQL file,
-parameter shape, and output rules. By executing queries through this contract,
-the executor can enforce parameter expectations, apply output mapping or
-validation, and provide a stable identity for debugging and observability.
-
-`createCatalogExecutor` is wired with a SQL loader and a concrete query executor,
-and can optionally apply rewriters, binders, SQL caching,
-`allowNamedParamsWithoutBinder`, extensions, or an `observabilitySink`.
-
-When observability is enabled, execution emits lifecycle events
-(`query_start`, `query_end`, `query_error`) including `spec.id`, `sqlFile`,
-and execution identifiers, allowing queries to be traced and debugged by
-specification rather than raw SQL strings.
-
----
-
-#### Basic result APIs: one and list
-
-Reader provides two primary methods:
-
-- one : returns a single row
-- list : returns multiple rows
-
-```ts
-const customer = await reader.one(
-  'select customer_id, customer_name from customers where customer_id = $1',
-  [1]
-)
-
-const customers = await reader.list(
-  'select customer_id, customer_name from customers'
-)
-```
-
-These methods focus only on execution.
-Mapping behavior depends on how the reader is configured.
-
----
-
-#### Duck typing (minimal, disposable)
-
-For quick or localized queries, you can rely on structural typing without defining models.
-
-```ts
-const rows = await reader.list<{ customerId: number }>(
-  'select customer_id from customers limit 1',
-)
-```
-
-You can also omit the DTO type entirely:
-
-```ts
-const rows = await reader.list(
-  'select customer_id from customers limit 1',
-)
-```
-
-This approach is:
-
-* Fast to write
-* Suitable for one-off queries
-* No runtime validation
-
----
-
-#### Custom mapping
-
-Reader allows custom projection logic when structural mapping is insufficient.
-
-```ts
-const rows = await reader.map(
-  'select price, quantity from order_items',
-  (row) => ({
-    total: row.price * row.quantity,
-  })
-)
-```
-
-This is useful for:
-
-* Derived values
-* Format conversion
-* Aggregated projections
-
----
-
-
-#### Column naming conventions (default behavior)
-
-Reader applies a default naming rule that converts snake_case database columns
-into camelCase JavaScript properties.
-
-This allows most queries to work without explicit mapping.
-
-Example:
-
-```sql
-select customer_id, created_at from customers
-```
-
-becomes:
-
-```ts
-{
-  customerId: number
-  createdAt: Date
-}
-```
-
-No mapping definition is required for this transformation.
-
----
-
-#### Mapper presets
-
-You can configure how column names are transformed.
-
-Example:
-
-```ts
-const reader = createReader(executor, mapperPresets.safe())
-```
-
-Common presets include:
-
-* appLike : snake_case → camelCase conversion
-* safe : no column name transformation
-
-Choose a preset based on how closely your domain models align with database naming.
-
----
-
-#### When explicit mapping is useful
-
-Even with automatic naming conversion, explicit mappings become valuable when:
-
-* Domain terms differ from column names
-* Multiple columns combine into one field
-* Queries are reused across modules
-* Schema stability should be decoupled from application models
-
----
-
-#### Single model mapping (reusable definition)
-
-Mapping models provide explicit control over how rows map to domain objects.
-
-Example:
-
-```ts
-const orderSummaryMapping = rowMapping({
-  name: 'OrderSummary',
-  key: 'orderId',
-  columnMap: {
-    orderId: 'order_id',
-    customerLabel: 'customer_display_name',
-    totalAmount: 'grand_total',
-  },
-})
-
-const summaries = await reader
-  .bind(orderSummaryMapping)
-  .list(`
-    select
-      order_id,
-      customer_display_name,
-      grand_total
-    from order_view
-  `)
-```
-
-In this example:
-
-* Domain terminology differs from database naming
-* Mapping clarifies intent
-* The definition can be reused across queries
-
-Benefits:
-
-* Reusable mapping definitions
-* Explicit domain language alignment
-* Reduced accidental schema coupling
-* Better long-term maintainability
-
----
-
-#### Composite keys
-
-`rowMapping` keys can now be more than a single column without breaking existing consumers:
-
-* **Array-based composite keys** — pass the raw column names in SQL order (`key: ['col_a', 'col_b']`). These column values are extracted directly from the executor’s row, so `columnMap` / `prefix` rules are not involved.
-* **Derived keys** — supply a function, e.g. `key: (row) => [row.col_a, row.col_b]`, that returns strings/numbers/bigints or an array thereof. The library type-tags each component so `'1'` and `1` are never conflated, and order of the array is preserved.
-
-Both forms feed through a single normalization path, so you can combine mixed types safely and receive clear errors if a value is `null`, `undefined`, or missing. Creating a synthetic column inside SQL (e.g. `SELECT CONCAT(col_a, '|', col_b) AS composite_key`) still works as a workaround, but we recommend using the multi-column helpers because they keep the schema explicit and avoid delimiter collisions.
-
-`name` continues to serve as the user-visible label for error messages, independent of whether the key is scalar, composite, or derived.
-
-#### Multi-model mapping
-
-Reader supports mapping joined results into multiple domain models by composing `rowMapping` definitions.
-
-```ts
-const customerMapping = rowMapping({
-  name: 'Customer',
-  key: 'customerId',
-  columnMap: {
-    customerId: 'customer_customer_id',
-    customerName: 'customer_customer_name',
-  },
-})
-
-const orderMapping = rowMapping<{
-  orderId: number
-  orderTotal: number
-  customerId: number
-  customer: { customerId: number; customerName: string }
-}>({
-  name: 'Order',
-  key: 'orderId',
-  columnMap: {
-    orderId: 'order_order_id',
-    orderTotal: 'order_total',
-    customerId: 'order_customer_id',
-  },
-}).belongsTo('customer', customerMapping, 'customerId')
-
-const result = await reader
-  .bind(orderMapping)
-  .list(`
-    select
-      c.id as customer_customer_id,
-      c.name as customer_customer_name,
-      o.id as order_order_id,
-      o.total as order_total,
-      o.customer_id as order_customer_id
-    from customers c
-    join orders o on o.customer_id = c.customer_id
-  `)
-```
-
-`belongsTo` attaches each customer row to its owning order, so the mapped result exposes a nested `customer` object without duplicating join logic.
-
-This enables structured projections from complex joins.
-
----
-
-#### Validator-backed mapping (recommended)
-
-Runtime validation ensures data correctness.
-Zod integration is the recommended approach.
-
-```ts
-import { z } from 'zod'
-
-const CustomerSchema = z.object({
-  customerId: z.number(),
-  customerName: z.string(),
-})
-
-const row = await reader
-  .validator(CustomerSchema)
-  .one(
-    'select customer_id, customer_name from customers where customer_id = $1',
-    [1]
-  )
-```
-
-Benefits include:
-
-* Runtime safety
-* Explicit schema documentation
-* Refactoring confidence
-* AI-friendly feedback loops
-
----
-
-### Scalar Queries
-
-Use scalar helpers when a query returns a single value.
-
-#### Basic scalar usage
-
-```ts
-const count = await reader.scalar(
-  'select count(*) from customers where status = $1',
-  ['active']
-)
-```
-
-This is useful for:
-
-* COUNT queries
-* Aggregate values
-* Existence checks
-
----
-
-#### Typed scalar mapping
-
-You can explicitly define the expected scalar type.
-
-```ts
-const count = await reader.scalar<number>(
-  'select count(*) from customers where status = $1',
-  ['active']
-)
-```
-
-This improves readability and helps prevent accidental misuse.
-
----
-
-#### Scalar validation with Zod (recommended)
-
-For stricter guarantees, scalar values can be validated at runtime.
-
-```ts
-import { z } from 'zod'
-
-const count = await reader.scalar(
-  z.number(),
-  'select count(*) from customers where status = $1',
-  ['active']
-)
-```
-
-This approach ensures:
-
-* Runtime type safety
-* Clear intent
-* Safer refactoring
-
----
-
-### Zod integration and coercion helpers
-
-Reader integrates smoothly with Zod for runtime validation and safe type conversion.
-
-Zod validation helps ensure that query results match your domain expectations,
-especially when working with numeric or date values returned as strings by drivers.
-
----
-
-#### Row validation with Zod
-
-```ts
-import { z } from 'zod'
-
-const CustomerSchema = z.object({
-  customerId: z.number(),
-  customerName: z.string(),
-})
-
-const row = await reader
-  .validator(CustomerSchema)
-  .one(
-    'select customer_id, customer_name from customers where customer_id = $1',
-    [1]
-  )
-```
-
-This provides:
-
-* Runtime safety
-* Clear schema documentation
-* Refactoring confidence
-
----
-
-#### Scalar validation with Zod
-
-```ts
-const count = await reader.scalar(
-  z.number(),
-  'select count(*) from customers'
-)
-```
-
----
-
-#### Coercion helpers for numeric values
-
-Some database drivers return numeric values as strings.
-The package provides helpers to safely convert them.
-
-Example:
-
-```ts
-import { z } from 'zod'
-import {
-  zNumberFromString,
-  zBigIntFromString
-} from '@rawsql-ts/sql-contract-zod'
-
-const schema = z.object({
-  totalAmount: zNumberFromString,
-  largeCounter: zBigIntFromString,
-})
-```
-
-These helpers:
-
-* Convert strings into numeric types
-* Fail fast when values are invalid
-* Reduce manual parsing logic
-
----
-
-#### When to use coercion
-
-Use coercion helpers when:
-
-* Working with NUMERIC / DECIMAL columns
-* Drivers return BIGINT as strings
-* You want runtime guarantees
-
----
-
-### Writer: Simple CUD Helpers
-
-Writer helpers build simple INSERT/UPDATE/DELETE SQL:
-
-```ts
-await writer.insert('projects', {
-  name: 'Apollo',
-  owner_id: 7
-})
-
-await writer.update(
-  'projects',
-  { name: 'Apollo' },
-  { project_id: 1 }
-)
-
-await writer.remove('projects', { project_id: 1 })
-```
-
-You can also build statements without execution:
-
-```ts
-const stmt = writer.build.insert(
-  'projects',
-  { name: 'Apollo' }
-)
-```
-
-## Reducers (Coercion Helpers)
-
-The package exposes pure coercion helpers:
-
-* `decimalStringToNumberUnsafe`
-* `bigintStringToBigInt`
-
-They convert raw DB output strings into numbers or bigints when needed.
-
-## DBMS Differences
-
-sql-contract does not normalize SQL dialects or placeholder styles.
-You must use the placeholder syntax required by your driver.
-
-Examples:
-
-```ts
-await executor(
- 'select * from customers where id = $1',
- [42],
-)
-await executor(
- 'select * from customers where id = :id',
- { id: 42 },
-)
-```
-
-## Influences / Related Ideas
-
-sql-contract is inspired by minimal mapping libraries such as Dapper,
-stopping short of a full ORM and instead providing a predictable, transparent layer.
+# @rawsql-ts/sql-contract
+
+![npm version](https://img.shields.io/npm/v/@rawsql-ts/sql-contract)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+A lightweight library for mapping SQL query results into typed application models. It removes the repetitive, mechanical code around handwritten SQL while keeping SQL as the authoritative source for domain logic.
+
+Inspired by minimal mapping libraries such as Dapper — stopping short of a full ORM and instead providing a predictable, transparent layer.
+
+## Features
+
+- Zero runtime dependencies
+- Works with any SQL executor returning rows (driver/DBMS agnostic)
+- Automatic snake_case to camelCase column name conversion
+- Single and multi-model mapping with `rowMapping`
+- Validator-agnostic schema integration (Zod, ArkType, or any `parse`/`assert` compatible library)
+- Scalar query helpers for COUNT / aggregate values
+
+## Installation
+
+```bash
+npm install @rawsql-ts/sql-contract
+```
+
+## Quick Start
+
+```ts
+import { createReader, type QueryParams } from '@rawsql-ts/sql-contract'
+
+const executor = async (sql: string, params: QueryParams) => {
+  const result = await pool.query(sql, params as unknown[])
+  return result.rows
+}
+
+const reader = createReader(executor)
+
+const customers = await reader.list(
+  'SELECT customer_id, customer_name FROM customers WHERE status = $1',
+  ['active']
+)
+// [{ customerId: 1, customerName: 'Alice' }, ...]
+```
+
+## Reader API
+
+### Basic queries: `one` and `list`
+
+```ts
+const customer = await reader.one(
+  'SELECT customer_id, customer_name FROM customers WHERE customer_id = $1',
+  [1]
+)
+
+const customers = await reader.list(
+  'SELECT customer_id, customer_name FROM customers'
+)
+```
+
+### Column naming conventions
+
+By default, Reader converts snake_case columns to camelCase properties automatically:
+
+```sql
+SELECT customer_id, created_at FROM customers
+```
+
+becomes:
+
+```ts
+{ customerId: number, createdAt: Date }
+```
+
+Presets are available to change this behavior:
+
+```ts
+import { mapperPresets } from '@rawsql-ts/sql-contract'
+
+const reader = createReader(executor, mapperPresets.safe())  // no transformation
+```
+
+### Custom mapping
+
+For derived values or format conversion:
+
+```ts
+const rows = await reader.map(
+  'SELECT price, quantity FROM order_items',
+  (row) => ({ total: row.price * row.quantity })
+)
+```
+
+### Row mapping with `rowMapping`
+
+For reusable, explicit mappings where domain terms differ from column names:
+
+```ts
+import { rowMapping } from '@rawsql-ts/sql-contract'
+
+const orderSummaryMapping = rowMapping({
+  name: 'OrderSummary',
+  key: 'orderId',
+  columnMap: {
+    orderId: 'order_id',
+    customerLabel: 'customer_display_name',
+    totalAmount: 'grand_total',
+  },
+})
+
+const summaries = await reader
+  .bind(orderSummaryMapping)
+  .list('SELECT order_id, customer_display_name, grand_total FROM order_view')
+```
+
+Keys can be composite (`key: ['col_a', 'col_b']`) or derived (`key: (row) => [row.col_a, row.col_b]`).
+
+### Multi-model mapping
+
+Map joined results into nested domain models with `belongsTo`:
+
+```ts
+const customerMapping = rowMapping({
+  name: 'Customer',
+  key: 'customerId',
+  columnMap: {
+    customerId: 'customer_customer_id',
+    customerName: 'customer_customer_name',
+  },
+})
+
+const orderMapping = rowMapping({
+  name: 'Order',
+  key: 'orderId',
+  columnMap: {
+    orderId: 'order_order_id',
+    orderTotal: 'order_total',
+    customerId: 'order_customer_id',
+  },
+}).belongsTo('customer', customerMapping, 'customerId')
+
+const orders = await reader.bind(orderMapping).list(`
+  SELECT
+    c.id AS customer_customer_id,
+    c.name AS customer_customer_name,
+    o.id AS order_order_id,
+    o.total AS order_total,
+    o.customer_id AS order_customer_id
+  FROM customers c
+  JOIN orders o ON o.customer_id = c.customer_id
+`)
+// [{ orderId: 1, orderTotal: 500, customerId: 3, customer: { customerId: 3, customerName: 'Alice' } }]
+```
+
+### Scalar queries
+
+```ts
+const count = await reader.scalar(
+  'SELECT count(*) FROM customers WHERE status = $1',
+  ['active']
+)
+```
+
+## Validation Integration
+
+The `.validator()` method accepts any object implementing `parse(value)` or `assert(value)`. This means **Zod**, **ArkType**, and other validation libraries work out of the box — no additional adapter packages required.
+
+### With Zod
+
+```ts
+import { z } from 'zod'
+
+const CustomerSchema = z.object({
+  customerId: z.number(),
+  customerName: z.string(),
+})
+
+const customers = await reader
+  .validator(CustomerSchema)
+  .list('SELECT customer_id, customer_name FROM customers')
+```
+
+### With ArkType
+
+```ts
+import { type } from 'arktype'
+
+const CustomerSchema = type({
+  customerId: 'number',
+  customerName: 'string',
+})
+
+const customers = await reader
+  .validator((value) => {
+    CustomerSchema.assert(value)
+    return value
+  })
+  .list('SELECT customer_id, customer_name FROM customers')
+```
+
+Validators run after row mapping, so schema errors surface before application code relies on the result shape. Validators are also chainable: `.validator(v1).validator(v2)`.
+
+## Catalog Executor
+
+For larger projects, `createCatalogExecutor` executes queries through a `QuerySpec` contract instead of raw SQL strings. A `QuerySpec` couples an SQL file, parameter shape, and output rules into a stable identity for debugging and observability.
+
+### QuerySpec
+
+A `QuerySpec` is the core contract type:
+
+```ts
+import type { QuerySpec } from '@rawsql-ts/sql-contract'
+import { rowMapping } from '@rawsql-ts/sql-contract'
+
+const activeCustomersSpec: QuerySpec<[], { customerId: number; customerName: string }> = {
+  id: 'customers.active',
+  sqlFile: 'customers/active.sql',
+  params: { shape: 'positional', example: [] },
+  metadata: {
+    material: ['active_customer_ids'],
+    scalarMaterial: ['active_customer_count'],
+  },
+  output: {
+    mapping: rowMapping({
+      name: 'Customer',
+      key: 'customerId',
+      columnMap: {
+        customerId: 'customer_id',
+        customerName: 'customer_name',
+      },
+    }),
+    example: { customerId: 1, customerName: 'Alice' },
+  },
+  tags: { domain: 'crm' },
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique identifier for debugging and observability |
+| `sqlFile` | Path passed to the SQL loader |
+| `params.shape` | `'positional'` (array) or `'named'` (record) |
+| `params.example` | Example parameters (for documentation and testing) |
+| `output.mapping` | Optional `rowMapping` applied before validation |
+| `output.validate` | Optional function to validate/transform each row |
+| `output.example` | Example output (for documentation and testing) |
+| `notes` | Optional human-readable description |
+| `tags` | Optional key-value metadata forwarded to observability events |
+| `metadata.material` | Optional CTE names to materialize as temp tables at runtime |
+| `metadata.scalarMaterial` | Optional CTE names to treat as scalar materializations at runtime |
+
+### QuerySpec metadata
+
+Use `metadata` when runtime adapters need execution hints without changing the SQL asset itself:
+
+```ts
+const monthlyReportSpec: QuerySpec<{ tenantId: string }, { value: number }> = {
+  id: 'reports.monthly',
+  sqlFile: 'reports/monthly.sql',
+  params: {
+    shape: 'named',
+    example: { tenantId: 'tenant-1' },
+  },
+  metadata: {
+    material: ['report_base'],
+    scalarMaterial: ['report_total'],
+  },
+  output: {
+    example: { value: 1 },
+  },
+}
+```
+
+The metadata remains available on `spec.metadata` inside rewriters and is also forwarded to runtime extensions through `ExecInput.metadata`.
+
+### Creating a CatalogExecutor
+
+```ts
+import { createCatalogExecutor } from '@rawsql-ts/sql-contract'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+function createFileSqlLoader(baseDir: string) {
+  return {
+    load(sqlFile: string) {
+      return readFile(resolve(baseDir, sqlFile), 'utf-8')
+    },
+  }
+}
+
+const catalog = createCatalogExecutor({
+  loader: createFileSqlLoader('sql'),
+  executor,
+})
+```
+
+The executor exposes three methods matching the Reader API:
+
+```ts
+const customers = await catalog.list(activeCustomersSpec, [])
+const customer  = await catalog.one(customerByIdSpec, [42])
+const count     = await catalog.scalar(customerCountSpec, [])
+```
+
+For larger applications, keeping the file-backed loader in one helper avoids
+repeating the same `readFile(resolve(...))` wiring in every repository module.
+
+### Common catalog output patterns
+
+The output pipeline for `list()` / `one()` is:
+
+1. raw SQL row
+2. `output.mapping` (optional)
+3. `output.validate` (optional)
+
+That means validators should read the mapped DTO shape, not the raw SQL row.
+
+For scalar queries, the pipeline is:
+
+1. raw SQL row
+2. single-column scalar extraction
+3. `output.validate` (optional)
+
+That makes `count(*)` and `RETURNING id` contracts read more clearly when they
+validate the extracted scalar directly instead of inventing a one-field DTO.
+
+See [docs/recipes/sql-contract.md](../../docs/recipes/sql-contract.md) for
+copy-paste-ready catalog examples covering:
+
+- reusable file-backed loaders
+- mapped DTO validation
+- scalar contract patterns
+
+### Named parameters
+
+Specs declaring `shape: 'named'` require either a `Binder` or an explicit opt-in:
+
+```ts
+const catalog = createCatalogExecutor({
+  loader,
+  executor,
+  // Option A: provide a binder that converts named → positional
+  binders: [{
+    name: 'pg-named',
+    bind: ({ sql, params }) => {
+      // convert :name placeholders to $1, $2, ...
+      return { sql: boundSql, params: positionalArray }
+    },
+  }],
+  // Option B: pass named params directly to the executor
+  // allowNamedParamsWithoutBinder: true,
+})
+```
+
+### Mutation specs
+
+Catalog specs can declare mutation metadata for `INSERT`, `UPDATE`, and `DELETE` assets:
+
+```ts
+const createUserSpec: QuerySpec<
+  { id: string; display_name?: string | null; created_at?: string },
+  never
+> = {
+  id: 'user.create',
+  sqlFile: 'user/create.sql',
+  params: {
+    shape: 'named',
+    example: {
+      id: 'user-1',
+      display_name: 'Alice',
+      created_at: '2026-03-05T00:00:00.000Z',
+    },
+  },
+  mutation: {
+    kind: 'insert',
+  },
+  output: {
+    example: undefined as never,
+  },
+}
+```
+
+The `insert` behavior is covered by `packages/sql-contract/tests/catalog.create.test.ts`.
+
+```ts
+const updateUserSpec: QuerySpec<
+  { id: string; display_name?: string | null; bio?: string | null },
+  never
+> = {
+  id: 'user.update-profile',
+  sqlFile: 'user/update-profile.sql',
+  params: {
+    shape: 'named',
+    example: { id: 'user-1', display_name: 'Alice', bio: null },
+  },
+  mutation: {
+    kind: 'update',
+  },
+  output: {
+    example: undefined as never,
+  },
+}
+```
+
+Phase 1 intentionally keeps the safety rules narrow:
+
+- `INSERT` subtracts only direct `VALUES (:named_param)` entries when the key is missing or `undefined`.
+- `UPDATE` and `DELETE` require a `WHERE` clause by default.
+- `UPDATE` subtracts only simple `SET column = :param` assignments when the key is missing or `undefined`.
+- `null` is preserved, so `SET column = :param` still executes and binds `NULL`.
+- Mandatory parameter validation only inspects the `WHERE` clause because Phase 1 focuses on preventing accidental broad mutations first.
+
+For example, the SQL asset below will drop `display_name = :display_name` when
+`display_name` is omitted or `undefined`, but it keeps the fixed timestamp write:
+
+```sql
+UPDATE public.user_account
+SET display_name = :display_name,
+    bio = :bio,
+    updated_at = NOW()
+WHERE id = :id
+```
+
+Assignments with inline comments or more complex expressions stay untouched in
+Phase 1. They remain visible in SQL and any unresolved placeholders still flow
+through the configured binder/executor path.
+
+### Rewriters
+
+Rewriters apply semantic-preserving SQL transformations before execution:
+
+```ts
+const catalog = createCatalogExecutor({
+  loader,
+  executor,
+  rewriters: [{
+    name: 'add-limit',
+    rewrite: ({ sql, params }) => ({
+      sql: `${sql} LIMIT 1000`,
+      params,
+    }),
+  }],
+})
+```
+
+The execution pipeline order is: **SQL load → rewriters → binders → executor**.
+
+Mutation specs apply one extra safety rule in Phase 1: every configured
+rewriter must explicitly declare `mutationSafety: 'safe'`. This keeps mutation
+preprocessing stable by rejecting rewriters that might alter `SET` or `WHERE`
+structure.
+
+```ts
+const auditCommentRewriter: Rewriter & { mutationSafety: 'safe' } = {
+  name: 'audit-comment',
+  mutationSafety: 'safe',
+  rewrite: ({ sql, params }) => ({
+    sql: `${sql} -- audit`,
+    params,
+  }),
+}
+```
+
+Rewriters without that explicit marker still work for non-mutation specs.
+
+### DELETE guards and `rowCount`
+
+Physical deletes default to an affected-row guard of `exactly 1`. To evaluate
+that guard safely, the configured executor must expose `rowCount` via
+`{ rows, rowCount }` results.
+
+```ts
+const executor = async (sql: string, params: QueryParams) => {
+  const result = await client.query(sql, params as unknown[])
+  return {
+    rows: result.rows,
+    rowCount: result.rowCount,
+  }
+}
+```
+
+If the executor does not expose `rowCount`, delete specs fail by default. You
+may opt out per spec only when you intentionally want no guard:
+
+```ts
+mutation: {
+  kind: 'delete',
+  delete: {
+    affectedRowsGuard: { mode: 'none' },
+  },
+}
+```
+
+For fixture-backed tests, `@rawsql-ts/testkit-core` provides `createCatalogRewriter()` so you can plug `SelectFixtureRewriter` into the catalog pipeline without writing an adapter:
+
+```ts
+import { createCatalogExecutor } from '@rawsql-ts/sql-contract'
+import { createCatalogRewriter } from '@rawsql-ts/testkit-core'
+
+const catalog = createCatalogExecutor({
+  loader,
+  executor,
+  rewriters: [createCatalogRewriter({
+    fixtures: [{
+      tableName: 'users',
+      rows: [{ id: 1, name: 'Alice' }],
+      schema: {
+        columns: {
+          id: 'INTEGER',
+          name: 'TEXT',
+        },
+      },
+    }],
+  })],
+})
+```
+
+### Observability
+
+When an `observabilitySink` is provided, the executor emits lifecycle events:
+
+```ts
+const catalog = createCatalogExecutor({
+  loader,
+  executor,
+  observabilitySink: {
+    emit(event) {
+      // event.kind: 'query_start' | 'query_end' | 'query_error'
+      // event.specId, event.sqlFile, event.execId, event.durationMs, ...
+      console.log(`[${event.kind}] ${event.specId}`)
+    },
+  },
+})
+```
+
+### Error handling
+
+Catalog errors form a hierarchy rooted at `CatalogError`:
+
+| Error class | Cause |
+|-------------|-------|
+| `SQLLoaderError` | SQL file could not be loaded |
+| `RewriterError` | A rewriter threw during transformation |
+| `BinderError` | A binder failed or returned invalid output |
+| `ContractViolationError` | Parameter shape mismatch, unexpected row count, etc. |
+| `CatalogExecutionError` | The underlying query executor failed |
+
+All error classes expose `specId` and `cause` properties for structured logging.
+
+## Execution Scope and Transaction Boundaries
+
+sql-contract is responsible for **query definition and result mapping**. Transaction control (`BEGIN` / `COMMIT` / `ROLLBACK`) and connection lifecycle management are outside its scope — they remain the caller's execution concern.
+
+### What sql-contract manages
+
+- SQL loading and transformation (rewriters, binders)
+- Parameter binding and placeholder conversion
+- Result row mapping and validation
+- Observability events for query execution
+
+### What the caller manages
+
+- Connection pooling and lifecycle (open, close, release)
+- Transaction boundaries (`BEGIN` / `COMMIT` / `ROLLBACK`)
+- Error recovery and retry policies
+- Connection scoping (ensuring related queries share one connection)
+
+### QueryExecutor and connection scoping
+
+The `QueryExecutor` type assumes it runs within a **single connection scope**. When using a connection pool, each call to the executor may be dispatched to a different connection, which makes multi-statement transactions unsafe.
+
+To execute transactional workflows, the caller should obtain a dedicated connection and build the executor from it:
+
+```ts
+// Acquire a dedicated connection from the pool
+const client = await pool.connect();
+try {
+  await client.query('BEGIN');
+
+  // Build an executor scoped to this connection
+  const executor = async (sql: string, params: readonly unknown[]) => {
+    const result = await client.query(sql, params as unknown[]);
+    return result.rows;
+  };
+
+  const reader = createReader(executor);
+  const user = await reader.one('SELECT ...', [userId]);
+  // ... additional queries on the same connection ...
+
+  await client.query('COMMIT');
+} catch (e) {
+  try {
+    await client.query('ROLLBACK');
+  } catch {
+    // ignore secondary rollback failure
+  }
+  throw e;
+} finally {
+  client.release();
+}
+```
+
+This separation keeps sql-contract focused on the mapping layer while leaving execution policy decisions — such as isolation level, retry logic, and savepoints — in the application layer where they belong.
+
+## DBMS Differences
+
+sql-contract does not normalize SQL dialects or placeholder styles. Use the syntax required by your driver:
+
+```ts
+// PostgreSQL ($1, $2, ...)
+await executor('SELECT * FROM customers WHERE id = $1', [42])
+
+// Named parameters (:id)
+await executor('SELECT * FROM customers WHERE id = :id', { id: 42 })
+```
+
+## License
+
+MIT