@biref/scanner 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,1507 @@
+/**
+ * Structural type for the database client the Postgres adapter consumes.
+ *
+ * Declares a single `query` method that takes a SQL string plus
+ * optional parameters and returns an object with a `rows` array.
+ * `pg.Client`, `pg.Pool`, and any structurally compatible library
+ * satisfy the shape without the SDK importing `pg`.
+ *
+ * @example
+ * ```ts
+ * import pg from 'pg';
+ * const client = new pg.Client({ ... });
+ * await client.connect();
+ * postgresAdapter.create(client);
+ * ```
+ */
+interface PostgresClient {
+    query<TRow = unknown>(text: string, params?: readonly unknown[]): Promise<{
+        rows: TRow[];
+    }>;
+}
+
+/**
+ * The paradigm of an underlying data store.
+ *
+ * Used as a discriminator on `DataModel` so consumers can branch on the
+ * paradigm without inspecting adapter-specific details. New paradigms can
+ * be added without breaking existing consumers; fall back to `'unknown'`
+ * if you do not recognize a value.
+ */
+type EngineKind = 'relational' | 'document' | 'key-value' | 'graph' | 'wide-column' | 'time-series' | 'unknown';
+
+/**
+ * Kind of constraint declared on an entity.
+ *
+ * Categories:
+ *   'unique':    enforces uniqueness on a set of fields
+ *   'check':     evaluates an expression that must be true for every row
+ *   'exclusion': pg-style exclusion constraint
+ *   'custom':    paradigm-specific constraint that does not fit the above
+ */
+type ConstraintKind = 'unique' | 'check' | 'exclusion' | 'custom';
+/**
+ * A constraint declared on an entity.
+ *
+ * Excludes the primary key, which is exposed through the entity's
+ * `identifier` instead. Excludes foreign keys, which are exposed through
+ * `relationships`.
+ *
+ * Fields:
+ *   name:       constraint name as reported by the data store
+ *   kind:       category of constraint
+ *   fields:     field names the constraint applies to
+ *   expression: textual definition (e.g. CHECK clause body) or null
+ */
+interface Constraint {
+    readonly name: string;
+    readonly kind: ConstraintKind;
+    readonly fields: readonly string[];
+    readonly expression: string | null;
+}
+
+/**
+ * Normalized category of a field's type, abstracted from any specific
+ * data store's native type system.
+ *
+ * Adapters are responsible for mapping their native types onto these
+ * categories. Consumers should branch on `category` rather than
+ * `nativeType` for portable, paradigm-neutral logic (e.g. "render a
+ * date picker for `date` fields").
+ */
+type FieldTypeCategory = 'string' | 'integer' | 'decimal' | 'boolean' | 'date' | 'timestamp' | 'time' | 'json' | 'uuid' | 'binary' | 'enum' | 'array' | 'reference' | 'unknown';
+/**
+ * A field's type, normalized across data store paradigms.
+ *
+ * `nativeType` is the raw string the adapter reported, kept for
+ * transparency and edge cases. Optional properties carry additional
+ * structure when meaningful for the category.
+ */
+interface FieldType {
+    readonly category: FieldTypeCategory;
+    readonly nativeType: string;
+    /** Maximum length, when applicable (e.g. varchar(255)). */
+    readonly length?: number;
+    /** Numeric precision, when applicable. */
+    readonly precision?: number;
+    /** Numeric scale, when applicable. */
+    readonly scale?: number;
+    /** Allowed values, for enum-typed fields. */
+    readonly enumValues?: readonly string[];
+    /** Element type, for array/collection fields. */
+    readonly elementType?: FieldType;
+}
+
+/**
+ * A single field within an entity.
+ *
+ * Maps to:
+ *  - relational: column
+ *  - document:   document field
+ *  - graph:      node/edge property
+ *
+ * `nullable` and `defaultValue` may be best-effort approximations in
+ * paradigms without strict schemas. Adapters document how they determine
+ * each value.
+ */
+interface Field {
+    readonly name: string;
+    readonly type: FieldType;
+    readonly nullable: boolean;
+    /**
+     * True if this field participates in the entity's identifier.
+     * Paradigm-neutral replacement for "primary key".
+     */
+    readonly isIdentifier: boolean;
+    readonly defaultValue: string | null;
+    readonly description: string | null;
+}
+
+/**
+ * Kind of index physically created on an entity.
+ *
+ * Includes the common Postgres families. Adapters that target other
+ * stores map their native index types onto these or report 'unknown'.
+ */
+type IndexKind = 'btree' | 'hash' | 'gin' | 'gist' | 'brin' | 'spgist' | 'unknown';
+/**
+ * An index defined on an entity.
+ *
+ * Excludes the index that backs the primary key, since that information
+ * is already available through the entity's `identifier`.
+ *
+ * Fields:
+ *   name:       index name as reported by the data store
+ *   fields:     field names the index covers, in order
+ *   unique:     true if the index enforces uniqueness
+ *   kind:       physical index type
+ *   partial:    true if the index has a WHERE clause
+ *   definition: textual definition (e.g. CREATE INDEX statement) or null
+ */
+interface Index {
+    readonly name: string;
+    readonly fields: readonly string[];
+    readonly unique: boolean;
+    readonly kind: IndexKind;
+    readonly partial: boolean;
+    readonly definition: string | null;
+}
+
+/**
+ * Action a data store takes when a referenced row/document is updated or
+ * deleted. `null` indicates the paradigm does not enforce referential
+ * actions (e.g. document stores).
+ */
+type ReferentialAction = 'no-action' | 'restrict' | 'cascade' | 'set-null' | 'set-default';
+/**
+ * A qualified pointer to an entity, used to identify the source and
+ * target of a `Reference` without embedding the full entity.
+ */
+interface EntityRef {
+    readonly namespace: string;
+    readonly name: string;
+}
+/**
+ * A pointer from one set of fields in one entity to another set of
+ * fields in another entity.
+ *
+ * Paradigm-neutral abstraction:
+ *  - relational: built from a declared FOREIGN KEY constraint
+ *  - document:   inferred from naming conventions and value sampling
+ *  - graph:      built from declared edge definitions
+ *
+ * `confidence` is `1` for declared references (e.g. SQL foreign keys)
+ * and less than `1` for inferred references. Adapters that only ever
+ * return declared references should always set this to `1`.
+ */
+interface Reference {
+    readonly name: string;
+    readonly fromEntity: EntityRef;
+    readonly fromFields: readonly string[];
+    readonly toEntity: EntityRef;
+    readonly toFields: readonly string[];
+    readonly confidence: number;
+    readonly onUpdate: ReferentialAction | null;
+    readonly onDelete: ReferentialAction | null;
+}
+
+/**
+ * Direction of a relationship from the perspective of the entity that
+ * owns it.
+ *
+ *  - 'outbound': this entity holds the reference and points outward.
+ *  - 'inbound':  another entity holds a reference that points to this one.
+ *
+ * Storing both directions on each entity is the central feature of the
+ * SDK. Most introspection tools only expose outbound relationships,
+ * forcing consumers to know which other entities reference theirs ahead
+ * of time.
+ */
+type RelationshipDirection = 'outbound' | 'inbound';
+/**
+ * A relationship as seen from a specific entity, with a direction.
+ *
+ * The same underlying `Reference` appears as 'outbound' on the source
+ * entity and 'inbound' on the target entity.
+ */
+interface Relationship {
+    readonly direction: RelationshipDirection;
+    readonly reference: Reference;
+}
+
+/**
+ * A unit of data with named fields, identifier, relationships,
+ * constraints, and indexes.
+ *
+ * Maps to:
+ *   relational: table or view
+ *   document:   collection
+ *   graph:      node label
+ *   key-value:  bucket
+ *
+ * Fields:
+ *   namespace:     schema or database the entity lives in
+ *   name:          entity name
+ *   fields:        the entity's fields, in declaration order
+ *   identifier:    field names that uniquely identify a row of this entity;
+ *                  contains all fields involved in a composite identifier;
+ *                  empty when the entity has no identifier
+ *   relationships: all relationships involving this entity, in BOTH
+ *                  directions; filter by `direction` to get outbound or
+ *                  inbound separately
+ *   constraints:   constraints declared on the entity (unique, check,
+ *                  exclusion, custom); excludes the primary key
+ *   indexes:       indexes defined on the entity; excludes the index
+ *                  that backs the primary key
+ *   description:   human-readable comment, when available
+ */
+interface Entity {
+    readonly namespace: string;
+    readonly name: string;
+    readonly fields: readonly Field[];
+    readonly identifier: readonly string[];
+    readonly relationships: readonly Relationship[];
+    readonly constraints: readonly Constraint[];
+    readonly indexes: readonly Index[];
+    readonly description: string | null;
+}
+
+/**
+ * The aggregate root for an introspected data store.
+ *
+ * Holds all entities discovered by an `Introspector`, indexed for
+ * efficient lookup, and exposes navigation helpers around relationships.
+ *
+ * Paradigm-neutral: the same shape is returned for relational, document,
+ * graph, and other data stores. Use `kind` to branch when needed.
+ */
+declare class DataModel {
+    readonly kind: EngineKind;
+    readonly entities: readonly Entity[];
+    private readonly index;
+    constructor(kind: EngineKind, entities: readonly Entity[]);
+    /**
+     * Build the lookup key for an entity. Exposed as a static helper so
+     * consumers can compute keys consistently when building their own
+     * indexes on top of a `DataModel`.
+     */
+    static qualifiedName(namespace: string, name: string): string;
+    getEntity(namespace: string, name: string): Entity | undefined;
+    hasEntity(namespace: string, name: string): boolean;
+    /**
+     * All relationships an entity participates in, in both directions.
+     * Returns an empty array if the entity is unknown.
+     */
+    relationshipsOf(namespace: string, name: string): readonly Relationship[];
+    /**
+     * Outbound relationships: this entity holds the reference.
+     * In a relational store these correspond to FOREIGN KEY constraints
+     * declared by the entity itself.
+     */
+    outboundRelationshipsOf(namespace: string, name: string): readonly Relationship[];
+    /**
+     * Inbound relationships: other entities hold references pointing here.
+     *
+     * This is the differentiating feature of the SDK. Most introspection
+     * tools only surface outbound relationships, requiring consumers to
+     * know which other entities reference theirs ahead of time.
+     */
+    inboundRelationshipsOf(namespace: string, name: string): readonly Relationship[];
+}
+
+/**
+ * Port: a paradigm-specific introspector capable of producing a
+ * `DataModel` from an underlying data store.
+ *
+ * Implementations are provided by adapters, registered with an
+ * `AdapterRegistry`, and resolved through the public `Scanner` facade.
+ *
+ * Adapters are responsible for accepting their own native client/driver
+ * in their constructor. The SDK does not impose a unified client
+ * abstraction because the shape of "a client" varies wildly across
+ * paradigms.
+ */
+interface Introspector {
+    /** Stable adapter identifier (e.g. 'postgres', 'mongo'). */
+    readonly name: string;
+    /** Paradigm of the underlying data store. */
+    readonly kind: EngineKind;
+    /** Read the data store and produce a paradigm-neutral `DataModel`. */
+    introspect(options?: IntrospectOptions): Promise<DataModel>;
+}
+interface IntrospectOptions {
+    /**
+     * Namespaces to include. The adapter chooses a default if omitted
+     * (Postgres picks `['public']`). Pass the literal string `'all'`
+     * to scan every non-system namespace the adapter can discover -
+     * useful when bootstrapping codegen against an unfamiliar
+     * database.
+     */
+    readonly namespaces?: readonly string[] | 'all';
+    /** Optional entity allowlist (matched after namespace filtering). */
+    readonly includeEntities?: readonly string[];
+    /** Optional entity denylist (matched after namespace filtering). */
+    readonly excludeEntities?: readonly string[];
+}
+
+/**
+ * Postgres implementation of the `Introspector` port.
+ *
+ * Runs six queries against `pg_catalog` in parallel (tables, columns,
+ * primary keys, foreign keys, indexes, constraints) and hands the
+ * result to `EntityAssembler`, which stitches them into a paradigm-
+ * neutral `DataModel`.
+ *
+ * What it returns for each entity:
+ *   - fields with normalized type categories
+ *   - identifier (primary key columns)
+ *   - relationships in BOTH directions
+ *   - constraints (unique, check, exclusion)
+ *   - indexes (excluding the primary key index)
+ *
+ * Accepts any client that satisfies `PostgresClient`, so it works with
+ * `pg.Client`, `pg.Pool`, or any compatible library without the SDK
+ * importing `pg`.
+ */
+declare class PostgresIntrospector implements Introspector {
+    private readonly client;
+    readonly name = "postgres";
+    readonly kind: "relational";
+    constructor(client: PostgresClient);
+    introspect(options?: IntrospectOptions): Promise<DataModel>;
+    private resolveNamespaces;
+    private static readonly ALL_NAMESPACES_SQL;
+    private static applyEntityFilters;
+}
+
+/**
+ * Adapter metadata constants for Postgres.
+ *
+ * Centralized so the rest of the adapter never references the literal
+ * string 'postgres' or the URL schemes by hand. Anywhere those values
+ * are needed, import the constant.
+ */
+declare const POSTGRES_ADAPTER_NAME = "postgres";
+/** Literal type for the Postgres adapter name, used for discrimination. */
+type PostgresAdapterName = typeof POSTGRES_ADAPTER_NAME;
+declare const POSTGRES_URL_SCHEMES: readonly string[];
+
+/**
+ * Output of `QueryEngine.build`.
+ *
+ * Holds:
+ *   command:  the engine-specific instruction to execute
+ *   params:   the bound parameter values
+ *   metadata: information about the engine and parameter count
+ *
+ * The SDK never executes a `BuiltQuery`. The consumer passes `command`
+ * and `params` to their own driver.
+ *
+ * `TCommand` is the shape of the command for a given engine:
+ *   relational engines -> `BuiltQuery<string>` (SQL string)
+ *   document engines   -> `BuiltQuery<DocFilter>` (filter object)
+ */
+interface BuiltQuery<TCommand = unknown> {
+    readonly command: TCommand;
+    readonly params: readonly unknown[];
+    readonly metadata: BuiltQueryMetadata;
+}
+interface BuiltQueryMetadata {
+    /** Engine that produced this query (e.g. 'postgres', 'mongo'). */
+    readonly engine: string;
+    /** Number of parameters bound. */
+    readonly paramCount: number;
+}
+
+/**
+ * Declarative description of a query against a `DataModel`.
+ *
+ * Paradigm-neutral: the same `QuerySpec` can be handed to a relational
+ * `QueryEngine` (which produces a SQL string) or a document
+ * `QueryEngine` (which produces a Mongo filter, etc).
+ *
+ * Engines are responsible for raising clear errors when a spec contains
+ * something they cannot represent in their target language.
+ */
+interface QuerySpec {
+    readonly namespace: string;
+    readonly entity: string;
+    /** Field names to project. `undefined` means "all fields". */
+    readonly select?: readonly string[];
+    readonly filters?: readonly Filter[];
+    readonly orderBy?: readonly OrderBy[];
+    readonly limit?: number;
+    readonly offset?: number;
+}
+interface Filter {
+    readonly field: string;
+    readonly operator: FilterOperator;
+    readonly value: unknown;
+}
+type FilterOperator = 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'like' | 'ilike' | 'in' | 'not-in' | 'is-null' | 'is-not-null' | 'between';
+interface OrderBy {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+
+/**
+ * Port: a paradigm-specific engine that turns a `QuerySpec` into a
+ * ready-to-execute `BuiltQuery`.
+ *
+ * `TCommand` lets each engine pick the right command shape for its
+ * paradigm: a SQL string, a Mongo filter, a Cypher query, etc. The
+ * default of `unknown` is intentional. Code that holds an
+ * engine-agnostic reference cannot accidentally assume a command shape.
+ */
+interface QueryEngine<TCommand = unknown> {
+    /** Stable engine identifier (e.g. 'postgres', 'mongo'). */
+    readonly name: string;
+    /** Paradigm this engine targets. */
+    readonly kind: EngineKind;
+    /**
+     * Build a query from a declarative spec, validating it against the
+     * provided `DataModel`. Engines must throw on unknown entities or
+     * fields rather than silently producing broken queries.
+     */
+    build(spec: QuerySpec, model: DataModel): BuiltQuery<TCommand>;
+}
+
+/**
+ * Postgres implementation of the `QueryEngine` port.
+ *
+ * Produces parameterized SQL using `$1`, `$2`, ... placeholders and
+ * double-quoted identifiers. Validates the spec against the
+ * `DataModel` before emitting any SQL: unknown entities or fields
+ * throw rather than yielding a broken query.
+ *
+ * Scope:
+ *   - SELECT against a single entity
+ *   - WHERE filters (every `FilterOperator`)
+ *   - ORDER BY
+ *   - LIMIT and OFFSET
+ *   - No joins, group by, or aggregates yet
+ */
+declare class PostgresQueryEngine implements QueryEngine<string> {
+    readonly name = "postgres";
+    readonly kind: "relational";
+    build(spec: QuerySpec, model: DataModel): BuiltQuery<string>;
+}
+
+/**
+ * The set of JS values a `RecordParser` produces after coercing raw
+ * driver output. Covers the common cases without pulling in
+ * framework-specific types.
+ *
+ * `null` represents both SQL NULL and a missing document field.
+ */
+type ParsedValue = string | number | bigint | boolean | Date | null | ParsedValue[] | {
+    readonly [key: string]: ParsedValue;
+};
+/**
+ * A single record after parsing. A map of field name to coerced value.
+ *
+ * Returned by `RecordParser.parse`. Consumed by `Formatter.serialize`.
+ */
+interface ParsedRecord {
+    readonly [field: string]: ParsedValue;
+}
+
+/**
+ * Port: turns raw rows from a database driver into typed `ParsedRecord`s
+ * using an `Entity`'s field metadata to coerce values.
+ *
+ * Implementations live in the SDK (default) or can be provided by users
+ * who need custom coercion (e.g. mapping `decimal` columns to a Big.js
+ * type instead of the default string).
+ */
+interface RecordParser {
+    /** Parse a single raw row using the entity's field definitions. */
+    parse(entity: Entity, row: Readonly<Record<string, unknown>>): ParsedRecord;
+    /** Parse many rows. Convenience wrapper around `parse`. */
+    parseMany(entity: Entity, rows: readonly Readonly<Record<string, unknown>>[]): readonly ParsedRecord[];
+}
+
+/**
+ * Default `RecordParser` used when no adapter-specific parser is needed.
+ *
+ * Coerces raw driver output to JS values using the field type
+ * categories from the `DataModel`:
+ *   string | uuid | enum  -> JS string
+ *   integer               -> JS number (or bigint if raw is bigint)
+ *   decimal               -> JS string (preserves precision)
+ *   boolean               -> JS boolean
+ *   date | timestamp | time -> JS Date
+ *   json                  -> pass-through
+ *   binary                -> pass-through
+ *   array                 -> pass-through if already an array, else []
+ *   reference             -> pass-through
+ *   unknown               -> pass-through
+ *
+ * Null and undefined raw values become `null`. Fields on the entity
+ * that are absent from the row are omitted from the result, so a
+ * partial projection only emits the keys that were selected.
+ *
+ * The `coerce` method is `protected` so adapter-specific subclasses
+ * (for example `PostgresRecordParser`) can override or extend it.
+ */
+declare class DefaultRecordParser implements RecordParser {
+    parse(entity: Entity, row: Readonly<Record<string, unknown>>): ParsedRecord;
+    parseMany(entity: Entity, rows: readonly Readonly<Record<string, unknown>>[]): readonly ParsedRecord[];
+    protected coerce(field: Field, raw: unknown): ParsedValue;
+}
+
+/**
+ * Postgres-aware `RecordParser`.
+ *
+ * Extends `DefaultRecordParser` with behavior that matches how the
+ * `pg` driver returns Postgres values:
+ *
+ *   - `int8` / `bigint` columns are returned by `pg` as strings by
+ *     default (to preserve precision). This parser converts them to
+ *     JS `bigint` so downstream code does not silently lose digits.
+ *
+ *   - `json` / `jsonb` columns are usually already parsed by `pg`,
+ *     but when they arrive as strings (for example from drivers that
+ *     do not auto-parse) this parser parses them.
+ *
+ *   - All other categories fall through to `DefaultRecordParser`.
+ *
+ * Use this parser when consuming rows that come from a `pg.Client` or
+ * `pg.Pool`. For adapters that handle these concerns themselves, the
+ * default parser is still appropriate.
+ */
+declare class PostgresRecordParser extends DefaultRecordParser {
+    protected coerce(field: Field, raw: unknown): ParsedValue;
+}
+
+/**
+ * Port: executes a `BuiltQuery` against an underlying driver and
+ * returns the raw rows.
+ *
+ * Sits one layer below `RecordParser`: the runner only hands back
+ * untyped row objects, and the parser turns them into `ParsedRecord`s
+ * using the entity's field metadata.
+ *
+ * Each adapter implements this against its own client (for example
+ * `PostgresRawQueryRunner` wraps a `PostgresClient`). Used by
+ * `QueryPlanExecutor` to drive the typed query API.
+ *
+ * @example
+ * ```ts
+ * const rows = await runner.run(built);
+ * ```
+ */
+interface RawQueryRunner {
+    run<TRow = unknown>(built: BuiltQuery): Promise<readonly TRow[]>;
+}
+
+/**
+ * Names of the adapters that ship with the SDK.
+ *
+ * Grows as new adapters are added. Consumers can still register custom
+ * adapters with any name; the type accepts arbitrary strings in
+ * addition to the known ones (see `AdapterName`).
+ */
+type KnownAdapterName = 'postgres';
+/**
+ * Adapter name type.
+ *
+ * Known adapter names appear in IDE autocomplete when calling
+ * `Biref.scan(...)`, `AdapterRegistry.get(...)`, and similar APIs.
+ * Any other string is still accepted so consumers can register
+ * adapters the SDK does not know about.
+ *
+ * Pattern: `KnownAdapterName | (string & {})` preserves literal
+ * suggestions while also accepting the broader string type.
+ */
+type AdapterName = KnownAdapterName | (string & {});
+/**
+ * An adapter packaged for registration with `Biref` or `AdapterRegistry`.
+ *
+ * Generic over `TName` so each adapter declares its name as a literal
+ * string type. Consumers narrow by comparing `adapter.name` against an
+ * exported constant from the adapter module:
+ *
+ *   import { POSTGRES_ADAPTER_NAME } from '@biref/scanner';
+ *
+ *   if (adapter.name === POSTGRES_ADAPTER_NAME) {
+ *     // adapter is narrowed to Adapter<'postgres'>
+ *   }
+ *
+ * Fields:
+ *   name:         literal name of the adapter (e.g. 'postgres')
+ *   introspector: produces a `DataModel` from the data store
+ *   engine:       turns a `QuerySpec` into a `BuiltQuery`
+ *   runner:       executes a `BuiltQuery` and returns raw rows
+ *   parser:       coerces raw rows into typed `ParsedRecord`s
+ *   urlSchemes:   URL schemes the adapter handles, for auto-detection
+ *
+ * `runner` and `parser` are optional on the interface so older adapter
+ * modules stay source-compatible. The typed query API requires both.
+ */
+interface Adapter<TName extends AdapterName = AdapterName> {
+    readonly name: TName;
+    readonly introspector: Introspector;
+    readonly engine: QueryEngine;
+    readonly runner?: RawQueryRunner;
+    readonly parser?: RecordParser;
+    readonly urlSchemes?: readonly string[];
+}
+/**
+ * Registry of `Adapter` instances keyed by name.
+ *
+ * Looked up by `Biref` and the lower-level facades. Registration is
+ * explicit: the SDK has zero runtime dependencies and cannot know
+ * which adapters are installed.
+ */
+declare class AdapterRegistry {
+    private readonly adapters;
+    register(adapter: Adapter): void;
+    unregister(name: AdapterName): boolean;
+    get(name: AdapterName): Adapter;
+    has(name: AdapterName): boolean;
+    list(): readonly string[];
+    /**
+     * Find an adapter that claims the given URL scheme. Case-insensitive.
+     * Returns `undefined` if no adapter handles it.
+     */
+    findByUrlScheme(scheme: string): Adapter | undefined;
+    /**
+     * Same as `findByUrlScheme` but throws a helpful error listing the
+     * known schemes when no match is found.
+     */
+    getByUrlScheme(scheme: string): Adapter;
+}
+
+/**
+ * Common interface every adapter module exports.
+ *
+ * Describes how to construct an `Adapter` for a specific data store.
+ *
+ * Type parameters:
+ *   TClient: shape of the driver client the factory expects (for
+ *            example `PostgresClient` for the Postgres adapter)
+ *   TName:   literal name type, exported alongside the factory for
+ *            type-safe discrimination at call sites
+ *
+ * Fields:
+ *   name:       literal adapter name (e.g. 'postgres')
+ *   urlSchemes: URL schemes the adapter handles
+ *   create:     builds an `Adapter<TName>` bound to the given client
+ *
+ * @example
+ * ```ts
+ * import { Biref, postgresAdapter } from '@biref/scanner';
+ *
+ * const biref = Biref.builder()
+ *   .withAdapter(postgresAdapter.create(client))
+ *   .build();
+ * ```
+ */
+interface AdapterFactory<TClient = unknown, TName extends AdapterName = AdapterName> {
+    readonly name: TName;
+    readonly urlSchemes: readonly string[];
+    create(client: TClient): Adapter<TName>;
+}
+
+/**
+ * Postgres adapter factory.
+ *
+ * Implements `AdapterFactory<PostgresClient, PostgresAdapterName>`.
+ * `create` builds an `Adapter` bound to the user-provided client.
+ *
+ * @example
+ * ```ts
+ * import pg from 'pg';
+ * import { Biref, postgresAdapter } from '@biref/scanner';
+ *
+ * const client = new pg.Client({ ... });
+ * await client.connect();
+ *
+ * const biref = Biref.builder()
+ *   .withAdapter(postgresAdapter.create(client))
+ *   .build();
+ *
+ * const model = await biref.scan();
+ * ```
+ */
+declare const postgresAdapter: AdapterFactory<PostgresClient, PostgresAdapterName>;
+/**
+ * Type guard: narrows a generic `Adapter` to an `Adapter<PostgresAdapterName>`.
+ *
+ * @example
+ * ```ts
+ * if (isPostgresAdapter(adapter)) {
+ *   // adapter.name is now typed as 'postgres'
+ * }
+ * ```
+ */
+declare function isPostgresAdapter(adapter: Adapter): adapter is Adapter<PostgresAdapterName>;
+
+/**
+ * Content of the first-run overrides file scaffold.
+ *
+ * The CLI only writes this if the target path does not already
+ * exist - once the user has started editing it, regenerating the
+ * schema never overwrites their work.
+ */
+declare function overridesScaffold(): string;
+
+/**
+ * A single file produced by split-mode codegen.
+ *
+ * Paths are always relative to the output folder the user passed to
+ * the CLI (or to `writeSchemaFiles`) and use forward slashes. The
+ * caller is responsible for joining them onto an absolute path and
+ * creating any intermediate directories.
+ */
+interface SchemaFile {
+    readonly path: string;
+    readonly content: string;
+}
+/**
+ * Emit a TypeScript schema declaration from a scanned `DataModel` as
+ * a single self-contained `.ts` file.
+ *
+ * The output exports:
+ *
+ *   - `RawBirefSchema`: the literal schema shape the model discovered
+ *   - `BirefSchema`:    `RawBirefSchema` with user overrides applied
+ *
+ * Deterministic: the same `DataModel` input always produces the same
+ * string, suitable for snapshot tests and stable git diffs.
+ *
+ * Use this when you want everything in one file. For larger schemas
+ * `generateSchemaFiles` emits one file per entity plus an index and
+ * tends to be easier to browse.
+ */
+declare function generateSchema(model: DataModel): string;
+/**
+ * Emit a folder of split schema files from a scanned `DataModel`.
+ *
+ * Layout:
+ *
+ *   index.ts                Root file re-exporting every per-entity
+ *                           interface and composing `RawBirefSchema`
+ *                           plus `BirefSchema`.
+ *   <namespace>/<entity>.ts One file per entity with its field
+ *                           descriptor, identifier tuple, and
+ *                           relations map.
+ *
+ * The overrides file is **not** emitted by this function - it is
+ * scaffolded once by the CLI and never touched again.
+ *
+ * Returns the files in a deterministic order so consumers can write
+ * them or snapshot-test them safely.
+ */
+declare function generateSchemaFiles(model: DataModel): readonly SchemaFile[];
+
+/**
+ * Maps a paradigm-neutral `FieldType` to the TypeScript type literal
+ * string emitted into the codegen-generated schema.
+ *
+ * JSON / JSONB categories map to `unknown` (users replace them via
+ * the sibling overrides file). Enum categories with known values map
+ * to a union of string literals. Array categories recurse on the
+ * element type. Everything else follows the fixed table described in
+ * the README.
+ */
+declare function tsTypeFor(type: FieldType, nullable: boolean): string;
+
+/**
+ * A node in the typed query builder's plan tree.
+ *
+ * Each node wraps a single-entity `QuerySpec` (executed against the
+ * adapter's engine) plus any child includes to resolve recursively.
+ * `QueryPlanExecutor` walks this tree to execute and stitch.
+ */
+interface QueryPlan {
+    readonly spec: QuerySpec;
+    readonly includes: readonly QueryInclude[];
+}
+/**
+ * A nested include on a parent plan.
+ *
+ * `relationName` is the name the user wrote in `.include('orders', ...)`
+ * on the builder (either a friendly name computed from the model or,
+ * on collisions, the underlying foreign key constraint name).
+ *
+ * `direction` mirrors `Relationship.direction`. `parentKeys` are the
+ * columns on the parent entity used to filter children; `childKeys`
+ * are their counterparts on the child entity. For outbound includes
+ * (FK → target PK) the parent holds the FK columns; for inbound the
+ * parent holds the PK columns.
+ *
+ * `cardinality` drives how the executor stitches children into the
+ * parent record: `'one'` picks the first match, `'many'` returns the
+ * full array.
+ */
+interface QueryInclude {
+    readonly relationName: string;
+    readonly plan: QueryPlan;
+    readonly direction: 'inbound' | 'outbound';
+    readonly parentKeys: readonly string[];
+    readonly childKeys: readonly string[];
+    readonly cardinality: 'one' | 'many';
+}
+
+/**
+ * Executes a `QueryPlan` tree against an adapter's engine, runner, and
+ * parser, stitching include results into nested shapes on the parent.
+ *
+ * Runs one query per plan node - root first, then one query per
+ * include level, filtered to the parent keys it just collected. This
+ * matches Prisma's approach: sequential sub-queries with in-process
+ * hydration, rather than SQL JOINs. It keeps the engine layer
+ * paradigm-neutral and works without any JOIN support in the
+ * adapter's `QueryEngine`.
+ *
+ * Projection honoring: join-key columns are transparently added to
+ * both the parent's and each child's SELECT so the stitcher can read
+ * them, then removed from the final hydrated records so the caller
+ * sees only the columns they originally asked for.
+ */
+declare class QueryPlanExecutor {
+    private readonly engine;
+    private readonly runner;
+    private readonly parser;
+    constructor(engine: QueryEngine, runner: RawQueryRunner, parser: RecordParser);
+    execute(plan: QueryPlan, model: DataModel): Promise<readonly ParsedRecord[]>;
+    private attachIncludes;
+    private static prepareChildPlan;
+    private static injectFields;
+    private static collectParentKeys;
+    /**
+     * Compute the set of keys a hydrated record should expose to the
+     * caller: the user's selected fields (or every entity field when
+     * no select was given) plus every nested include's relation name
+     * so attached children survive the final filter step.
+     */
+    private static resolveExposedKeys;
+    /**
+     * Resolve the exposed-keys set for an include's nested plan.
+     *
+     * Uses the ORIGINAL include.plan (not the mutated child plan we
+     * handed to the executor) so injected join keys do not leak into
+     * the final output.
+     */
+    private static resolveChildExposedKeys;
+    private static project;
+    private static indexByKey;
+    private static buildKey;
+    private static filterKeys;
+}
+
+/**
+ * Runtime context threaded through every `ChainBuilder` instance.
+ *
+ * Holds the scanned `DataModel` used for validation and the
+ * `QueryPlanExecutor` that actually runs terminal methods like
+ * `findMany` / `findFirst`.
+ */
+interface ChainBuilderContext {
+    readonly model: DataModel;
+    readonly executor: QueryPlanExecutor;
+}
+/**
+ * Immutable fluent builder that accumulates a `QueryPlan`.
+ *
+ * Each mutating method (`select`, `where`, `orderBy`, `limit`,
+ * `offset`, `include`) returns a **new** `ChainBuilder` - chains are
+ * safe to fork.
+ *
+ * Field and relation names are validated against the `DataModel` at
+ * call time so mistakes throw immediately with a clear message.
+ * Compile-time typing comes from the generic parameters (see
+ * `src/query/types/*`); the runtime implementation here is
+ * schema-agnostic.
+ */
+declare class ChainBuilder {
+    private readonly ctx;
+    private readonly plan;
+    constructor(ctx: ChainBuilderContext, plan: QueryPlan);
+    /**
+     * Narrow the projection to a specific set of fields.
+     *
+     *   .select('id', 'email')  -- only these two columns
+     *   .select('*')            -- every field of the entity
+     *   .select()               -- equivalent to '*', kept for ergonomic parity
+     *
+     * Unknown field names throw immediately with a clear error; the
+     * wildcard sentinel skips validation and leaves the plan's `select`
+     * undefined so the engine emits every column the adapter reported.
+     */
+    select(...fields: readonly string[]): ChainBuilder;
+    where(field: string, operator: FilterOperator, value?: unknown): ChainBuilder;
+    orderBy(field: string, direction?: 'asc' | 'desc'): ChainBuilder;
+    limit(count: number): ChainBuilder;
+    offset(count: number): ChainBuilder;
+    /**
+     * Attach a nested include to the plan.
+     *
+     * Three call shapes are supported:
+     *
+     *   .include('orders')                                 -- all fields, no nested
+     *   .include('orders', (q) => q.select('id', 'total')) -- narrow the child
+     *   .include('*')                                      -- every relation on this entity
+     *
+     * The callback is optional. When omitted, the child plan uses the
+     * default projection (all fields of the related entity) and no
+     * further includes. Pass a callback when you want to narrow the
+     * projection or chain additional nested includes.
+     *
+     * The wildcard `'*'` expands to one include per relation discovered
+     * on the current entity. Each expanded include uses the default
+     * projection. Combining `'*'` with a callback is not supported -
+     * the sub-builder's shape differs per relation, so a single
+     * callback cannot narrow all of them coherently.
+     */
+    include(relationName: string, build?: (q: ChainBuilder) => ChainBuilder): ChainBuilder;
+    findMany(): Promise<readonly ParsedRecord[]>;
+    findFirst(): Promise<ParsedRecord | null>;
+    /**
+     * Escape hatch for advanced callers (tests, tooling): exposes the
+     * accumulated plan without executing it. The typed builder's public
+     * surface does not reference this directly.
+     */
+    toPlan(): QueryPlan;
+    private requireEntity;
+}
+
+/**
+ * Compile-time descriptor for a single field in a codegen schema.
+ *
+ * `ts` is the TypeScript type the field's values will be hydrated as
+ * (e.g. `string`, `number`, `Date`, or a user-provided override type).
+ * `nullable` and `isIdentifier` mirror the runtime `Field`. `category`
+ * carries the original `FieldTypeCategory` so the typed builder can
+ * pick the allowed `where` operator set for this field.
+ */
+interface SchemaFieldDescriptor<TS = unknown, Nullable extends boolean = boolean, Identifier extends boolean = boolean, Category extends FieldTypeCategory = FieldTypeCategory> {
+    readonly ts: TS;
+    readonly nullable: Nullable;
+    readonly isIdentifier: Identifier;
+    readonly category: Category;
+}
+/**
+ * Compile-time descriptor for a single relation in a codegen schema.
+ *
+ * `target` is a qualified entity name `'namespace.entity'`. The typed
+ * builder splits on the dot to resolve the target entity at compile
+ * time.
+ */
+interface SchemaRelationDescriptor<Direction extends 'inbound' | 'outbound' = 'inbound' | 'outbound', Target extends `${string}.${string}` = `${string}.${string}`, FromFields extends readonly string[] = readonly string[], ToFields extends readonly string[] = readonly string[], Cardinality extends 'one' | 'many' = 'one' | 'many'> {
+    readonly direction: Direction;
+    readonly target: Target;
+    readonly fromFields: FromFields;
+    readonly toFields: ToFields;
+    readonly cardinality: Cardinality;
+}
+/**
+ * Compile-time descriptor for one entity: the fields map, the
+ * identifier tuple, and the relations map.
+ */
+interface SchemaEntityDescriptor {
+    readonly fields: {
+        readonly [field: string]: SchemaFieldDescriptor;
+    };
+    readonly identifier: readonly string[];
+    readonly relations: {
+        readonly [relation: string]: SchemaRelationDescriptor;
+    };
+}
+/**
+ * Compile-time descriptor for a namespace.
+ */
+type SchemaNamespaceDescriptor = {
+    readonly [entity: string]: SchemaEntityDescriptor;
+};
+/**
+ * Loose structural constraint for schema types passed to
+ * `biref.query<Schema>()`.
+ *
+ * A concrete interface with literal namespace / entity / field keys
+ * satisfies `object`, so users can hand a codegen-generated
+ * `BirefSchema` directly without opting into a string index
+ * signature. The actual narrowing (field map, relation target, etc.)
+ * is handled by the type-level helpers in `src/query/types/*`, which
+ * match via conditional types and fall back to `never` when the
+ * schema does not line up.
+ */
+type BirefSchemaShape = object;
+
+/**
+ * Split a `'namespace.entity'` string literal on the dot.
+ *
+ * Used to resolve the target entity of a relation at compile time from
+ * its qualified `target` string. The result is a tuple `[Ns, E]`.
+ */
+type Split<T extends string, Sep extends string> = T extends `${infer L}${Sep}${infer R}` ? [L, R] : never;
+/**
+ * Relations map of a given entity - indexable by relation name.
+ */
+type RelationsOfEntity<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns]> = S[Ns][E] extends {
+    readonly relations: infer R;
+} ? R : never;
+/**
+ * The descriptor for a specific relation on a specific entity.
+ */
+type RelationDescriptor<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], R extends keyof RelationsOfEntity<S, Ns, E>> = RelationsOfEntity<S, Ns, E>[R];
+/**
+ * Extract the target namespace literal from a relation descriptor's
+ * `target: 'ns.entity'` field.
+ */
+type TargetNs<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], R extends keyof RelationsOfEntity<S, Ns, E>> = RelationDescriptor<S, Ns, E, R> extends SchemaRelationDescriptor<infer _Dir, infer Target, infer _From, infer _To, infer _Card> ? Split<Target, '.'>[0] extends keyof S ? Split<Target, '.'>[0] : never : never;
+/**
+ * Extract the target entity literal from a relation descriptor.
+ */
+type TargetE<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], R extends keyof RelationsOfEntity<S, Ns, E>> = RelationDescriptor<S, Ns, E, R> extends SchemaRelationDescriptor<infer _Dir, infer Target, infer _From, infer _To, infer _Card> ? TargetNs<S, Ns, E, R> extends keyof S ? Split<Target, '.'>[1] extends keyof S[TargetNs<S, Ns, E, R>] ? Split<Target, '.'>[1] : never : never : never;
+/**
+ * Extract the cardinality (`'one' | 'many'`) from a relation
+ * descriptor, used to decide whether an include field wraps its
+ * result in an array.
+ */
+type CardinalityOf<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], R extends keyof RelationsOfEntity<S, Ns, E>> = RelationDescriptor<S, Ns, E, R> extends SchemaRelationDescriptor<infer _Dir, infer _Target, infer _From, infer _To, infer Card> ? Card : never;
+
+/**
+ * Compile-time helpers that project row shapes out of a codegen schema.
+ *
+ * These types accept an arbitrary `Schema` (which is usually the
+ * `BirefSchema` generated by codegen) plus a namespace / entity / field
+ * path, and produce the shapes the typed builder needs: field maps,
+ * per-field TS types (with nullability applied), categories for
+ * operator selection, default and narrowed row shapes, and the final
+ * hydrated row that merges projected columns with nested include
+ * results.
+ */
+type FieldsOf<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns]> = S[Ns][E] extends {
+    readonly fields: infer F;
+} ? F : never;
+type RelationsOf<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns]> = S[Ns][E] extends {
+    readonly relations: infer R;
+} ? R : never;
+type CategoryOf<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], F extends keyof FieldsOf<S, Ns, E>> = FieldsOf<S, Ns, E>[F] extends SchemaFieldDescriptor<infer _TS, infer _Null, infer _Ident, infer Category> ? Category : never;
+type TypeOf<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], F extends keyof FieldsOf<S, Ns, E>> = FieldsOf<S, Ns, E>[F] extends SchemaFieldDescriptor<infer TS, infer Nullable, infer _Ident, infer _Category> ? Nullable extends true ? TS | null : TS : never;
+/**
+ * Selection shape: a map from selected field name to its TS type,
+ * with nullability applied. Produced by `select(...)`.
+ */
+type Selection = {
+    readonly [field: string]: unknown;
+};
+/**
+ * The default selection when `select()` is not called: every field on
+ * the entity, keyed by its declared name.
+ */
+type DefaultSelect<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns]> = {
+    readonly [F in keyof FieldsOf<S, Ns, E>]: TypeOf<S, Ns, E, F>;
+};
+/**
+ * Narrowed selection from a `select('id', 'email')` call.
+ */
+type PickSelect<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], Keys extends readonly (keyof FieldsOf<S, Ns, E>)[]> = {
+    readonly [K in Keys[number]]: TypeOf<S, Ns, E, K>;
+};
+/**
+ * An accumulated include map on a chain builder. Each key is a
+ * relation name; each value is the resolved nested row type.
+ */
+type IncludeMap = {
+    readonly [relation: string]: unknown;
+};
+/**
+ * The final hydrated row: a merge of the projected selection plus all
+ * nested include results. Each include key maps to either a single
+ * nested row (`cardinality: 'one'`) or an array (`cardinality:
+ * 'many'`).
+ */
+type HydratedRow<Sel extends Selection, Inc extends IncludeMap> = {
+    readonly [K in keyof Sel]: Sel[K];
+} & {
+    readonly [K in keyof Inc]: Inc[K];
+};
+
+/**
+ * Operators valid for each `FieldTypeCategory`.
+ *
+ * Equality + nullability operators are always valid. Comparable
+ * categories (integer, decimal, date, timestamp, time) additionally
+ * support ordered comparisons and `between`. String-like categories
+ * support `like` / `ilike`. Arrays of the same element type support
+ * `in` / `not-in`.
+ *
+ * This type is consumed by the typed builder's `where` signature so
+ * the operator argument narrows by the field's category. Accepts an
+ * unconstrained `Category` so callers can pass the output of
+ * `CategoryOfField<...>` without having to widen it manually.
+ */
+type OpsFor<Category> = Category extends 'string' | 'uuid' | 'enum' ? 'eq' | 'neq' | 'in' | 'not-in' | 'like' | 'ilike' | 'is-null' | 'is-not-null' : Category extends 'integer' | 'decimal' | 'date' | 'timestamp' | 'time' ? 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'between' | 'in' | 'not-in' | 'is-null' | 'is-not-null' : Category extends 'boolean' ? 'eq' | 'neq' | 'is-null' | 'is-not-null' : 'eq' | 'neq' | 'is-null' | 'is-not-null';
+/**
+ * Value shape required for a given operator and a given field TS
+ * type:
+ *
+ *   `in` / `not-in`    → readonly T[]
+ *   `between`          → readonly [T, T]
+ *   `is-null` / `is-not-null` → value is not supplied (the where
+ *                               overload drops the argument)
+ *   everything else    → T
+ */
+type ValueFor<Op extends string, T> = Op extends 'in' | 'not-in' ? readonly T[] : Op extends 'between' ? readonly [T, T] : T;
+/**
+ * Operators that take no value argument.
+ */
+type NullaryOps = 'is-null' | 'is-not-null';
+
+/**
+ * Type-narrowed fluent interface for the typed query builder.
+ *
+ * Mirrors the runtime `ChainBuilder` class method-for-method but
+ * layers compile-time narrowing on top: `select(...)` narrows the row
+ * shape, `include(...)` appends nested include results, `where(...)`
+ * only accepts operators valid for the field's category. The runtime
+ * `ChainBuilder` instance is cast to this interface by
+ * `NamespaceProxy`.
+ *
+ * Generic parameters:
+ *
+ *   S   - the user's schema (usually codegen-emitted `BirefSchema`)
+ *   Ns  - current namespace key
+ *   E   - current entity key
+ *   Sel - accumulated projection (starts as `DefaultSelect`)
+ *   Inc - accumulated include map
+ */
+interface TypedChain<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], Sel extends Selection = DefaultSelect<S, Ns, E>, Inc extends IncludeMap = Record<string, never>> {
+    /**
+     * Narrow the projection to a specific set of field names. Each name
+     * must exist on the entity; unknowns throw at chain time.
+     */
+    select<const K extends readonly (keyof FieldsOf<S, Ns, E>)[]>(...fields: K): TypedChain<S, Ns, E, PickSelect<S, Ns, E, K>, Inc>;
+    /**
+     * Explicit wildcard: every field of the entity, same shape as
+     * calling `findMany()` without `select` at all. Kept as a
+     * discoverable sentinel so `.select('*')` reads clearly in code.
+     */
+    select(wildcard: '*'): TypedChain<S, Ns, E, DefaultSelect<S, Ns, E>, Inc>;
+    /**
+     * Zero-argument shorthand for the wildcard.
+     */
+    select(): TypedChain<S, Ns, E, DefaultSelect<S, Ns, E>, Inc>;
+    where<F extends keyof FieldsOf<S, Ns, E>, Op extends Exclude<OpsFor<CategoryOfField<S, Ns, E, F>>, NullaryOps>>(field: F, operator: Op, value: ValueFor<Op, TypeOf<S, Ns, E, F>>): TypedChain<S, Ns, E, Sel, Inc>;
+    where<F extends keyof FieldsOf<S, Ns, E>>(field: F, operator: Extract<OpsFor<CategoryOfField<S, Ns, E, F>>, NullaryOps>): TypedChain<S, Ns, E, Sel, Inc>;
+    orderBy<F extends keyof FieldsOf<S, Ns, E>>(field: F, direction?: 'asc' | 'desc'): TypedChain<S, Ns, E, Sel, Inc>;
+    limit(count: number): TypedChain<S, Ns, E, Sel, Inc>;
+    offset(count: number): TypedChain<S, Ns, E, Sel, Inc>;
+    /**
+     * Wildcard include: expand every relation discovered on the
+     * current entity, each with the default projection. No callback
+     * is accepted - the sub-builder shape varies per relation, so a
+     * single callback cannot narrow all of them coherently. Use
+     * named includes for per-relation narrowing.
+     *
+     *   .include('*')  // every inbound and outbound relation, flat
+     *
+     * Listed first so TypeScript's overload resolver picks it before
+     * the generic single-arg form for the literal `'*'` argument.
+     */
+    include(relation: '*'): TypedChain<S, Ns, E, Sel, Inc & {
+        readonly [K in keyof RelationsOfEntity<S, Ns, E>]: WrapForCardinality<CardinalityOf<S, Ns, E, K>, HydratedRow<DefaultSelect<S, TargetNs<S, Ns, E, K>, TargetE<S, Ns, E, K>>, Record<string, never>>>;
+    }>;
+    /**
+     * Shorthand include: attach the relation with default projection
+     * (every field of the related entity, no nested includes).
+     *
+     *   .include('orders')  // every column of each order, flat
+     *
+     * For narrowing or nesting, use the two-argument overload below.
+     */
+    include<R extends keyof RelationsOfEntity<S, Ns, E>>(relation: R): TypedChain<S, Ns, E, Sel, Inc & {
+        readonly [K in R]: WrapForCardinality<CardinalityOf<S, Ns, E, R>, HydratedRow<DefaultSelect<S, TargetNs<S, Ns, E, R>, TargetE<S, Ns, E, R>>, Record<string, never>>>;
+    }>;
+    /**
+     * Full-control include: the callback receives a zero-state
+     * sub-builder and returns one with the shape you want hydrated
+     * for this include. Supports nested `.include(...)` calls to any
+     * depth, constrained by TypeScript recursion depth.
+     */
+    include<R extends keyof RelationsOfEntity<S, Ns, E>, SubSel extends Selection, SubInc extends IncludeMap>(relation: R, build: (q: TypedChain<S, TargetNs<S, Ns, E, R>, TargetE<S, Ns, E, R>, DefaultSelect<S, TargetNs<S, Ns, E, R>, TargetE<S, Ns, E, R>>, Record<string, never>>) => TypedChain<S, TargetNs<S, Ns, E, R>, TargetE<S, Ns, E, R>, SubSel, SubInc>): TypedChain<S, Ns, E, Sel, Inc & {
+        readonly [K in R]: WrapForCardinality<CardinalityOf<S, Ns, E, R>, HydratedRow<SubSel, SubInc>>;
+    }>;
+    findMany(): Promise<readonly HydratedRow<Sel, Inc>[]>;
+    findFirst(): Promise<HydratedRow<Sel, Inc> | null>;
+    toPlan(): QueryPlan;
+}
+/**
+ * Wraps a hydrated nested row in an array for `cardinality: 'many'`
+ * relations, or yields `T | null` for `cardinality: 'one'`.
+ */
+type WrapForCardinality<Card, T> = Card extends 'many' ? readonly T[] : T | null;
+/**
+ * Shortcut for extracting the category of a field whose key type is
+ * unioned, used inside the `where` overloads above.
+ */
+type CategoryOfField<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], F extends keyof FieldsOf<S, Ns, E>> = FieldsOf<S, Ns, E>[F] extends {
+    readonly category: infer C;
+} ? C : never;
+/**
+ * Two-layer typed root returned from `biref.query<Schema>(model)`.
+ *
+ * Top level keyed by namespace, inner level keyed by entity. Each
+ * leaf is a zero-state `TypedChain` bound to that namespace/entity.
+ */
+type TypedQueryRoot<S extends BirefSchemaShape> = {
+    readonly [Ns in keyof S]: {
+        readonly [E in keyof S[Ns]]: TypedChain<S, Ns, E>;
+    };
+};
+
+/**
+ * Top-level facade for the SDK.
+ *
+ * Wraps a configured `AdapterRegistry` and exposes scanning and the
+ * typed query builder. The API is ergonomic for the common case of a
+ * single registered adapter and still supports multi-adapter
+ * scenarios via explicit names or URL scheme detection.
+ *
+ * @example
+ * ```ts
+ * const biref = Biref.builder()
+ *   .withAdapter(somePostgresAdapter)
+ *   .build();
+ * const model = await biref.scan();
+ * const rows = await biref.query(model).public.users.findMany();
+ * ```
+ */
+declare class Biref {
+    private readonly registry;
+    constructor(registry: AdapterRegistry);
+    /** Entry point for the fluent builder. */
+    static builder(): BirefBuilder;
+    /**
+     * Introspect a data store. With a single registered adapter, no
+     * arguments are needed. Pass `IntrospectOptions` to customize the
+     * scan, or an adapter name when more than one adapter is registered.
+     */
+    scan(): Promise<DataModel>;
+    scan(options: IntrospectOptions): Promise<DataModel>;
+    scan(adapterName: AdapterName, options?: IntrospectOptions): Promise<DataModel>;
+    /**
+     * Introspect a data store using whichever registered adapter handles
+     * the URL's scheme. The URL is only used to pick the adapter; the
+     * actual connection is still owned by the client the user passed to
+     * the adapter at construction time.
+     */
+    scanByUrl(url: string, options?: IntrospectOptions): Promise<DataModel>;
+    /**
+     * Typed query entry point. Returns a namespace-level Proxy over the
+     * given `DataModel`:
+     *
+     *   biref.query(model).public.users
+     *     .select('id', 'email')
+     *     .where('active', 'eq', true)
+     *     .include('orders', (q) => q.select('id', 'total'))
+     *     .findMany();
+     *
+     * The Proxy layers (`namespace` → `entity`) enumerate what's
+     * actually in the scanned model, so `Object.keys(biref.query(model))`
+     * returns the discovered namespaces. Access to a non-existent
+     * namespace or entity returns `undefined`; the chain methods throw
+     * with a clear error when given unknown fields or relations.
+     *
+     * With a single registered adapter, the adapter is picked
+     * automatically. Pass `adapterName` explicitly to target a specific
+     * adapter when more than one is registered.
+     */
+    query<Schema extends BirefSchemaShape = never>(model: DataModel, adapterName?: AdapterName): [Schema] extends [never] ? UntypedQueryRoot : TypedQueryRoot<Schema>;
+    /** Direct access to the underlying registry. */
+    get adapters(): AdapterRegistry;
+    private executorFor;
+    private resolveScanArgs;
+    private requireSingleAdapter;
+}
+/**
+ * Fallback return type for `biref.query(model)` when called without a
+ * schema generic. Degrades to a two-layer record of dynamic
+ * `ChainBuilder`s so chains still work at runtime - callers just
+ * don't get the narrowed compile-time shapes.
+ */
+type UntypedQueryRoot = Readonly<Record<string, Readonly<Record<string, ChainBuilder>>>>;
+/**
+ * Fluent builder for `Biref`. Collects adapters and produces a wired
+ * `Biref` facade. Call `build()` once and discard the builder.
+ */
+declare class BirefBuilder {
+    private readonly pending;
+    /**
+     * Register an adapter. The adapter's `name` is used as the lookup
+     * key when calling `Biref.scan(name)`. Its optional `urlSchemes` are
+     * used by `Biref.scanByUrl(url)`.
+     */
+    withAdapter(adapter: Adapter): this;
+    /** Convenience for registering multiple adapters in one call. */
+    withAdapters(...adapters: readonly Adapter[]): this;
+    /**
+     * Materialize the builder into a `Biref` facade. Throws if any
+     * adapter has a duplicate name.
+     */
+    build(): Biref;
+}
+
+/**
+ * Public facade for introspection.
+ *
+ * Takes an `AdapterRegistry`, looks up an adapter by name, and runs
+ * its introspector to produce a `DataModel`. Used for low-level
+ * scenarios where `Biref` is too high-level; most consumers should
+ * prefer `Biref` instead.
+ *
+ * @example
+ * ```ts
+ * const registry = new AdapterRegistry();
+ * registry.register(somePostgresAdapter);
+ * const scanner = new Scanner(registry);
+ * const model = await scanner.scan('postgres');
+ * ```
+ */
+declare class Scanner {
+    private readonly registry;
+    constructor(registry: AdapterRegistry);
+    /**
+     * Scan a data store using the named adapter and return a paradigm-
+     * neutral `DataModel`.
+     */
+    scan(adapterName: string, options?: IntrospectOptions): Promise<DataModel>;
+}
+
+/**
+ * Port: turns a stream of `ParsedRecord`s into a representation suitable
+ * for transport, storage, or display.
+ *
+ * `TOutput` is generic so different formatters can produce different
+ * shapes:
+ *  - `Formatter<string>`: JSON, CSV, NDJSON, etc.
+ *  - `Formatter<readonly ParsedRecord[]>`: pass-through (raw)
+ *  - `Formatter<Uint8Array>`: binary formats (e.g. parquet)
+ *
+ * Formatters are stateless and pure: the same input always produces the
+ * same output. They do not depend on any database driver.
+ */
+interface Formatter<TOutput = string> {
+    /** Stable format identifier (e.g. 'json', 'csv', 'raw'). */
+    readonly format: string;
+    /** MIME type, for HTTP responses or file naming. */
+    readonly contentType: string;
+    /** Serialize a stream of records into the formatter's target shape. */
+    serialize(records: readonly ParsedRecord[], options?: SerializeOptions): TOutput;
+}
+interface SerializeOptions {
+    /**
+     * Explicit field order for formatters where column order matters
+     * (CSV, fixed-width). If omitted, the formatter derives order from
+     * the keys of the first record.
+     */
+    readonly fields?: readonly string[];
+}
+
+interface CsvFormatterOptions {
+    /** Delimiter character. Defaults to ','. */
+    readonly delimiter?: string;
+    /** Whether to emit a header row. Defaults to true. */
+    readonly includeHeader?: boolean;
+    /** Line terminator. Defaults to '\n'. */
+    readonly lineTerminator?: string;
+}
+/**
+ * Serializes parsed records to a CSV string.
+ *
+ * Field order:
+ *   1. `options.fields` from the call site, if provided
+ *   2. The keys of the first record, otherwise
+ *   3. Empty string when there are no records
+ *
+ * Escaping follows RFC 4180: cells containing the delimiter, double
+ * quotes, or newlines are wrapped in double quotes, with internal double
+ * quotes doubled.
+ *
+ * Non-string cell values are coerced as follows:
+ *   - `Date`              → ISO 8601 string
+ *   - `bigint`            → decimal string
+ *   - object/array        → JSON-encoded string
+ *   - `null` / `undefined` → empty cell
+ */
+declare class CsvFormatter implements Formatter<string> {
+    private readonly options;
+    readonly format = "csv";
+    readonly contentType = "text/csv";
+    constructor(options?: CsvFormatterOptions);
+    serialize(records: readonly ParsedRecord[], options?: SerializeOptions): string;
+    private resolveFields;
+    private serializeCell;
+    private escape;
+}
+
+interface JsonFormatterOptions {
+    /** Indent the output with 2 spaces if true. Defaults to false. */
+    readonly pretty?: boolean;
+}
+/**
+ * Serializes parsed records to a JSON array string.
+ *
+ * Handles values that `JSON.stringify` does not natively support:
+ *   - `Date`   → ISO 8601 string
+ *   - `bigint` → decimal string
+ */
+declare class JsonFormatter implements Formatter<string> {
+    private readonly options;
+    readonly format = "json";
+    readonly contentType = "application/json";
+    constructor(options?: JsonFormatterOptions);
+    serialize(records: readonly ParsedRecord[]): string;
+    private static replacer;
+}
+
+/**
+ * "Raw" formatter: returns the parsed records as-is, without
+ * serialization. Useful when the consumer wants to keep working with
+ * native JS values (e.g. piping into another JS function) instead of
+ * converting to a string format.
+ *
+ * Unlike the other built-in formatters, this one's `TOutput` is the
+ * record array itself rather than a string. The `Formatter` interface
+ * is generic precisely so this case fits without special-casing.
+ */
+declare class RawFormatter implements Formatter<readonly ParsedRecord[]> {
+    readonly format = "raw";
+    readonly contentType = "application/javascript";
+    serialize(records: readonly ParsedRecord[]): readonly ParsedRecord[];
+}
+
+/**
+ * Shape of the sibling `biref.schema.overrides.ts` file.
+ *
+ * Keyed by qualified entity name `'namespace.entity'`, each entry
+ * maps field names to the TS type the user wants for that column.
+ * Typical use: forcing a concrete shape on a jsonb column whose
+ * structure the scanner cannot see.
+ *
+ * @example
+ * ```ts
+ * export interface Overrides {
+ *   'identity.users': {
+ *     profile: { plan: 'free' | 'pro'; prefs: { darkMode: boolean } };
+ *   };
+ * }
+ * ```
+ */
+interface BirefOverridesShape {
+    readonly [qualifiedEntity: `${string}.${string}`]: {
+        readonly [field: string]: unknown;
+    };
+}
+/**
+ * Deep-merge a user `Overrides` map onto a `RawBirefSchema` produced
+ * by codegen, replacing the `ts` slot on matching fields while
+ * preserving every other descriptor property.
+ *
+ * The override key is the qualified entity name
+ * `'namespace.entity'`, matching the single-level shape of
+ * `BirefOverridesShape`. Entities or fields absent from the overrides
+ * pass through unchanged.
+ */
+type ApplySchemaOverrides<Raw extends BirefSchemaShape, Overrides extends BirefOverridesShape> = {
+    readonly [Ns in keyof Raw]: {
+        readonly [E in keyof Raw[Ns]]: Raw[Ns][E] extends {
+            readonly fields: infer F;
+            readonly identifier: infer I;
+            readonly relations: infer R;
+        } ? {
+            readonly fields: {
+                readonly [FieldName in keyof F]: `${Ns & string}.${E & string}` extends keyof Overrides ? FieldName extends keyof Overrides[`${Ns & string}.${E & string}`] ? ReplaceFieldTs<F[FieldName], Overrides[`${Ns & string}.${E & string}`][FieldName]> : F[FieldName] : F[FieldName];
+            };
+            readonly identifier: I;
+            readonly relations: R;
+        } : Raw[Ns][E];
+    };
+};
+type ReplaceFieldTs<Field, NewTs> = Field extends SchemaFieldDescriptor<infer _OldTs, infer Nullable, infer Identifier, infer Category> ? SchemaFieldDescriptor<NewTs, Nullable, Identifier, Category> : Field;
+
+export { type Adapter, type AdapterFactory, type AdapterName, AdapterRegistry, type ApplySchemaOverrides, Biref, BirefBuilder, type BirefOverridesShape, type BirefSchemaShape, type BuiltQuery, type BuiltQueryMetadata, type CardinalityOf, type CategoryOf, type CategoryOfField, ChainBuilder, type ChainBuilderContext, type Constraint, type ConstraintKind, CsvFormatter, type CsvFormatterOptions, DataModel, DefaultRecordParser, type DefaultSelect, type EngineKind, type Entity, type EntityRef, type Field, type FieldType, type FieldTypeCategory, type FieldsOf, type Filter, type FilterOperator, type Formatter, type HydratedRow, type IncludeMap, type Index, type IndexKind, type IntrospectOptions, type Introspector, JsonFormatter, type JsonFormatterOptions, type KnownAdapterName, type NullaryOps, type OpsFor, type OrderBy, POSTGRES_ADAPTER_NAME, POSTGRES_URL_SCHEMES, type ParsedRecord, type ParsedValue, type PickSelect, type PostgresAdapterName, type PostgresClient, PostgresIntrospector, PostgresQueryEngine, PostgresRecordParser, type QueryEngine, type QueryInclude, type QueryPlan, QueryPlanExecutor, type QuerySpec, RawFormatter, type RawQueryRunner, type RecordParser, type Reference, type ReferentialAction, type RelationsOf, type RelationsOfEntity, type Relationship, type RelationshipDirection, Scanner, type SchemaEntityDescriptor, type SchemaFieldDescriptor, type SchemaFile, type SchemaNamespaceDescriptor, type SchemaRelationDescriptor, type Selection, type SerializeOptions, type Split, type TargetE, type TargetNs, type TypeOf, type TypedChain, type TypedQueryRoot, type UntypedQueryRoot, type ValueFor, type WrapForCardinality, generateSchema, generateSchemaFiles, isPostgresAdapter, overridesScaffold, postgresAdapter, tsTypeFor };