tempest-db-js 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,28 +1,386 @@
+/** One joined table. */
+interface JoinClause {
+    readonly kind: "inner" | "left";
+    readonly table: string;
+    readonly alias: string;
+    /** Equality pairs of qualified columns: `["user.id", "order.userId"]`. */
+    readonly on: readonly (readonly [string, string])[];
+}
+/** A selected column, qualified by source alias. */
+interface JoinSelection {
+    readonly alias: string;
+    readonly column: string;
+}
+/** Collapse a union of object types into their intersection. */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * `where` filter for a join. Keys are `alias.column` refs; each value accepts a
+ * bare value (shorthand for `eq`) or an operator object restricted to the
+ * operators valid for that column's type — exactly like the single-table
+ * {@link WhereInput}, but qualified per source. `like` on a numeric join column,
+ * or `gt` on a string one, is a compile error.
+ */
+type JoinWhereInput<S extends Sources> = Partial<UnionToIntersection<{
+    [A in keyof S]: {
+        [C in keyof NonNullable<S[A]> & string as `${A & string}.${C}`]: NonNullable<S[A]>[C] | OperatorsFor<NonNullable<NonNullable<S[A]>[C]>>;
+    };
+}[keyof S]>>;
+/** Serializable AST for a multi-table SELECT. */
+interface JoinNode {
+    readonly kind: "join_select";
+    readonly base: {
+        readonly table: string;
+        readonly alias: string;
+    };
+    readonly joins: readonly JoinClause[];
+    readonly selections: readonly JoinSelection[];
+    readonly where: CondNode | undefined;
+    readonly orderBy: readonly {
+        readonly ref: string;
+        readonly direction: SortDirection;
+    }[];
+    readonly limit: number | undefined;
+    readonly offset: number | undefined;
+    /** Per-alias property → column maps, for the sources that rename columns. */
+    readonly names?: Readonly<Record<string, NameMap>> | undefined;
+    /**
+     * Project only this source, with **bare** column names instead of the
+     * `alias.column` labels a composite row needs.
+     *
+     * Set by {@link JoinBuilder.pick}. It is what lets a join stand where a plain
+     * `SELECT` of one table would — the recursive branch of a `WITH RECURSIVE`, for
+     * instance, whose columns have to line up with the CTE's.
+     */
+    readonly pick?: string | undefined;
+    /** `WITH` entries this statement carries, in order. */
+    readonly with?: readonly CteNode[] | undefined;
+}
+/** A map of source alias → its (possibly nullable) row type. */
+type Sources = Record<string, object | null>;
+/** Every `alias.column` reference across the current sources. */
+type ColRef<S extends Sources> = {
+    [A in keyof S]: `${A & string}.${keyof NonNullable<S[A]> & string}`;
+}[keyof S];
+/** Valid `alias.column` references for a newly joined model. */
+type RightRef<A extends string, C extends ModelClass> = `${A}.${keyof InferModel<C> & string}`;
+/** The `on` condition: map existing-source refs to new-table refs (equality). */
+type JoinOn<S extends Sources, A extends string, C extends ModelClass> = Partial<Record<ColRef<S>, RightRef<A, C>>>;
+/**
+ * Immutable, chainable multi-table SELECT builder.
+ *
+ * @typeParam S - the accumulated sources (alias → row type; nullable for left joins).
+ */
+declare class JoinBuilder<S extends Sources> {
+    readonly node: JoinNode;
+    /** Source models keyed by alias, for SQL expansion and row coercion. */
+    readonly sources: Readonly<Record<string, ModelClass>>;
+    /** Phantom: the composite result row type. */
+    readonly __row: {
+        [A in keyof S]: S[A];
+    };
+    constructor(node: JoinNode, 
+    /** Source models keyed by alias, for SQL expansion and row coercion. */
+    sources: Readonly<Record<string, ModelClass>>);
+    private add;
+    private clause;
+    /** Inner join another model under `alias`. */
+    innerJoin<C extends ModelClass, A extends string>(model: C, alias: A, on: JoinOn<S, A, C>): JoinBuilder<S & {
+        [K in A]: InferModel<C>;
+    }>;
+    /** Left (outer) join another model under `alias` — its side becomes nullable. */
+    leftJoin<C extends ModelClass, A extends string>(model: C, alias: A, on: JoinOn<S, A, C>): JoinBuilder<S & {
+        [K in A]: InferModel<C> | null;
+    }>;
+    /**
+     * Project **one** source, flat, instead of the composite row.
+     *
+     * The join still happens — it just stops being what comes back. Needed wherever
+     * the result has to match a single table's shape: the recursive branch of a
+     * CTE, an `INSERT ... SELECT`, a `UNION` branch.
+     *
+     * @param alias The source to project.
+     * @returns A builder whose rows are that source's rows.
+     *
+     * @example
+     * ```ts
+     * join(Category, "c").innerJoin(subtree, "s", { "c.parentId": "s.id" }).pick("c");
+     * // SELECT "c"."id" AS "id", "c"."name" AS "name" ... — not "c.id"
+     * ```
+     */
+    pick<A extends keyof S & string>(alias: A): JoinBuilder<S> & {
+        readonly __row: NonNullable<S[A]>;
+    };
+    /** Filter by `alias.column` references (object form) or an `and`/`or`/`not`. */
+    where(input: JoinWhereInput<S> | Condition): JoinBuilder<S>;
+    /** Order by an `alias.column` reference. */
+    orderBy(ref: ColRef<S>, direction?: SortDirection): JoinBuilder<S>;
+    limit(n: number): JoinBuilder<S>;
+    offset(n: number): JoinBuilder<S>;
+}
+/**
+ * Start a multi-table query from a base model under `alias`.
+ *
+ * @param model The base model.
+ * @param alias The alias to key the base table's rows under in the result.
+ * @returns A `JoinBuilder` with the base source registered.
+ */
+declare function join<C extends ModelClass, A extends string>(model: C, alias: A): JoinBuilder<{
+    [K in A]: InferModel<C>;
+}>;
+
+/**
+ * tempest-db-js — set operations (`UNION`, `INTERSECT`, `EXCEPT`).
+ *
+ * Combining two queries in any way other than a join meant dropping to
+ * `session.raw`, losing the row type, the coercion and the composition. A set
+ * operation is also the one place a typed builder can catch a mistake the
+ * database only reports at runtime: branches whose projections do not line up.
+ */
+
+/** Which set operation combines the branches. */
+type SetOperator = "union" | "unionAll" | "intersect" | "except";
+/** Serializable AST for a set operation. */
+interface SetNode {
+    readonly kind: "set_op";
+    readonly op: SetOperator;
+    /** The combined SELECTs, in order. A branch may be a join projecting one source. */
+    readonly branches: readonly (SelectNode | JoinNode)[];
+    /** Ordering applied to the **result**, not to a branch. */
+    readonly orderBy: readonly OrderTerm[];
+    readonly limit: number | undefined;
+    readonly offset: number | undefined;
+}
+/**
+ * A combined query, executable like a `SelectBuilder`.
+ *
+ * `orderBy` / `limit` / `offset` here apply to the **combined** result, which is
+ * what SQL does: a branch that needs its own limit keeps it, and the dialect
+ * parenthesizes that branch.
+ *
+ * @typeParam Row - the row type every branch projects.
+ */
+declare class SetBuilder<Row> {
+    readonly node: SetNode;
+    /** The first branch's model, used to coerce the returned rows. */
+    readonly source: ModelClass;
+    /** Phantom: the result element type, read only by the type system. */
+    readonly __row: Row;
+    constructor(node: SetNode, 
+    /** The first branch's model, used to coerce the returned rows. */
+    source: ModelClass);
+    private with;
+    /**
+     * Order the combined result.
+     *
+     * @param column A column of the projected row.
+     * @param direction Sort direction (default ascending).
+     * @returns A builder carrying the ordering.
+     */
+    orderBy(column: keyof Row & string, direction?: SortDirection): SetBuilder<Row>;
+    /** Limit the combined result. */
+    limit(count: number): SetBuilder<Row>;
+    /** Skip rows of the combined result. */
+    offset(count: number): SetBuilder<Row>;
+}
+/**
+ * What a set operation combines: anything that compiles to a SELECT and yields
+ * `Row` — a `select()`, or a join narrowed to one source with `.pick()`.
+ */
+interface Branch<Row> {
+    /** The branch's AST. */
+    readonly node: SelectNode | JoinNode;
+    /** Phantom: the row type this branch yields. */
+    readonly __row: Row;
+    /** The model rows are coerced through, when the branch has a single source. */
+    readonly source?: ModelClass;
+    /** Source models by alias, for a join branch. */
+    readonly sources?: Readonly<Record<string, ModelClass>>;
+}
+/**
+ * `UNION` — every row of either branch, **duplicates removed**.
+ *
+ * Every branch must project the same shape; that is checked at compile time here,
+ * where the database would only report it at runtime.
+ *
+ * @param branches The queries to combine.
+ * @returns The combined builder.
+ *
+ * @example
+ * ```ts
+ * union(
+ *   select(Post, ["id", "createdAt"]).where({ authorId: me }),
+ *   select(Comment, ["id", "createdAt"]).where({ authorId: me }),
+ * ).orderBy("createdAt", "desc").limit(50);
+ * ```
+ */
+declare function union<Row>(...branches: Branch<Row>[]): SetBuilder<Row>;
+/**
+ * `UNION ALL` — every row of either branch, duplicates **kept**.
+ *
+ * Cheaper than `UNION`, which has to sort or hash to deduplicate. Prefer it
+ * whenever the branches cannot overlap.
+ *
+ * @param branches The queries to combine.
+ * @returns The combined builder.
+ */
+declare function unionAll<Row>(...branches: Branch<Row>[]): SetBuilder<Row>;
+/**
+ * `INTERSECT` — only the rows present in every branch.
+ *
+ * @param branches The queries to combine.
+ * @returns The combined builder.
+ */
+declare function intersect<Row>(...branches: Branch<Row>[]): SetBuilder<Row>;
+/**
+ * `EXCEPT` — the rows of the first branch that are not in the others.
+ *
+ * @param branches The queries to combine.
+ * @returns The combined builder.
+ */
+declare function except<Row>(...branches: Branch<Row>[]): SetBuilder<Row>;
+
+/**
+ * tempest-db-js — common table expressions (`WITH`).
+ *
+ * A CTE names a query so the rest of the statement can select from it, and —
+ * when it is recursive — so it can select from **itself**. That second form is
+ * the only way to walk a tree (a category hierarchy, a reply chain, a dependency
+ * graph) in one statement instead of one query per level.
+ *
+ * The alias is a real model class with the CTE's name as its table, so everything
+ * that already takes a model — `select`, `join`, `where` — takes a CTE with no
+ * special casing anywhere else.
+ */
+
+/** A query that can be the body of a CTE. */
+type CteBody<Row> = SelectBuilder<any, Row, any> | SetBuilder<Row>;
+/** One `WITH` entry, as the AST carries it. */
+interface CteNode {
+    /** The name the rest of the statement refers to. */
+    readonly name: string;
+    /** True for `WITH RECURSIVE`. */
+    readonly recursive: boolean;
+    /** The body query. */
+    readonly body: SelectNode | SetNode;
+    /**
+     * `MATERIALIZED` / `NOT MATERIALIZED`, or `null` to let the planner decide.
+     * PostgreSQL 12+ only.
+     */
+    readonly materialized: boolean | null;
+}
+/** Options for {@link cte} and {@link cteRecursive}. */
+interface CteOptions {
+    /**
+     * Force (or forbid) materialization of the CTE.
+     *
+     * PostgreSQL 12+ inlines a CTE used once, which is usually what you want;
+     * `true` pins the old behavior when the body is expensive and used twice.
+     * Ignored where the dialect has no such syntax.
+     */
+    readonly materialized?: boolean;
+}
+/**
+ * A named query, usable anywhere a model is.
+ *
+ * @typeParam C - the model class whose rows the CTE yields.
+ */
+declare class Cte<C extends ModelClass> {
+    /** The alias model: the same columns, under the CTE's name. */
+    readonly model: C;
+    /** The `WITH` entry this attaches to a statement. */
+    readonly node: CteNode;
+    constructor(
+    /** The alias model: the same columns, under the CTE's name. */
+    model: C, 
+    /** The `WITH` entry this attaches to a statement. */
+    node: CteNode);
+    /**
+     * Select from the CTE, with the `WITH` clause attached.
+     *
+     * @param columns Optional projection.
+     * @returns A builder over the CTE.
+     */
+    select(): SelectBuilder<InferModel<C>, InferModel<C>>;
+    select<K extends keyof InferModel<C> & string>(columns: readonly K[]): SelectBuilder<InferModel<C>, Pick<InferModel<C>, K>>;
+}
+/**
+ * Attach a `WITH` entry to a builder that reads from the CTE.
+ *
+ * Use it when the outer query is not a plain `select(cte.model)` — a join, for
+ * instance, whose builder was assembled elsewhere.
+ *
+ * @param builder The outer query.
+ * @param node The `WITH` entry.
+ * @returns The same builder shape, carrying the clause.
+ */
+declare function attach<B extends {
+    node: object;
+}>(builder: B, node: CteNode): B;
+/**
+ * A named query the rest of the statement can select from.
+ *
+ * @param name The CTE's name.
+ * @param model The model whose row shape the body yields.
+ * @param body The query to name.
+ * @param options Materialization hint.
+ * @returns The CTE, whose `.model` is usable anywhere a model is.
+ *
+ * @example
+ * ```ts
+ * const recent = cte("recent", Order, select(Order).where({ createdAt: { gte: since } }));
+ * const rows = await session.execute(recent.select().where({ status: "open" })).all();
+ * // WITH "recent" AS (SELECT * FROM "orders" WHERE ...) SELECT * FROM "recent" WHERE ...
+ * ```
+ */
+declare function cte<C extends ModelClass>(name: string, model: C, body: CteBody<InferModel<C>>, options?: CteOptions): Cte<C>;
 /**
- * tempest-db-js — Phase 2 feasibility spike: the typed query builder.
+ * A CTE whose body refers to itself — the way to walk a tree in one statement.
  *
- * The builder is PURE AST + phantom types. It does not touch a database — that is
- * Phase 4 (`session.execute`). This file proves that:
- *   - `select(User)` infers the full row type,
- *   - `select(User, ["id", "name"])` infers a `Pick` projection,
- *   - `.where(...)` / `.orderBy(...)` reject keys that are not columns,
- * all at compile time.
+ * The builder receives the CTE's own alias model, so the recursive branch can
+ * join against it.
  *
- * This is a SPIKE, not the final API.
+ * @param name The CTE's name.
+ * @param model The model whose row shape the body yields.
+ * @param build Receives the self-reference and returns the body (a `union`/
+ *   `unionAll` of the seed and the step).
+ * @param options Materialization hint.
+ * @returns The CTE.
+ *
+ * @example
+ * ```ts
+ * const subtree = cteRecursive("subtree", Category, (self) =>
+ *   unionAll(
+ *     select(Category).where({ id: rootId }),
+ *     join(Category, "c").innerJoin(self, "s", { "c.parentId": "s.id" }).select("c"),
+ *   ),
+ * );
+ * ```
  */
+declare function cteRecursive<C extends ModelClass>(name: string, model: C, build: (self: C) => CteBody<InferModel<C>>, options?: CteOptions): Cte<C>;
 
+/** The value type an expression produces, for `compute`'s row type. */
+type ExpressionValue<E> = E extends Expression<infer T> ? T : unknown;
+/** Flatten an intersection into one object literal, for readable inference. */
+type Simplify$1<T> = {
+    [K in keyof T]: T[K];
+} & {};
 /** Sort direction for ORDER BY. */
 type SortDirection = "asc" | "desc";
 /** One ORDER BY term. */
 interface OrderTerm {
-    readonly column: string;
+    /** The column to sort by, or an expression (a full-text rank, for instance). */
+    readonly column: string | ExprNode;
     readonly direction: SortDirection;
 }
 /** One aggregate expression in a grouped SELECT (`COUNT(*) AS "n"`). */
 interface AggregateTerm {
     readonly fn: "count" | "sum" | "avg" | "min" | "max";
-    /** The column to aggregate, or `"*"` (only valid for `count`). */
-    readonly column: string | "*";
+    /**
+     * What is aggregated: a column name, `"*"` (only valid for `count`), or an
+     * expression — which is how a conditional aggregate
+     * (`SUM(CASE WHEN ... END)`) is expressed.
+     */
+    readonly column: string | "*" | ExprNode;
     /** The result alias. */
     readonly alias: string;
 }
