@biref/scanner 0.0.1

package/README.md

@@ -0,0 +1,1109 @@
+# @biref/scanner
+
+[![CI](https://github.com/joelorzet/biref-db-scanner/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/joelorzet/biref-db-scanner/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/typescript-strict-blue)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+Scan any database, inspect every relationship in **both** directions, generate a typed schema from a live scan, and write Prisma-style fluent queries against tables you didn't have to hand-model - with fully hydrated nested results. One SDK, one mental model, for every adapter.
+
+---
+
+## Table of contents
+
+- [What it does](#what-it-does)
+- [The differentiating feature: inbound references](#the-differentiating-feature-inbound-references)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Core concepts](#core-concepts)
+- [Pipeline walkthrough](#pipeline-walkthrough)
+  - [1. Wire an adapter](#1-wire-an-adapter)
+  - [2. Scan the database](#2-scan-the-database)
+  - [3. Inspect the `DataModel`](#3-inspect-the-datamodel)
+  - [4. Generate a typed schema (codegen)](#4-generate-a-typed-schema-codegen)
+  - [5. Build typed queries](#5-build-typed-queries)
+  - [6. Return types - how narrowing works](#6-return-types--how-narrowing-works)
+  - [7. Parsers and formatters](#7-parsers-and-formatters)
+  - [8. JavaScript consumers (no codegen)](#8-javascript-consumers-no-codegen)
+- [How tables map to the domain model](#how-tables-map-to-the-domain-model)
+- [Relation naming rules](#relation-naming-rules)
+- [Codegen output layout](#codegen-output-layout)
+- [Adapters](#adapters)
+- [API reference](#api-reference)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## What it does
+
+`@biref/scanner` is a headless TypeScript SDK with a four-stage pipeline:
+
+1. **Wire** an adapter - hand the SDK a driver client (`pg.Client`, `pg.Pool`, or anything structurally compatible).
+2. **Scan** the data store - produce a paradigm-neutral `DataModel` with every entity, field, relationship, constraint, and index discovered from the live database.
+3. **Generate** a typed schema file from that scan (`biref gen` CLI or `generateSchema` programmatic).
+4. **Query** with a Prisma-style fluent API whose typed proxy knows your schema, executes against your client, and returns hydrated rows with nested includes.
+
+The domain is paradigm-neutral: `Entity`, `Field`, `Reference`, `Relationship`, `Constraint`, `Index` - the same shape comes back for every adapter. A `kind` discriminator on `DataModel` lets you branch on paradigm when needed.
+
+## The differentiating feature: inbound references
+
+Most introspection tools only surface the foreign keys an entity *declares*. If you scan `users` you see the columns and the FKs `users` points at, but not the fact that `orders`, `invoices`, and `sessions` all reference `users.id`.
+
+`@biref/scanner` walks the graph once and attaches relationships in **both directions** to every entity:
+
+- **outbound**: this entity holds the reference (a declared FK pointing outward).
+- **inbound**: another entity holds a reference pointing here.
+
+The typed query builder exposes both directions under friendly names you did not have to invent. `.include('orders', ...)` on `users` walks the inbound hop; `.include('user', ...)` on `orders` walks the outbound hop. Both are one call.
+
+---
+
+## Install
+
+```bash
+# pnpm
+pnpm add @biref/scanner pg
+
+# npm
+npm install @biref/scanner pg
+
+# yarn
+yarn add @biref/scanner pg
+```
+
+**Requirements**
+
+- Node.js **20.12 or later** (for `process.loadEnvFile` and Corepack)
+- Node.js **24+** if you want to run `.ts` scratch files without a transpiler (`node index.ts`). For Node 22, pass `--experimental-strip-types`.
+- Your own database driver (`pg` for the Postgres adapter). The SDK has **zero runtime dependencies** - it never imports the driver itself, so you pick the version you trust.
+
+**Package manager support**
+
+Any of pnpm, npm, yarn, or bun works. The `biref` CLI is installed under `node_modules/.bin`:
+
+```bash
+pnpm exec biref gen --url postgres://localhost/mydb
+npm  exec biref gen --url postgres://localhost/mydb   # or: npx biref gen ...
+yarn exec biref gen --url postgres://localhost/mydb
+```
+
+> The package is not published to npm yet - the name is reserved. Until it ships, install directly from this repo.
+
+---
+
+## Quick start
+
+Two commands and one file:
+
+```bash
+# 1. Generate a typed schema from a live database.
+pnpm exec biref gen \
+  --url postgres://user:pass@localhost/mydb \
+  --all-namespaces
+```
+
+```ts
+// 2. Scan, query, enjoy typed autocomplete on every namespace,
+//    entity, field, and relation the scanner discovered.
+import pg from 'pg';
+import { Biref, postgresAdapter } from '@biref/scanner';
+import type { BirefSchema } from './biref/biref.schema';
+
+const client = new pg.Client({ connectionString: 'postgres://localhost/mydb' });
+await client.connect();
+
+const biref = Biref.builder()
+  .withAdapter(postgresAdapter.create(client))
+  .build();
+
+const model = await biref.scan({ namespaces: 'all' });
+
+const rows = await biref
+  .query<BirefSchema>(model)
+  .public.users
+  .select('id', 'email')
+  .where('status', 'eq', 'active')
+  .include('orders', (order) =>
+    order
+      .select('id', 'total')
+      .include('order_items', (item) => item.select('variant_id', 'quantity')),
+  )
+  .findMany();
+
+// rows is typed as:
+//   readonly {
+//     readonly id: bigint;
+//     readonly email: string;
+//     readonly orders: readonly {
+//       readonly id: bigint;
+//       readonly total: string;
+//       readonly order_items: readonly {
+//         readonly variant_id: number;
+//         readonly quantity: number;
+//       }[];
+//     }[];
+//   }[]
+```
+
+After step 1, the `./biref/` folder contains:
+
+```
+biref/
+├── biref.schema.ts             # generated every run
+├── biref.schema.overrides.ts   # scaffolded once, never regenerated
+└── (split mode) index.ts + <namespace>/<entity>.ts per table
+```
+
+Step 2 imports `BirefSchema` from the generated file, and every `.select(...)`, `.where(...)`, `.include(...)` call narrows both its input and its return type based on the live schema.
+
+---
+
+## Core concepts
+
+These five nouns are all you need to keep in your head:
+
+| Concept | One-liner |
+| --- | --- |
+| **Adapter** | A plug-in that bundles an `Introspector`, `QueryEngine`, `RawQueryRunner`, and `RecordParser` for a specific data store. Currently ships with Postgres. |
+| **`DataModel`** | The paradigm-neutral schema produced by a scan. Aggregate of every `Entity` discovered, with relationships in both directions attached. |
+| **Typed query root** | The object returned by `biref.query<Schema>(model)`. A two-layer Proxy keyed by namespace then entity, every leaf a zero-state fluent chain. |
+| **`QueryPlan`** | The immutable tree built up by the chain. Each node is a single-entity `QuerySpec` plus a list of nested includes. |
+| **`QueryPlanExecutor`** | The core driver that walks a plan tree, runs one SQL query per include level, and stitches children into parents in process. Lives in `src/core/` and is paradigm-neutral. |
+
+The **typed path** and the **dynamic path** run the exact same runtime. The distinction is compile-time only: pass a schema generic and your editor narrows types; omit it and everything still works with `any`-shaped autocomplete.
+
+---
+
+## Pipeline walkthrough
+
+Each subsection is self-contained and builds on the previous. You can stop at step 3 if all you want is schema metadata, or layer the typed query builder on top for real queries.
+
+### 1. Wire an adapter
+
+`Biref.builder()` returns a fluent builder. Register one or more adapters, call `.build()`, and you have a facade.
+
+```ts
+import pg from 'pg';
+import { Biref, postgresAdapter } from '@biref/scanner';
+
+const pgClient = new pg.Client({ connectionString: 'postgres://localhost/mydb' });
+await pgClient.connect();
+
+const biref = Biref.builder()
+  .withAdapter(postgresAdapter.create(pgClient))
+  .build();
+```
+
+Registering multiple adapters at once:
+
+```ts
+const biref = Biref.builder()
+  .withAdapters(postgresAdapter.create(pgClient))
+  .build();
+```
+
+The builder stores each adapter together with its engine, parser, and query runner. When you later call `biref.query(...)...findMany()`, the SDK uses the runner to execute the SQL through the driver you provided - you never touch the client again for query execution.
+
+**Structural client typing.** `postgresAdapter.create(client)` accepts any object that matches:
+
+```ts
+interface PostgresClient {
+  query<TRow>(text: string, params?: readonly unknown[]):
+    Promise<{ rows: TRow[] }>;
+}
+```
+
+Both `pg.Client` and `pg.Pool` satisfy this shape. If your driver is compatible, pass it directly - the SDK never imports `pg` itself.
+
+### 2. Scan the database
+
+`biref.scan()` produces a `DataModel` - the aggregate of every entity the adapter discovered.
+
+**Defaults (Postgres):** scans the `public` schema only.
+
+```ts
+const model = await biref.scan();
+```
+
+**Specific namespaces** (recommended when you know the layout):
+
+```ts
+const model = await biref.scan({
+  namespaces: ['public', 'auth', 'billing'],
+});
+```
+
+**Wildcard - every non-system namespace:**
+
+```ts
+const model = await biref.scan({ namespaces: 'all' });
+```
+
+The `'all'` sentinel asks the adapter to query its system catalog for every schema that isn't internal. For Postgres that excludes `pg_catalog`, `information_schema`, `pg_toast*`, and `pg_temp_*`. Use this when you want to bootstrap codegen against a database you didn't design.
+
+**Allowlist / denylist entities** (applied after namespace filtering):
+
+```ts
+const model = await biref.scan({
+  namespaces: ['public'],
+  includeEntities: ['users', 'orders', 'products'],
+  // or:
+  excludeEntities: ['audit_log', 'schema_migrations'],
+});
+```
+
+**Multi-adapter setups:**
+
+```ts
+// Pick explicitly by adapter name.
+const model = await biref.scan('postgres');
+
+// Or route by URL scheme.
+const model = await biref.scanByUrl('postgres://localhost/mydb');
+```
+
+**`IntrospectOptions` reference:**
+
+| Field | Type | Effect |
+| --- | --- | --- |
+| `namespaces` | `readonly string[] \| 'all'` | Namespaces to scan. Omit for the adapter's default (Postgres: `['public']`). Pass `'all'` for every non-system namespace. |
+| `includeEntities` | `readonly string[]` | Allowlist applied after namespace filtering. |
+| `excludeEntities` | `readonly string[]` | Denylist applied after namespace filtering. |
+
+### 3. Inspect the `DataModel`
+
+The model is the same paradigm-neutral shape you get from the codegen - usable directly when you want metadata rather than queries (schema docs, change detection, migration tools, data explorers).
+
+```ts
+// Count discovered entities.
+console.log(model.entities.length);
+
+// Look up a specific entity.
+const users = model.getEntity('public', 'users');
+
+// Iterate everything by namespace.
+for (const entity of model.entities) {
+  console.log(`${entity.namespace}.${entity.name} (${entity.fields.length} fields)`);
+}
+```
+
+**Entity shape:**
+
+```ts
+users?.namespace;    // 'public'
+users?.name;         // 'users'
+users?.identifier;   // readonly string[] - primary key columns, declaration order preserved
+users?.description;  // string | null - the Postgres COMMENT ON TABLE, if any
+```
+
+**Field shape** (`Field`):
+
+```ts
+const email = users?.fields.find((f) => f.name === 'email');
+email?.name;          // 'email'
+email?.type.category; // 'string' - normalized category
+email?.type.nativeType; // 'text' - original adapter type
+email?.nullable;      // boolean
+email?.isIdentifier;  // is this column part of the primary key?
+email?.defaultValue;  // string | null - the column default expression
+email?.description;   // string | null - Postgres COMMENT ON COLUMN
+```
+
+`FieldTypeCategory` is the enum of normalized categories:
+
+```ts
+type FieldTypeCategory =
+  | 'string'
+  | 'integer'
+  | 'decimal'
+  | 'boolean'
+  | 'date'
+  | 'timestamp'
+  | 'time'
+  | 'json'
+  | 'uuid'
+  | 'binary'
+  | 'enum'
+  | 'array'
+  | 'reference'
+  | 'unknown';
+```
+
+Enum fields carry their labels on `type.enumValues`; array fields carry an `elementType` recursively, including enum element types.
+
+**Constraints:**
+
+```ts
+users?.constraints;  // Constraint[]
+// Each has: { name, kind: 'unique' | 'check' | 'exclusion' | 'custom', fields, expression }
+```
+
+**Indexes** (excluding the primary key index):
+
+```ts
+users?.indexes;  // Index[]
+// Each has: { name, kind: 'btree' | 'hash' | 'gin' | 'gist' | 'brin' | 'spgist' | 'unknown', fields, unique, partial, definition }
+```
+
+**Relationships - the headline feature:**
+
+```ts
+// Every relationship involving this entity, in both directions.
+model.relationshipsOf('public', 'users');
+
+// Just the outbound ones (FKs this entity declares).
+model.outboundRelationshipsOf('public', 'users');
+
+// Just the inbound ones (other entities pointing here).
+const incoming = model.inboundRelationshipsOf('public', 'users');
+
+for (const rel of incoming) {
+  const from = rel.reference.fromEntity; // { namespace, name }
+  const cols = rel.reference.fromFields; // columns on the other side
+  const onDel = rel.reference.onDelete;  // 'no-action' | 'cascade' | 'set-null' | …
+  console.log(`${from.namespace}.${from.name}(${cols.join(', ')}) -> users.id (${onDel})`);
+}
+```
+
+Self-referential FKs appear on the same entity as **both** an inbound and an outbound relationship. Composite keys are preserved column-by-column in declaration order on both sides. See [How tables map to the domain model](#how-tables-map-to-the-domain-model) for the full translation rules.
+
+### 4. Generate a typed schema (codegen)
+
+The `biref` CLI connects to a live database once, scans it, and emits `.ts` files with a `BirefSchema` type that mirrors the schema. Import that type at your call sites to get fully typed autocomplete and return types on the query builder.
+
+**Single-file mode** - everything in one `./biref/biref.schema.ts`:
+
+```bash
+pnpm exec biref gen \
+  --url postgres://user:pass@localhost/mydb \
+  --namespace public \
+  --namespace billing
+```
+
+**Split mode** - one file per entity plus an `index.ts`, ideal for browsing large schemas table-by-table:
+
+```bash
+pnpm exec biref gen \
+  --url postgres://user:pass@localhost/mydb \
+  --split \
+  --all-namespaces
+```
+
+Split-mode output layout:
+
+```
+biref/
+├── index.ts                        # re-exports + BirefSchema type
+├── biref.schema.overrides.ts       # scaffolded once, never regenerated
+├── identity/
+│   ├── users.ts                    # export interface IdentityUsers { ... }
+│   └── accounts.ts
+├── catalog/
+│   ├── products.ts
+│   └── ...
+└── commerce/
+    └── orders.ts
+```
+
+Both modes import the same type at your call sites:
+
+```ts
+import type { BirefSchema } from './biref/biref.schema';        // single-file
+import type { BirefSchema } from './biref';                      // split mode (resolves to biref/index.ts)
+```
+
+**All CLI flags:**
+
+| Flag | Effect |
+| --- | --- |
+| `--url <connection>` | Required. Database URL the CLI connects to. |
+| `--out <path>` | Output file (single mode) or folder (split mode). Defaults to `./biref/biref.schema.ts` or `./biref`. |
+| `--split` | Emit per-entity files + an index instead of a single file. |
+| `--namespace <name>` | Scan this namespace. Repeatable. |
+| `--all-namespaces` | Scan every non-system namespace the database exposes. Mutually exclusive with `--namespace`. |
+| `--overwrite` / `--no-overwrite` | Overwrite existing generated files (default) or refuse and error out - useful for CI drift checks. The overrides file is always preserved. |
+| `--adapter <name>` | Explicitly pick an adapter when more than one is known. Optional. |
+
+**What the command writes:**
+
+| File | Regenerated? | Purpose |
+| --- | --- | --- |
+| `biref.schema.ts` (single) or `index.ts` + `<namespace>/<entity>.ts` (split) | Every run | Generated descriptors + `BirefSchema = ApplySchemaOverrides<Raw, Overrides>`. |
+| `biref.schema.overrides.ts` | **Never** after first write | Type your jsonb columns or override any auto-inferred type. |
+
+**Typing a jsonb column** via overrides:
+
+```ts
+// biref.schema.overrides.ts
+export interface Overrides {
+  'identity.users': {
+    profile: { plan: 'free' | 'pro'; prefs: { darkMode: boolean } };
+  };
+}
+```
+
+After the next regen, `q.identity.users.select('profile').findFirst()` returns `{ profile: { plan: 'free' | 'pro'; prefs: { darkMode: boolean } } | null }`. Overrides deep-merge onto the emitted schema via a public `ApplySchemaOverrides<Raw, Overrides>` type - keyed by qualified entity name `'namespace.entity'`, one level of mapped-type gymnastics.
+
+**Programmatic API.** Every piece the CLI uses is exported:
+
+```ts
+import {
+  generateSchema,       // (model: DataModel): string
+  generateSchemaFiles,  // (model: DataModel): readonly SchemaFile[]
+  overridesScaffold,    // (): string
+  tsTypeFor,            // (fieldType, nullable): string
+  type SchemaFile,      // { path: string; content: string }
+} from '@biref/scanner';
+```
+
+**Single-file codegen from your own script:**
+
+```ts
+import { writeFileSync } from 'node:fs';
+import { generateSchema, Biref, postgresAdapter } from '@biref/scanner';
+import pg from 'pg';
+
+const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
+await client.connect();
+const biref = Biref.builder().withAdapter(postgresAdapter.create(client)).build();
+const model = await biref.scan({ namespaces: 'all' });
+writeFileSync('./biref/biref.schema.ts', generateSchema(model));
+await client.end();
+```
+
+**Split-mode codegen from your own script:**
+
+```ts
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { generateSchemaFiles, overridesScaffold } from '@biref/scanner';
+
+const outDir = resolve('./biref');
+mkdirSync(outDir, { recursive: true });
+
+for (const file of generateSchemaFiles(model)) {
+  const abs = resolve(outDir, file.path);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, file.content);
+}
+
+// Scaffold the overrides file only on first run so your edits survive.
+const overridesPath = resolve(outDir, 'biref.schema.overrides.ts');
+if (!existsSync(overridesPath)) {
+  writeFileSync(overridesPath, overridesScaffold());
+}
+```
+
+The generated schema always imports `./biref.schema.overrides` (type-only). The CLI writes the scaffold on first run; programmatic callers need to do the same themselves, otherwise the `import type { Overrides }` line at the top of the generated file will fail to resolve.
+
+### 5. Build typed queries
+
+`biref.query<BirefSchema>(model)` returns a **two-layer Proxy**: the first layer is keyed by namespace, the second by entity, and every leaf is a fresh `TypedChain` bound to that `(namespace, entity)` pair.
+
+```ts
+const root = biref.query<BirefSchema>(model);
+
+// Dot-access surfaces every namespace and entity discovered by the scan.
+const users = root.identity.users;     // TypedChain bound to identity.users
+const products = root.catalog.products; // TypedChain bound to catalog.products
+```
+
+The chain is **immutable** - every method returns a new `TypedChain`. Your projection narrows the row shape at compile time, your filters narrow the allowed operators by the field's category, and your includes narrow the nested result shape recursively.
+
+Each method below has the runtime behavior first, then the compile-time narrowing.
+
+#### `.select(...)` - project a subset of columns
+
+Three shapes, all valid:
+
+```ts
+// Explicit fields: narrows the row type to { id, email } and strips everything else from the SQL.
+root.identity.users.select('id', 'email');
+
+// Explicit wildcard: same as omitting .select() entirely. Narrows nothing.
+root.identity.users.select('*');
+
+// Zero-arg shorthand for the wildcard.
+root.identity.users.select();
+```
+
+**Rules:**
+
+- Every named field must exist on the entity. Unknown names throw at chain time before any SQL is emitted.
+- Mixing `'*'` with named fields throws.
+- Wildcard leaves `plan.spec.select` as `undefined`, so the engine emits every column the adapter reported. The parser projects every column into the result record.
+
+#### `.where(field, operator, value)` - narrow by predicate
+
+The operator set narrows automatically based on the field's category:
+
+| Category | Allowed operators |
+| --- | --- |
+| `string`, `uuid`, `enum` | `eq`, `neq`, `in`, `not-in`, `like`, `ilike`, `is-null`, `is-not-null` |
+| `integer`, `decimal`, `date`, `timestamp`, `time` | `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `between`, `in`, `not-in`, `is-null`, `is-not-null` |
+| `boolean` | `eq`, `neq`, `is-null`, `is-not-null` |
+| everything else | `eq`, `neq`, `is-null`, `is-not-null` |
+
+**Value shape** depends on the operator:
+
+| Operator | Value shape |
+| --- | --- |
+| `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `like`, `ilike` | scalar - same type as the field |
+| `in`, `not-in` | `readonly T[]` - empty array short-circuits to `FALSE` / `TRUE` respectively |
+| `between` | `readonly [min, max]` tuple |
+| `is-null`, `is-not-null` | no value - use the two-argument form |
+
+Examples:
+
+```ts
+await root.catalog.products
+  .select('id', 'sku', 'price')
+  .where('active', 'eq', true)
+  .where('price', 'between', ['1.00', '99.99'])
+  .where('sku', 'ilike', 'BOOK-%')
+  .where('deleted_at', 'is-null')                 // two-arg form
+  .where('status', 'in', ['active', 'archived'])  // array value
+  .findMany();
+```
+
+Unknown fields in `.where` throw at chain time. Passing the wrong operator for a category (e.g. `.where('email', 'between', ...)`) is a compile-time error in the typed path.
+
+#### `.orderBy(field, direction?)` - sort
+
+```ts
+root.commerce.orders
+  .orderBy('placed_at', 'desc')
+  .orderBy('id', 'asc');
+```
+
+Defaults to `'asc'` when direction is omitted. Multiple `.orderBy` calls compose.
+
+#### `.limit(n)` / `.offset(n)` - pagination
+
+```ts
+root.commerce.orders
+  .orderBy('placed_at', 'desc')
+  .limit(100)
+  .offset(200);
+```
+
+Limit and offset are bound as parameters (`$N`), not inlined into the SQL.
+
+#### `.include(relation, build?)` - recursive nested hydration
+
+Four shapes - pick whichever matches your intent:
+
+```ts
+// 1. Shorthand: every field of the related entity, no nested includes.
+root.identity.users.include('orders');
+
+// 2. Narrowing: pick child fields and/or chain further includes.
+root.identity.users.include('orders', (order) =>
+  order.select('id', 'total').include('order_items', (item) =>
+    item.select('variant_id', 'quantity'),
+  ),
+);
+
+// 3. Wildcard: every relation the entity has, each with default projection.
+root.identity.users.include('*');
+
+// 4. Combined: a single entity can stack multiple includes of any shape.
+root.identity.users
+  .include('orders')
+  .include('sessions', (s) => s.select('id', 'expires_at'))
+  .include('*');
+```
+
+**Runtime behavior:**
+
+- The executor runs one SQL query per include level. Root query first, then one query per hop, filtered to the parent keys it just collected (`WHERE child_key IN (...parent_keys)`). No SQL JOINs; all stitching happens in process.
+- This works uniformly for single-column, composite, self-referential, and cross-schema FKs.
+- **Outbound relations** hydrate as a single object (`T | null`) - cardinality `'one'`. The target of an outbound FK is always unique (primary key), so there's at most one match.
+- **Inbound relations** hydrate as an array (`readonly T[]`) - cardinality `'many'`. Any number of rows can reference back.
+- **Self-referential FKs** use the conventional `'parent'` (outbound) and `'children'` (inbound) relation names.
+
+**Projection honoring:** the executor transparently injects the parent's join keys into the parent's `SELECT` and the child's join keys into the child's `SELECT` so the stitcher can read them. After stitching, those injected keys are filtered back out - the final rows only expose the columns you actually asked for.
+
+**Validation:** unknown relation names throw at chain time with a list of every valid name on the current entity. `.include('*', callback)` throws because the sub-builder shape varies per relation - a single callback can't narrow all of them coherently.
+
+#### `.findMany()` / `.findFirst()` - terminals
+
+```ts
+// Fetch many. Returns readonly HydratedRow<...>[].
+const all = await root.catalog.products
+  .select('id', 'sku', 'name')
+  .where('active', 'eq', true)
+  .findMany();
+
+// Fetch one. Applies limit: 1 and returns HydratedRow<...> | null.
+const one = await root.catalog.products
+  .select('id', 'sku')
+  .where('sku', 'eq', 'WIDGET-001')
+  .findFirst();
+```
+
+Both execute against the adapter's captured client. You never touch the driver once the chain is assembled.
+
+`.toPlan()` is also available for tests and tooling - it returns the accumulated `QueryPlan` without executing. The final Prisma-style `count()` terminal is on the v1.1 roadmap; use `findMany().then(r => r.length)` until then.
+
+### 6. Return types - how narrowing works
+
+The typed chain's return type is `HydratedRow<Sel, Inc>` where:
+
+- **`Sel`** is the accumulated projection (how `.select()` narrowed it).
+- **`Inc`** is the accumulated include map (every `.include()` grows it).
+
+Five things compose to produce the final row type:
+
+**(a)** `select('id', 'email')` narrows `Sel` to `{ id: <type>, email: <type> }`. No `.select()` (or `.select('*')`) leaves `Sel` as `DefaultSelect<S, Ns, E>`, which is every field on the entity.
+
+**(b)** Each field descriptor carries both its TS type (`ts`) and its nullability (`nullable`). `TypeOf<S, Ns, E, F>` returns `ts` if non-nullable, `ts | null` if nullable. So `.select('deleted_at')` on a nullable column produces `{ deleted_at: Date | null }` - no surprises from `null` at runtime.
+
+**(c)** `.include('orders', ...)` grows `Inc` by adding `{ orders: WrapForCardinality<'many', HydratedRow<SubSel, SubInc>> }`. `WrapForCardinality` checks the stored cardinality literal and produces either `readonly T[]` (many) or `T | null` (one).
+
+**(d)** Nested includes recurse through `HydratedRow` - a child include builds its own `(SubSel, SubInc)` pair inside the callback and contributes its own `HydratedRow` shape into the parent's `Inc`.
+
+**(e)** The final `HydratedRow<Sel, Inc>` is `Sel & { [K in keyof Inc]: Inc[K] }`. Your editor sees the merged shape.
+
+**Concrete example:**
+
+```ts
+const rows = await biref
+  .query<BirefSchema>(model)
+  .identity.users
+  .select('id', 'email')
+  .include('orders', (order) =>
+    order
+      .select('id', 'total')
+      .include('order_items', (item) => item.select('variant_id', 'quantity')),
+  )
+  .findMany();
+```
+
+The inferred type is:
+
+```ts
+readonly {
+  readonly id: bigint;
+  readonly email: string;
+  readonly orders: readonly {
+    readonly id: bigint;
+    readonly total: string;
+    readonly order_items: readonly {
+      readonly variant_id: number;
+      readonly quantity: number;
+    }[];
+  }[];
+}[]
+```
+
+**Cardinality recap:**
+
+| Direction | Include key | Cardinality | Result type |
+| --- | --- | --- | --- |
+| Outbound (this entity holds FK → target) | `user`, `kyc`, `parent_category`, ... | `one` | `HydratedRow<...> \| null` |
+| Inbound (other entity holds FK → this) | `orders`, `sessions`, `children`, ... | `many` | `readonly HydratedRow<...>[]` |
+
+### 7. Parsers and formatters
+
+Raw driver output rarely matches what you want to work with: `int8` columns come back as strings, `numeric` columns come back as strings, `timestamp` columns vary per driver. A `RecordParser` normalizes that using the `DataModel`.
+
+**The typed query builder uses the adapter's parser automatically** - you don't construct one yourself. This section is for advanced use (custom adapters, direct SQL execution, export pipelines).
+
+#### `DefaultRecordParser` - paradigm-neutral coercion
+
+| Field category | Coercion |
+| --- | --- |
+| `string`, `uuid`, `enum` | `String(raw)` |
+| `integer` | `Number(raw)`, keeping `bigint` when the driver passes one |
+| `decimal` | kept as string (precision-preserving) |
+| `boolean` | `Boolean(raw)` |
+| `date`, `timestamp`, `time` | `new Date(raw)` if not already a `Date` |
+| `json`, `binary`, `array`, `reference`, `unknown` | pass-through |
+
+Missing fields in the row are **omitted** from the parsed record (not filled with `null`), so projection stays tight all the way through.
+
+#### `PostgresRecordParser` - Postgres driver specifics
+
+Extends `DefaultRecordParser` with:
+
+- `int8` / `bigint` native types → JS `bigint` (pg returns these as strings by default, to preserve precision)
+- `json` / `jsonb` arriving as strings → parsed to objects (for drivers that don't auto-parse)
+
+**Projection honoring.** Both parsers only emit fields that are actually present in the driver row. `.select('id', 'email')` sends `SELECT "id", "email"` to Postgres, pg returns `{id, email}` rows, and the parser emits `{id, email}` parsed records. Unselected columns never inflate payloads.
+
+#### Formatters - JSON, CSV, raw
+
+```ts
+import { JsonFormatter, CsvFormatter, RawFormatter } from '@biref/scanner';
+
+// ParsedRecord[] -> JSON string.
+new JsonFormatter({ pretty: true }).serialize(rows);
+// Handles Date -> ISO string, bigint -> decimal string.
+
+// ParsedRecord[] -> RFC 4180 CSV.
+new CsvFormatter({ delimiter: ',', includeHeader: true }).serialize(rows);
+
+// ParsedRecord[] -> ParsedRecord[] (pass-through).
+new RawFormatter().serialize(rows);
+```
+
+All three implement `Formatter<TOutput>` and accept an optional `{ fields }` override if you want to force a specific column set.
+
+### 8. JavaScript consumers (no codegen)
+
+You can use the SDK from plain JavaScript and still get full IntelliSense, via JSDoc type imports that resolve the codegen-generated `.ts` file. The TypeScript language server (VS Code, Cursor, WebStorm, Zed, Neovim with `tsserver`) will then narrow `biref.query(model)` calls exactly as it would for a TS consumer.
+
+**Drop this at the top of your JS file:**
+
+```js
+/**
+ * @typedef {import('./biref/biref.schema').BirefSchema} BirefSchema
+ * @typedef {import('@biref/scanner').TypedQueryRoot<BirefSchema>} TypedRoot
+ */
+
+const biref = Biref.builder().withAdapter(postgresAdapter.create(client)).build();
+const model = await biref.scan({ namespaces: 'all' });
+
+/** @type {TypedRoot} */
+const q = /** @type {any} */ (biref.query(model));
+
+// Full autocomplete on q.public.users.select('id', 'email'):
+await q.public.users
+  .select('id', 'email')
+  .include('orders', (o) => o.select('id', 'total'))
+  .findMany();
+```
+
+**One-time project setup.** Add a `jsconfig.json` at the project root so the language server knows to analyze your `.js` files and resolve types from `.ts`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "allowJs": true,
+    "checkJs": false,
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["**/*.js", "biref/**/*.ts"]
+}
+```
+
+`checkJs: false` means JSDoc types drive autocomplete without firing type errors on every line of JS - usually what JS users want.
+
+**Runtime is identical** in JS and TS - same Proxy, same chain builder, same executor, same queries. The TS/JS distinction exists only in the editor.
+
+---
+
+## How tables map to the domain model
+
+The Postgres adapter runs six parallel queries against `pg_catalog` and stitches the results into paradigm-neutral `Entity` objects. Here's what each piece of SQL becomes:
+
+**Tables** (`pg_class` where `relkind IN ('r', 'p')`) → `Entity` records with `namespace`, `name`, and `description` (from `pg_description`). Both regular tables and partitioned tables are picked up.
+
+**Columns** (`pg_attribute` + `pg_type`) → `Field[]`. Each column becomes one `Field` with:
+
+- `name` - the column name
+- `type.category` - one of 14 `FieldTypeCategory` values (see the enum in §3)
+- `type.nativeType` - the original `format_type()` output (`varchar(120)`, `numeric(10,2)`, `text[]`, etc.)
+- `nullable`, `isIdentifier`, `defaultValue`, `description`
+
+**Type category mapping.** Every Postgres built-in is mapped to a category:
+
+| Postgres type | Category | Notes |
+| --- | --- | --- |
+| `text`, `varchar`, `bpchar`, `char`, `name`, `citext` | `string` | |
+| `int2`, `int4`, `int8`, `smallint`, `integer`, `bigint` | `integer` | `int8` → `bigint` via the Postgres parser |
+| `numeric`, `decimal`, `float4`, `float8`, `money`, `real`, `double precision` | `decimal` | Kept as string to preserve precision |
+| `bool`, `boolean` | `boolean` | |
+| `date` | `date` | |
+| `timestamp`, `timestamptz` | `timestamp` | Parsed as JS `Date` |
+| `time`, `timetz` | `time` | Parsed as JS `Date` |
+| `json`, `jsonb` | `json` | Parsed to object; override type via `biref.schema.overrides.ts` |
+| `uuid` | `uuid` | |
+| `bytea` | `binary` | |
+| Custom `CREATE TYPE AS ENUM` | `enum` | Labels on `type.enumValues` |
+| Arrays (`text[]`, `int4[]`, ...) | `array` | Element type on `type.elementType` (including enum element types) |
+| `interval`, `inet`, `cidr`, `macaddr`, `macaddr8`, `bit`, `varbit`, geometric types, text search, range types, `xml` | `unknown` | Native type string preserved for branching |
+
+**Primary keys** (`pg_constraint` where `contype='p'`) → `entity.identifier`. Composite keys are preserved in declaration order; they drive both the typed chain's identifier tuple and the executor's stitching logic for inbound references.
+
+**Foreign keys** (`pg_constraint` where `contype='f'`) → two `Relationship` entries per FK, one on the source entity (direction `'outbound'`) and one on the target entity (direction `'inbound'`). Both directions reference the same underlying `Reference` object:
+
+```ts
+interface Reference {
+  name: string;                              // FK constraint name
+  fromEntity: { namespace: string; name: string };
+  fromFields: readonly string[];             // FK column(s) on the source
+  toEntity: { namespace: string; name: string };
+  toFields: readonly string[];               // PK column(s) on the target
+  confidence: 1;                             // always 1 for declared FKs
+  onUpdate: ReferentialAction | null;
+  onDelete: ReferentialAction | null;
+}
+```
+
+**Every FK flavor is supported:**
+
+- Single-column FKs
+- Composite FKs (multiple columns on both sides, column order preserved)
+- Self-referential FKs (same entity on both sides)
+- Cross-schema FKs (`billing.invoices.order_id` → `commerce.orders.id`)
+- Every `ON UPDATE` / `ON DELETE` action: `no-action`, `restrict`, `cascade`, `set-null`, `set-default`
+
+**Indexes** (`pg_index` excluding primary-key indexes) → `Index[]` with `kind` normalized to `'btree' | 'hash' | 'gin' | 'gist' | 'brin' | 'spgist' | 'unknown'`, plus `unique`, `partial`, `definition`, and the indexed field names.
+
+**Constraints** (`pg_constraint` where `contype IN ('c', 'u', 'x')`) → `Constraint[]` with `kind: 'unique' | 'check' | 'exclusion' | 'custom'` and the original expression text.
+
+---
+
+## Relation naming rules
+
+This is the most opinionated piece of the SDK. Understanding the rules up front saves a lot of "what's this relation called?" round-trips.
+
+### Outbound relations - named after the FK column
+
+When **this entity holds the FK**, the relation is named after the column with the trailing `_id` / `Id` stripped:
+
+| FK column | Friendly name | Rationale |
+| --- | --- | --- |
+| `user_id` | `user` | Obvious |
+| `kyc_id` | `kyc` | Matches the target table in simple cases |
+| `created_by_user_id` | `created_by_user` | ORM pattern (`createdByUserId` in camelCase also works) |
+| `primary_contact_id` | `primary_contact` | Column name matters more than target table name |
+| Composite `[tenant_id, user_id]` | `tenant_user` | Each stripped, joined with `_` |
+| Just `id` (rare) | (falls back to target entity name) | |
+
+The column's **semantic name** wins over the target table's name. If you have `customers.primary_contact_id` pointing at a `users` table, the relation is `primary_contact`, not `users`. This mirrors how Prisma and TypeORM name their relations.
+
+**Multiple FKs to the same target** are automatically distinct because their columns are different:
+
+```ts
+// posts.created_by_id → users.id    relation: 'created_by'
+// posts.modified_by_id → users.id   relation: 'modified_by'
+
+await root.public.posts
+  .include('created_by', (u) => u.select('id', 'email'))
+  .include('modified_by', (u) => u.select('id', 'email'))
+  .findMany();
+```
+
+### Inbound relations - named after the source entity
+
+When **another entity points at this one**, the relation uses the source entity's bare name:
+
+| Inbound source | Friendly name |
+| --- | --- |
+| `bank_details.customer_id → customers.id` | `bank_details` (on customers) |
+| `orders.user_id → users.id` | `orders` (on users) |
+| `sessions.user_id → users.id` | `sessions` (on users) |
+
+### Collisions - disambiguation by source column
+
+When two inbound FKs come from the **same source table** (e.g. `orders.created_by_id` and `orders.modified_by_id`, both pointing at `users`), the primary name goes to the first one and subsequent ones get `<source>_by_<stripped-column>`:
+
+```ts
+// users receives two inbounds from orders:
+// orders.created_by_id → friendly: 'orders'
+// orders.modified_by_id → friendly: 'orders_by_modified_by'
+
+await root.identity.users
+  .include('orders', ...)
+  .include('orders_by_modified_by', ...)
+  .findMany();
+```
+
+### Self-references - `parent` / `children`
+
+A self-referential FK (both sides of the relationship are the same entity) uses the conventional `'parent'` (outbound) and `'children'` (inbound) names instead of colliding on the entity's own name:
+
+```ts
+// catalog.categories has a self-ref FK (parent_id → id).
+await root.catalog.categories
+  .include('parent', (p) => p.select('id', 'name'))
+  .include('children', (c) => c.select('id', 'name'))
+  .findMany();
+```
+
+### Ultimate fallback
+
+If every other strategy still collides (pathological schema), the resolver falls back to the raw FK constraint name with a numeric suffix if needed. You can type the relation using that constraint name - ugly, but always addressable.
+
+---
+
+## Codegen output layout
+
+Everything codegen writes lives under `./biref/` by default:
+
+```
+biref/
+├── biref.schema.ts             ← single-file mode (or .ts re-exports below)
+├── biref.schema.overrides.ts   ← scaffolded once, never regenerated
+└── (split mode)
+    ├── index.ts                ← re-exports every per-entity interface + BirefSchema
+    ├── identity/
+    │   ├── users.ts            ← export interface IdentityUsers { ... }
+    │   └── accounts.ts
+    ├── catalog/
+    │   └── products.ts
+    └── commerce/
+        └── orders.ts
+```
+
+**When to use each mode.**
+
+| Mode | Use when | Import path |
+| --- | --- | --- |
+| Single file | Small to medium schemas, one file is easier to grep | `./biref/biref.schema` |
+| Split | Dozens of tables, you want per-table diffs in git | `./biref` (resolves to `./biref/index.ts`) |
+
+Both modes produce the same `BirefSchema` type and work identically with `biref.query<BirefSchema>(model)`. Pick whichever is easier to browse in your editor.
+
+**Regeneration contract.**
+
+- Every run overwrites every generated file deterministically.
+- `biref.schema.overrides.ts` is **only** written on first run (or if you deleted it). Your jsonb typings survive forever.
+- `--no-overwrite` refuses to touch existing generated files - useful for CI drift checks where you want the build to fail if the schema's out of date.
+
+---
+
+## Adapters
+
+Each adapter bundles an `Introspector` (reads the store), a `QueryEngine<TCommand>` (builds parameterized queries), a `RawQueryRunner` (executes them against the driver), and a `RecordParser` (coerces rows). Wiring is uniform: `someAdapter.create(client)`.
+
+### Postgres
+
+**Status:** Shipping.
+
+Reads `pg_catalog` and covers tables and partitioned tables in a single round trip of parallel queries (tables, columns, primary keys, foreign keys, indexes, constraints).
+
+**Wiring:**
+
+```ts
+import pg from 'pg';
+import { Biref, postgresAdapter } from '@biref/scanner';
+
+const client = new pg.Client({ connectionString: 'postgres://localhost/mydb' });
+await client.connect();
+
+const biref = Biref.builder()
+  .withAdapter(postgresAdapter.create(client))
+  .build();
+```
+
+The adapter accepts any client that satisfies the structural `PostgresClient` interface - `pg.Client`, `pg.Pool`, or any compatible library. The SDK never imports `pg` itself.
+
+**URL schemes:** `postgres://`, `postgresql://`.
+
+**Feature coverage:**
+
+| Area | Supported |
+| --- | --- |
+| Namespaces (schemas) | ✅ multiple per scan, cross-schema FKs, `'all'` sentinel |
+| Tables | ✅ regular and partitioned |
+| Columns | ✅ nullable, default, description (Postgres COMMENT) |
+| Primary keys | ✅ single and composite, declaration order preserved |
+| Foreign keys | ✅ single, composite, self-referential, cross-schema, every `ON UPDATE` / `ON DELETE` action |
+| Unique / check / exclusion constraints | ✅ with full definition |
+| Indexes | ✅ btree, hash, gin, gist, brin, spgist (partial + unique detected) |
+| Enums | ✅ including element detection on `enum[]` columns |
+| Arrays | ✅ all element types, enum element types, multi-dimensional |
+| Generated columns | ✅ |
+| Table / column comments | ✅ |
+| Typed query builder | ✅ `.query`, `.findMany`, `.findFirst`, `.include('*')`, `.select('*')` |
+
+**Type coverage:** every Postgres built-in mapped to a `FieldTypeCategory`. Types with no paradigm-neutral home (`interval`, `inet`, `cidr`, `macaddr`, bit strings, geometric types, text search, range types, `xml`) are tagged `unknown` with the native type string preserved, so callers can branch on it explicitly.
+
+**Parser:** `PostgresRecordParser`. Handles `int8` / `bigint` → JS `bigint`, `json` / `jsonb` strings → parsed objects, and falls back to `DefaultRecordParser` for everything else.
+
+---
+
+## API reference
+
+### Facade
+
+| Symbol | Purpose |
+| --- | --- |
+| `Biref.builder()` | Returns a fluent `BirefBuilder`. |
+| `BirefBuilder.withAdapter(adapter)` | Registers an adapter. |
+| `BirefBuilder.withAdapters(...adapters)` | Registers multiple adapters at once. |
+| `BirefBuilder.build()` | Materializes a `Biref` facade. |
+| `Biref.scan()` / `.scan(options)` / `.scan(name, options?)` | Introspects a data store. |
+| `Biref.scanByUrl(url, options?)` | Introspects via the adapter whose URL scheme matches. |
+| `Biref.query<Schema>(model, adapterName?)` | Returns a typed namespace proxy over `model`. Omit the generic for the untyped fallback. |
+| `Biref.adapters` | Direct access to the underlying `AdapterRegistry`. |
+
+### Typed query builder
+
+| Symbol | Purpose |
+| --- | --- |
+| `TypedChain<S, Ns, E, Sel, Inc>` | Narrowed fluent interface exposed via the proxy. |
+| `TypedQueryRoot<Schema>` | Two-layer typed root returned from `biref.query<Schema>(model)`. |
+| `UntypedQueryRoot` | Dynamic fallback for `biref.query(model)` without a generic. |
+| `ChainBuilder` | Runtime class behind the typed interface. Cast through for advanced use. |
+| `QueryPlan`, `QueryInclude` | Plan tree produced by the builder. |
+| `QueryPlanExecutor` | Core driver that walks a plan tree via `engine` + `runner` + `parser`. |
+| `RawQueryRunner` | Port: executes a `BuiltQuery` against an adapter's client. |
+
+### Type-level helpers (consumed by generated schemas)
+
+| Symbol | Purpose |
+| --- | --- |
+| `BirefSchemaShape` | Loose constraint for schemas passed to `biref.query<Schema>`. |
+| `SchemaFieldDescriptor`, `SchemaRelationDescriptor`, `SchemaEntityDescriptor`, `SchemaNamespaceDescriptor` | Compile-time descriptors emitted by codegen. |
+| `ApplySchemaOverrides<Raw, Overrides>`, `BirefOverridesShape` | Deep-merge user overrides onto a generated schema. |
+| `FieldsOf`, `TypeOf`, `CategoryOf`, `DefaultSelect`, `PickSelect`, `HydratedRow`, `Selection`, `IncludeMap`, `RelationsOf` | Row/selection narrowing helpers. |
+| `OpsFor`, `ValueFor`, `NullaryOps` | `where`-operator narrowing by field category. |
+| `RelationsOfEntity`, `TargetNs`, `TargetE`, `CardinalityOf`, `Split` | Relation / include narrowing. |
+| `CategoryOfField`, `WrapForCardinality` | Shared helpers used inside `TypedChain`. |
+
+### Codegen
+
+| Symbol | Purpose |
+| --- | --- |
+| `generateSchema(model)` | Pure function: emits the single-file schema text for a `DataModel`. |
+| `generateSchemaFiles(model)` | Pure function: emits the split-mode file list for a `DataModel`. |
+| `overridesScaffold()` | Returns the first-run `biref.schema.overrides.ts` template. |
+| `tsTypeFor(fieldType, nullable)` | Maps a `FieldType` to a TS type literal string. |
+| `biref gen --url … [--split] [--all-namespaces]` | CLI that connects, scans, and writes `./biref/` (+ overrides scaffold on first run). |
+
+### Domain
+
+| Symbol | Purpose |
+| --- | --- |
+| `DataModel`, `Entity`, `Field`, `FieldType`, `FieldTypeCategory` | Paradigm-neutral schema model. |
+| `Relationship`, `RelationshipDirection`, `Reference`, `EntityRef`, `ReferentialAction` | Bidirectional relationship model. |
+| `Constraint`, `ConstraintKind`, `Index`, `IndexKind` | Unique, check, exclusion, custom, and index kinds. |
+| `EngineKind` | Paradigm discriminator. |
+| `QuerySpec`, `Filter`, `FilterOperator`, `OrderBy`, `BuiltQuery`, `BuiltQueryMetadata` | Low-level declarative query types used internally by the builder. |
+
+### Parsers and formatters
+
+| Symbol | Purpose |
+| --- | --- |
+| `RecordParser`, `ParsedRecord`, `ParsedValue` | Parser contract and output shape. |
+| `DefaultRecordParser`, `PostgresRecordParser` | Generic + adapter-aware parsers. |
+| `Formatter`, `SerializeOptions`, `JsonFormatter`, `CsvFormatter`, `RawFormatter` | Serialization for parsed rows (dumps, exports). |
+
+### Adapter authoring
+
+Full guide in [CONTRIBUTING.md](./CONTRIBUTING.md). Public ports:
+
+| Symbol | Purpose |
+| --- | --- |
+| `Introspector`, `IntrospectOptions`, `QueryEngine<TCommand>`, `RawQueryRunner`, `AdapterFactory<TClient, TName>` | Ports a new adapter must implement. |
+| `Adapter<TName>`, `AdapterName`, `KnownAdapterName`, `AdapterRegistry` | Generic adapter shape and the registry that holds them. |
+
+---
+
+## Contributing
+
+Architecture notes, repository layout, development workflow, and tooling conventions live in **[CONTRIBUTING.md](./CONTRIBUTING.md)**. PRs welcome.
+
+## License
+
+MIT.