@@ -52,6 +410,8 @@ interface LockOptions {
 interface SelectNode {
     readonly kind: "select";
     readonly table: string;
+    /** The name the table is read under (`FROM "users" AS "sub"`), when aliased. */
+    readonly alias?: string | undefined;
     /** Projected columns, or "*" for the whole row. */
     readonly columns: readonly string[] | "*";
     /** Emit `SELECT DISTINCT` when true. */
@@ -64,6 +424,12 @@ interface SelectNode {
     /** `HAVING` condition, keyed by aggregate alias or grouped column. */
     readonly having?: CondNode | undefined;
     readonly orderBy: readonly OrderTerm[];
+    /** Per-column codecs for custom types, by property name, when the model has any. */
+    readonly codecs?: Readonly<Record<string, ColumnCodec>> | undefined;
+    /** `WITH` entries this statement carries, in order. */
+    readonly with?: readonly CteNode[] | undefined;
+    /** Extra projected expressions, by result alias (window functions, CASE, …). */
+    readonly computed?: Readonly<Record<string, ExprNode>> | undefined;
     readonly limit: number | undefined;
     readonly offset: number | undefined;
     /** Row-level locking clause, or `undefined` for none. */
@@ -84,14 +450,70 @@ interface Subquery<T> {
     /** The AST the outer statement embeds. */
     readonly node: SelectNode;
 }
+/**
+ * `EXISTS (subquery)` — true when the subquery returns at least one row.
+ *
+ * The right shape for "is there any…" questions: the database can stop at the
+ * first match, which an `IN` over a materialized list cannot. Correlate it by
+ * referencing an outer column with a qualified `col("users.id")`.
+ *
+ * @param subquery The inner SELECT, as a builder or a `.asSubquery()` result.
+ * @returns A condition, composable with `and`/`or`/`not`.
+ *
+ * @example
+ * ```ts
+ * select(User).where(
+ *   exists(select(Order).where({ userId: col("users.id"), status: "open" })),
+ * );
+ * // WHERE EXISTS (SELECT * FROM "orders" WHERE "userId" = "users"."id" AND ...)
+ * ```
+ */
+declare function exists(subquery: SubqueryLike): Condition;
+/**
+ * `NOT EXISTS (subquery)` — true when the subquery returns no row.
+ *
+ * @param subquery The inner SELECT.
+ * @returns The condition.
+ */
+declare function notExists(subquery: SubqueryLike): Condition;
+/**
+ * A scalar subquery — a `SELECT` of one column used where a value goes.
+ *
+ * Takes the result of `.asSubquery(column)` rather than a bare builder, because
+ * that is what pins the projection to exactly **one** column: a scalar subquery
+ * returning two columns is a runtime error in every database, and this makes it a
+ * compile error instead.
+ *
+ * @param subquery A single-column subquery.
+ * @returns An expression usable in `where`, `orderBy` or an aggregate.
+ *
+ * @example
+ * ```ts
+ * select(User).where(
+ *   scalar(select(Order, ["total"]).where({ userId: col("users.id") })
+ *     .orderBy("createdAt", "desc").limit(1).asSubquery("total")).gt(100),
+ * );
+ * ```
+ */
+declare function scalar<T>(subquery: Subquery<T>): Expression;
+/** What the subquery helpers accept: a builder, or a narrowed subquery. */
+type SubqueryLike = SelectBuilder<any, any, any> | Subquery<unknown>;
 /** Runtime guard: is this `in`/`notIn` operand a subquery rather than a list? */
 declare function isSubquery(value: unknown): value is Subquery<unknown>;
+/**
+ * A comparison operand: a value of the column's type, or another expression.
+ *
+ * Accepting an {@link Expression} is what makes a correlated subquery readable —
+ * `where({ userId: col("users.id") })` compares two columns instead of binding
+ * the string `"users.id"` as a parameter.
+ */
+type Operand<T> = T | Expression;
 /** Operators valid on every column type. */
 interface BaseOperators<T> {
     /** Equal to. */
-    eq?: T;
+    eq?: Operand<T>;
     /** Not equal to. */
-    ne?: T;
+    ne?: Operand<T>;
     /**
      * One of the given values (`IN`) — a list, or a single-column
      * {@link Subquery} built with `.asSubquery(column)`.
@@ -105,13 +527,13 @@ interface BaseOperators<T> {
 /** Extra operators for ordered types (numbers, bigint, dates). */
 interface OrderedOperators<T> extends BaseOperators<T> {
     /** Greater than. */
-    gt?: T;
+    gt?: Operand<T>;
     /** Greater than or equal. */
-    gte?: T;
+    gte?: Operand<T>;
     /** Less than. */
-    lt?: T;
+    lt?: Operand<T>;
     /** Less than or equal. */
-    lte?: T;
+    lte?: Operand<T>;
     /** Inclusive range `BETWEEN lo AND hi`. */
     between?: readonly [T, T];
 }
@@ -132,7 +554,16 @@ interface StringOperators<T> extends BaseOperators<T> {
      * wildcards. The safe operator for a case-insensitive lookup (login, email),
      * and the one that matches a `lower(col)` functional index.
      */
-    ieq?: T;
+    ieq?: Operand<T>;
+    /**
+     * Case-insensitive **substring** match of a literal — the safe operator for a
+     * search box.
+     *
+     * The operand is text the user typed, not a pattern: `%` and `_` in it are
+     * escaped, so searching for `100%` matches `100%` instead of every row. It
+     * compiles to `ILIKE '%…%' ESCAPE '\\'` (`LIKE` where there is no `ILIKE`).
+     */
+    iContains?: string;
 }
 /** Extra operators for array columns (PostgreSQL). */
 interface ArrayOperators<T> extends BaseOperators<T> {
@@ -159,29 +590,29 @@ type OperatorsFor<T> = [T] extends [readonly unknown[]] ? ArrayOperators<T> : [T
  * `string`, is a compile error.
  */
 type WhereInput<Row = Record<string, unknown>> = {
-    [K in keyof Row]?: Row[K] | OperatorsFor<NonNullable<Row[K]>>;
+    [K in keyof Row]?: Row[K] | Expression | OperatorsFor<NonNullable<Row[K]>>;
 };
 /** The full set of operator keys, for the dialect compiler to recognize. */
-declare const OPERATORS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "like", "ilike", "ieq", "in", "notIn", "between", "isNull", "contains", "containedBy", "overlaps"];
+declare const OPERATORS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "like", "ilike", "ieq", "iContains", "in", "notIn", "between", "isNull", "contains", "containedBy", "overlaps"];
 /** One supported operator name. */
 type Operator = (typeof OPERATORS)[number];
 /** An aggregate expression carrying its result type `T` as a phantom. */
 declare class Agg<T> {
     readonly fn: AggregateTerm["fn"];
-    readonly column: string | "*";
+    readonly column: string | "*" | ExprNode;
     readonly __t: T;
-    constructor(fn: AggregateTerm["fn"], column: string | "*");
+    constructor(fn: AggregateTerm["fn"], column: string | "*" | ExprNode);
 }
 /** `COUNT(*)` — the number of rows in the group (never null). */
 declare function count(): Agg<number>;
 /** `SUM(column)` — null when the group has no non-null values. */
-declare function sum(column: string): Agg<number | null>;
+declare function sum(column: string | Expression): Agg<number | null>;
 /** `AVG(column)` — null when the group has no non-null values. */
-declare function avg(column: string): Agg<number | null>;
+declare function avg(column: string | Expression): Agg<number | null>;
 /** `MIN(column)` — numeric columns; null on an empty group. */
-declare function min(column: string): Agg<number | null>;
+declare function min(column: string | Expression): Agg<number | null>;
 /** `MAX(column)` — numeric columns; null on an empty group. */
-declare function max(column: string): Agg<number | null>;
+declare function max(column: string | Expression): Agg<number | null>;
 /** Extract the phantom result type of an aggregate expression. */
 type AggResult<A> = A extends Agg<infer T> ? T : never;
 /** Flatten an intersection into a single object literal. */
@@ -259,7 +690,26 @@ declare class SelectBuilder<Full, Proj = Full, Grouped extends boolean = false>
      * @param direction `"asc"` (default) or `"desc"`.
      * @returns A builder carrying the ordering term.
      */
-    orderBy(column: (keyof Full & string) | (keyof Proj & string), direction?: SortDirection): SelectBuilder<Full, Proj, Grouped>;
+    /**
+     * Project extra expressions alongside the columns, by alias.
+     *
+     * This is where a window function lands: unlike `aggregate()`, it does **not**
+     * group — every row stays, with the computed value attached.
+     *
+     * @param map Alias → expression.
+     * @returns A builder whose row type carries the aliases.
+     *
+     * @example
+     * ```ts
+     * select(Sale).compute({
+     *   rank: over(rowNumber(), { partitionBy: ["region"], orderBy: [["total", "desc"]] }),
+     * });
+     * ```
+     */
+    compute<M extends Record<string, Expression<unknown>>>(map: M): SelectBuilder<Full, Simplify$1<Proj & {
+        [K in keyof M]: ExpressionValue<M[K]>;
+    }>, Grouped>;
+    orderBy(column: (keyof Full & string) | (keyof Proj & string) | Expression, direction?: SortDirection): SelectBuilder<Full, Proj, Grouped>;
     /** Limit the number of rows. */
     limit(n: number): SelectBuilder<Full, Proj, Grouped>;
     /** Skip the first `n` rows. */
@@ -369,7 +819,49 @@ type ExprNode = {
     readonly kind: "fn";
     readonly name: string;
     readonly args: readonly ExprNode[];
+} | {
+    readonly kind: "case";
+    readonly branches: readonly {
+        readonly when: CondNode;
+        readonly result: ExprNode;
+    }[];
+    readonly fallback: ExprNode | null;
+} | {
+    readonly kind: "cast";
+    readonly operand: ExprNode;
+    readonly to: CastType;
+} | {
+    readonly kind: "scalar";
+    readonly select: unknown;
+} | {
+    readonly kind: "star";
+} | {
+    readonly kind: "window";
+    /** The function being windowed (`row_number()`, `sum(total)`, …). */
+    readonly fn: ExprNode;
+    /** `PARTITION BY` columns, by property name. */
+    readonly partitionBy: readonly string[];
+    /** `ORDER BY` inside the window. */
+    readonly orderBy: readonly {
+        readonly column: string;
+        readonly direction: "asc" | "desc";
+    }[];
+    /** An explicit frame clause (`ROWS BETWEEN …`), or `null` for the default. */
+    readonly frame: string | null;
+} | {
+    readonly kind: "rank";
+    readonly columns: readonly string[];
+    readonly term: string;
+    readonly language: string;
 };
+/**
+ * A target type for {@link cast}.
+ *
+ * Kept as a portable vocabulary rather than raw SQL: each dialect maps it to the
+ * name it actually accepts (`integer` is `INTEGER` on PostgreSQL and `SIGNED` on
+ * MySQL), so the same model does not need a different cast per database.
+ */
+type CastType = "integer" | "bigint" | "real" | "numeric" | "text" | "boolean" | "date" | "datetime" | "timestamp" | "uuid" | "json" | "jsonb" | "blob";
 /** Logical condition nodes. */
 type CondNode = CondFields | {
     readonly kind: "and";
@@ -385,6 +877,22 @@ type CondNode = CondFields | {
     readonly left: ExprNode;
     readonly op: Operator;
     readonly right: ExprNode;
+} | {
+    readonly kind: "exists";
+    /** The subquery's SELECT node. */
+    readonly select: unknown;
+    /** True for `NOT EXISTS`. */
+    readonly negate: boolean;
+} | {
+    readonly kind: "fullText";
+    readonly columns: readonly string[];
+    readonly term: string;
+    readonly language: string;
+    /**
+     * The substring condition to compile where there is no text-search engine.
+     * Built once, here, so the dialects do not each reimplement the fallback.
+     */
+    readonly fallback: CondNode;
 };
 declare const CONDITION: unique symbol;
 /** A composed condition produced by `and`/`or`/`not`. */
@@ -415,9 +923,11 @@ declare function isExpression(value: unknown): value is Expression;
  * expressible at all. An operand that is not an `Expression` is bound as a
  * parameter, so `.eq(probe)` stays safe by default.
  */
-declare class Expression {
+declare class Expression<T = unknown> {
     /** The expression AST the dialect renders. */
     readonly node: ExprNode;
+    /** Phantom: the value type this expression produces, read only by the types. */
+    readonly __t?: T;
     constructor(
     /** The expression AST the dialect renders. */
     node: ExprNode);
@@ -497,18 +1007,57 @@ declare function col<Row = Record<string, unknown>>(name: keyof Row & string): E
  */
 declare function val(value: unknown): Expression;
 /**
- * Build a call to a SQL function.
+ * A `CASE WHEN ... THEN ... ELSE ... END` expression.
  *
- * A bare string argument is a **column name** — that is the useful default here
- * (`fn.lower("username")`), and it is why a literal has to be wrapped in
- * {@link val}. The function name is interpolated into the statement, so it is
- * validated as a plain identifier and must never come from user input; the
- * arguments are always rendered through the expression compiler.
+ * The branch conditions are the same `where` language used everywhere else — the
+ * object form or a `Condition` — so no second grammar shows up just for `CASE`.
+ * The branch results are expressions, and a bare value there is **bound**, not
+ * interpolated.
  *
- * @param name The SQL function name.
- * @param args Column names or expressions.
- * @returns An expression for the call.
- * @throws Error When `name` is not a plain SQL identifier.
+ * The classic use is a conditional aggregate: summing only the rows that match,
+ * in one pass over the table instead of one query per bucket.
+ *
+ * @param branches `[condition, result]` pairs, evaluated in order.
+ * @param fallback The `ELSE` result. Omitted, a row matching no branch is `NULL`.
+ * @returns An expression usable anywhere an expression is.
+ * @throws Error When no branch is given — `CASE END` is not valid SQL.
+ *
+ * @example
+ * ```ts
+ * select(Order).aggregate(["customer"], {
+ *   paid: sum(caseWhen([[{ status: "paid" }, col("total")]], val(0))),
+ * });
+ * // SUM(CASE WHEN "status" = $1 THEN "total" ELSE $2 END) AS "paid"
+ * ```
+ */
+declare function caseWhen<Row = Record<string, unknown>>(branches: readonly (readonly [WhereArg<Row>, unknown])[], fallback?: unknown): Expression;
+/**
+ * A `CAST(x AS type)` expression.
+ *
+ * @param operand The expression to convert; a bare string is a column name.
+ * @param to The target type, from the portable {@link CastType} vocabulary.
+ * @returns An expression for the cast.
+ *
+ * @example
+ * ```ts
+ * select(Event).where(cast("externalId", "integer").eq(42));
+ * // WHERE CAST("externalId" AS INTEGER) = $1
+ * ```
+ */
+declare function cast(operand: Expression | string, to: CastType): Expression;
+/**
+ * Build a call to a SQL function.
+ *
+ * A bare string argument is a **column name** — that is the useful default here
+ * (`fn.lower("username")`), and it is why a literal has to be wrapped in
+ * {@link val}. The function name is interpolated into the statement, so it is
+ * validated as a plain identifier and must never come from user input; the
+ * arguments are always rendered through the expression compiler.
+ *
+ * @param name The SQL function name.
+ * @param args Column names or expressions.
+ * @returns An expression for the call.
+ * @throws Error When `name` is not a plain SQL identifier.
  */
 declare function call(name: string, ...args: (Expression | string)[]): Expression;
 /**
@@ -550,6 +1099,90 @@ declare function or<Row = Record<string, unknown>>(...inputs: WhereArg<NoInfer<R
 /** Negate a condition with `NOT`. */
 declare function not<Row = Record<string, unknown>>(input: WhereArg<NoInfer<Row>>): Condition;
 
+/**
+ * tempest-db-js — window functions.
+ *
+ * The questions a `GROUP BY` cannot answer without a second query: the position
+ * of a row inside its group, a running total, the difference to the previous row.
+ * Without them, "top 3 per region" becomes one query per region — the N+1 of
+ * reporting.
+ */
+
+/**
+ * A function that is only legal **inside** a window.
+ *
+ * `row_number()` and `lag()` are errors without an `OVER` clause — SQLite says
+ * "misuse of window function", PostgreSQL "window function ... requires an OVER
+ * clause". Making them their own type means {@link over} is the only place they
+ * can go, so the mistake does not compile instead of failing at runtime.
+ */
+interface WindowFn<T = unknown> {
+    /** The call node this wraps. */
+    readonly call: ExprNode;
+    /** Phantom: the value the function produces. */
+    readonly __t?: T;
+}
+/** How a window is framed around the current row. */
+interface WindowSpec {
+    /** Restart the window for each distinct value of these columns. */
+    readonly partitionBy?: readonly string[];
+    /** Order inside the window — what `rank` and a running total are computed over. */
+    readonly orderBy?: readonly (string | readonly [string, "asc" | "desc"])[];
+    /**
+     * An explicit frame (`ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`).
+     *
+     * Omitted, the database's default applies — and the default is `RANGE`, which
+     * for a running total lumps **every peer** of the current row together. When
+     * rows share an `orderBy` value and that matters, say `ROWS` explicitly.
+     */
+    readonly frame?: string;
+}
+/**
+ * Apply a function `OVER` a window.
+ *
+ * @param fn The window function ({@link rowNumber}, {@link lag}, …) or an
+ *   aggregate (`sum("total")`) used as one.
+ * @param spec Partitioning, ordering and framing.
+ * @returns An expression usable in `compute`, `where` and `orderBy`.
+ *
+ * @example
+ * ```ts
+ * select(Sale).compute({
+ *   rank: over(rowNumber(), { partitionBy: ["region"], orderBy: [["total", "desc"]] }),
+ *   running: over(sum("total"), { partitionBy: ["region"], orderBy: ["date"] }),
+ * });
+ * ```
+ */
+declare function over<T = unknown>(fn: WindowFn<T> | Expression<T> | Agg<T>, spec?: WindowSpec): Expression<T>;
+/** `row_number()` — 1, 2, 3 … within the window, with no ties. */
+declare function rowNumber(): WindowFn<number>;
+/** `rank()` — ties share a position, and the next one skips (1, 1, 3). */
+declare function rank(): WindowFn<number>;
+/** `dense_rank()` — ties share a position, and the next one does not skip (1, 1, 2). */
+declare function denseRank(): WindowFn<number>;
+/** `percent_rank()` — the rank as a fraction between 0 and 1. */
+declare function percentRank(): WindowFn<number>;
+/**
+ * `lag(column, offset)` — the value from a row **behind** the current one.
+ *
+ * @param column The column to read.
+ * @param offset How many rows back (default 1).
+ * @returns The expression.
+ */
+declare function lag<T = unknown>(column: string, offset?: number): WindowFn<T | null>;
+/**
+ * `lead(column, offset)` — the value from a row **ahead** of the current one.
+ *
+ * @param column The column to read.
+ * @param offset How many rows forward (default 1).
+ * @returns The expression.
+ */
+declare function lead<T = unknown>(column: string, offset?: number): WindowFn<T | null>;
+/** `first_value(column)` — the first value in the window. */
+declare function firstValue<T = unknown>(column: string): WindowFn<T | null>;
+/** `last_value(column)` — the last value in the window (mind the default frame). */
+declare function lastValue<T = unknown>(column: string): WindowFn<T | null>;
+
 /**
  * tempest-db-js — Phase 2: typed INSERT / UPDATE / DELETE builders.
  *
@@ -571,11 +1204,11 @@ type Returning = readonly string[] | "*" | null;
  * optional.
  */
 type WriteValues<Row> = {
-    [K in keyof Row]: Row[K] | SqlExpression;
+    [K in keyof Row]: Row[K] | SqlExpression | Expression;
 };
 /** A partial write shape — the `SET` clause of an UPDATE or a `DO UPDATE`. */
 type WritePatch<Row> = {
-    [K in keyof Row]?: Row[K] | SqlExpression;
+    [K in keyof Row]?: Row[K] | SqlExpression | Expression;
 };
 /**
  * Conflict-resolution clause for an INSERT (`ON CONFLICT`). `target` is the
@@ -611,8 +1244,19 @@ interface OnConflictUpdateOptions<Full> {
 /** Serializable AST for an INSERT. */
 interface InsertNode {
     readonly kind: "insert";
+    /** Per-column codecs for custom types, by property name. */
+    readonly codecs?: Readonly<Record<string, ColumnCodec>> | undefined;
     readonly table: string;
     readonly values: readonly Record<string, unknown>[];
+    /**
+     * A `SELECT` feeding the insert, with the target columns it fills.
+     *
+     * Set by {@link InsertBuilder.fromSelect}; mutually exclusive with `values`.
+     */
+    readonly fromSelect?: {
+        readonly columns: readonly string[];
+        readonly select: unknown;
+    } | undefined;
     readonly returning: Returning;
     /** Conflict handling (`ON CONFLICT ...`), or `undefined` for none. */
     readonly onConflict?: OnConflict;
@@ -676,6 +1320,31 @@ declare class InsertBuilder<Full, Ins, Ret = number> {
      * @throws ValidationError When a `set` value cannot be bound.
      */
     onConflictDoUpdate(target: readonly (keyof Full & string)[], set: WritePatch<Full>, options?: OnConflictUpdateOptions<Full>): InsertBuilder<Full, Ins, Ret>;
+    /**
+     * Fill the table from another query — `INSERT INTO t (a, b) SELECT …`.
+     *
+     * The rows never leave the database, which is the point: archiving or copying a
+     * million rows should not become a million round trips through this process.
+     *
+     * @param columns The target columns, in the order the query projects them.
+     * @param query The query producing the rows.
+     * @returns A builder ready to execute.
+     * @throws Error When no target column is given.
+     *
+     * @example
+     * ```ts
+     * insert(ArchivedOrder).fromSelect(
+     *   ["id", "total"],
+     *   select(Order, ["id", "total"]).where({ createdAt: { lt: cutoff } }),
+     * );
+     * ```
+     */
+    fromSelect<K extends keyof Ins & string>(columns: readonly K[], query: {
+        readonly node: unknown;
+        readonly __row: {
+            [P in K]: unknown;
+        };
+    }): InsertBuilder<Full, Ins, Ret>;
     /** Return the full inserted row(s). */
     returning(): InsertBuilder<Full, Ins, Full>;
     /** Return only the given columns of the inserted row(s). */
@@ -686,7 +1355,14 @@ declare function insert<C extends ModelClass>(model: C): InsertBuilder<InferMode
 /** Serializable AST for an UPDATE. */
 interface UpdateNode {
     readonly kind: "update";
+    /** Per-column codecs for custom types, by property name. */
+    readonly codecs?: Readonly<Record<string, ColumnCodec>> | undefined;
     readonly table: string;
+    /** Extra source tables (`UPDATE ... FROM other`), by alias. */
+    readonly from?: readonly {
+        readonly table: string;
+        readonly alias: string;
+    }[];
     readonly set: Record<string, unknown>;
     readonly where: CondNode | undefined;
     /** True once a where-clause or explicit opt-in makes the write safe. */
@@ -732,6 +1408,21 @@ declare class UpdateBuilder<Full, Guarded extends boolean, Ret = number> {
      * ```
      */
     set(values: WritePatch<Full>): UpdateBuilder<Full, Guarded, Ret>;
+    /**
+     * Read from another table while updating — `UPDATE t SET … FROM other WHERE …`.
+     *
+     * The join condition goes in `where`, where SQL wants it:
+     * `.where({ customerId: col("c.id") })`.
+     *
+     * PostgreSQL and SQLite (3.33+) only. MySQL spells this as a multi-table
+     * `UPDATE a JOIN b`, which is out of this project's active scope, so it throws
+     * there rather than emitting something the server rejects.
+     *
+     * @param model The extra source.
+     * @param alias The name to reference it by.
+     * @returns A builder carrying the extra source.
+     */
+    from<C extends ModelClass>(model: C, alias: string): UpdateBuilder<Full, Guarded, Ret>;
     /** Restrict the rows to update. Marks the builder safe to execute. */
     where(input: WhereInput<Full> | Condition): UpdateBuilder<Full, true, Ret>;
     /** Explicit opt-in to update EVERY row. Use deliberately. */
@@ -746,7 +1437,14 @@ declare function update<C extends ModelClass>(model: C): UpdateBuilder<InferMode
 /** Serializable AST for a DELETE. */
 interface DeleteNode {
     readonly kind: "delete";
+    /** Per-column codecs for custom types, by property name. */
+    readonly codecs?: Readonly<Record<string, ColumnCodec>> | undefined;
     readonly table: string;
+    /** Extra source tables (`DELETE ... USING other`), by alias. */
+    readonly using?: readonly {
+        readonly table: string;
+        readonly alias: string;
+    }[];
     readonly where: CondNode | undefined;
     readonly guarded: boolean;
     readonly returning: Returning;
@@ -770,6 +1468,18 @@ declare class DeleteBuilder<Full, Guarded extends boolean, Ret = number> {
     /** The source model, used to coerce returned rows on execution. */
     source: ModelClass);
     private with;
+    /**
+     * Delete by matching another table — `DELETE FROM t USING other WHERE …`.
+     *
+     * PostgreSQL only. SQLite and MySQL have no `USING` here; there the portable
+     * form is `where({ id: { in: select(Other, ["id"]).where(...).asSubquery("id") } })`,
+     * and this throws rather than pretending.
+     *
+     * @param model The extra source.
+     * @param alias The name to reference it by.
+     * @returns A builder carrying the extra source.
+     */
+    using<C extends ModelClass>(model: C, alias: string): DeleteBuilder<Full, Guarded, Ret>;
     /** Restrict the rows to delete. Marks the builder safe to execute. */
     where(input: WhereInput<Full> | Condition): DeleteBuilder<Full, true, Ret>;
     /** Explicit opt-in to delete EVERY row. Use deliberately. */
@@ -855,6 +1565,10 @@ declare class ValidationError extends Error {
     readonly issues: readonly string[];
     constructor(table: string, issues: readonly string[]);
 }
+/** Encode one native row value to its JSON-safe form, by column kind. */
+declare function encodeValue(column: Column<unknown>, value: unknown): unknown;
+/** Decode one dict value to its native row form, by column kind. */
+declare function decodeValue(column: Column<unknown>, value: unknown): unknown;
 /**
  * Convert a row to a plain dict of native values, restricted to known columns.
  * Strips any non-column properties; keeps `Date`/`bigint`/`Uint8Array` as-is.
@@ -893,400 +1607,166 @@ declare function fromDict<C extends ModelClass>(model: C, data: Record<string, u
 declare function parse<C extends ModelClass>(model: C, json: string): InferModel<C>;
 
 /**
- * tempest-db-js — Phase 5: typed joins with composite result types.
+ * tempest-db-js — capture the query plans of everything a block runs.
  *
- * `join(User, "user").innerJoin(Order, "order", { "user.id": "order.userId" })`
- * yields rows shaped `{ user: UserRow; order: OrderRow }`. A `leftJoin` makes the
- * joined side nullable (`OrderRow | null`), matching SQL outer-join semantics.
- *
- * Columns are aliased in SQL (`"user"."id" AS "user.id"`) so a flat driver row is
- * split back into one nested object per source, each coerced by its model.
+ * A development tool for "why is this endpoint slow?", where the honest answer
+ * usually needs the database's own opinion rather than a wall-clock number.
+ * Wrapping the code beats copying SQL out of a log by hand, because the
+ * parameters that go into the plan are the ones the code actually used.
  */
 
-/** One joined table. */
-interface JoinClause {
-    readonly kind: "inner" | "left";
-    readonly table: string;
-    readonly alias: string;
-    /** Equality pairs of qualified columns: `["user.id", "order.userId"]`. */
-    readonly on: readonly (readonly [string, string])[];
-}
-/** A selected column, qualified by source alias. */
-interface JoinSelection {
-    readonly alias: string;
-    readonly column: string;
+/** One statement's plan. */
+interface QueryPlan {
+    /** The statement that was explained. */
+    readonly sql: string;
+    /** The parameters it ran with. */
+    readonly params: readonly unknown[];
+    /** The database's plan, in its own shape (JSON on PostgreSQL, rows on SQLite). */
+    readonly plan: unknown;
+    /** A one-line, human-readable digest of the plan. */
+    summary(): string;
 }
-/** Collapse a union of object types into their intersection. */
-type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-/**
- * `where` filter for a join. Keys are `alias.column` refs; each value accepts a
- * bare value (shorthand for `eq`) or an operator object restricted to the
- * operators valid for that column's type — exactly like the single-table
- * {@link WhereInput}, but qualified per source. `like` on a numeric join column,
- * or `gt` on a string one, is a compile error.
- */
-type JoinWhereInput<S extends Sources> = Partial<UnionToIntersection<{
-    [A in keyof S]: {
-        [C in keyof NonNullable<S[A]> & string as `${A & string}.${C}`]: NonNullable<S[A]>[C] | OperatorsFor<NonNullable<NonNullable<S[A]>[C]>>;
-    };
-}[keyof S]>>;
-/** Serializable AST for a multi-table SELECT. */
-interface JoinNode {
-    readonly kind: "join_select";
-    readonly base: {
-        readonly table: string;
-        readonly alias: string;
-    };
-    readonly joins: readonly JoinClause[];
-    readonly selections: readonly JoinSelection[];
-    readonly where: CondNode | undefined;
-    readonly orderBy: readonly {
-        readonly ref: string;
-        readonly direction: SortDirection;
-    }[];
-    readonly limit: number | undefined;
-    readonly offset: number | undefined;
-    /** Per-alias property → column maps, for the sources that rename columns. */
-    readonly names?: Readonly<Record<string, NameMap>> | undefined;
+/** Everything a block ran, with a plan each. */
+interface ExplainReport {
+    /** One entry per statement, in execution order. */
+    readonly plans: readonly QueryPlan[];
+    /** A multi-line digest of every plan, for a test failure message or a log. */
+    summary(): string;
 }
-/** A map of source alias → its (possibly nullable) row type. */
-type Sources = Record<string, object | null>;
-/** Every `alias.column` reference across the current sources. */
-type ColRef<S extends Sources> = {
-    [A in keyof S]: `${A & string}.${keyof NonNullable<S[A]> & string}`;
-}[keyof S];
-/** Valid `alias.column` references for a newly joined model. */
-type RightRef<A extends string, C extends ModelClass> = `${A}.${keyof InferModel<C> & string}`;
-/** The `on` condition: map existing-source refs to new-table refs (equality). */
-type JoinOn<S extends Sources, A extends string, C extends ModelClass> = Partial<Record<ColRef<S>, RightRef<A, C>>>;
-/**
- * Immutable, chainable multi-table SELECT builder.
- *
- * @typeParam S - the accumulated sources (alias → row type; nullable for left joins).
- */
-declare class JoinBuilder<S extends Sources> {
-    readonly node: JoinNode;
-    /** Source models keyed by alias, for SQL expansion and row coercion. */
-    readonly sources: Readonly<Record<string, ModelClass>>;
-    /** Phantom: the composite result row type. */
-    readonly __row: {
-        [A in keyof S]: S[A];
-    };
-    constructor(node: JoinNode, 
-    /** Source models keyed by alias, for SQL expansion and row coercion. */
-    sources: Readonly<Record<string, ModelClass>>);
-    private add;
-    private clause;
-    /** Inner join another model under `alias`. */
-    innerJoin<C extends ModelClass, A extends string>(model: C, alias: A, on: JoinOn<S, A, C>): JoinBuilder<S & {
-        [K in A]: InferModel<C>;
-    }>;
-    /** Left (outer) join another model under `alias` — its side becomes nullable. */
-    leftJoin<C extends ModelClass, A extends string>(model: C, alias: A, on: JoinOn<S, A, C>): JoinBuilder<S & {
-        [K in A]: InferModel<C> | null;
-    }>;
-    /** Filter by `alias.column` references (object form) or an `and`/`or`/`not`. */
-    where(input: JoinWhereInput<S> | Condition): JoinBuilder<S>;
-    /** Order by an `alias.column` reference. */
-    orderBy(ref: ColRef<S>, direction?: SortDirection): JoinBuilder<S>;
-    limit(n: number): JoinBuilder<S>;
-    offset(n: number): JoinBuilder<S>;
+/** Options for {@link explainQueries}. */
+interface ExplainOptions {
+    /**
+     * Run `EXPLAIN ANALYZE`, which **executes** the statement to measure it.
+     *
+     * Refused for anything that is not a `SELECT`: analyzing an `UPDATE` would
+     * apply it a second time.
+     */
+    readonly analyze?: boolean;
+    /** Explain only the statements matching this predicate. */
+    readonly filter?: (sql: string) => boolean;
 }
+/** True for a statement that only reads. */
+declare function isReadOnlyStatement(sql: string): boolean;
 /**
- * Start a multi-table query from a base model under `alias`.
+ * Build the digest of a PostgreSQL JSON plan or a SQLite plan row set.
  *
- * @param model The base model.
- * @param alias The alias to key the base table's rows under in the result.
- * @returns A `JoinBuilder` with the base source registered.
+ * @param plan The raw plan.
+ * @returns One line describing it.
  */
-declare function join<C extends ModelClass, A extends string>(model: C, alias: A): JoinBuilder<{
-    [K in A]: InferModel<C>;
-}>;
+declare function summarizePlan(plan: unknown): string;
 
 /**
- * tempest-db-js — Phase 4a: dialect SQL compilation.
+ * tempest-db-js — an opt-in unit of work with an identity map.
  *
- * Turns the dialect-neutral AST (`SelectNode`, `InsertNode`, `UpdateNode`,
- * `DeleteNode` from Phases 1-2) into `{ sql, params }`. This is the ONLY place
- * SQL is produced — always parameterized (`?` for SQLite, `$1` for PostgreSQL),
- * never string interpolation, so it is injection-safe by construction.
+ * The default stays what it has always been: a row is a plain object, and a write
+ * happens when you ask for it. This adds the other model, for the code that wants
+ * it — load a row once, mutate it, and let one `flush()` work out the statements.
  *
- * It does NOT touch a database — execution is Phase 4b (`session.execute`).
+ * Two things it buys, both of which the plain path cannot:
+ *
+ * - **Identity.** Loading the same row twice returns the **same object**, so two
+ *   references cannot drift apart in memory while both believe they are the row.
+ * - **Batching.** Ten mutations become the statements the changes actually
+ *   require, in one transaction, instead of ten round trips.
  */
 
-/** A compiled, parameterized statement ready to hand to a driver. */
-interface CompiledQuery {
-    readonly sql: string;
-    readonly params: readonly unknown[];
-}
-/** Any compilable AST node. */
-type QueryNode = SelectNode | InsertNode | UpdateNode | DeleteNode | JoinNode;
+/** Phantom brand distinguishing a tracked row from a plain one. */
+declare const TRACKED: unique symbol;
 /**
- * Collects bound parameters and renders placeholders in dialect style. Exposed
- * because dialect subclasses receive it when overriding clause rendering.
+ * A row the unit of work is watching.
+ *
+ * The brand is what makes "tracked" visible in the type: a function taking a
+ * `Tracked<Row>` cannot be handed a plain object that nothing will ever flush.
  */
-declare class Params {
-    private readonly placeholder;
-    readonly values: unknown[];
-    constructor(placeholder: (index: number) => string);
-    bind(value: unknown): string;
+type Tracked<Row> = Row & {
+    readonly [TRACKED]?: true;
+};
+/** What a flush did. */
+interface FlushResult {
+    /** Rows inserted. */
+    readonly inserted: number;
+    /** Rows updated. */
+    readonly updated: number;
+    /** Rows deleted. */
+    readonly deleted: number;
 }
 /**
- * Base SQL compiler shared by every dialect. Subclasses customize only what
- * actually differs between databases (placeholder syntax, `ILIKE` support).
+ * An identity map plus a change log, flushed as one transaction.
+ *
+ * Scope it explicitly — one per request, one per job — and flush it before it
+ * goes away. Nothing here is global.
  */
-declare abstract class BaseDialect {
-    abstract readonly name: Dialect;
-    /**
-     * INSERT SQL templates keyed by structure (dialect|table|columns|rowCount|
-     * returning). Shared across dialect instances — the key namespaces by dialect
-     * name, and the placeholder text is dialect-specific but structure-determined.
-     */
-    private static readonly insertTemplates;
-    /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
-    private static readonly quotedIds;
-    /** Render the n-th (1-based) placeholder. */
-    protected abstract placeholder(index: number): string;
-    /** Render a case-insensitive LIKE for the active dialect. */
-    protected abstract ilike(column: string, param: string): string;
+declare class UnitOfWork {
+    private readonly session;
+    private readonly entries;
+    constructor(session: AsyncSession);
+    /** How many rows are being tracked. */
+    get size(): number;
     /**
-     * Validate a subquery operand before it is rendered, for dialects that restrict
-     * what an `IN (SELECT ...)` may contain. The default accepts everything.
+     * Load a row by primary key, or return the one already loaded.
      *
-     * @param _node The subquery's AST.
-     * @throws Error When the dialect cannot execute this subquery.
+     * The second call for the same key does **not** hit the database and returns
+     * the **same object** as the first.
+     *
+     * @param model The model class.
+     * @param key The primary key — a value, or an object for a composite key.
+     * @returns The tracked row, or `null` when there is none.
      */
-    protected checkSubquery(_node: SelectNode): void;
+    get<C extends ModelClass>(model: C, key: unknown): Promise<Tracked<InferModel<C>> | null>;
     /**
-     * The SQL operator for an array containment/overlap test.
+     * Track an existing row that was loaded elsewhere.
      *
-     * Only PostgreSQL has native arrays; the other dialects throw rather than
-     * emitting an operator that means something else there.
-     *
-     * @param op The array operator name.
-     * @returns The SQL operator text.
-     * @throws Error On a dialect without native array support.
+     * @param model The model class.
+     * @param row The row, as loaded.
+     * @returns The tracked object — the same one, if this row is already known.
      */
-    protected arrayOperator(op: "contains" | "containedBy" | "overlaps"): string;
+    track<C extends ModelClass>(model: C, row: InferModel<C>): Tracked<InferModel<C>>;
     /**
-     * Quote an identifier (column/table) for the active dialect.
+     * Schedule an insert.
      *
-     * Memoized: identifiers form a small, stable set (column/table names), but this
-     * runs for every identifier on every compile. Caching the quoted form removes a
-     * regex-replace + string allocation from the hot path. The standard double-quote
-     * form is identical across both dialects, so one shared cache is correct.
+     * @param model The model class.
+     * @param data The row to insert; it must carry the primary key, since the
+     *   identity map is keyed by it and a database-generated id is not known yet.
+     * @returns The tracked row.
+     * @throws Error When the key is incomplete.
      */
-    protected quoteId(name: string): string;
-    /** Compile any node to `{ sql, params }`. */
-    compile(node: QueryNode): CompiledQuery;
+    add<C extends ModelClass>(model: C, data: InferInsert<C>): Tracked<InferModel<C>>;
     /**
-     * Render a qualified `alias.column` ref as `"alias"."column"`, translating the
-     * property name to the real column name for that alias's model.
+     * Schedule a delete.
      *
-     * @param ref The `alias.property` reference (a bare name is left unqualified).
-     * @param names The node's per-alias name maps, if any source renames columns.
-     * @returns The quoted, qualified identifier.
+     * A row added and then removed before the flush simply disappears — no
+     * statement is emitted for it.
+     *
+     * @param model The model class.
+     * @param row The row to delete.
      */
-    private qualify;
+    remove<C extends ModelClass>(model: C, row: InferModel<C>): void;
     /**
-     * Quote a column identifier, translating the model property name to the real
-     * database column name first.
+     * Write every pending change, in one transaction.
      *
-     * `names` is `undefined` for a model that renames nothing — the overwhelmingly
-     * common case — so this stays a single lookup plus the memoized quote.
+     * Order is inserts, then updates, then deletes — the order that keeps a
+     * foreign key satisfied when a new parent and its children are flushed
+     * together. It is **not** a topological sort: a graph that needs one should be
+     * flushed in stages.
      *
-     * @param prop The model property name as written in the builder.
-     * @param names The node's property → column map, if any.
-     * @returns The quoted database identifier.
+     * A statement that fails takes the whole flush with it, since it all runs in
+     * one transaction. The tracked state is left untouched in that case, so the
+     * caller can fix and flush again.
+     *
+     * @returns How many rows were inserted, updated and deleted.
      */
-    protected columnId(prop: string, names: NameMap | undefined): string;
+    flush(): Promise<FlushResult>;
+    /** Forget everything tracked, without writing. */
+    clear(): void;
     /**
-     * Render a {@link SqlExpression} inline, binding the parameters it carries.
+     * The identity-map key for a row or a primary key.
      *
-     * This is what keeps `set({ attempts: sql.raw("attempts + 1") })` an expression
-     * instead of a bound object: the fragment goes into the statement text, and
-     * only a `sql.expr` template's interpolations become parameters.
-     *
-     * @param expr The branded expression.
-     * @param params The parameter collector for the statement being compiled.
-     * @returns The SQL text of the expression.
-     */
-    protected renderExpression(expr: SqlExpression, params: Params): string;
-    /** Render one write value: a SQL expression inline, anything else as a parameter. */
-    protected renderValue(value: unknown, params: Params): string;
-    /**
-     * Render a row-level locking clause (`FOR UPDATE ...`).
-     *
-     * Standard on PostgreSQL and MySQL 8.0+; SQLite overrides it to throw.
-     *
-     * @param lock The locking clause from the node.
-     * @returns The SQL text, leading space included.
-     */
-    protected renderLock(lock: LockClause): string;
-    /**
-     * Compile a SELECT.
-     *
-     * Two alias rules differ between clauses and are handled here: PostgreSQL does
-     * NOT accept a `SELECT` alias in `HAVING`, so an aggregate key is re-emitted as
-     * its expression (`COUNT(*) > $1`), a form every dialect accepts; `ORDER BY`,
-     * by contrast, accepts the output alias everywhere, so it is emitted as
-     * written.
-     *
-     * @param node The select AST.
-     * @param params The parameter collector.
-     * @returns The SQL text.
-     */
-    private compileSelect;
-    /**
-     * Compile an INSERT.
-     *
-     * Takes the cached fast path only when the statement text is a pure function of
-     * its structure. A SQL expression among the values, or a conflict predicate,
-     * makes the text depend on the values themselves — those compile uncached, in
-     * SQL order, so placeholder positions stay correct.
-     */
-    private compileInsert;
-    /**
-     * Compile an INSERT without the template cache, rendering clauses in statement
-     * order so every parameter is bound at the position it appears.
-     *
-     * @param node The insert node.
-     * @param columns The column keys shared by every row.
-     * @param params The parameter collector.
-     * @returns The SQL text.
-     */
-    private compileInsertDirect;
-    /**
-     * The INSERT SQL template for a given structure, cached across calls.
-     *
-     * The text depends only on (dialect, table, columns, row count, returning,
-     * conflict shape) — never on the bound values — and placeholder positions are
-     * deterministic from the counts (a fresh statement always starts binding at 1).
-     * So a per-row insert loop compiles the string once and reuses it every row.
-     */
-    private insertTemplate;
-    /**
-     * Render the conflict-handling clause. Standard SQL (SQLite/PostgreSQL) uses
-     * `ON CONFLICT (...) [WHERE predicate] DO NOTHING | DO UPDATE SET ... [WHERE ...]`;
-     * MySQL overrides this.
-     *
-     * The index predicate is rendered before the `DO UPDATE` assignments because
-     * that is where it sits in the statement, so its parameters bind first.
-     *
-     * @param onConflict The conflict clause from the node.
-     * @param conflictCols The columns to overwrite on `DO UPDATE` (empty for nothing).
-     * @param nextValue Yields the SQL for the next `DO UPDATE` assignment value.
-     * @param names The node's property → column map, if any.
-     * @param params The parameter collector, for the predicates.
-     * @returns The SQL text, leading space included.
-     */
-    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined, params: Params): string;
-    private compileUpdate;
-    private compileDelete;
-    private compileJoin;
-    protected compileReturning(returning: readonly string[] | "*" | null, names?: NameMap | undefined): string;
-    /**
-     * Compile a condition tree (fields / and / or / not) to SQL. `idFor` renders a
-     * key to a quoted identifier — `quoteId` for single-table, `qualify` for joins —
-     * so select/update/delete/join all share this one compiler.
-     */
-    private compileCondition;
-    /**
-     * Render one side of a comparison.
-     *
-     * A column reference goes through `idFor`, so an explicit `.name()` mapping and
-     * join qualification apply here exactly as they do in the object form of
-     * `where` — `col()` is not a way around them. Only a `value` node binds.
-     *
-     * @param node The expression AST.
-     * @param params The parameter collector.
-     * @param idFor The identifier resolver for the enclosing statement.
-     * @returns The SQL text of the expression.
-     */
-    private renderExpr;
-    /**
-     * Compile a comparison whose right-hand side is another expression rather than
-     * a bound value (`total > paid`, `lower(a) = lower(b)`).
-     *
-     * The list and null operators are excluded: `IN`, `BETWEEN` and `IS NULL` take
-     * a value operand, and accepting an expression there would silently compile to
-     * something else.
-     *
-     * @param left The rendered left-hand side.
-     * @param op The operator name.
-     * @param right The rendered right-hand side.
-     * @returns The SQL text of the predicate.
-     * @throws Error When the operator needs a value operand.
-     */
-    private compileExprOperator;
-    private compileOperator;
-    /**
-     * Compile `IN` / `NOT IN`, whose operand is either a value list or a
-     * single-column subquery.
-     *
-     * The subquery is rendered at the position it appears in the outer statement
-     * and shares the same parameter collector, so its own placeholders land in the
-     * right order — and it keeps its own `names` map, since the inner model may use
-     * a different naming convention than the outer one.
-     *
-     * @param id The quoted column identifier being tested.
-     * @param operand A list of values, or a {@link Subquery}.
-     * @param params The parameter collector for the statement being compiled.
-     * @param negate True for `NOT IN`.
-     * @returns The SQL text of the predicate.
-     */
-    private compileIn;
-}
-/** SQLite dialect: `?` placeholders; `ILIKE` falls back to `LIKE` (ASCII-insensitive). */
-declare class SqliteDialect extends BaseDialect {
-    readonly name: "sqlite";
-    protected placeholder(): string;
-    protected ilike(column: string, param: string): string;
-    /**
-     * SQLite has no row-level locking, so a lock request is an error rather than a
-     * silently unlocked `SELECT` — a lock that does not exist only shows up as
-     * duplicated work under production concurrency.
-     */
-    protected renderLock(): string;
-}
-/** PostgreSQL dialect: `$1` placeholders; native `ILIKE`; native array operators. */
-declare class PostgresDialect extends BaseDialect {
-    readonly name: "postgresql";
-    protected placeholder(index: number): string;
-    protected ilike(column: string, param: string): string;
-    protected arrayOperator(op: "contains" | "containedBy" | "overlaps"): string;
-}
-/**
- * MySQL dialect: `?` placeholders, backtick identifiers, `ON DUPLICATE KEY
- * UPDATE` for upsert, and case-insensitive `LIKE` (default collation). MySQL has
- * no `RETURNING`, so requesting it throws.
- */
-declare class MysqlDialect extends BaseDialect {
-    readonly name: "mysql";
-    protected placeholder(): string;
-    protected ilike(column: string, param: string): string;
-    protected quoteId(name: string): string;
-    /**
-     * MySQL rejects `LIMIT` inside an `IN` subquery with
-     * `ER_NOT_SUPPORTED_YET: This version of MySQL doesn't yet support
-     * 'LIMIT & IN/ALL/ANY/SOME subquery'`. Failing at compile time names the fix
-     * instead of surfacing that error from the driver at runtime.
-     */
-    protected checkSubquery(node: SelectNode): void;
-    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined): string;
-    /**
-     * MySQL has no `RETURNING`, so it cannot be compiled into a statement.
-     *
-     * `session.execute()` still honors `.returning()` on a **single-row INSERT** by
-     * running the insert and reading the row back by key on the same connection —
-     * that is execution, not compilation, so it never reaches here. Compiling a
-     * node with `returning` directly is an error, rather than SQL that silently
-     * returns nothing.
+     * @param model The model class.
+     * @param key The row, or the key.
+     * @returns A stable string key.
      */
-    protected compileReturning(returning: readonly string[] | "*" | null): string;
+    private identity;
 }
-/** Get a dialect instance by name. */
-declare function getDialect(name: Dialect): BaseDialect;
 
 /** The outcome of running one statement. */
 interface DriverResult {
@@ -1346,17 +1826,51 @@ declare class NodeSqliteDriver implements SyncDriver {
     iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
     close(): void;
 }
+/**
+ * SQLite driver backed by the `better-sqlite3` peer dependency.
+ *
+ * Selected with `{ driver: "better-sqlite3" }` or the URL suffix
+ * `sqlite+better-sqlite3://…`; the built-in `node:sqlite` stays the default, so
+ * nothing has to be installed to use SQLite. Pick this one when the service
+ * already runs on better-sqlite3, or needs what it exposes and `node:sqlite`
+ * does not — `pragma()`, loadable extensions, its own WAL helpers.
+ *
+ * Row shape matches {@link NodeSqliteDriver}: plain objects, BLOBs as `Buffer`
+ * (a `Uint8Array` subclass), which is what `coerceRow` already expects.
+ */
+declare class BetterSqliteDriver implements SyncDriver {
+    private readonly db;
+    /** Prepared-statement cache keyed by SQL text — see {@link NodeSqliteDriver}. */
+    private readonly statements;
+    constructor(database: any);
+    /**
+     * Open a `better-sqlite3` database at the given path (or `":memory:"`).
+     *
+     * @param path The database file, or `":memory:"`.
+     * @param options Passed straight to `new Database()` (`readonly`, `timeout`, …).
+     * @returns A driver over the open handle.
+     * @throws If `better-sqlite3` is not installed — it is an optional peer
+     *   dependency, so the error names the package to install.
+     */
+    static open(path: string, options?: Readonly<Record<string, unknown>>): BetterSqliteDriver;
+    /** Return the cached prepared statement for `sql`, preparing it on first use. */
+    private prepare;
+    execute(sql: string, params: readonly unknown[]): DriverResult;
+    iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
+    close(): void;
+}
 type AnySelect = SelectBuilder<any, any, any>;
 type AnyInsert = InsertBuilder<any, any, any>;
 type GuardedUpdate = UpdateBuilder<any, true, any>;
 type GuardedDelete = DeleteBuilder<any, true, any>;
 type AnyJoin = JoinBuilder<any>;
+type AnySet = SetBuilder<any>;
 /**
  * A builder that is safe to execute. UPDATE/DELETE are accepted only once
  * guarded (after `.where()` or `.unguarded()`) — an unguarded full-table write
  * is a compile error at the execution boundary.
  */
-type Executable = AnySelect | AnyInsert | GuardedUpdate | GuardedDelete | AnyJoin;
+type Executable = AnySelect | AnyInsert | GuardedUpdate | GuardedDelete | AnyJoin | AnySet;
 /** The element type a builder yields on execution. */
 type RowOf<B> = B extends {
     readonly __row: infer R;
@@ -1393,6 +1907,40 @@ type QueryLogger = (event: {
     readonly sql: string;
     readonly params: readonly unknown[];
 }) => void;
+/**
+ * What a statement did, reported **after** it ran.
+ *
+ * `onQuery` fires before execution, so it cannot time anything; this is the other
+ * half. It fires on the failure path too, with `error` set — a slow statement that
+ * then fails is exactly the one worth seeing.
+ */
+interface QueryEndEvent {
+    /** The statement text. */
+    readonly sql: string;
+    /** The bound parameters, in placeholder order. */
+    readonly params: readonly unknown[];
+    /** Wall-clock time the driver took, in milliseconds. */
+    readonly durationMs: number;
+    /** Rows returned (a SELECT or `RETURNING`), or rows affected by a write. */
+    readonly rowCount: number;
+    /** The driver's error, when the statement failed. */
+    readonly error?: unknown;
+}
+/**
+ * Called after every statement, with its duration.
+ *
+ * Errors thrown by the hook are ignored, like {@link QueryLogger}.
+ */
+type QueryEndLogger = (event: QueryEndEvent) => void;
+/** The per-statement hooks a session carries. */
+interface QueryHooks {
+    /** Called before a statement runs. */
+    readonly onQuery?: QueryLogger | undefined;
+    /** Called after a statement runs, with its duration. */
+    readonly onQueryEnd?: QueryEndLogger | undefined;
+    /** When set, `onQueryEnd` fires only for statements at least this slow (ms). */
+    readonly slowQueryMs?: number | undefined;
+}
 /** Synchronous result view over already-fetched rows. */
 declare class SyncResult<Row> {
     private readonly rows;
@@ -1418,16 +1966,41 @@ declare class AsyncResult<Row> {
     scalars(): Promise<unknown[]>;
     rowsAffected(): Promise<number>;
 }
+/**
+ * A transaction isolation level, in the SQL standard's names.
+ *
+ * The database's default is what you get without asking: `read committed` on
+ * PostgreSQL and MySQL's `repeatable read`. SQLite has only `serializable`.
+ */
+type IsolationLevel = "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+/** Characteristics for one transaction block. */
+interface TransactionOptions {
+    /**
+     * The isolation level for this block.
+     *
+     * Raising it is how the queue and outbox patterns get their invariants: under
+     * `read committed` two workers can both pass the same check before either
+     * commits. Asking for a level a dialect does not implement throws.
+     */
+    readonly isolation?: IsolationLevel;
+    /**
+     * Open the block read-only, so the database itself rejects a write in it.
+     * PostgreSQL and MySQL only; SQLite throws.
+     */
+    readonly readOnly?: boolean;
+}
 /** A synchronous unit of work (SQLite). */
 declare class SyncSession {
     private readonly driver;
     private readonly dialect;
-    /** Optional per-statement logger (query tracing). */
-    private readonly logger?;
+    /** Optional per-statement hooks (query tracing and timing). */
+    private readonly hooks?;
     constructor(driver: SyncDriver, dialect: BaseDialect, 
-    /** Optional per-statement logger (query tracing). */
-    logger?: QueryLogger | undefined);
-    /** Log, run, and error-wrap one raw statement. */
+    /** Optional per-statement hooks (query tracing and timing). */
+    hooks?: QueryHooks | undefined);
+    /** Open `transaction()` blocks on this session; only the outermost commits. */
+    private depth;
+    /** Log, run, time, and error-wrap one raw statement. */
     private exec;
     /**
      * Run a raw, parameterized SQL statement (synchronous) — the runtime counterpart of the
@@ -1466,7 +2039,29 @@ declare class SyncSession {
     /** Compile, run, and coerce a builder into a result. */
     execute<B extends Executable>(builder: B): SyncResult<RowOf<B>>;
     /** Run `fn` inside a transaction: commit on success, rollback on throw. */
-    transaction<T>(fn: (tx: SyncSession) => T): T;
+    /**
+     * How many `transaction()` blocks are open on this session.
+     *
+     * The counter is what makes a service that orchestrates two repositories work:
+     * both hold the same session, so an inner block **joins** the outer one instead
+     * of emitting a second `BEGIN`, and only the outermost exit commits.
+     */
+    get transactionDepth(): number;
+    /** Whether a `transaction()` block is currently open on this session. */
+    get inTransaction(): boolean;
+    /**
+     * Run `fn` inside a transaction, committing on a clean exit and rolling back on
+     * a throw.
+     *
+     * **Re-entrant:** a nested call joins the block already open on this session —
+     * one `BEGIN`, one `COMMIT`, and an inner failure rolls the whole thing back.
+     * To recover from an inner failure without discarding the outer work, use
+     * {@link beginNested}, which is a real savepoint.
+     *
+     * @param fn The body; receives the session to work through.
+     * @returns Whatever `fn` returned.
+     */
+    transaction<T>(fn: (tx: SyncSession) => T, options?: TransactionOptions): T;
     /** Run `fn` inside a SAVEPOINT (nested transaction). */
     beginNested<T>(fn: (sp: SyncSession) => T): T;
     /**
@@ -1482,12 +2077,14 @@ declare class SyncSession {
 declare class AsyncSession {
     private readonly driver;
     private readonly dialect;
-    /** Optional per-statement logger (query tracing). */
-    private readonly logger?;
+    /** Optional per-statement hooks (query tracing and timing). */
+    private readonly hooks?;
     constructor(driver: AsyncDriver, dialect: BaseDialect, 
-    /** Optional per-statement logger (query tracing). */
-    logger?: QueryLogger | undefined);
-    /** Log, run, and error-wrap one raw statement. */
+    /** Optional per-statement hooks (query tracing and timing). */
+    hooks?: QueryHooks | undefined);
+    /** Open `transaction()` blocks on this session; only the outermost commits. */
+    private depth;
+    /** Log, run, time, and error-wrap one raw statement. */
     private exec;
     /**
      * Run a raw, parameterized SQL statement — the runtime counterpart of the
@@ -1543,7 +2140,61 @@ declare class AsyncSession {
     private insertAndReadBack;
     /** Lazily iterate result rows. Uses driver streaming when available. */
     stream<B extends Executable>(builder: B): AsyncIterableIterator<RowOf<B>>;
-    transaction<T>(fn: (tx: AsyncSession) => Promise<T>): Promise<T>;
+    /**
+     * How many `transaction()` blocks are open on this session.
+     *
+     * The counter is what makes a service that orchestrates two repositories work:
+     * both hold the same session, so an inner block **joins** the outer one instead
+     * of emitting a second `BEGIN`, and only the outermost exit commits.
+     */
+    get transactionDepth(): number;
+    /** Whether a `transaction()` block is currently open on this session. */
+    get inTransaction(): boolean;
+    /**
+     * Run `fn` inside a transaction, committing on a clean exit and rolling back on
+     * a throw.
+     *
+     * **Re-entrant:** a nested call joins the block already open on this session,
+     * so a service orchestrating several repositories bound to the same session
+     * gets one `BEGIN` and one `COMMIT`, not two of each. An inner failure rolls the
+     * whole block back; use {@link beginNested} for a savepoint that can be
+     * recovered from.
+     *
+     * Pooled drivers (PostgreSQL) pin one connection for the block: `BEGIN`/`COMMIT`
+     * and every statement between them have to run on the same connection, or
+     * postgres.js rejects the raw transaction. Single-connection drivers (SQLite)
+     * skip the reservation.
+     *
+     * @param fn The body; receives the session to work through (the pinned one, on a
+     *   pooled driver).
+     * @returns Whatever `fn` returned.
+     */
+    transaction<T>(fn: (tx: AsyncSession) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Run `fn` inside a `SAVEPOINT` (a nested transaction that can be rolled back on
+     * its own).
+     *
+     * This is the difference from a nested {@link transaction}: a savepoint that
+     * fails discards **only** its own work, so the enclosing block can catch the
+     * error and carry on. A nested `transaction()` joins the outer block, and its
+     * failure takes the whole block down.
+     *
+     * Must run inside an open transaction — PostgreSQL rejects a savepoint outside a
+     * transaction block.
+     *
+     * @param fn The body; receives the same session.
+     * @returns Whatever `fn` returned.
+     */
+    beginNested<T>(fn: (sp: AsyncSession) => Promise<T>): Promise<T>;
+    /**
+     * Open an opt-in {@link UnitOfWork} over this session.
+     *
+     * The default stays a plain object written when you ask; this is the other
+     * model, for code that prefers to mutate and flush once.
+     *
+     * @returns A new, empty unit of work.
+     */
+    unitOfWork(): UnitOfWork;
     close(): Promise<void>;
     /** `await using session = ...` closes the driver when the scope exits. */
     [Symbol.asyncDispose](): Promise<void>;
@@ -1556,178 +2207,1854 @@ interface PoolOptions {
     readonly idleTimeoutMs?: number;
     /** Give up acquiring a connection after this long (ms). */
     readonly connectTimeoutMs?: number;
+    /**
+     * Validate a connection before pinning it for a transaction.
+     *
+     * A pooled connection can die without the pool noticing — a failover, a
+     * pgbouncer restart, a firewall dropping an idle socket. The damage lands on
+     * whoever picks it up next, and it lands worst on a transaction: `BEGIN`
+     * succeeds, a statement mid-block fails, and the block dies halfway.
+     *
+     * With this on, `transaction()` runs `SELECT 1` on the reserved connection
+     * first and reserves another one if that fails. It costs a round trip per
+     * transaction, which is why it is opt-in.
+     *
+     * PostgreSQL only — MySQL throws, and SQLite has no pool.
+     */
+    readonly prePing?: boolean;
+    /**
+     * Close and reopen a connection older than this (ms), regardless of activity.
+     *
+     * The blunt companion to {@link prePing}: it bounds how long a connection can
+     * have been alive, which is what keeps a slow leak (a server-side timeout, a
+     * load balancer's idle cap) from becoming a mystery error hours later.
+     *
+     * PostgreSQL only — MySQL throws, and SQLite has no pool.
+     */
+    readonly recycleMs?: number;
+}
+/**
+ * A server-side notice (a PostgreSQL `NOTICE`). The shape is the driver's own —
+ * passed through untouched rather than normalized, since what is useful in it
+ * differs per database.
+ */
+type NoticeLogger = (notice: Record<string, unknown>) => void;
+/**
+ * SQLite journal modes accepted by `PRAGMA journal_mode`.
+ *
+ * `"wal"` is the one worth reaching for on a server: readers stop blocking the
+ * writer. It needs a real file — an in-memory database refuses it and stays on
+ * `"memory"`, which this layer reports as an error rather than a silent no-op.
+ */
+type SqliteJournalMode = "delete" | "truncate" | "persist" | "memory" | "wal" | "off";
+/** Durability levels accepted by `PRAGMA synchronous`. */
+type SqliteSynchronous = "off" | "normal" | "full" | "extra";
+/**
+ * Per-connection SQLite settings, applied right after the handle opens.
+ *
+ * Pragmas are **per connection**, not per database file, so they belong to the
+ * engine rather than to a migration. Only `foreignKeys` has a default that
+ * changes behavior; every other field is emitted only when given, so an existing
+ * database keeps whatever it was configured with.
+ */
+interface SqliteOptions {
+    /**
+     * Enforce `FOREIGN KEY` constraints. **Defaults to `true`.**
+     *
+     * SQLite ships with enforcement `OFF`, per connection, so a declared foreign
+     * key is decorative until someone turns it on: an orphan `INSERT` is accepted
+     * and `ON DELETE CASCADE` never fires. tempest-db-js turns it on, which makes
+     * the same model behave the same on all three databases.
+     *
+     * Set it to `false` only for the case it exists for — loading a dump whose
+     * insert order does not respect the graph.
+     */
+    readonly foreignKeys?: boolean;
+    /** `PRAGMA journal_mode`. Omitted: the database keeps its current mode. */
+    readonly journalMode?: SqliteJournalMode;
+    /** `PRAGMA busy_timeout`, in milliseconds. How long a writer waits on a lock. */
+    readonly busyTimeoutMs?: number;
+    /** `PRAGMA synchronous`. Durability vs write throughput. */
+    readonly synchronous?: SqliteSynchronous;
+}
+/** Options shared by both engine flavors. */
+interface EngineOptions {
+    /**
+     * Override the driver detected from the URL.
+     *
+     * SQLite ships two: `"node:sqlite"` (the built-in, default — nothing to
+     * install) and `"better-sqlite3"` (the optional peer dependency). PostgreSQL
+     * runs on `"postgres"` (postgres.js) and MySQL on `"mysql2"`; naming those is
+     * a no-op today, kept so the option means the same thing everywhere.
+     *
+     * A name this dialect does not have throws — passing `{ driver: "sqlite3" }`
+     * is a decision that would otherwise be silently ignored.
+     *
+     * The `+suffix` in the URL (`sqlite+better-sqlite3:///app.db`) selects the same
+     * way, with one difference: a suffix naming a driver from another ecosystem
+     * (`sqlite+aiosqlite`, `postgresql+asyncpg`) is ignored rather than rejected,
+     * so a URL copied from a Python service still connects.
+     */
+    readonly driver?: string;
+    /** Connection-pool tuning (PostgreSQL only). */
+    readonly pool?: PoolOptions;
+    /**
+     * Called for every statement a session runs — SQL + bound params. Use for
+     * query logging/tracing. Thrown errors are swallowed so it never breaks a query.
+     */
+    readonly onQuery?: QueryLogger;
+    /**
+     * Called for every server-side notice (`CREATE TABLE IF NOT EXISTS` on an
+     * existing table, `DROP ... IF EXISTS` on a missing one, and so on).
+     *
+     * **Without this, notices are silenced.** postgres.js defaults to printing them
+     * with `console.log`, which drops a nine-line object into the host service's
+     * stdout in the middle of its structured log — on every boot, since a migration
+     * runner is usually the first thing to run. Writing to the host's stdout is the
+     * application's decision, not a library's, so the default is to say nothing and
+     * let you route them:
+     *
+     * ```ts
+     * createEngine(url, { onNotice: (n) => logger.debug({ pg: n }, "postgres notice") });
+     * ```
+     *
+     * Thrown errors are swallowed, like `onQuery`.
+     */
+    readonly onNotice?: NoticeLogger;
+    /**
+     * Options passed straight to the underlying driver, applied **last** so they
+     * win over everything this layer derives (`pool`, `onNotice`).
+     *
+     * The escape hatch for what the typed surface does not model and is not going
+     * to — postgres.js `connection`/`types`/`transform`/`ssl`, mysql2's own
+     * settings, `node:sqlite`'s `readOnly` — so a gap need not become a feature
+     * request.
+     */
+    readonly driverOptions?: Readonly<Record<string, unknown>>;
+    /**
+     * Per-connection SQLite pragmas (`foreign_keys`, `journal_mode`, …), applied
+     * as soon as the handle opens. Passing it to a PostgreSQL or MySQL engine
+     * throws — the settings have no meaning there, and silently ignoring them is
+     * how a durability choice gets lost.
+     */
+    readonly sqlite?: SqliteOptions;
+    /**
+     * Called **after** every statement, with how long the driver took.
+     *
+     * `onQuery` fires before execution, so it cannot time anything; this is the
+     * other half, and it fires on the failure path too (with `error` set). Use it
+     * for latency metrics, tracing spans, and finding the query dragging p99.
+     *
+     * Errors thrown by the hook are swallowed, like `onQuery`.
+     */
+    readonly onQueryEnd?: QueryEndLogger;
+    /**
+     * Only report statements at least this slow (milliseconds) to `onQueryEnd`.
+     *
+     * The cheapest slow-query log there is: set a threshold, log what crosses it.
+     * Without it every statement is reported.
+     */
+    readonly slowQueryMs?: number;
+}
+/** A synchronous engine (SQLite only). */
+declare class SyncEngine {
+    private readonly driver;
+    private readonly hooks?;
+    readonly dialect: Dialect;
+    constructor(driver: SyncDriver, hooks?: QueryHooks | undefined);
+    session(): SyncSession;
+    transaction<T>(fn: (tx: SyncSession) => T, options?: TransactionOptions): T;
+    close(): void;
+    /** `using engine = createSyncEngine(...)` closes the pool when the scope exits. */
+    [Symbol.dispose](): void;
+}
+/** An asynchronous engine. */
+declare class AsyncEngine {
+    private readonly driver;
+    readonly dialect: Dialect;
+    private readonly hooks?;
+    constructor(driver: AsyncDriver, dialect: Dialect, hooks?: QueryHooks | undefined);
+    session(): AsyncSession;
+    transaction<T>(fn: (tx: AsyncSession) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Run `fn` and return the query plan of every statement it ran.
+     *
+     * The block gets its own session over a **recording** driver, so the plans are
+     * built from the statements and the parameters the code really used — not from
+     * SQL copied out of a log by hand. A development tool: it runs the block once
+     * and then one `EXPLAIN` per statement, so keep it out of the hot path.
+     *
+     * @param fn The code to observe; receives the recording session.
+     * @param options `analyze: true` to measure (refused for writes), `filter` to
+     *   explain only some statements.
+     * @returns The report, one plan per statement in execution order.
+     * @throws Error When `analyze` is requested for a statement that writes, or on
+     *   a dialect that has no `EXPLAIN ANALYZE`.
+     *
+     * @example
+     * ```ts
+     * const report = await engine.explain(async (session) => {
+     *   await new BaseRepository(Order, session).paginate({ page: 3 });
+     * });
+     * console.log(report.summary());
+     * ```
+     */
+    explain(fn: (session: AsyncSession) => Promise<unknown>, options?: ExplainOptions): Promise<ExplainReport>;
+    close(): Promise<void>;
+    /** `await using engine = createEngine(...)` closes the pool when the scope exits. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Adapt a sync **or** async driver to the async interface.
+ *
+ * `await` normalizes both: a sync driver returns a plain value, an async one a
+ * promise, and awaiting either yields the result. That is what lets the migration
+ * CLI take one code path instead of branching on a difference it cannot detect
+ * from the object's shape.
+ *
+ * @param driver Either driver flavor.
+ * @returns An async driver delegating to it.
+ */
+declare function toAsyncDriver(driver: SyncDriver | AsyncDriver): AsyncDriver;
+/**
+ * Create a **synchronous** engine from a database URL. SQLite only — PostgreSQL
+ * has no sane synchronous driver in Node, so a Postgres URL throws, pointing at
+ * the async `createEngine`.
+ *
+ * @param url A SQLite URL, e.g. `"sqlite:///app.db"` or `"sqlite://:memory:"`.
+ * @param options Engine options.
+ * @returns A `SyncEngine`.
+ */
+declare function createSyncEngine(url: string, options?: EngineOptions): SyncEngine;
+/**
+ * Create an **asynchronous** engine from a database URL (the default). Works for
+ * both SQLite (sync driver wrapped as async) and PostgreSQL (postgres.js,
+ * lazy-loaded).
+ *
+ * @param url A database URL, e.g. `"postgresql://app@localhost/app"` or
+ *   `"sqlite:///app.db"`.
+ * @param options Engine options.
+ * @returns An `AsyncEngine`.
+ */
+declare function createEngine(url: string, options?: EngineOptions): AsyncEngine;
+
+/**
+ * tempest-db-js — Phase 4a: dialect SQL compilation.
+ *
+ * Turns the dialect-neutral AST (`SelectNode`, `InsertNode`, `UpdateNode`,
+ * `DeleteNode` from Phases 1-2) into `{ sql, params }`. This is the ONLY place
+ * SQL is produced — always parameterized (`?` for SQLite, `$1` for PostgreSQL),
+ * never string interpolation, so it is injection-safe by construction.
+ *
+ * It does NOT touch a database — execution is Phase 4b (`session.execute`).
+ */
+
+/** A compiled, parameterized statement ready to hand to a driver. */
+interface CompiledQuery {
+    readonly sql: string;
+    readonly params: readonly unknown[];
+}
+/** Any compilable AST node. */
+type QueryNode = SelectNode | InsertNode | UpdateNode | DeleteNode | JoinNode | SetNode;
+/**
+ * Collects bound parameters and renders placeholders in dialect style. Exposed
+ * because dialect subclasses receive it when overriding clause rendering.
+ */
+declare class Params {
+    private readonly placeholder;
+    readonly values: unknown[];
+    constructor(placeholder: (index: number) => string);
+    bind(value: unknown): string;
+}
+/**
+ * Base SQL compiler shared by every dialect. Subclasses customize only what
+ * actually differs between databases (placeholder syntax, `ILIKE` support).
+ */
+declare abstract class BaseDialect {
+    abstract readonly name: Dialect;
+    /**
+     * INSERT SQL templates keyed by structure (dialect|table|columns|rowCount|
+     * returning). Shared across dialect instances — the key namespaces by dialect
+     * name, and the placeholder text is dialect-specific but structure-determined.
+     */
+    private static readonly insertTemplates;
+    /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
+    private static readonly quotedIds;
+    /** Render the n-th (1-based) placeholder. */
+    protected abstract placeholder(index: number): string;
+    /** Render a case-insensitive LIKE for the active dialect. */
+    protected abstract ilike(column: string, param: string): string;
+    /**
+     * Render a case-insensitive LIKE whose pattern carries escaped wildcards.
+     *
+     * The `ESCAPE` clause is not decoration: PostgreSQL treats `\` as the escape
+     * character by default, **SQLite has none at all** until one is declared, so
+     * without this the escaping done on our side would be meaningless there.
+     *
+     * @param column The rendered column.
+     * @param param The bound pattern.
+     * @returns The rendered comparison.
+     */
+    protected ilikeEscaped(column: string, param: string): string;
+    /**
+     * Validate a subquery operand before it is rendered, for dialects that restrict
+     * what an `IN (SELECT ...)` may contain. The default accepts everything.
+     *
+     * @param _node The subquery's AST.
+     * @throws Error When the dialect cannot execute this subquery.
+     */
+    protected checkSubquery(_node: SelectNode): void;
+    /**
+     * The SQL operator for an array containment/overlap test.
+     *
+     * Only PostgreSQL has native arrays; the other dialects throw rather than
+     * emitting an operator that means something else there.
+     *
+     * @param op The array operator name.
+     * @returns The SQL operator text.
+     * @throws Error On a dialect without native array support.
+     */
+    protected arrayOperator(op: "contains" | "containedBy" | "overlaps"): string;
+    /**
+     * Quote an identifier (column/table) for the active dialect.
+     *
+     * Memoized: identifiers form a small, stable set (column/table names), but this
+     * runs for every identifier on every compile. Caching the quoted form removes a
+     * regex-replace + string allocation from the hot path. The standard double-quote
+     * form is identical across both dialects, so one shared cache is correct.
+     */
+    protected quoteId(name: string): string;
+    /** Compile any node to `{ sql, params }`. */
+    compile(node: QueryNode): CompiledQuery;
+    /**
+     * Render a condition as schema SQL, with values inlined.
+     *
+     * Same compiler as a `WHERE`, different parameter strategy — so a `CHECK` and
+     * the query language cannot drift apart in what they mean.
+     *
+     * @param node The condition.
+     * @param params A {@link LiteralParams}.
+     * @returns The rendered predicate.
+     */
+    renderConditionLiteral(node: CondNode, params: Params): string;
+    /**
+     * Render the `WITH` clause of a statement.
+     *
+     * `RECURSIVE` is a property of the **clause**, not of an entry: one recursive
+     * entry makes the whole `WITH` recursive, which is what the SQL standard says
+     * and what PostgreSQL and SQLite both implement.
+     *
+     * @param entries The `WITH` entries, if any.
+     * @param params The parameter collector.
+     * @returns The clause with a trailing space, or an empty string.
+     */
+    protected compileWith(entries: readonly CteNode[] | undefined, params: Params): string;
+    /**
+     * The `EXPLAIN` prefix for this dialect.
+     *
+     * @param analyze Whether to measure by actually running the statement.
+     * @returns The prefix to put in front of the statement.
+     * @throws Error When the dialect cannot do what was asked.
+     */
+    explainPrefix(analyze: boolean): string;
+    /**
+     * The SQL keyword for a set operation.
+     *
+     * @param op The operator.
+     * @returns The keyword.
+     * @throws Error On a dialect that does not implement it.
+     */
+    protected setOperator(op: SetOperator): string;
+    /**
+     * Compile a set operation.
+     *
+     * A branch carrying its own `ORDER BY`/`LIMIT` is parenthesized: without the
+     * parentheses those clauses bind to the **combined** result, which is a
+     * different query and a classic source of silently wrong output.
+     *
+     * @param node The set-operation node.
+     * @param params The parameter collector.
+     * @returns The rendered statement.
+     */
+    protected compileSetOp(node: SetNode, params: Params): string;
+    /**
+     * Render a qualified `alias.column` ref as `"alias"."column"`, translating the
+     * property name to the real column name for that alias's model.
+     *
+     * @param ref The `alias.property` reference (a bare name is left unqualified).
+     * @param names The node's per-alias name maps, if any source renames columns.
+     * @returns The quoted, qualified identifier.
+     */
+    private qualify;
+    /**
+     * Quote a column identifier, translating the model property name to the real
+     * database column name first.
+     *
+     * `names` is `undefined` for a model that renames nothing — the overwhelmingly
+     * common case — so this stays a single lookup plus the memoized quote.
+     *
+     * @param prop The model property name as written in the builder.
+     * @param names The node's property → column map, if any.
+     * @returns The quoted database identifier.
+     */
+    protected columnId(prop: string, names: NameMap | undefined): string;
+    /**
+     * Render a {@link SqlExpression} inline, binding the parameters it carries.
+     *
+     * This is what keeps `set({ attempts: sql.raw("attempts + 1") })` an expression
+     * instead of a bound object: the fragment goes into the statement text, and
+     * only a `sql.expr` template's interpolations become parameters.
+     *
+     * @param expr The branded expression.
+     * @param params The parameter collector for the statement being compiled.
+     * @returns The SQL text of the expression.
+     */
+    protected renderExpression(expr: SqlExpression, params: Params): string;
+    /** Render one write value: a SQL expression inline, anything else as a parameter. */
+    protected renderValue(value: unknown, params: Params): string;
+    /**
+     * The statements that open a transaction with the requested characteristics.
+     *
+     * Returned as a list because the dialects disagree on shape: PostgreSQL takes
+     * everything on the `BEGIN` itself, MySQL needs a separate `SET TRANSACTION`
+     * before it, and SQLite has no syntax at all.
+     *
+     * @param options The requested isolation level and read-only flag.
+     * @returns The statements to run, in order.
+     * @throws Error When the dialect cannot honor what was asked.
+     */
+    beginStatements(options?: TransactionOptions): string[];
+    /**
+     * Render a row-level locking clause (`FOR UPDATE ...`).
+     *
+     * Standard on PostgreSQL and MySQL 8.0+; SQLite overrides it to throw.
+     *
+     * @param lock The locking clause from the node.
+     * @returns The SQL text, leading space included.
+     */
+    protected renderLock(lock: LockClause): string;
+    /**
+     * Compile a SELECT.
+     *
+     * Two alias rules differ between clauses and are handled here: PostgreSQL does
+     * NOT accept a `SELECT` alias in `HAVING`, so an aggregate key is re-emitted as
+     * its expression (`COUNT(*) > $1`), a form every dialect accepts; `ORDER BY`,
+     * by contrast, accepts the output alias everywhere, so it is emitted as
+     * written.
+     *
+     * @param node The select AST.
+     * @param params The parameter collector.
+     * @returns The SQL text.
+     */
+    private compileSelect;
+    /**
+     * Compile an INSERT.
+     *
+     * Takes the cached fast path only when the statement text is a pure function of
+     * its structure. A SQL expression among the values, or a conflict predicate,
+     * makes the text depend on the values themselves — those compile uncached, in
+     * SQL order, so placeholder positions stay correct.
+     */
+    private compileInsert;
+    /**
+     * Compile an INSERT without the template cache, rendering clauses in statement
+     * order so every parameter is bound at the position it appears.
+     *
+     * @param node The insert node.
+     * @param columns The column keys shared by every row.
+     * @param params The parameter collector.
+     * @returns The SQL text.
+     */
+    private compileInsertDirect;
+    /**
+     * The INSERT SQL template for a given structure, cached across calls.
+     *
+     * The text depends only on (dialect, table, columns, row count, returning,
+     * conflict shape) — never on the bound values — and placeholder positions are
+     * deterministic from the counts (a fresh statement always starts binding at 1).
+     * So a per-row insert loop compiles the string once and reuses it every row.
+     */
+    private insertTemplate;
+    /**
+     * Render the conflict-handling clause. Standard SQL (SQLite/PostgreSQL) uses
+     * `ON CONFLICT (...) [WHERE predicate] DO NOTHING | DO UPDATE SET ... [WHERE ...]`;
+     * MySQL overrides this.
+     *
+     * The index predicate is rendered before the `DO UPDATE` assignments because
+     * that is where it sits in the statement, so its parameters bind first.
+     *
+     * @param onConflict The conflict clause from the node.
+     * @param conflictCols The columns to overwrite on `DO UPDATE` (empty for nothing).
+     * @param nextValue Yields the SQL for the next `DO UPDATE` assignment value.
+     * @param names The node's property → column map, if any.
+     * @param params The parameter collector, for the predicates.
+     * @returns The SQL text, leading space included.
+     */
+    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined, params: Params): string;
+    private compileUpdate;
+    private compileDelete;
+    protected compileJoin(node: JoinNode, params: Params): string;
+    /**
+     * Render the extra sources of an `UPDATE ... FROM` / `DELETE ... USING`.
+     *
+     * The dialects that do not have the clause override this and throw: emitting it
+     * anyway would produce a statement the server rejects, and quietly dropping it
+     * would change which rows are written.
+     *
+     * @param keyword `FROM` or `USING`.
+     * @param sources The extra tables, if any.
+     * @returns The clause with a leading space, or an empty string.
+     */
+    protected compileExtraSources(keyword: "FROM" | "USING", sources: readonly {
+        readonly table: string;
+        readonly alias: string;
+    }[] | undefined): string;
+    protected compileReturning(returning: readonly string[] | "*" | null, names?: NameMap | undefined): string;
+    /**
+     * Compile a condition tree (fields / and / or / not) to SQL. `idFor` renders a
+     * key to a quoted identifier — `quoteId` for single-table, `qualify` for joins —
+     * so select/update/delete/join all share this one compiler.
+     */
+    protected compileCondition(node: CondNode | undefined, params: Params, idFor: (key: string) => string, encode?: (key: string, value: unknown) => unknown): string;
+    /**
+     * Compile a full-text condition.
+     *
+     * PostgreSQL gets the real thing (`@@ websearch_to_tsquery`); the dialects with
+     * no text-search engine override this and compile the node's prebuilt substring
+     * fallback instead, so the query still returns the right rows.
+     *
+     * @param node The full-text condition node.
+     * @param params The parameter collector.
+     * @param idFor Column-name resolver.
+     * @returns The rendered condition.
+     */
+    protected compileFullText(node: Extract<CondNode, {
+        kind: "fullText";
+    }>, params: Params, idFor: (key: string) => string): string;
+    /**
+     * Render one side of a comparison.
+     *
+     * A column reference goes through `idFor`, so an explicit `.name()` mapping and
+     * join qualification apply here exactly as they do in the object form of
+     * `where` — `col()` is not a way around them. Only a `value` node binds.
+     *
+     * @param node The expression AST.
+     * @param params The parameter collector.
+     * @param idFor The identifier resolver for the enclosing statement.
+     * @returns The SQL text of the expression.
+     */
+    /**
+     * Render what an aggregate is applied to: `*`, a column, or an expression.
+     *
+     * An expression operand is what makes a conditional aggregate
+     * (`SUM(CASE WHEN ... END)`) expressible — one pass over the table instead of a
+     * query per bucket.
+     *
+     * @param agg The aggregate term.
+     * @param params The parameter collector.
+     * @param names The node's column-name map.
+     * @returns The rendered operand.
+     */
+    private aggregateOperand;
+    private renderExpr;
+    /**
+     * Render a full-text relevance score.
+     *
+     * PostgreSQL has `ts_rank`; the others have nothing equivalent, and they
+     * override this to a constant so that ordering by it is a no-op rather than a
+     * compile error — the fallback keeps returning the right rows, only unranked.
+     *
+     * @param columns The columns making up the document.
+     * @param term The search term.
+     * @param language The text-search configuration.
+     * @param params The parameter collector.
+     * @param idFor Column-name resolver.
+     * @returns The rendered score expression.
+     */
+    protected renderRank(columns: readonly string[], term: string, language: string, params: Params, idFor: (key: string) => string): string;
+    /**
+     * Build the `to_tsvector(...)` document out of the searched columns.
+     *
+     * `coalesce(col, '')` matters: in SQL a `NULL` anywhere in a concatenation makes
+     * the whole document `NULL`, so one empty column would silently exclude the row.
+     *
+     * @param columns The columns making up the document.
+     * @param config The already-bound placeholder for the text-search config.
+     * @param idFor Column-name resolver.
+     * @returns The rendered `to_tsvector(...)` call.
+     */
+    protected tsVector(columns: readonly string[], config: string, idFor: (key: string) => string): string;
+    /**
+     * The SQL type name this dialect accepts in a `CAST`.
+     *
+     * The base mapping is the standard one PostgreSQL takes; SQLite and MySQL
+     * override it, because the names genuinely differ (MySQL's `CAST(x AS SIGNED)`
+     * is not `INTEGER`, and SQLite only has five storage classes to aim at).
+     *
+     * @param to The portable cast target.
+     * @returns The dialect's own type name.
+     */
+    protected castTypeName(to: CastType): string;
+    /**
+     * Compile a comparison whose right-hand side is another expression rather than
+     * a bound value (`total > paid`, `lower(a) = lower(b)`).
+     *
+     * The list and null operators are excluded: `IN`, `BETWEEN` and `IS NULL` take
+     * a value operand, and accepting an expression there would silently compile to
+     * something else.
+     *
+     * @param left The rendered left-hand side.
+     * @param op The operator name.
+     * @param right The rendered right-hand side.
+     * @returns The SQL text of the predicate.
+     * @throws Error When the operator needs a value operand.
+     */
+    private compileExprOperator;
+    private compileOperator;
+    /**
+     * Compile `IN` / `NOT IN`, whose operand is either a value list or a
+     * single-column subquery.
+     *
+     * The subquery is rendered at the position it appears in the outer statement
+     * and shares the same parameter collector, so its own placeholders land in the
+     * right order — and it keeps its own `names` map, since the inner model may use
+     * a different naming convention than the outer one.
+     *
+     * @param id The quoted column identifier being tested.
+     * @param operand A list of values, or a {@link Subquery}.
+     * @param params The parameter collector for the statement being compiled.
+     * @param negate True for `NOT IN`.
+     * @returns The SQL text of the predicate.
+     */
+    private compileIn;
+}
+/** SQLite dialect: `?` placeholders; `ILIKE` falls back to `LIKE` (ASCII-insensitive). */
+declare class SqliteDialect extends BaseDialect {
+    readonly name: "sqlite";
+    /**
+     * SQLite explains with `EXPLAIN QUERY PLAN`, and has no `ANALYZE` — the plain
+     * `EXPLAIN` there dumps bytecode, which answers a different question.
+     */
+    explainPrefix(analyze: boolean): string;
+    /**
+     * SQLite has `UPDATE ... FROM` (3.33+) but no `DELETE ... USING`.
+     *
+     * The portable shape there is a subquery — `where({ id: { in: … } })` — so this
+     * throws and says so, rather than emitting a clause SQLite does not parse.
+     */
+    protected compileExtraSources(keyword: "FROM" | "USING", sources: readonly {
+        readonly table: string;
+        readonly alias: string;
+    }[] | undefined): string;
+    /**
+     * SQLite has no text-search engine, so the prebuilt substring fallback is
+     * compiled instead. The rows are right; the ranking is what is missing.
+     */
+    protected compileFullText(node: Extract<CondNode, {
+        kind: "fullText";
+    }>, params: Params, idFor: (key: string) => string): string;
+    /** No text-search engine means no score: a constant, so ordering by it is inert. */
+    protected renderRank(): string;
+    /**
+     * SQLite has five storage classes, so most targets collapse onto `TEXT` or
+     * `INTEGER`. Naming a type it does not know would not fail — SQLite applies the
+     * closest affinity — but it would make the cast mean something different here
+     * than on the other databases, which is what this mapping avoids.
+     */
+    protected castTypeName(to: CastType): string;
+    protected placeholder(): string;
+    protected ilike(column: string, param: string): string;
+    /**
+     * SQLite runs one writer at a time, so its only isolation level **is**
+     * serializable — there is no syntax to ask for another, and no weaker level to
+     * fall back to. Asking for one is an error rather than a silent no-op, since a
+     * caller who wrote `repeatable read` was reasoning about a guarantee.
+     *
+     * `readOnly` likewise has no per-transaction form here (`PRAGMA query_only` is
+     * per connection), so it is refused instead of quietly ignored.
+     */
+    beginStatements(options?: TransactionOptions): string[];
+    /**
+     * SQLite has no row-level locking, so a lock request is an error rather than a
+     * silently unlocked `SELECT` — a lock that does not exist only shows up as
+     * duplicated work under production concurrency.
+     */
+    protected renderLock(): string;
+}
+/** PostgreSQL dialect: `$1` placeholders; native `ILIKE`; native array operators. */
+declare class PostgresDialect extends BaseDialect {
+    readonly name: "postgresql";
+    protected placeholder(index: number): string;
+    protected ilike(column: string, param: string): string;
+    protected arrayOperator(op: "contains" | "containedBy" | "overlaps"): string;
+}
+/**
+ * MySQL dialect: `?` placeholders, backtick identifiers, `ON DUPLICATE KEY
+ * UPDATE` for upsert, and case-insensitive `LIKE` (default collation). MySQL has
+ * no `RETURNING`, so requesting it throws.
+ */
+declare class MysqlDialect extends BaseDialect {
+    readonly name: "mysql";
+    protected placeholder(): string;
+    protected ilike(column: string, param: string): string;
+    /** MySQL's `EXPLAIN FORMAT=JSON` spells the option differently. */
+    explainPrefix(analyze: boolean): string;
+    /**
+     * MySQL only gained `INTERSECT`/`EXCEPT` in 8.0.31, and this project does not
+     * invest in MySQL beyond what already works — so they are refused here rather
+     * than emitted against a server that may reject them.
+     */
+    protected setOperator(op: SetOperator): string;
+    /**
+     * MySQL writes multi-table updates as `UPDATE a JOIN b`, and has no
+     * `DELETE ... USING` in this shape. Both are out of the project's active scope,
+     * so they are refused rather than emitted against a server that rejects them.
+     */
+    protected compileExtraSources(keyword: "FROM" | "USING", sources: readonly {
+        readonly table: string;
+        readonly alias: string;
+    }[] | undefined): string;
+    /**
+     * MySQL's full-text search needs a `FULLTEXT` index and different syntax, and it
+     * is outside this project's active scope — the substring fallback is compiled,
+     * like on SQLite.
+     */
+    protected compileFullText(node: Extract<CondNode, {
+        kind: "fullText";
+    }>, params: Params, idFor: (key: string) => string): string;
+    /** No `ts_rank` equivalent in scope: a constant, so ordering by it is inert. */
+    protected renderRank(): string;
+    /**
+     * MySQL sets the level with a statement **before** the transaction opens, and
+     * spells the read-only flag on `START TRANSACTION` rather than on `BEGIN`.
+     */
+    beginStatements(options?: TransactionOptions): string[];
+    /**
+     * MySQL's `CAST` takes its own vocabulary — `SIGNED`, not `INTEGER`; `CHAR`,
+     * not `TEXT` — and rejects the standard names outright.
+     */
+    protected castTypeName(to: CastType): string;
+    protected quoteId(name: string): string;
+    /**
+     * MySQL rejects `LIMIT` inside an `IN` subquery with
+     * `ER_NOT_SUPPORTED_YET: This version of MySQL doesn't yet support
+     * 'LIMIT & IN/ALL/ANY/SOME subquery'`. Failing at compile time names the fix
+     * instead of surfacing that error from the driver at runtime.
+     */
+    protected checkSubquery(node: SelectNode): void;
+    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined): string;
+    /**
+     * MySQL has no `RETURNING`, so it cannot be compiled into a statement.
+     *
+     * `session.execute()` still honors `.returning()` on a **single-row INSERT** by
+     * running the insert and reading the row back by key on the same connection —
+     * that is execution, not compilation, so it never reaches here. Compiling a
+     * node with `returning` directly is an error, rather than SQL that silently
+     * returns nothing.
+     */
+    protected compileReturning(returning: readonly string[] | "*" | null): string;
+}
+/** Get a dialect instance by name. */
+declare function getDialect(name: Dialect): BaseDialect;
+
+/**
+ * tempest-db-js — opt-in model mixins.
+ *
+ * The same four or five columns show up on every real table: when the row was
+ * created and last touched, whether it was soft-deleted, who changed it. Writing
+ * them out per model is repetition that drifts — one table gets `updated_at`
+ * without `onUpdate`, another spells it `updatedOn`.
+ *
+ * These mixins are functions that take a base class and return a subclass
+ * carrying the extra columns, mirroring `tempest-fastapi-sdk`'s
+ * `SoftDeleteMixin` / `AuditMixin`. They compose:
+ *
+ * ```ts
+ * class Order extends withSoftDelete(withTimestamps(Model)) {
+ *   static override tablename = "orders";
+ *   id = column.integer().primaryKey();
+ * }
+ * ```
+ *
+ * The columns are real columns: they appear in `InferModel`, in the migration IR
+ * and in the generated DDL, exactly as if you had typed them.
+ */
+
+/** Any class usable as a mixin base — `Model` itself, or another mixin's result. */
+type ModelBase = abstract new (...args: any[]) => Model;
+/**
+ * Add `createdAt` / `updatedAt` to a model.
+ *
+ * Both default to the database's own clock (`sql.now()`), and `updatedAt` carries
+ * `onUpdate(sql.now())`, so an `UPDATE` refreshes it without the call site
+ * remembering to. Both are `NOT NULL` with a default, so neither shows up as
+ * required in `InferInsert`.
+ *
+ * @param Base The class to extend (`Model`, or another mixin's result).
+ * @returns A subclass carrying the two timestamp columns.
+ */
+declare function withTimestamps<TBase extends ModelBase>(Base: TBase): (abstract new (...args: any[]) => {
+    /** When the row was inserted. */
+    createdAt: Column<Date, ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** When the row was last updated — refreshed by every `UPDATE`. */
+    updatedAt: Column<Date, ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+}) & TBase;
+/**
+ * Add `deletedAt` to a model, for non-destructive deletes.
+ *
+ * A row is alive while `deletedAt IS NULL`. **Filtering is the caller's job** —
+ * the mixin only declares the column, so it composes with whatever query strategy
+ * a table needs (a partial index, a repository default, a view). Use
+ * {@link notDeleted} to spell the predicate.
+ *
+ * @param Base The class to extend.
+ * @returns A subclass carrying the `deletedAt` column.
+ */
+declare function withSoftDelete<TBase extends ModelBase>(Base: TBase): (abstract new (...args: any[]) => {
+    /** When the row was soft-deleted, or `null` while it is alive. */
+    deletedAt: Column<Date, ColumnFlags>;
+}) & TBase;
+/**
+ * The `where` fragment matching rows that are **not** soft-deleted.
+ *
+ * @typeParam Row - the row type being filtered.
+ * @returns `{ deletedAt: { isNull: true } }`, typed for the row.
+ */
+declare function notDeleted<Row>(): WhereInput<Row>;
+/**
+ * The `where` fragment matching **only** soft-deleted rows.
+ *
+ * @typeParam Row - the row type being filtered.
+ * @returns `{ deletedAt: { isNull: false } }`, typed for the row.
+ */
+declare function onlyDeleted<Row>(): WhereInput<Row>;
+/**
+ * Add `createdBy` / `updatedBy` to a model — *who* touched the row.
+ *
+ * The actor column defaults to `column.uuid()`, matching the SDK's user id. A
+ * service whose users are keyed by something else passes a factory:
+ * `withAudit(Model, () => column.integer())`. It must be a factory, not a column:
+ * the two properties need two independent column instances.
+ *
+ * Both columns are nullable — a row created by a background job has no actor, and
+ * forcing a sentinel value there is worse than a `NULL`.
+ *
+ * @param Base The class to extend.
+ * @param actor Factory producing the actor column (default: `column.uuid()`).
+ * @returns A subclass carrying the two actor columns.
+ */
+declare function withAudit<TBase extends ModelBase, A = string>(Base: TBase, actor?: () => Column<A, ColumnFlags>): (abstract new (...args: any[]) => {
+    /** Who created the row, or `null` when nobody was attributed. */
+    createdBy: Column<A, ColumnFlags>;
+    /** Who last updated the row, or `null`. */
+    updatedBy: Column<A, ColumnFlags>;
+}) & TBase;
+
+/**
+ * tempest-db-js — read a constraint violation back out of the driver's error.
+ *
+ * A database says *why* it refused a write, and says it in prose whose shape is
+ * the driver's, not the application's. Answering `409 {"code":"EMAIL_TAKEN"}`
+ * instead of a generic conflict otherwise means every service writing its own
+ * regular expression against whichever dialect the author had running.
+ *
+ * The two dialects in scope say the same five things two different ways:
+ * PostgreSQL names the constraint and lists the columns in a `DETAIL:` line,
+ * while SQLite spells the table and columns into the message and says nothing
+ * about the constraint's name.
+ */
+
+/** What kind of constraint refused the write. */
+type IntegrityViolation = "unique" | "foreignKey" | "notNull" | "check" | "exclusion";
+/** A constraint violation, read out of the driver's error. */
+interface IntegrityFailure {
+    /** Which kind of constraint refused the write. */
+    readonly violation: IntegrityViolation;
+    /** The constraint's name, when the database reported one (PostgreSQL does). */
+    readonly constraint: string | null;
+    /** The table, when the database reported one. */
+    readonly table: string | null;
+    /**
+     * The columns the constraint covers.
+     *
+     * Empty when the database did not say — a SQLite `FOREIGN KEY constraint
+     * failed` carries no names at all.
+     */
+    readonly columns: readonly string[];
+    /** The driver's own message, kept verbatim for logging. */
+    readonly detail: string;
+}
+/**
+ * Read a driver error back into the constraint that refused the write.
+ *
+ * @param error Anything thrown by a write — a `QueryExecutionError` from this
+ *   package, or the driver's own error; the cause chain is followed either way.
+ * @param model Optional. When given, database column names are translated back to
+ *   the model's property names, so a `snake_case` schema reports `idempotencyKey`
+ *   rather than `idempotency_key`.
+ * @returns The violation, or `null` when the error is not an integrity violation
+ *   (or came from MySQL, which is out of scope — see the recipe).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.create({ email });
+ * } catch (err) {
+ *   const failure = parseIntegrityError(err, User);
+ *   if (failure?.violation === "unique" && failure.columns.includes("email")) {
+ *     throw new EmailTaken();
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+declare function parseIntegrityError(error: unknown, model?: ModelClass): IntegrityFailure | null;
+
+/**
+ * tempest-db-js — text search that survives what users actually type.
+ *
+ * Two layers, because they answer different questions:
+ *
+ * - {@link contains} — tokenized, **escaped** substring matching. Identical on
+ *   every dialect, needs no extension, no index and no migration. This is what
+ *   "find the row whose name contains what the user typed" should use.
+ * - {@link fullText} / {@link fullTextRank} — PostgreSQL's `to_tsvector` /
+ *   `websearch_to_tsquery` / `ts_rank`: stemming, stop words and a relevance
+ *   score. On any other database they fall back to the first layer, which is the
+ *   honest degradation — the query still returns the right rows, just without
+ *   stemming.
+ */
+
+/**
+ * A PostgreSQL text-search configuration (`regconfig`), such as `"english"` or
+ * `"portuguese"`. `"simple"` disables stemming and stop-word removal.
+ */
+type TextSearchLanguage = string;
+/** Options shared by the full-text helpers. */
+interface TextSearchOptions {
+    /** The PostgreSQL text-search configuration. Defaults to `"english"`. */
+    readonly language?: TextSearchLanguage;
+}
+/** Options for {@link contains}. */
+interface ContainsOptions {
+    /**
+     * Whether a row must match **every** token (default) or any one of them.
+     *
+     * `"all"` is what a search box wants: typing more words narrows the result.
+     */
+    readonly match?: "all" | "any";
+}
+/**
+ * Escape the `LIKE` wildcards in a literal, for use with `like` / `ilike`.
+ *
+ * `%` and `_` are wildcards, and `\` escapes them — so a user searching for
+ * `100%` matches every row unless the literal is escaped first. The pattern this
+ * produces is meant to be used with an `ESCAPE '\'` clause, which is what the
+ * {@link ContainsOptions} operator emits; PostgreSQL assumes that escape by
+ * default, SQLite has none until it is given one.
+ *
+ * @param value The literal the user typed.
+ * @returns The same text with `\`, `%` and `_` escaped.
+ */
+declare function escapeLike(value: string): string;
+/**
+ * Split a search term into the tokens a row has to match.
+ *
+ * @param term What the user typed.
+ * @returns The non-empty whitespace-separated tokens.
+ */
+declare function tokenize(term: string): string[];
+/**
+ * Case-insensitive substring search across one or more columns.
+ *
+ * The term is tokenized, and each token is matched — **escaped** — against every
+ * listed column; a row matches when every token appears in at least one of them.
+ * Behaves the same on every dialect, with no index or extension needed.
+ *
+ * @param columns The columns to search, by property name.
+ * @param term What the user typed.
+ * @param options `match: "any"` to require a single token instead of all of them.
+ * @returns A condition for `where`, matching nothing when the term is blank.
+ * @throws Error When no column is given.
+ *
+ * @example
+ * ```ts
+ * select(User).where(contains(["name", "email"], "100% ana"));
+ * // (name ILIKE '%100\%%' ESCAPE '\' OR email ILIKE ...) AND (name ILIKE '%ana%' ...)
+ * ```
+ */
+declare function contains<Row = Record<string, unknown>>(columns: readonly string[], term: string, options?: ContainsOptions): Condition;
+/**
+ * PostgreSQL full-text search over one or more columns, with a portable fallback.
+ *
+ * On PostgreSQL this compiles to `to_tsvector(config, col || ' ' || col) @@
+ * websearch_to_tsquery(config, term)`, so the search stems (`buying` matches
+ * `buy`), drops stop words, and understands the quoting and `-exclusion` syntax
+ * users already know from web search boxes.
+ *
+ * On any other database it compiles to {@link contains} instead — the same rows a
+ * substring search would find, without stemming. That is a documented
+ * degradation, not a silent one: a dev SQLite database keeps working, and the
+ * difference is in ranking quality, not correctness.
+ *
+ * @param columns The columns to search, by property name.
+ * @param term What the user typed.
+ * @param options The text-search configuration.
+ * @returns A condition for `where`.
+ * @throws Error When no column is given.
+ */
+declare function fullText<Row = Record<string, unknown>>(columns: readonly string[], term: string, options?: TextSearchOptions): Condition;
+/**
+ * The relevance score of a full-text match, for `orderBy`.
+ *
+ * On PostgreSQL this is `ts_rank(...)`, the number that makes "best match first"
+ * mean something. Elsewhere it renders as a constant, so ordering by it is a
+ * no-op and the query falls back to whatever other ordering is given — ranking is
+ * the part that genuinely does not exist without a text-search engine.
+ *
+ * @param columns The same columns passed to {@link fullText}.
+ * @param term The same term.
+ * @param options The same configuration.
+ * @returns An expression usable in `orderBy`.
+ * @throws Error When no column is given.
+ *
+ * @example
+ * ```ts
+ * select(Post)
+ *   .where(fullText(["title", "body"], term, { language: "portuguese" }))
+ *   .orderBy(fullTextRank(["title", "body"], term, { language: "portuguese" }), "desc");
+ * ```
+ */
+declare function fullTextRank(columns: readonly string[], term: string, options?: TextSearchOptions): Expression;
+
+/**
+ * tempest-db-js — lifecycle signals around the repository's write path.
+ *
+ * Reacting to persistence — busting a cache, enqueuing an outbox event, syncing a
+ * search index, writing an audit row — otherwise means wrapping every call site
+ * by hand, and the one call site somebody forgets is the bug.
+ *
+ * Handlers run **inside** whatever transaction is open, because they are handed
+ * the same session the write used: a handler that writes commits with the write,
+ * or rolls back with it.
+ */
+
+/** The points a repository write is observable at. */
+type RepositorySignal = "preSave" | "postSave" | "preDelete" | "postDelete";
+/** What a handler receives. */
+interface SignalPayload<C extends ModelClass> {
+    /**
+     * The row the signal is about.
+     *
+     * `preSave` on an insert carries what was passed to `create`, so a
+     * database-generated id is not there yet — `postSave` carries the stored row.
+     * `preDelete` carries the row as it was just before it was deleted.
+     */
+    readonly row: InferModel<C>;
+    /** The model being written. */
+    readonly model: C;
+    /** The session the write is running on — the same transaction, if one is open. */
+    readonly session: AsyncSession;
+    /** True when the write that fired this was an insert rather than an update. */
+    readonly isInsert: boolean;
+}
+/** A signal handler; may be async, and is awaited. */
+type SignalHandler<C extends ModelClass> = (payload: SignalPayload<C>) => void | Promise<void>;
+/**
+ * Register a handler for one signal on one model.
+ *
+ * @param model The model to observe.
+ * @param signal Which point to observe.
+ * @param handler The handler; awaited, and free to use the payload's session.
+ * @returns A function that unregisters this handler.
+ *
+ * @example
+ * ```ts
+ * const off = onSignal(User, "postSave", async ({ row }) => {
+ *   await cache.del(`user:${row.id}`);
+ * });
+ * ```
+ */
+declare function onSignal<C extends ModelClass>(model: C, signal: RepositorySignal, handler: SignalHandler<C>): () => void;
+/**
+ * Whether anything is listening to a signal on a model.
+ *
+ * The repository asks before doing work only a handler would need — reading the
+ * rows a filter-based `update`/`delete` is about to touch costs a `SELECT`, and
+ * nobody should pay it when no handler exists.
+ *
+ * @param model The model.
+ * @param signal The signal.
+ * @returns True when at least one handler is registered.
+ */
+declare function hasHandlers(model: ModelClass, signal: RepositorySignal): boolean;
+/**
+ * Fire a signal, awaiting every handler in registration order.
+ *
+ * A handler that throws **propagates**: on `preSave`/`preDelete` that vetoes the
+ * write, which is the point — a veto that could be swallowed would be a
+ * suggestion.
+ *
+ * @param signal The signal to fire.
+ * @param payload What to hand the handlers.
+ */
+declare function emitSignal<C extends ModelClass>(signal: RepositorySignal, payload: SignalPayload<C>): Promise<void>;
+/**
+ * Drop registered handlers — for tests, which otherwise leak them across cases.
+ *
+ * @param model Only this model's handlers; omitted, every model's.
+ */
+declare function clearSignals(model?: ModelClass): void;
+
+/**
+ * tempest-db-js — Phase 7: typed repository + pagination.
+ *
+ * `BaseRepository<Model>` mirrors the `tempest-fastapi-sdk` repository: a thin,
+ * fully-typed CRUD + pagination layer over a model and an async session. The
+ * 404-convention is honored — `getById` throws when absent, collection methods
+ * return `[]` (never a "not found" error for an empty list).
+ */
+
+/** Pagination request — 1-indexed page. */
+interface PaginationFilter<Row> {
+    readonly page?: number;
+    readonly pageSize?: number;
+    readonly orderBy?: keyof Row & string;
+    readonly ascending?: boolean;
+    readonly filters?: WhereInput<Row>;
+}
+/** A page of results plus metadata (mirrors `BasePaginationSchema`). */
+interface PaginationResult<Row> {
+    readonly items: Row[];
+    readonly total: number;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly pages: number;
+}
+/**
+ * Cursor-pagination request.
+ *
+ * Cursor paging trades random access for two things offset paging cannot give on a
+ * large table: no `COUNT(*)`, and a page boundary that does not shift when rows are
+ * inserted while the user is reading.
+ *
+ * @typeParam Row - the row type being paginated.
+ */
+interface CursorPaginationFilter<Row> {
+    /** Opaque cursor from the previous page. Absent/`null` asks for the first page. */
+    readonly cursor?: string | null;
+    /** Maximum rows to return (default 20). */
+    readonly limit?: number;
+    /** Column to sort by. Defaults to the first primary-key column. */
+    readonly orderBy?: keyof Row & string;
+    /** Sort ascending. Defaults to `false`, so the newest rows come first. */
+    readonly ascending?: boolean;
+    /** Domain filters, applied to every page. */
+    readonly filters?: WhereInput<Row>;
+}
+/** One cursor-paginated page. */
+interface CursorPage<Row> {
+    /** The rows of this page. */
+    readonly items: Row[];
+    /** Cursor for the next page, or `null` when this was the last one. */
+    readonly nextCursor: string | null;
+}
+/** Raised when a cursor is not one this repository produced. */
+declare class InvalidCursor extends Error {
+    constructor(reason: string);
+}
+/** Request for {@link BaseRepository.changesSince}. */
+interface ChangesSinceFilter<Row> {
+    /**
+     * The client's high-water mark. Rows changed **strictly after** it are
+     * returned; `null` (or absent) asks for everything, which is the first sync.
+     */
+    readonly since?: Date | null;
+    /** Cursor from the previous page of this same pull. */
+    readonly cursor?: string | null;
+    /** Maximum rows per page (default 50). */
+    readonly limit?: number;
+    /** Domain filters, applied to every page. */
+    readonly filters?: WhereInput<Row>;
+}
+/** One page of changes, plus the watermark to persist for the next pull. */
+interface ChangesPage<Row> extends CursorPage<Row> {
+    /**
+     * The server's clock, read **before** the query ran.
+     *
+     * This is what a client persists as its next `since` — not the newest
+     * `updatedAt` it saw. A row committed while this page was being built carries
+     * a later timestamp, so it surfaces on the following pull instead of falling
+     * into the gap between the two.
+     */
+    readonly serverTime: Date;
+}
+/** Options for {@link BaseRepository.bulkUpsert}. */
+interface BulkUpsertOptions<Row> {
+    /** The columns forming the conflict target (a unique constraint or index). */
+    readonly conflictColumns: readonly (keyof Row & string)[];
+    /**
+     * Which columns to overwrite on conflict. Omitted, every column present in the
+     * incoming rows except the conflict target is written.
+     */
+    readonly update?: readonly (keyof Row & string)[];
+}
+/** Raised by single-record lookups (`getById`) when nothing matches (404). */
+declare class RecordNotFound extends Error {
+    constructor(table: string, key: unknown);
+}
+/**
+ * A fully-typed CRUD + pagination repository over a model and an async session.
+ *
+ * @typeParam C - the model class.
+ */
+declare class BaseRepository<C extends ModelClass> {
+    protected readonly model: C;
+    protected readonly session: AsyncSession;
+    private readonly pks;
+    constructor(model: C, session: AsyncSession);
+    /**
+     * Narrow every read this repository performs.
+     *
+     * The extension point a scoped repository overrides: returning a filter that
+     * always carries the scope's predicate is what makes it impossible for one
+     * query site to forget it. The base implementation adds nothing.
+     *
+     * @param filters The caller's filters.
+     * @returns The filters actually sent to the database.
+     */
+    protected scopeFilters(filters?: WhereInput<InferModel<C>>): WhereInput<InferModel<C>> | undefined;
+    /**
+     * Stamp every row this repository writes.
+     *
+     * The write-side counterpart of {@link scopeFilters}. The base implementation
+     * writes the row unchanged.
+     *
+     * @param data The row being written.
+     * @returns The row actually written.
+     */
+    protected scopeWrite<T extends Record<string, unknown>>(data: T): T;
+    /** All rows matching `filters` (or everything). Empty list when none match. */
+    list(input?: WhereInput<InferModel<C>>): Promise<InferModel<C>[]>;
+    /** The first row matching `filters`, or `null`. */
+    first(input?: WhereInput<InferModel<C>>): Promise<InferModel<C> | null>;
+    /**
+     * A single row by primary key, or `null`.
+     *
+     * @param id The key — a bare value for a single-column key, an object
+     *   (`{ orderId, lineNumber }`) for a composite one.
+     * @returns The row, or `null` when nothing matches.
+     * @throws Error When a scalar is given for a composite key, or the key is
+     *   incomplete.
+     */
+    getByIdOrNull(id: unknown): Promise<InferModel<C> | null>;
+    /**
+     * A single row by primary key; throws `RecordNotFound` when absent.
+     *
+     * @param id The key — see {@link getByIdOrNull}.
+     * @returns The row.
+     * @throws RecordNotFound When no row carries that key.
+     */
+    getById(id: unknown): Promise<InferModel<C>>;
+    /** Whether any row matches `filters`. */
+    exists(filters: WhereInput<InferModel<C>>): Promise<boolean>;
+    /** How many rows match `filters` (or the whole table). */
+    count(input?: WhereInput<InferModel<C>>): Promise<number>;
+    /**
+     * Insert one row, returning the created row.
+     *
+     * Fires `preSave` (which can veto by throwing) and then `postSave`.
+     *
+     * @param data The row to insert.
+     * @returns The stored row.
+     */
+    create(data: InferInsert<C>): Promise<InferModel<C>>;
+    /**
+     * Insert many rows, returning the created rows.
+     *
+     * Signals fire per row, so a handler sees one row at a time whether it was
+     * inserted alone or in a batch.
+     *
+     * @param data The rows to insert.
+     * @returns The stored rows.
+     */
+    createMany(data: readonly InferInsert<C>[]): Promise<InferModel<C>[]>;
+    /**
+     * Update rows matching `filters`; returns the number of rows affected.
+     *
+     * With a `preSave`/`postSave` handler registered, the matching rows are read
+     * first so the handler can see them — that extra `SELECT` is skipped entirely
+     * when nothing is listening.
+     *
+     * @param filters Which rows to update.
+     * @param set The columns to change.
+     * @returns The number of rows affected.
+     */
+    update(input: WhereInput<InferModel<C>>, set: Partial<InferModel<C>>): Promise<number>;
+    /**
+     * Delete rows matching `filters`; returns the number of rows affected.
+     *
+     * `preDelete` and `postDelete` receive the row as it was **before** the delete —
+     * the only chance to see it. Reading it costs a `SELECT`, which is skipped when
+     * no handler is registered.
+     *
+     * @param filters Which rows to delete.
+     * @returns The number of rows affected.
+     */
+    delete(input: WhereInput<InferModel<C>>): Promise<number>;
+    /**
+     * Fire one signal for one row on this repository's model and session.
+     *
+     * @param signal Which signal.
+     * @param row The row it is about.
+     * @param isInsert Whether the write was an insert.
+     */
+    private fire;
+    /**
+     * A page of rows plus metadata. `total` counts all matching rows.
+     *
+     * @param filter Page, size, ordering and filters.
+     * @returns The page and pagination metadata.
+     */
+    paginate(filter?: PaginationFilter<InferModel<C>>): Promise<PaginationResult<InferModel<C>>>;
+    /**
+     * A cursor-paginated page: the rows after `cursor`, plus the cursor for the
+     * next page.
+     *
+     * No `COUNT(*)` runs, and the page boundary is stable under concurrent inserts —
+     * the two reasons to reach for this instead of {@link paginate} on a large table.
+     * The trade-off is losing random access: there is no "page 7".
+     *
+     * The primary key is always appended as a tie-break, so rows sharing an
+     * `orderBy` value cannot be skipped or repeated across pages.
+     *
+     * @param filter Cursor, page size, ordering and filters.
+     * @returns The page and the next cursor (`null` on the last page).
+     * @throws InvalidCursor When the cursor is malformed or was built for a
+     *   different ordering.
+     */
+    cursorPaginate(filter?: CursorPaginationFilter<InferModel<C>>): Promise<CursorPage<InferModel<C>>>;
+    /**
+     * Whether any **other** row matches `filters`.
+     *
+     * The uniqueness check for an update: "is this e-mail taken by somebody else?"
+     * A plain `exists` would find the row being edited and report a false conflict.
+     *
+     * @param filters What to look for.
+     * @param key The primary key to exclude — the row being updated.
+     * @returns True when a different row matches.
+     */
+    existsExcluding(filters: WhereInput<InferModel<C>>, key: unknown): Promise<boolean>;
+    /**
+     * The rows that changed since a high-water mark — the delta-sync read.
+     *
+     * Rows come back oldest change first, tie-broken by primary key, so a client
+     * can advance its watermark monotonically and resume mid-stream with the
+     * cursor. The filter is **strict** (`updatedAt > since`).
+     *
+     * Soft-deleted rows are included on purpose: they are the tombstones that tell
+     * the client to delete its local copy. Filtering them out would strand deleted
+     * rows on the device forever.
+     *
+     * @param filter The watermark, cursor, page size and domain filters.
+     * @returns The page, plus the `serverTime` to persist as the next watermark.
+     * @throws Error When the model has no `updatedAt` column (see `withTimestamps`).
+     */
+    changesSince(filter?: ChangesSinceFilter<InferModel<C>>): Promise<ChangesPage<InferModel<C>>>;
+    /**
+     * Insert many rows, overwriting the ones that conflict — one statement.
+     *
+     * @param rows The rows to write.
+     * @param options The conflict target, and optionally which columns to overwrite.
+     * @returns The stored rows.
+     * @throws Error When no conflict column is given.
+     */
+    bulkUpsert(rows: readonly InferInsert<C>[], options: BulkUpsertOptions<InferModel<C>>): Promise<InferModel<C>[]>;
+    /**
+     * Mark a row deleted without removing it (`deletedAt = now()`).
+     *
+     * @param key The primary key.
+     * @returns The updated row.
+     * @throws Error When the model has no `deletedAt` column (see `withSoftDelete`).
+     * @throws RecordNotFound When no row carries that key.
+     */
+    softDelete(key: unknown): Promise<InferModel<C>>;
+    /**
+     * Bring a soft-deleted row back (`deletedAt = null`).
+     *
+     * @param key The primary key.
+     * @returns The updated row.
+     * @throws Error When the model has no `deletedAt` column.
+     * @throws RecordNotFound When no row carries that key.
+     */
+    restore(key: unknown): Promise<InferModel<C>>;
+    /**
+     * Delete many rows by primary key, in one statement.
+     *
+     * @param keys The primary keys.
+     * @returns The number of rows actually deleted (keys that matched nothing are
+     *   not an error — deleting what is already gone is the desired end state).
+     * @throws Error When the model has a composite primary key: `IN` over a tuple is
+     *   not portable, and the caller should loop or build the condition explicitly.
+     */
+    deleteBatch(keys: readonly unknown[]): Promise<number>;
+    /**
+     * Fail loudly when a method needs a column the model does not declare.
+     *
+     * @param column The property name required.
+     * @param method The method asking, for the message.
+     * @throws Error When the column is absent.
+     */
+    private requireColumn;
+}
+
+/** Where an outbox row is in its lifecycle. */
+type OutboxStatus = "pending" | "sending" | "sent" | "failed";
+/**
+ * Build the base class for a service's outbox table.
+ *
+ * @param tablename The table to store events in.
+ * @returns A model base carrying the outbox columns; extend it to add your own.
+ *
+ * @example
+ * ```ts
+ * class OutboxEvent extends outboxModel("outbox") {}
+ * ```
+ */
+declare function outboxModel(name: string): (abstract new () => {
+    /** Monotonic id; also the claim order, so events publish in the order written. */
+    id: Column<bigint, ColumnFlags & {
+        primaryKey: true;
+        hasDefault: true;
+    }>;
+    /** The routing key the relay publishes under. */
+    topic: Column<string, ColumnFlags & {
+        notNull: true;
+    }>;
+    /** The event body. */
+    payload: Column<Record<string, unknown>, ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Lifecycle state. */
+    status: Column<"pending" | "sending" | "sent" | "failed", ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** How many publish attempts have been made. */
+    attempts: Column<number, ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** Epoch milliseconds before which the row must not be claimed (backoff). */
+    availableAt: Column<bigint, ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** When the row was written. */
+    createdAt: Column<Date, ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** When the relay confirmed the publish. */
+    sentAt: Column<Date, ColumnFlags>;
+    /** The last failure's message, kept for triage. */
+    lastError: Column<string, ColumnFlags>;
+}) & {
+    tablename: string;
+    tableArgs?: () => readonly TableConstraint[];
+    naming?: NamingStrategy;
+};
+/** An event to write to the outbox. */
+interface OutboxEventInput {
+    /** The routing key. */
+    readonly topic: string;
+    /** The event body. */
+    readonly payload: Record<string, unknown>;
+    /** Delay the first attempt by this many milliseconds. */
+    readonly delayMs?: number;
+}
+/** Options for {@link OutboxRepository.claim}. */
+interface ClaimOptions {
+    /** Only claim events on these topics. */
+    readonly topics?: readonly string[];
+    /** Treat the clock as this instant (tests). */
+    readonly now?: number;
+}
+/** Options for {@link OutboxRepository.markFailed}. */
+interface FailOptions {
+    /** Wait this long before the row can be claimed again. */
+    readonly retryInMs?: number;
+    /** Give up permanently instead of scheduling a retry. */
+    readonly permanent?: boolean;
+}
+/**
+ * The relay's half of the outbox: claim, confirm, and fail with backoff.
+ *
+ * @typeParam C - the outbox model class.
+ */
+declare class OutboxRepository<C extends ModelClass> extends BaseRepository<C> {
+    /**
+     * Write events to the outbox.
+     *
+     * Call it inside the same `transaction()` as the business write — that is the
+     * whole point, and it is why this does not open a transaction of its own.
+     *
+     * @param events One event, or many.
+     * @returns The stored rows.
+     */
+    publish(events: OutboxEventInput | readonly OutboxEventInput[]): Promise<InferModel<C>[]>;
+    /**
+     * Claim a batch of due events for this relay, in one statement.
+     *
+     * Uses `FOR UPDATE SKIP LOCKED` over a subquery, so two relays running at once
+     * take **disjoint** batches instead of fighting over the same rows. SQLite has
+     * no row locking and throws — a single-process relay there can claim with
+     * `pending()` plus an update.
+     *
+     * @param limit How many events to take.
+     * @param options Topic filter, and a clock override for tests.
+     * @returns The claimed rows, oldest first.
+     */
+    claim(limit: number, options?: ClaimOptions): Promise<InferModel<C>[]>;
+    /**
+     * The events that are due, without claiming them.
+     *
+     * @param limit How many to read.
+     * @param options Topic filter and clock override.
+     * @returns The due rows, oldest first.
+     */
+    pending(limit: number, options?: ClaimOptions): Promise<InferModel<C>[]>;
+    /**
+     * Confirm that events were published.
+     *
+     * @param ids The claimed ids.
+     * @returns How many rows were marked sent.
+     */
+    markSent(ids: readonly bigint[]): Promise<number>;
+    /**
+     * Record a failed publish, scheduling a retry unless it is permanent.
+     *
+     * The attempt counter was already incremented by {@link claim}, so a row that
+     * keeps failing carries its own history — which is what a dead-letter policy
+     * reads.
+     *
+     * @param id The event's id.
+     * @param error The failure, for triage.
+     * @param options Backoff delay, or `permanent` to stop retrying.
+     * @returns How many rows were updated (0 or 1).
+     */
+    markFailed(id: bigint, error: unknown, options?: FailOptions): Promise<number>;
+    /**
+     * The SELECT of events that may be claimed now.
+     *
+     * @param now The current epoch milliseconds.
+     * @param topics Optional topic filter.
+     * @returns The builder, unordered.
+     */
+    private dueQuery;
+}
+
+/**
+ * tempest-db-js — a repository scoped to one tenant.
+ *
+ * In a shared-schema multi-tenant database every tenant's rows live in the same
+ * table, told apart by a column. The danger is plain: forget one
+ * `WHERE tenantId = ?` and tenant A reads — or deletes — tenant B's data. The
+ * footgun is not the missing predicate, it is that **every query site** has to
+ * remember it.
+ *
+ * This binds the tenant once, at construction, and injects the predicate into
+ * every read and every write the repository performs.
+ */
+
+/** How a repository is bound to one tenant. */
+interface TenantScope {
+    /** The column carrying the tenant, by property name. */
+    readonly column: string;
+    /** The tenant's identifier. */
+    readonly id: unknown;
 }
 /**
- * A server-side notice (a PostgreSQL `NOTICE`). The shape is the driver's own —
- * passed through untouched rather than normalized, since what is useful in it
- * differs per database.
+ * A repository whose every read and write is confined to one tenant.
+ *
+ * @typeParam C - the model class.
  */
-type NoticeLogger = (notice: Record<string, unknown>) => void;
-/** Options shared by both engine flavors. */
-interface EngineOptions {
-    /** Override the driver detected from the URL (e.g. `"better-sqlite3"`). */
-    readonly driver?: string;
-    /** Connection-pool tuning (PostgreSQL only). */
-    readonly pool?: PoolOptions;
+declare class TenantScopedRepository<C extends ModelClass> extends BaseRepository<C> {
+    private readonly scope;
     /**
-     * Called for every statement a session runs — SQL + bound params. Use for
-     * query logging/tracing. Thrown errors are swallowed so it never breaks a query.
+     * Bind a repository to one tenant.
+     *
+     * @param model The model class.
+     * @param session The session to run on.
+     * @param scope The tenant column and id.
+     * @throws Error When the model has no such column — a scope that silently
+     *   matches nothing is worse than no scope at all.
      */
-    readonly onQuery?: QueryLogger;
+    constructor(model: C, session: AsyncSession, scope: TenantScope);
+    /** The tenant this repository is bound to. */
+    get tenantId(): unknown;
     /**
-     * Called for every server-side notice (`CREATE TABLE IF NOT EXISTS` on an
-     * existing table, `DROP ... IF EXISTS` on a missing one, and so on).
+     * Merge the tenant predicate into every read.
      *
-     * **Without this, notices are silenced.** postgres.js defaults to printing them
-     * with `console.log`, which drops a nine-line object into the host service's
-     * stdout in the middle of its structured log — on every boot, since a migration
-     * runner is usually the first thing to run. Writing to the host's stdout is the
-     * application's decision, not a library's, so the default is to say nothing and
-     * let you route them:
+     * The caller's filters are **added to**, never replaced: passing another
+     * tenant's id produces a contradiction that matches nothing, which is the safe
+     * outcome.
      *
-     * ```ts
-     * createEngine(url, { onNotice: (n) => logger.debug({ pg: n }, "postgres notice") });
-     * ```
+     * @param filters The caller's filters.
+     * @returns The filters plus the tenant predicate.
+     */
+    protected scopeFilters(filters?: WhereInput<InferModel<C>>): WhereInput<InferModel<C>> | undefined;
+    /**
+     * Stamp the tenant onto every row written.
      *
-     * Thrown errors are swallowed, like `onQuery`.
+     * A row that arrives carrying a **different** tenant is refused rather than
+     * overwritten: silently rewriting it would turn a caller's bug into data that
+     * looks deliberate.
+     *
+     * @param data The row being written.
+     * @returns The row with the tenant column set.
+     * @throws Error When the row names another tenant.
      */
-    readonly onNotice?: NoticeLogger;
+    protected scopeWrite<T extends Record<string, unknown>>(data: T): T;
+}
+
+/** What happened to the row. */
+type AuditAction = "insert" | "update" | "delete";
+/** A before/after pair per changed column. */
+type AuditDiff = Record<string, readonly [unknown, unknown]>;
+/**
+ * Build the base class for a service's audit-log table.
+ *
+ * @param name The table to store entries in.
+ * @returns A model base carrying the audit columns; extend it to add your own.
+ *
+ * @example
+ * ```ts
+ * class AuditLog extends auditLogModel("audit_log") {}
+ * ```
+ */
+declare function auditLogModel(name: string): (abstract new () => {
+    /** Monotonic id — also the order the changes happened in. */
+    id: Column<bigint, ColumnFlags & {
+        primaryKey: true;
+        hasDefault: true;
+    }>;
+    /** The audited table. */
+    tableName: Column<string, ColumnFlags & {
+        notNull: true;
+    }>;
+    /** The audited row's primary key, as an object. */
+    rowKey: Column<Record<string, unknown>, ColumnFlags & {
+        notNull: true;
+    }>;
+    /** What happened. */
+    action: Column<"insert" | "update" | "delete", ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Who did it, when the caller could say. */
+    actor: Column<string, ColumnFlags>;
+    /** The changed columns as `[before, after]`; the whole row on insert/delete. */
+    changes: Column<AuditDiff, ColumnFlags & {
+        notNull: true;
+    }>;
+    /** When the entry was written. */
+    at: Column<Date, ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+}) & {
+    tablename: string;
+    tableArgs?: () => readonly TableConstraint[];
+    naming?: NamingStrategy;
+};
+/** How auditing is wired for one model. */
+interface AuditOptions<L extends ModelClass> {
+    /** The audit-log model to write entries into. */
+    readonly log: L;
     /**
-     * Options passed straight to the underlying driver, applied **last** so they
-     * win over everything this layer derives (`pool`, `onNotice`).
+     * Who is making the change.
      *
-     * The escape hatch for what the typed surface does not model and is not going
-     * to — postgres.js `connection`/`types`/`transform`/`ssl`, mysql2's own
-     * settings, `node:sqlite`'s `readOnly` — so a gap need not become a feature
-     * request.
+     * Called at write time, so it can read whatever request-scoped context the
+     * service keeps. Return `null` for a change with no human behind it.
      */
-    readonly driverOptions?: Readonly<Record<string, unknown>>;
+    readonly actor?: () => string | null;
+    /** Columns never worth recording (a password hash, a big blob). */
+    readonly exclude?: readonly string[];
 }
-/** A synchronous engine (SQLite only). */
-declare class SyncEngine {
-    private readonly driver;
-    private readonly logger?;
-    readonly dialect: Dialect;
-    constructor(driver: SyncDriver, logger?: QueryLogger | undefined);
-    session(): SyncSession;
-    transaction<T>(fn: (tx: SyncSession) => T): T;
-    close(): void;
-    /** `using engine = createSyncEngine(...)` closes the pool when the scope exits. */
-    [Symbol.dispose](): void;
+/**
+ * The columns of a row, encoded for storage in the log's JSON column.
+ *
+ * @param model The audited model.
+ * @param row The row.
+ * @param exclude Columns to leave out.
+ * @returns The row as JSON-safe values.
+ */
+declare function snapshot(model: ModelClass, row: Record<string, unknown>, exclude?: readonly string[]): Record<string, unknown>;
+/**
+ * The columns that differ between two snapshots.
+ *
+ * Compared **after** encoding, so a `Date` and its stored string do not read as a
+ * change; a column missing from one side counts as a change to `null`.
+ *
+ * @param before The earlier snapshot.
+ * @param after The later snapshot.
+ * @returns One `[before, after]` pair per changed column.
+ */
+declare function diffSnapshots(before: Record<string, unknown>, after: Record<string, unknown>): AuditDiff;
+/**
+ * Record every create, update and delete of a model into an audit log.
+ *
+ * Wired through the repository signals, so entries are written on the same
+ * session — and therefore inside the same transaction — as the change. A change
+ * that rolls back takes its audit entry with it.
+ *
+ * @param model The model to audit.
+ * @param options The log model, the actor resolver and any excluded columns.
+ * @returns A function that turns auditing off again.
+ *
+ * @example
+ * ```ts
+ * class AuditLog extends auditLogModel("audit_log") {}
+ * enableAudit(Order, { log: AuditLog, actor: () => currentUser()?.id ?? null });
+ * ```
+ */
+declare function enableAudit<C extends ModelClass, L extends ModelClass>(model: C, options: AuditOptions<L>): () => void;
+/** The row type of an audit-log model, for the reader's convenience. */
+type AuditEntry<L extends ModelClass> = InferModel<L>;
+
+/**
+ * tempest-db-js — backup and restore, driven from the CLI.
+ *
+ * The step every runbook asks for before a migration, wrapped so it is the same
+ * command against both databases in scope. It shells out to the canonical tooling
+ * rather than reimplementing a dump format: `pg_dump`/`pg_restore`/`psql` on
+ * PostgreSQL, and SQLite's own `VACUUM INTO` — which, unlike copying the file, is
+ * consistent while the database is being written to.
+ */
+/** Raised when the tool a dialect needs is not on the PATH. */
+declare class BackupToolMissing extends Error {
+    constructor(tool: string);
 }
-/** An asynchronous engine. */
-declare class AsyncEngine {
-    private readonly driver;
-    readonly dialect: Dialect;
-    private readonly logger?;
-    constructor(driver: AsyncDriver, dialect: Dialect, logger?: QueryLogger | undefined);
-    session(): AsyncSession;
-    transaction<T>(fn: (tx: AsyncSession) => Promise<T>): Promise<T>;
-    close(): Promise<void>;
-    /** `await using engine = createEngine(...)` closes the pool when the scope exits. */
-    [Symbol.asyncDispose](): Promise<void>;
+/** Raised for a dialect that has no backup path here. */
+declare class UnsupportedBackupBackend extends Error {
+    constructor(dialect: string);
+}
+/** Options shared by backup and restore. */
+interface BackupOptions {
+    /** Overwrite the target if it already exists (restore only). */
+    readonly force?: boolean;
+    /** Extra arguments appended to the underlying tool's command line. */
+    readonly extraArgs?: readonly string[];
+}
+/** What a backup or restore did. */
+interface BackupResult {
+    /** The file written (backup) or read (restore). */
+    readonly file: string;
+    /** The dialect it was taken from. */
+    readonly dialect: string;
+    /** The tool used, or `"VACUUM INTO"` / `"copy"` for SQLite. */
+    readonly via: string;
 }
 /**
- * Adapt a sync **or** async driver to the async interface.
+ * The dump format implied by a file's extension.
  *
- * `await` normalizes both: a sync driver returns a plain value, an async one a
- * promise, and awaiting either yields the result. That is what lets the migration
- * CLI take one code path instead of branching on a difference it cannot detect
- * from the object's shape.
+ * `.dump` is `pg_dump`'s custom format, which `pg_restore` reads selectively and
+ * in parallel; `.sql` is plain text, restored by piping it through `psql`. The
+ * extension decides so the two commands cannot disagree about the file.
  *
- * @param driver Either driver flavor.
- * @returns An async driver delegating to it.
+ * @param file The backup file's path.
+ * @returns Which format it is.
  */
-declare function toAsyncDriver(driver: SyncDriver | AsyncDriver): AsyncDriver;
+declare function backupFormat(file: string): "custom" | "plain";
 /**
- * Create a **synchronous** engine from a database URL. SQLite only — PostgreSQL
- * has no sane synchronous driver in Node, so a Postgres URL throws, pointing at
- * the async `createEngine`.
+ * The connection URL with the driver suffix removed.
  *
- * @param url A SQLite URL, e.g. `"sqlite:///app.db"` or `"sqlite://:memory:"`.
- * @param options Engine options.
- * @returns A `SyncEngine`.
+ * `postgresql+asyncpg://…` is a URL a Python service wrote; `pg_dump` does not
+ * know that scheme.
+ *
+ * @param url The URL as configured.
+ * @returns The URL a client tool accepts.
  */
-declare function createSyncEngine(url: string, options?: EngineOptions): SyncEngine;
+declare function toolUrl(url: string): string;
 /**
- * Create an **asynchronous** engine from a database URL (the default). Works for
- * both SQLite (sync driver wrapped as async) and PostgreSQL (postgres.js,
- * lazy-loaded).
+ * Write a backup of the database to a file.
  *
- * @param url A database URL, e.g. `"postgresql://app@localhost/app"` or
- *   `"sqlite:///app.db"`.
- * @param options Engine options.
- * @returns An `AsyncEngine`.
+ * @param url The database URL.
+ * @param file Where to write. On PostgreSQL the extension picks the format
+ *   (`.sql` plain, anything else custom).
+ * @param options Extra arguments for the underlying tool.
+ * @returns What was done.
+ * @throws BackupToolMissing When PostgreSQL's client tools are absent.
+ * @throws UnsupportedBackupBackend On a dialect without a backup path.
  */
-declare function createEngine(url: string, options?: EngineOptions): AsyncEngine;
+declare function backupDatabase(url: string, file: string, options?: BackupOptions): Promise<BackupResult>;
+/**
+ * Restore a database from a backup file.
+ *
+ * @param url The database URL to restore **into**.
+ * @param file The backup file.
+ * @param options `force` to overwrite an existing SQLite file; extra tool args.
+ * @returns What was done.
+ * @throws Error When restoring SQLite over an existing file without `force`.
+ * @throws BackupToolMissing When PostgreSQL's client tools are absent.
+ * @throws UnsupportedBackupBackend On a dialect without a restore path.
+ */
+declare function restoreDatabase(url: string, file: string, options?: BackupOptions): Promise<BackupResult>;
 
 /**
- * tempest-db-js — Phase 7: typed repository + pagination.
+ * tempest-db-js — table aliases outside the join builder.
  *
- * `BaseRepository<Model>` mirrors the `tempest-fastapi-sdk` repository: a thin,
- * fully-typed CRUD + pagination layer over a model and an async session. The
- * 404-convention is honored — `getById` throws when absent, collection methods
- * return `[]` (never a "not found" error for an empty list).
+ * `join(Model, "a")` has always taken an alias, so a self-join works there. A
+ * plain `select()` had no way to name its table, which is what a correlated
+ * subquery over the **same** table needs: without an alias, the inner and outer
+ * `users` are the same name, and the correlation cannot be written at all.
  */
 
-/** Pagination request — 1-indexed page. */
-interface PaginationFilter<Row> {
-    readonly page?: number;
-    readonly pageSize?: number;
-    readonly orderBy?: keyof Row & string;
-    readonly ascending?: boolean;
-    readonly filters?: WhereInput<Row>;
-}
-/** A page of results plus metadata (mirrors `BasePaginationSchema`). */
-interface PaginationResult<Row> {
-    readonly items: Row[];
-    readonly total: number;
-    readonly page: number;
-    readonly pageSize: number;
-    readonly pages: number;
-}
-/** Raised by single-record lookups (`getById`) when nothing matches (404). */
-declare class RecordNotFound extends Error {
-    constructor(table: string, id: unknown);
-}
 /**
- * A fully-typed CRUD + pagination repository over a model and an async session.
+ * The same model, reading from an alias.
  *
- * @typeParam C - the model class.
+ * The result is a real model class — same columns, same naming strategy, same
+ * codecs — whose `tablename` is the alias. Everything that already takes a model
+ * takes this: `select`, `join`, `col("alias.column")`, row coercion.
+ *
+ * Table constraints are **not** carried over: an alias is a way to read a table,
+ * not a second declaration of it, and reflecting it into a migration would try to
+ * create a table named after the alias.
+ *
+ * @param model The model to alias.
+ * @param alias The name to read it under.
+ * @returns A model class bound to the alias.
+ *
+ * @example
+ * ```ts
+ * const sub = aliased(User, "sub");
+ * select(User).where(
+ *   exists(select(sub).where({ managerId: col("users.id") })),
+ * );
+ * // WHERE EXISTS (SELECT * FROM "users" AS "sub" WHERE "managerId" = "users"."id")
+ * ```
  */
-declare class BaseRepository<C extends ModelClass> {
-    protected readonly model: C;
-    protected readonly session: AsyncSession;
-    private readonly pk;
-    constructor(model: C, session: AsyncSession);
-    /** All rows matching `filters` (or everything). Empty list when none match. */
-    list(filters?: WhereInput<InferModel<C>>): Promise<InferModel<C>[]>;
-    /** The first row matching `filters`, or `null`. */
-    first(filters?: WhereInput<InferModel<C>>): Promise<InferModel<C> | null>;
-    /** A single row by primary key, or `null`. */
-    getByIdOrNull(id: unknown): Promise<InferModel<C> | null>;
-    /** A single row by primary key; throws `RecordNotFound` when absent. */
-    getById(id: unknown): Promise<InferModel<C>>;
-    /** Whether any row matches `filters`. */
-    exists(filters: WhereInput<InferModel<C>>): Promise<boolean>;
-    /** How many rows match `filters` (or the whole table). */
-    count(filters?: WhereInput<InferModel<C>>): Promise<number>;
-    /** Insert one row, returning the created row. */
-    create(data: InferInsert<C>): Promise<InferModel<C>>;
-    /** Insert many rows, returning the created rows. */
-    createMany(data: readonly InferInsert<C>[]): Promise<InferModel<C>[]>;
-    /** Update rows matching `filters`; returns the number of rows affected. */
-    update(filters: WhereInput<InferModel<C>>, set: Partial<InferModel<C>>): Promise<number>;
-    /** Delete rows matching `filters`; returns the number of rows affected. */
-    delete(filters: WhereInput<InferModel<C>>): Promise<number>;
-    /**
-     * A page of rows plus metadata. `total` counts all matching rows.
-     *
-     * @param filter Page, size, ordering and filters.
-     * @returns The page and pagination metadata.
-     */
-    paginate(filter?: PaginationFilter<InferModel<C>>): Promise<PaginationResult<InferModel<C>>>;
-}
+declare function aliased<C extends ModelClass>(model: C, alias: string): C;
+/**
+ * The model an alias was made from, or `null` when it is not an alias.
+ *
+ * @param model Any model class.
+ * @returns The underlying model, or `null`.
+ */
+declare function aliasOf(model: ModelClass): ModelClass | null;
 
 /**
  * tempest-db-js — opt-in active-record layer.
@@ -1752,11 +4079,16 @@ declare class ActiveRecord<C extends ModelClass> {
     private readonly session;
     /** The current field values (a plain, typed row). */
     data: InferModel<C>;
-    private readonly pk;
+    private readonly pks;
     constructor(model: C, session: AsyncSession, 
     /** The current field values (a plain, typed row). */
     data: InferModel<C>);
-    /** The primary-key value of the wrapped row. */
+    /**
+     * The primary-key values of the wrapped row, as an object.
+     *
+     * Composite keys are the reason this is an object and not a value: identifying
+     * the row by one column of a two-column key hits the wrong row.
+     */
     private pkValue;
     private pkFilter;
     /**
@@ -1878,6 +4210,7 @@ declare function loadRelations<Row extends Record<string, unknown>, Spec extends
  *
  * This is a SPIKE, not the final API. It validates the type machinery only.
  */
+
 /** Phantom marker carrying the static TS type a column maps to. */
 declare const TYPE: unique symbol;
 /** Column flags that influence the inferred row/insert shape. */
@@ -1931,6 +4264,10 @@ type PortableExpression = "now" | "current_date" | "current_time" | "uuidv4" | {
     readonly raw: string;
 } | {
     readonly parts: readonly string[];
+}
+/** The incoming value of a column, inside an upsert's `DO UPDATE` clause. */
+ | {
+    readonly excluded: string;
 };
 /**
  * A column default. Either a constant literal value or a server-side expression
@@ -1966,6 +4303,18 @@ interface SqlExpression {
     /** Parameters bound into the fragment's gaps, in order (empty for a token). */
     readonly params: readonly unknown[];
 }
+/**
+ * Turn a stored column default (or `onUpdate` value) into something the write
+ * path can render.
+ *
+ * A default is kept as a {@link DefaultValue} — the shape the migration IR wants
+ * — while `set()` and `values()` want either a bindable value or a branded
+ * {@link SqlExpression}. This is the one conversion between the two.
+ *
+ * @param value The stored default.
+ * @returns A literal to bind, or a branded expression to render inline.
+ */
+declare function defaultAsWriteValue(value: DefaultValue): unknown;
 /**
  * Runtime guard: is this value a branded {@link SqlExpression}?
  *
@@ -1988,6 +4337,18 @@ declare const sql: {
     readonly currentTime: () => SqlExpression;
     /** A freshly generated UUID v4 (`gen_random_uuid()` / portable fallback). */
     readonly uuidv4: () => SqlExpression;
+    /**
+     * The **incoming** value of a column, valid only inside an upsert's
+     * `onConflictDoUpdate` patch.
+     *
+     * A multi-row upsert cannot spell the new value as a literal — each row has its
+     * own — so the assignment has to name the row being inserted:
+     * `EXCLUDED."total"` on PostgreSQL and SQLite, `VALUES(total)` on MySQL.
+     *
+     * @param column The column's property name.
+     * @returns The expression, for use as a write value.
+     */
+    readonly excluded: (column: string) => SqlExpression;
     /**
      * Escape hatch: a verbatim SQL expression rendered as-is, with no parameters.
      *
@@ -2055,6 +4416,8 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly reference: ForeignKeyRef | null;
     /** An explicit database column name overriding the property name, or `null`. */
     readonly dbName: string | null;
+    /** Conversion to and from the stored representation, or `null` for none. */
+    readonly codec: ColumnCodec | null;
     /** Phantom: never read at runtime, only inspected by the type system. */
     readonly [TYPE]: T;
     constructor(type: ColumnType, flags: F, 
@@ -2065,7 +4428,9 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     /** The foreign-key reference this column points to, or `null` for none. */
     reference?: ForeignKeyRef | null, 
     /** An explicit database column name overriding the property name, or `null`. */
-    dbName?: string | null);
+    dbName?: string | null, 
+    /** Conversion to and from the stored representation, or `null` for none. */
+    codec?: ColumnCodec | null);
     /** Clone this column with one facet replaced, carrying every other over. */
     private derive;
     primaryKey(): Column<T, F & {
@@ -2138,6 +4503,60 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
      */
     onUpdate(value: T | DefaultValue): Column<T, F>;
 }
+/**
+ * Conversion between a domain value and what the database stores.
+ *
+ * The pair is applied on **both** paths — writes and reads — plus on a `where`
+ * operand, so a custom-typed column cannot be compared against the wrong shape by
+ * accident.
+ */
+interface ColumnCodec {
+    /** Domain value → stored value. */
+    readonly toDb: (value: unknown) => unknown;
+    /** Stored value → domain value. */
+    readonly fromDb: (value: unknown) => unknown;
+}
+/**
+ * Declare a column type of your own, over one this package already has.
+ *
+ * Money as integer cents, a `Temporal.Instant`, a branded id, a value object —
+ * the conversion belongs to the column, not to every call site that forgets it.
+ * The DDL and the migration IR keep using the **base** type, so a custom type is
+ * invisible to the schema and cannot cause drift.
+ *
+ * @param spec `base` is a factory for the underlying column; `toDb`/`fromDb`
+ *   convert. `base` is a factory, not a column, because each declaration needs
+ *   its own instance.
+ * @returns A factory producing columns of the custom type.
+ *
+ * @example
+ * ```ts
+ * const money = customType<Money, bigint>({
+ *   base: () => column.bigInteger(),
+ *   toDb: (m) => m.cents,
+ *   fromDb: (cents) => Money.fromCents(cents),
+ * });
+ *
+ * class Order extends Model {
+ *   total = money().notNull();
+ * }
+ * ```
+ */
+declare function customType<Domain, Stored>(spec: {
+    base: () => Column<Stored, ColumnFlags>;
+    toDb: (value: Domain) => Stored;
+    fromDb: (value: Stored) => Domain;
+}): () => Column<Domain, ColumnFlags>;
+/**
+ * The codecs a model declares, by property name.
+ *
+ * `null` when the model has no custom type, which is the common case — the write
+ * and read paths skip the whole conversion step on that answer.
+ *
+ * @param model The model class.
+ * @returns The codec map, or `null`.
+ */
+declare function codecsOf(model: ModelClass): Record<string, ColumnCodec> | null;
 /**
  * Column factory mirroring SQLAlchemy's typed column constructors. Each entry
  * pairs a distinct SQL type with the TypeScript type it maps to.
@@ -2233,6 +4652,21 @@ type TableConstraint = {
     readonly kind: "unique";
     readonly name?: string | undefined;
     readonly columns: readonly string[];
+} | {
+    readonly kind: "check";
+    readonly name?: string | undefined;
+    /** The invariant, in the same condition language `where` uses. */
+    readonly expression: CondNode;
+    /** Columns the expression mentions, for the generated name. */
+    readonly columns: readonly string[];
+} | {
+    readonly kind: "index";
+    readonly name?: string | undefined;
+    readonly columns: readonly string[];
+    /** A unique index rather than a plain one. */
+    readonly unique?: boolean | undefined;
+    /** The predicate of a **partial** index, or `undefined` for a full one. */
+    readonly where?: CondNode | undefined;
 } | {
     readonly kind: "foreignKey";
     readonly name?: string | undefined;
@@ -2262,6 +4696,55 @@ declare function unique(...columns: string[]): TableConstraint;
  * @returns A foreign-key {@link TableConstraint}.
  * @throws Error When the column arrays are empty or mismatched in length.
  */
+/**
+ * Declare a `CHECK` constraint — an invariant the **database** enforces.
+ *
+ * The expression uses the same condition language as `where`, not a raw string:
+ * a string would have to be compared textually to decide whether the schema
+ * drifted, and two spellings of the same rule would read as a change.
+ *
+ * @param expression The invariant, e.g. `col("total").gte(0)`.
+ * @param options `name` to pin the constraint's name; `columns` to name the
+ *   generated one after something other than the expression's own columns.
+ * @returns A check {@link TableConstraint}.
+ *
+ * @example
+ * ```ts
+ * class Order extends Model {
+ *   static override tableArgs = () => [check(col("total").gte(0))];
+ * }
+ * ```
+ */
+declare function check(expression: Condition | Record<string, unknown>, options?: {
+    name?: string;
+    columns?: readonly string[];
+}): TableConstraint;
+/**
+ * Declare an index.
+ *
+ * An index the model does not declare is invisible to migrations: it never gets
+ * created, and a table rebuild on SQLite drops it. Declaring it puts it in the
+ * same place as the columns it covers.
+ *
+ * @param columns The indexed columns, in order.
+ * @param options `unique` for a unique index, `where` for a **partial** one, and
+ *   `name` to pin the name.
+ * @returns An index {@link TableConstraint}.
+ * @throws Error When no column is given.
+ *
+ * @example
+ * ```ts
+ * static override tableArgs = () => [
+ *   index(["customerId", "createdAt"]),
+ *   index(["email"], { unique: true, where: { deletedAt: { isNull: true } } }),
+ * ];
+ * ```
+ */
+declare function index(columns: readonly string[], options?: {
+    name?: string;
+    unique?: boolean;
+    where?: Condition | Record<string, unknown>;
+}): TableConstraint;
 declare function foreignKey(columns: string[], refTable: string, refColumns: string[], options?: {
     name?: string;
     onDelete?: FkAction;
@@ -2333,6 +4816,32 @@ declare function columnNamesOf(model: ModelClass): NameMap | null;
 declare function columnPropsOf(model: ModelClass): NameMap | null;
 /** Resolve one property name to its database column name. */
 declare function dbColumn(names: NameMap | null | undefined, prop: string): string;
+/**
+ * Every primary-key column of a model, in declaration order.
+ *
+ * A composite key is a list of more than one name — which is why this returns an
+ * array and not a single name. Reading only the first entry is how a repository
+ * ends up filtering half a key and touching the wrong row.
+ *
+ * @param model The model class.
+ * @returns The primary-key column names (property names, not database names).
+ * @throws Error When the model declares no primary key.
+ */
+declare function primaryKeysOf(model: ModelClass): string[];
+/**
+ * Turn a primary-key argument into the filter that identifies exactly one row.
+ *
+ * A single-column key takes the bare value (or an object carrying it); a
+ * composite key **requires** the object, because a scalar cannot say which of the
+ * key columns it is. Passing a scalar for a composite key throws instead of
+ * silently matching on one column.
+ *
+ * @param model The model class.
+ * @param id The key: a scalar, or an object with every key column.
+ * @returns A filter object covering the whole key.
+ * @throws Error When the key is incomplete, or a scalar was given for a composite key.
+ */
+declare function primaryKeyFilter(model: ModelClass, id: unknown): Record<string, unknown>;
 /** Pull the static type out of a Column. */
 type ColType<C> = C extends Column<infer T, infer _F> ? T : never;
 /** Keys of the model instance whose values are Columns. */
@@ -2396,4 +4905,4 @@ type InferInsert<C extends ModelClass> = Simplify<{
     [K in Exclude<ColumnKeys<InstanceType<C>>, OptionalInsertKeys<InstanceType<C>>>]: ColValue<InstanceType<C>[K]>;
 }>;
 
-export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type ExprNode, Expression, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, type LockClause, type LockOptions, Model, type ModelClass, MysqlDialect, type NameMap, type NamingStrategy, NoResultError, NodeSqliteDriver, type NoticeLogger, OPERATORS, type OnConflict, type OnConflictOptions, type OnConflictUpdateOptions, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, Params, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, type SqlExpression, SqliteDialect, type Subquery, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val };
+export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, type AuditAction, type AuditDiff, type AuditEntry, type AuditOptions, type BackupOptions, type BackupResult, BackupToolMissing, BaseDialect, BaseRepository, type BelongsTo, BetterSqliteDriver, type BulkUpsertOptions, type CastType, type ChangesPage, type ChangesSinceFilter, type ClaimOptions, type ColRef, type ColType, Column, type ColumnCodec, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type ContainsOptions, Cte, type CteBody, type CteNode, type CteOptions, type CursorPage, type CursorPaginationFilter, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type ExplainOptions, type ExplainReport, type ExprNode, Expression, type FailOptions, type FkAction, type FlushResult, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, type IntegrityFailure, type IntegrityViolation, InvalidCursor, InvalidDatabaseUrl, type IsolationLevel, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, type LockClause, type LockOptions, Model, type ModelBase, type ModelClass, MysqlDialect, type NameMap, type NamingStrategy, NoResultError, NodeSqliteDriver, type NoticeLogger, OPERATORS, type OnConflict, type OnConflictOptions, type OnConflictUpdateOptions, type Operator, type OperatorsFor, type OrderTerm, type OutboxEventInput, OutboxRepository, type OutboxStatus, type PaginationFilter, type PaginationResult, Params, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, type QueryEndEvent, type QueryEndLogger, QueryExecutionError, type QueryHooks, type QueryLogger, type QueryNode, type QueryPlan, RecordNotFound, type Relation, type RelationValue, type RepositorySignal, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, SetBuilder, type SetNode, type SetOperator, type SignalHandler, type SignalPayload, type SortDirection, type Sources, type SqlExpression, SqliteDialect, type SqliteJournalMode, type SqliteOptions, type SqliteSynchronous, type Subquery, type SubqueryLike, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, type TenantScope, TenantScopedRepository, type TextSearchLanguage, type TextSearchOptions, type Tracked, type TransactionOptions, UnitOfWork, UnsupportedBackupBackend, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WindowFn, type WindowSpec, type WithRelations, type WritePatch, type WriteValues, activeRecord, aliasOf, aliased, and, attach as attachCte, auditLogModel, avg, backupDatabase, backupFormat, belongsTo, caseWhen, cast, check, clearSignals, codecsOf, col, column, columnNamesOf, columnPropsOf, columnsOf, contains, count, createEngine, createSyncEngine, cte, cteRecursive, customType, dbColumn, decodeValue as decodeColumnValue, defaultAsWriteValue, del, denseRank, detectDialect, diffSnapshots, emitSignal, enableAudit, encodeValue as encodeColumnValue, escapeLike, except, exists, firstValue, fn, foreignKey, fromDict, fullText, fullTextRank, getDialect, hasHandlers, hasMany, index, insert, intersect, isCondition, isExpression, isReadOnlyStatement, isSqlExpression, isSubquery, join, lag, lastValue, lead, loadRelations, max, min, not, notDeleted, notExists, onSignal, onlyDeleted, or, outboxModel, over, parse, parseDatabaseUrl, parseIntegrityError, percentRank, primaryKeyFilter, primaryKeysOf, rank, restoreDatabase, rowNumber, scalar, select, snapshot, sql, stringify, sum, summarizePlan, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, tokenize, toolUrl, union, unionAll, unique, update, val, withAudit, withSoftDelete, withTimestamps };