@vibeorm/sql 4.1.0 → 4.3.0

package/dist/ast.d.ts

@@ -10,7 +10,7 @@ import type { RlsReadinessQuery } from "./dialects/postgres-rls-readiness.ts";
  * grows with the runtime in P2/P3. Every shape added here needs a catalog case
  * (tests/catalog/cases.ts) in the same change.
  */
-import type { AdvisoryLockMode, RlsContextIR, RowLockStrength, RowLockWaitPolicy, SchemaIR, SqlFragmentSpec } from "@vibeorm/schema";
+import type { AdvisoryLockMode, RlsContextIR, RowLockStrength, RowLockWaitPolicy, ScalarType, SchemaIR, SqlFragmentSpec } from "@vibeorm/schema";
 /** A column reference, optionally table-qualified. */
 export type ColRef = {
     readonly table?: string;
@@ -88,6 +88,33 @@ export type AggSelect = {
  */
 export type JsonFilterOp = "equals" | "string_contains" | "string_starts_with" | "string_ends_with" | "array_contains" | "array_starts_with" | "array_ends_with";
 export type ComparisonOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+/**
+ * The column facts one member of a {@link SqlExpr} `keyList` tuple needs to
+ * bind exactly like the equality `"col" = $n` would. Postgres binds each
+ * member as ONE typed array (`$n::<element type>[]`), so it needs the
+ * column's element type: the declared native type without its modifier
+ * (`timestamptz`, never `timestamptz(3)` — a typmod cast would round
+ * `.1234` onto a stored `.123` that `=` does not match), `bpchar` for
+ * `char(n)`, `citext`, the enum's own type. MySQL needs to know a time-of-day
+ * member (`SqlDialect.timeOfDayInStrategy`); SQLite needs nothing.
+ */
+export type KeyListMember = {
+    /** The column's scalar type; `"Enum"` for an enum column. */
+    readonly type: ScalarType | "Enum";
+    /** The declared `@db.*` native type, verbatim (`VarChar(191)`, `Uuid`, `Timestamptz(3)`). */
+    readonly nativeType?: string;
+    /**
+     * A database-stored (native) enum's type: `namespace` qualifies it, absence
+     * resolves it through the search path like the statement's table. Absent on
+     * a string-stored enum, whose column is text.
+     */
+    readonly enumType?: {
+        readonly namespace?: string;
+        readonly name: string;
+    };
+    /** A time-of-day column (`@db.Time(n)` / `@db.Timetz(n)`). */
+    readonly timeOfDay?: boolean;
+};
 export type SqlExpr = {
     readonly kind: "composed";
     readonly fragment: SqlFragment;
@@ -133,6 +160,68 @@ export type SqlExpr = {
     /** Candidate tuples — every row carries exactly `columns.length` values. */
     readonly rows: readonly (readonly unknown[])[];
     readonly negate?: boolean;
+}
+/**
+ * KEY-LIST membership — the public `where: { IN: [{ a, b }, …] }` filter:
+ * rows whose ordered tuple of column values equals one of `rows`, with
+ * semi-join semantics (a repeated tuple never repeats a result row). Renders
+ * per `SqlDialect.keyListStrategy`: postgres binds one typed ARRAY per
+ * member, `("a", "b") IN (SELECT * FROM unnest($1::int8[], $2::text[]))`,
+ * so the text and the planning cost stay constant however long the list is
+ * (an OR of 1 000 conjunctions planned in 114 ms on PGlite, 2 ms on
+ * postgres 18; the unnest form in 0.1–0.2 ms on both). A `DateTime` member
+ * without a declared native type switches postgres to the row-constructor
+ * list of untyped parameters (`keyListBindsUntypedRows`: the column may be a
+ * zone-less `timestamp`). MySQL renders the row-constructor list, SQLite
+ * `IN (VALUES …)`. Each member compares under the column's own type and
+ * collation, exactly like `"col" = $n`.
+ *
+ * An empty `rows` renders `1 = 0` (matches nothing, like an empty
+ * `inArray`). The runtime emits arity 1 as `inArray` instead, so a
+ * one-field key list keeps the scalar `in` SQL.
+ */
+ | {
+    readonly kind: "keyList";
+    /** Ordered tuple columns (compare references); `rows[i][j]` binds to `columns[j]`. */
+    readonly columns: readonly ColRef[];
+    /** How each member binds, in column order — see {@link KeyListMember}. */
+    readonly members: readonly KeyListMember[];
+    /** Encoded candidate tuples, each exactly `columns.length` long; may repeat. */
+    readonly rows: readonly (readonly unknown[])[];
+}
+/**
+ * ROW-VALUE comparison: `("a", "b") > ($1, $2)` — the keyset seek (D-01).
+ * SQL compares row values left to right, each pair with that column's own
+ * operator, affinity and collation, which is exactly the OR expansion
+ * `"a" > $1 OR ("a" = $2 AND "b" > $3)` when no member is NULL — and an
+ * index on `(a, b)` bounds it as one range (PostgreSQL `Index Cond: ROW(…) >
+ * ROW(…)`, SQLite `SEARCH … (a>?)`). A NULL member makes the comparison
+ * UNKNOWN as soon as the scan reaches it, so the runtime emits it only over
+ * non-null keys and values. Renders on every dialect (each has row
+ * constructors); whether the runtime emits it is
+ * `SqlDialect.keysetSeekStrategy`.
+ */
+ | {
+    readonly kind: "rowCompare";
+    readonly op: "gt" | "gte" | "lt" | "lte";
+    /** Ordered row members (compare references); `values[i]` binds to `columns[i]`. */
+    readonly columns: readonly ColRef[];
+    /** Encoded values, exactly `columns.length` of them. */
+    readonly values: readonly unknown[];
+}
+/**
+ * SUBQUERY membership: `"id" IN (SELECT …)`, or the row-value form
+ * `("a", "b") IN (SELECT …)` for a composite key — the key-first `distinct`
+ * page on PostgreSQL (D-04). The subquery projects exactly `columns.length`
+ * columns and shares the statement's parameter sequence. MySQL refuses a
+ * `LIMIT` directly inside an `IN` subquery (error 1235), so the renderer
+ * refuses that pair there with `VIBE_UNSUPPORTED_CAPABILITY`.
+ */
+ | {
+    readonly kind: "inSelect";
+    /** The tested columns, in the subquery's projection order. */
+    readonly columns: readonly ColRef[];
+    readonly select: SelectStatement;
 } | {
     readonly kind: "like";
     readonly column: ColRef;
@@ -435,6 +524,37 @@ export type InnerJoin = {
         readonly right: ColRef;
     }[];
 };
+/**
+ * One `LEFT JOIN (<select>) AS "alias" ON "alias"."k" = "outer"."c" [AND …]`
+ * clause — portable, equality ON pairs only. Built for the to-one relation
+ * `orderBy` (`orderBy: { author: { email: "asc" } }`): the target's key and
+ * sort columns ride a derived table under RESERVED aliases (`__vibe_ok0`,
+ * `__vibe_ov0`), so the outer statement's unqualified column names can never
+ * become ambiguous, and the outer ORDER BY names `"alias"."__vibe_ov0"`.
+ * Every engine merges such a derived table into a plain join (measured:
+ * postgres pulls it up into a hash/nested-loop left join, sqlite flattens it,
+ * mysql merges it), so the planner may hash-join instead of evaluating a
+ * correlated subquery per candidate row.
+ *
+ * The builder emits it only for links that match AT MOST ONE target row, so
+ * the join keeps the parent row count. The derived select must alias every
+ * projected column; its parameters (none today) join the statement's single
+ * sequence where the clause renders (after `keyTable`, before
+ * `lateralJoins`). A statement with a `rowLock` refuses it: postgres rejects
+ * FOR UPDATE on the nullable side of an outer join, and mysql would lock the
+ * joined rows too.
+ */
+export type LeftJoin = {
+    /** Derived-table alias (`__ord1`). */
+    readonly alias: string;
+    /** The derived table — every projected column carries an `alias`. */
+    readonly select: SelectStatement;
+    /** Equality pairs ANDed into the ON clause; never empty. */
+    readonly on: readonly {
+        readonly left: ColRef;
+        readonly right: ColRef;
+    }[];
+};
 /**
  * How one member of a {@link KeyTableJoin} tuple binds inside the derived
  * table. `value` binds the parameter as it is: it stays COERCIBLE, so a text
@@ -523,6 +643,57 @@ export type RowNumberProjection = {
     readonly orderBy: readonly OrderTerm[];
     readonly alias: string;
 };
+/**
+ * A PER-KEY PAGE of one child table as a derived-table FROM
+ * (`SelectStatement.keyPage`): for every listed key tuple, the child rows
+ * whose key columns equal it, ordered by `select.orderBy` and cut by
+ * `select.limit`/`select.offset` — each key's OWN page, plus a rank column
+ * (`rankAlias`) that orders the rows inside their key. The paged include's
+ * `ROW_NUMBER() OVER (PARTITION BY key …)` window returns the same rows but
+ * numbers EVERY child of every listed key first; this form reads one page of
+ * primary keys per key through an index on (key columns, order columns),
+ * then each page row once by its primary key.
+ *
+ * Rendered per `SqlDialect.keyPageStrategy`:
+ * - `lateral` (postgres): `unnest($1::<type>[], …) AS "__vibe_keys"
+ *   ("__vibe_k0", …) CROSS JOIN LATERAL (SELECT <identity>, ROW_NUMBER() OVER
+ *   (PARTITION BY <key> ORDER BY <order>) AS <rank> FROM <table> WHERE <key> =
+ *   "__vibe_keys"."__vibe_k<i>" … ORDER BY <order> LIMIT … OFFSET …) AS
+ *   "__vibe_ids" INNER JOIN <table> AS "__vibe_page" ON <identity> pairs`.
+ * - `inLimit` (sqlite, which has no LATERAL): the key tuples as `(VALUES …)`
+ *   (columns `column1`, `column2`, …, as SQLite names a VALUES clause's
+ *   columns) joined to `<table> AS "__vibe_page"` ON `(<identity>) IN (SELECT
+ *   <identity> … WHERE <key> = "__vibe_keys"."column<i>" … ORDER BY … LIMIT …)`,
+ *   the rank re-derived over the fetched page (`ROW_NUMBER() OVER (PARTITION
+ *   BY <key> ORDER BY <order>)`): its values differ from the window's, its
+ *   order inside a key does not.
+ * - `window` (mysql): refused with `VIBE_UNSUPPORTED_CAPABILITY` — measured
+ *   no gain there; the runtime keeps the window.
+ *
+ * The caller guarantees what makes the page equal to the window's: the order
+ * is total inside a key (the identity columns are among the key and order
+ * columns), the key tuples are distinct and compare exactly (no folding
+ * collation). Members bind like the key-list filter's (`KeyListMember`).
+ */
+export type KeyPage = {
+    /** How each key member binds, in member order (postgres: one typed array each). */
+    readonly members: readonly KeyListMember[];
+    /** Encoded, distinct key tuples; never empty, each `members.length` long. */
+    readonly rows: readonly (readonly unknown[])[];
+    /** The child columns each key member equals, in member order (unqualified). */
+    readonly keyColumns: readonly ColRef[];
+    /** The child's primary-key columns (unqualified) — each page row is read once by them. */
+    readonly identity: readonly ColRef[];
+    /**
+     * ONE key's page: the child `table` (no alias), the projected `columns`
+     * (unqualified; transforms and aliases render as usual), an optional extra
+     * `where`, the non-empty `orderBy` (plain column terms), `limit`/`offset`.
+     * Any other member is refused.
+     */
+    readonly select: SelectStatement;
+    /** Output name of the rank column. */
+    readonly rankAlias: string;
+};
 export type SelectStatement = {
     readonly kind: "select";
     readonly table: TableRef;
@@ -548,6 +719,14 @@ export type SelectStatement = {
      * guarantees that arrangement.
      */
     readonly distinctOn?: readonly ColRef[];
+    /**
+     * Plain `SELECT DISTINCT` over the whole projection — every dialect. The
+     * query builder sets it only where it returns exactly the rows its
+     * `ROW_NUMBER()` distinct emulation would (sqlite/mysql, value-exact keys,
+     * projection equal to the distinct fields); never together with
+     * `distinctOn` (the renderer refuses the pair).
+     */
+    readonly distinct?: true;
     /**
      * Derived-table FROM: renders `FROM (<fromSelect>) AS "<table.name>"` —
      * `table.name` is the subquery ALIAS and `table.alias` must be unset. Used
@@ -560,8 +739,29 @@ export type SelectStatement = {
     readonly innerJoins?: readonly InnerJoin[];
     /** Key-table join, rendered after `innerJoins` — mysql only, see {@link KeyTableJoin}. */
     readonly keyTable?: KeyTableJoin;
+    /** Fix lane Q2 (D-03): derived-table LEFT JOINs, rendered after `keyTable` — see {@link LeftJoin}. */
+    readonly leftJoins?: readonly LeftJoin[];
     /** ROW_NUMBER window projection — see {@link RowNumberProjection}. */
     readonly rowNumber?: RowNumberProjection;
+    /**
+     * Fix lane Q1 (DB-01): derived-table FROM over a per-key page — renders
+     * `FROM (<per-key page>) AS "<table.name>"` like `fromSelect` (and never
+     * together with it); see {@link KeyPage}.
+     */
+    readonly keyPage?: KeyPage;
+    /**
+     * Fix lane Q2 (round 3, DB-07): derived-table FROM over a `UNION ALL` of
+     * branch selects — renders `FROM (SELECT * FROM (<branch 0>) AS
+     * "__vibe_u0" UNION ALL SELECT * FROM (<branch 1>) AS "__vibe_u1" …) AS
+     * "<table.name>"`. Each branch keeps its own ORDER BY and LIMIT: wrapped in
+     * its own derived table, a limited branch is valid on all three engines
+     * (SQLite refuses ORDER BY/LIMIT on a bare compound member). At least two
+     * branches; each a plain `SELECT <columns> FROM <table> [WHERE] [ORDER BY]
+     * [LIMIT]` projecting the same output names in the same order; never
+     * together with `fromSelect`, `keyPage` or a `table.alias`. Parameters bind
+     * branch by branch, in text order.
+     */
+    readonly fromUnion?: readonly SelectStatement[];
     readonly where?: SqlExpr;
     readonly groupBy?: readonly ColRef[];
     /** HAVING predicate — grouped selects; may contain `aggCmp` expressions. */
@@ -674,6 +874,26 @@ export type InsertStatement = {
     readonly onConflict?: OnConflictClause;
     /** Rendered as RETURNING where the dialect supports it, else omitted+flagged. */
     readonly returning?: readonly ReturningColumn[];
+    /**
+     * Bind the rows as ONE typed array per column instead of one parameter per
+     * value (`SqlDialect.bulkInsertForm` `"unnest"`, postgres): `INSERT INTO t
+     * ("a", "b") SELECT "c1", "c2" FROM unnest($1::text[], $2::int4[]) WITH
+     * ORDINALITY AS "__vibe_rows" ("c1", "c2", "ord") ORDER BY "ord"`. The text
+     * is the same for 2 rows and for 3 000, and the statement binds one parameter
+     * per column. `ORDER BY "ord"` keeps input order (sequence values, the
+     * `ON CONFLICT DO NOTHING` winner).
+     *
+     * One entry per column, in `columns` order: the column's DECLARED type facts
+     * (see {@link KeyListMember}; a `Json` entry names its storage through
+     * `nativeType`). Each array binds the BASE type (`varchar`, never
+     * `varchar(191)` — an explicit modifier cast truncates silently), so the
+     * INSERT's own assignment applies the column's length and precision exactly
+     * as it does for a VALUES parameter. `rows` stays row-major: the renderer
+     * transposes it. Every cell is a plain value, SQL NULL or a
+     * {@link JsonParamCell} — never `DEFAULT` or the database clock (the query
+     * builder keeps VALUES for those; the renderer refuses them).
+     */
+    readonly unnest?: readonly KeyListMember[];
 };
 /** Conflicting rows are updated with these column values. */
 export type OnConflictUpdate = {

package/dist/codecs.d.ts

@@ -122,6 +122,8 @@ export declare function parseDateTimeText(params: {
 export declare function timeOfDayCodec(params: {
     nativeType: string | undefined;
 }): ScalarCodec | undefined;
+/** Canonical calendar-day text only; a driver Date cannot recover the authored day. */
+export declare const localDateCodec: ScalarCodec;
 /**
  * Parse stored JSON text at the centralized codec boundary. A supplied context
  * marks a bound field: its error contains only that context, never the document

package/dist/dialect.d.ts

@@ -93,6 +93,19 @@ export type ConflictKeyEquality = {
      */
     readonly duplicatesInOneStatement: "reject" | "lastWriteWins";
 };
+/**
+ * How an INSERT that names no column renders, when every value is its column
+ * default. `defaultValues`: `INSERT INTO t DEFAULT VALUES`, exactly one row per
+ * statement; `conflictClause` says whether a conflict clause may follow it
+ * (postgres: yes; sqlite's grammar has no upsert clause after DEFAULT VALUES).
+ * `emptyRow`: `INSERT INTO t () VALUES ()`, any number of rows (mysql).
+ */
+export type EmptyInsertSyntax = {
+    readonly form: "defaultValues";
+    readonly conflictClause: boolean;
+} | {
+    readonly form: "emptyRow";
+};
 export type SqlDialect = {
     readonly name: Dialect;
     /** Frozen feature table — consumed by runtime, migrate, generator, tests. */
@@ -108,10 +121,101 @@ export type SqlDialect = {
      * member, so composite membership always chunks against `paramBudget`.
      */
     readonly tupleInStrategy: "rowValue" | "expand";
+    /**
+     * Key-list membership (`SqlExpr` `keyList`, the public `where: { IN }`).
+     * `unnest` binds ONE typed array per member — `("a", "b") IN (SELECT * FROM
+     * unnest($1::int8[], $2::text[]))` — so the text and its planning cost do
+     * not grow with the list (postgres 18.6, 1 000 two-column keys: planning
+     * 0.09 ms against 2.0 ms for the OR of conjunctions; 5 000 keys: 0.09 ms
+     * against 12.6 ms, and 10 ms against 285 ms execution). `rowValue` renders
+     * the row-constructor list `(a, b) IN ((?, ?), …)` (mysql: 3.9 ms for 1 000
+     * keys through an index range scan, equal to a VALUES derived table and
+     * without its numeric casts; every probed type compared exactly like `=`).
+     * `values` renders `("a", "b") IN (VALUES (?, ?), …)` (sqlite 3.51: 0.9 ms
+     * prepare + run for 1 000 keys against 1.9 ms for the row list; an OR of
+     * 1 000 conjunctions is refused there, "Expression tree is too large").
+     * The row forms bind one parameter per member, like scalar `IN (?, …)`.
+     */
+    readonly keyListStrategy: "unnest" | "rowValue" | "values";
+    /**
+     * The keyset seek (`after`, `findPage`, a compound `cursor`, graph pages;
+     * D-01). `rowValue`: where every key sorts in one direction and no key or
+     * position value is NULL, one row-value comparison `("a", "b") > ($1, $2)`
+     * (`SqlExpr` `rowCompare`) that an index on `(a, b)` bounds as a range;
+     * with mixed directions the OR expansion ANDed with the inclusive bound on
+     * the leading key (`"a" >= $1 AND (…)`). Measured: PostgreSQL 18.6 at
+     * 500 000 rows deep 25.4 ms → 0.013 ms, SQLite 3.51 at 490 000 rows 12.9 →
+     * 0.007 ms — the OR alone is a full index walk from the first row. `or`:
+     * the OR expansion alone — MySQL's range optimizer already turns it into
+     * index ranges (22 rows touched at any depth) and SCANS a row-value
+     * inequality (194 ms at 490 000 rows deep). Nullable keys keep the OR on
+     * every dialect.
+     */
+    readonly keysetSeekStrategy: "rowValue" | "or";
+    /**
+     * Fix lane Q1 (round 3, DB-01): how a paged include (`include: { rel: {
+     * orderBy, take, skip } }`) cuts each parent's page when an index proves the
+     * per-key form (`SelectStatement.keyPage`, `KeyPage`). `lateral`: one
+     * primary-key page per key in a `CROSS JOIN LATERAL` over the unnested key
+     * arrays — PostgreSQL 18.6, 1 000 000 children, 50 parents: 59.1 → 1.08 ms
+     * (the window sorted every child of every parent); the key-only page keeps
+     * an index-only scan the planner prefers at every `skip`, where a lateral
+     * fetching whole rows flipped to bitmap + sort and LOST (40 → 64 ms).
+     * `inLimit`: SQLite has no LATERAL — `(VALUES …)` keys joined to the child
+     * by `IN (SELECT key … LIMIT)`, a correlated list subquery per key (SQLite
+     * 3.51, 500 000 children, 50 parents: 75.2 → 0.47 ms). `window`: keep the
+     * `ROW_NUMBER()` window (MySQL: a lateral page still read every child).
+     */
+    readonly keyPageStrategy: "lateral" | "inLimit" | "window";
+    /**
+     * Fix lane Q1 (round 3, DB-03): how a positive relation filter that pins ONE
+     * related row by a unique key renders. `exists`: the correlated `EXISTS` —
+     * PostgreSQL and MySQL turn it into a semi-join. `inSelect`: an uncorrelated
+     * `key IN (SELECT key …)` — SQLite runs a correlated `EXISTS` once per outer
+     * row (`post where author.email = x`: 134 → 0.15 ms, Post 500 000).
+     */
+    readonly relationFilterStrategy: "exists" | "inSelect";
+    /**
+     * DB-02: when a find with a TOTAL order (it ends with the full primary key)
+     * pages with `skip` ≥ `minSkip`, the runtime cuts the page as primary keys
+     * in a derived table (`SELECT pk FROM t WHERE … ORDER BY … LIMIT ? OFFSET ?`)
+     * and joins the rows back by primary key (`fromSelect` + `innerJoins`; MySQL
+     * refuses LIMIT inside `IN (subquery)`). MySQL 26.7 / 8.4 drop the index from
+     * skip ≈ 5 000 and sort the table (500 000 rows, skip 5 000: 116.6 → 1.21 ms;
+     * 100 000: 144 → 9.3 ms) — there it applies under that rule alone.
+     * PostgreSQL gains only when the key page is an index-only scan (`authorId =
+     * 1`, skip 4 000: 4.37 → 0.24 ms) and loses up to 15 % when the filter is not
+     * covered, so `requiresCoveringIndex` asks for one declared index that serves
+     * the filter, the order and the key. `null`: never (SQLite walks an index
+     * plus rowid lookups cheaply — skip 100 000: 1.02 ms).
+     */
+    readonly deferredJoinPage: {
+        readonly minSkip: number;
+        readonly requiresCoveringIndex: boolean;
+    } | null;
+    /**
+     * DB-07: where this engine sorts NULL when ORDER BY names no placement —
+     * `high`: above every value (postgres: last on ASC, first on DESC), `low`:
+     * below (sqlite, mysql: first on ASC, last on DESC). A b-tree stores NULLs in
+     * that position, so only the matching `nulls` placement is index order.
+     */
+    readonly nativeNullsOrder: "high" | "low";
+    /**
+     * DB-07: whether a paged find whose LEADING order key is nullable and asks
+     * for the non-native placement reads through a `UNION ALL` of two
+     * index-ordered branches (`SelectStatement.fromUnion`: the key's non-NULL
+     * rows, then its NULL rows, each limited to `skip + take`), re-ordered and
+     * paged outside. Today's statement sorts the whole table on every page:
+     * PostgreSQL 18 `desc nulls last` 34.8 → 0.075 ms, MySQL 26.7 `asc nulls
+     * last` 54.5 → 0.85 ms. SQLite 3.51 already walks the index for either
+     * placement (0.005 ms today, 0.020 ms as a union) — `false` there.
+     */
+    readonly nullsUnionPage: boolean;
     /**
      * Membership on a time-of-day column (`inArray` with `timeOfDay`): `in`
      * renders like any other membership; `equalities` renders an OR of `=`
-     * comparisons. MySQL 8.4 types a `?` inside a multi-value IN list against a
+     * comparisons (a key list with a time-of-day member: an OR of complete
+     * conjunctions). MySQL 8.4 types a `?` inside a multi-value IN list against a
      * TIME(n) column as TIME(6) and matches nothing unless n is 6 (live on
      * 8.4.11; 26.7 matches); `=` converts the parameter to the column's TIME on
      * every version.
@@ -230,6 +334,19 @@ export type SqlDialect = {
      * rows are grouped by column set into separate statements there (M4).
      */
     readonly rowDefaultKeyword: boolean;
+    /**
+     * How a multi-row INSERT whose rows all bind plain values may render
+     * (`InsertStatement.unnest`). `unnest` binds ONE typed array per column —
+     * `INSERT … SELECT … FROM unnest($1::text[], …) WITH ORDINALITY … ORDER BY`
+     * — so the text is constant and a statement binds one parameter per column
+     * (postgres and PGlite; the type table, efficiency campaign EPIC C, proved
+     * equal stored values and errors on adapter-pg, adapter-bun and PGlite).
+     * `values` keeps one parameter per value (mysql and sqlite have no typed
+     * array parameters); the renderer refuses an `unnest` statement there.
+     */
+    readonly bulkInsertForm: "unnest" | "values";
+    /** How an INSERT that names no column renders ({@link EmptyInsertSyntax}). */
+    readonly emptyInsert: EmptyInsertSyntax;
     /**
      * How a {@link ChainStatement} (an ordered chain of read and data-modifying
      * steps ending in one SELECT — round-trip campaign EPIC 4/F) renders, or

package/dist/dialects/mysql-check-probe.d.ts

@@ -5,6 +5,7 @@ export declare function renderMysqlCheckProbe(params: {
     dialect: SqlDialect;
     operation: "clone" | "add" | "read" | "drop";
     probe: string;
+    /** Source for clone, or qualified live table for a transient SHOW CREATE comparison. */
     table?: {
         readonly namespace: string;
         readonly name: string;

package/dist/dialects/mysql-generated-columns.d.ts

@@ -0,0 +1,43 @@
+import type { QualifiedSqlName } from "@vibeorm/schema";
+import type { SqlDialect } from "../dialect.ts";
+import type { ExtractedGeneratedColumn, GeneratedColumnDeclaration } from "../generated-columns.ts";
+import type { RenderedQuery } from "../render.ts";
+/** MySQL stored syntax, placed after complete type/charset/collation information. */
+export declare function renderMysqlGeneratedColumnClause({ generated }: {
+    readonly generated: GeneratedColumnDeclaration;
+}): string;
+/** Temporary CREATE/DROP operations avoid ALTER's implicit-commit boundary. */
+export type MysqlGeneratedColumnProbe = {
+    readonly operation: "context";
+} | {
+    readonly operation: "clone";
+    readonly probe: string;
+    readonly table: QualifiedSqlName;
+} | {
+    readonly operation: "create";
+    readonly probe: string;
+    readonly definition: string;
+    readonly column: string;
+    readonly columnDefinition: string;
+    readonly backslashEscapes: boolean;
+    readonly after?: string;
+} | {
+    readonly operation: "read";
+    readonly probe: string;
+    readonly table?: QualifiedSqlName;
+} | {
+    readonly operation: "drop";
+    readonly probe: string;
+};
+/** Render scratch SQL from independently provisioned table definitions; migrate owns cleanup. */
+export declare function renderMysqlGeneratedColumnProbe({ dialect, probe }: {
+    readonly dialect: SqlDialect;
+    readonly probe: MysqlGeneratedColumnProbe;
+}): RenderedQuery;
+/** SHOW CREATE's own escaping rules apply; information_schema uses a different spelling channel. */
+export declare function extractMysqlGeneratedColumn({ definition, column, backslashEscapes }: {
+    readonly definition: string;
+    readonly column: string;
+    readonly backslashEscapes: boolean;
+}): ExtractedGeneratedColumn | undefined;
+//# sourceMappingURL=mysql-generated-columns.d.ts.map

package/dist/dialects/mysql-index-expressions.d.ts

@@ -0,0 +1,20 @@
+import type { IndexKeyTermIR } from "@vibeorm/schema";
+import type { SqlDialect } from "../dialect.ts";
+import type { IndexExpressionProbeParams, IndexKeyOperand } from "../index-expressions.ts";
+import type { PredicateModel } from "../predicate.ts";
+import type { RenderedQuery } from "../render.ts";
+/** Qualify only expression-bearing keys through schema's shared width rule; never impose new bounds on ordinary indexes. */
+export declare function assertMysqlIndexKeyStorage({ model, terms }: {
+    readonly dialect: SqlDialect;
+    readonly model: PredicateModel;
+    readonly terms: readonly IndexKeyTermIR[];
+}): void;
+/** Recover SHOW CREATE key interiors, including exact CAST/charset/collation bytes. */
+export declare function extractMysqlIndexKeys({ definition, index, backslashEscapes }: {
+    readonly definition: string;
+    readonly index: string;
+    readonly backslashEscapes: boolean;
+}): readonly IndexKeyOperand[] | undefined;
+/** Reuse E's temporary-clone/read/drop operations, extending only CREATE's key replacement seam. */
+export declare function renderMysqlIndexExpressionProbe({ ...params }: IndexExpressionProbeParams): readonly RenderedQuery[];
+//# sourceMappingURL=mysql-index-expressions.d.ts.map

package/dist/dialects/mysql-row-rules.d.ts

@@ -0,0 +1,8 @@
+import type { SqlDialect } from "../dialect.ts";
+import type { EventRowRuleContext, RenderedRowRule } from "../row-rules.ts";
+/** Emit mode-safe SIGNAL diagnostics and one unfiltered BEFORE trigger per event. */
+export declare function renderMysqlRowRule({ dialect, context }: {
+    readonly dialect: SqlDialect;
+    readonly context: EventRowRuleContext;
+}): RenderedRowRule;
+//# sourceMappingURL=mysql-row-rules.d.ts.map

package/dist/dialects/postgres-generated-columns.d.ts

@@ -0,0 +1,30 @@
+import type { QualifiedSqlName } from "@vibeorm/schema";
+import type { SqlDialect } from "../dialect.ts";
+import type { GeneratedColumnDeclaration } from "../generated-columns.ts";
+import type { RenderedQuery } from "../render.ts";
+/** PostgreSQL stored syntax; the public dispatcher performs declaration admission. */
+export declare function renderPostgresGeneratedColumnClause({ generated }: {
+    readonly generated: GeneratedColumnDeclaration;
+}): string;
+/** The migration owner creates the desired base context inside the private savepoint. */
+export type PostgresGeneratedColumnProbe = {
+    readonly operation: "savepoint" | "rollback" | "release";
+    readonly savepoint: string;
+} | {
+    readonly operation: "add";
+    readonly table: QualifiedSqlName;
+    readonly column: string;
+    readonly definition: string;
+};
+/** Render pinned-session scratch statements; this helper never executes or manages a session. */
+export declare function renderPostgresGeneratedColumnProbe({ dialect, probe }: {
+    readonly dialect: SqlDialect;
+    readonly probe: PostgresGeneratedColumnProbe;
+}): RenderedQuery;
+/** Approved stored-generated to ordinary conversion, retaining the present stored values. */
+export declare function renderPostgresDropGeneratedExpression({ dialect, table, column }: {
+    readonly dialect: SqlDialect;
+    readonly table: QualifiedSqlName;
+    readonly column: string;
+}): RenderedQuery;
+//# sourceMappingURL=postgres-generated-columns.d.ts.map

package/dist/dialects/postgres-index-expressions.d.ts

@@ -0,0 +1,10 @@
+import type { IndexExpressionProbeParams, IndexKeyOperand } from "../index-expressions.ts";
+import type { RenderedQuery } from "../render.ts";
+/** CREATE INDEX extraction is conservative; structured catalog rows remain authoritative. */
+export declare function extractPostgresIndexKeys({ definition, index }: {
+    readonly definition: string;
+    readonly index: string;
+}): readonly IndexKeyOperand[] | undefined;
+/** Caller owns a fixed search_path and rollback savepoint; no populated user table is indexed. */
+export declare function renderPostgresIndexExpressionProbe({ ...params }: IndexExpressionProbeParams): readonly RenderedQuery[];
+//# sourceMappingURL=postgres-index-expressions.d.ts.map

package/dist/dialects/postgres-index-keys.d.ts

@@ -1,10 +1,25 @@
 import type { QualifiedSqlName } from "@vibeorm/schema";
 import type { SqlDialect } from "../dialect.ts";
 import type { RenderedQuery } from "../render.ts";
+/**
+ * Turn JIT compilation off for the rest of the current transaction and return
+ * the previous `jit` value as `previous` (read before the change). The bulk
+ * index-key read costs far above `jit_above_cost`, and compiling it takes longer
+ * than running it. Transaction-local: outside a transaction block it changes nothing.
+ */
+export declare function renderPostgresJitSuspend(params: {
+    dialect: SqlDialect;
+}): RenderedQuery;
+/** Restore the transaction's `jit` value read by {@link renderPostgresJitSuspend}. */
+export declare function renderPostgresJitRestore(params: {
+    dialect: SqlDialect;
+    previous: string;
+}): RenderedQuery;
 /** Physical operands and unambiguous server-default evidence for actual type/access-method pairs. */
 export declare function renderPostgresIndexKeys(params: {
     dialect: SqlDialect;
     table?: QualifiedSqlName;
     namespaces?: readonly string[];
+    expressionMetadata?: boolean;
 }): RenderedQuery;
 //# sourceMappingURL=postgres-index-keys.d.ts.map

package/dist/dialects/postgres-row-rules.d.ts

@@ -0,0 +1,25 @@
+import type { FieldIR, QualifiedSqlName, RowRuleIR, SqlObjectIdentity } from "@vibeorm/schema";
+import type { SqlDialect } from "../dialect.ts";
+import type { RenderedRowRule } from "../row-rules.ts";
+/** A finalized PostgreSQL comparison context, supplied by the canonical schema collector. */
+export type PostgresRowRuleContext = {
+    readonly model: string;
+    readonly table: QualifiedSqlName;
+    readonly rule: RowRuleIR;
+    readonly functionIdentity: Extract<SqlObjectIdentity, {
+        readonly kind: "function";
+    }>;
+    readonly triggerIdentity: {
+        readonly kind: "trigger";
+        readonly table: QualifiedSqlName;
+        readonly name: string;
+    };
+    readonly protectedFields: readonly FieldIR[];
+    readonly gateField?: FieldIR;
+};
+/** Emit one ordinary invoker function and an unfiltered BEFORE row trigger; no live objects are taken over. */
+export declare function renderPostgresRowRule({ dialect, context }: {
+    readonly dialect: SqlDialect;
+    readonly context: PostgresRowRuleContext;
+}): RenderedRowRule;
+//# sourceMappingURL=postgres-row-rules.d.ts.map

package/dist/dialects/sqlite-generated-columns.d.ts

@@ -0,0 +1,18 @@
+import type { ExtractedGeneratedColumn, GeneratedColumnDeclaration } from "../generated-columns.ts";
+/** SQLite stored syntax; adding a stored column still requires the migrate rebuild path. */
+export declare function renderSqliteGeneratedColumnClause({ generated }: {
+    readonly generated: GeneratedColumnDeclaration;
+}): string;
+/** Shared source-slice extraction for SQLite source and MySQL SHOW CREATE, not SQL equivalence. */
+export declare function extractGenerationFromDefinition({ definition, column, backslashEscapes, mysql }: {
+    readonly definition: string;
+    readonly column: string;
+    readonly backslashEscapes?: boolean;
+    readonly mysql?: boolean;
+}): ExtractedGeneratedColumn | undefined;
+/** Recover the exact AS interior; omitted storage means virtual, never inferred stored. */
+export declare function extractSqliteGeneratedColumn({ definition, column }: {
+    readonly definition: string;
+    readonly column: string;
+}): ExtractedGeneratedColumn | undefined;
+//# sourceMappingURL=sqlite-generated-columns.d.ts.map

package/dist/dialects/sqlite-index-expressions.d.ts

@@ -0,0 +1,23 @@
+import type { IndexKeyOperand } from "../index-expressions.ts";
+import type { TableDefinitionToken } from "./sqlite-table-definition.ts";
+/** Exact outer-key slices shared by CREATE INDEX and MySQL table-key clauses. */
+export declare function extractIndexKeyList({ sql, open, close, tokens, wrapped, removeWrapper }: {
+    readonly sql: string;
+    readonly open: TableDefinitionToken;
+    readonly close: TableDefinitionToken;
+    readonly tokens: readonly TableDefinitionToken[];
+    readonly wrapped?: boolean;
+    readonly removeWrapper?: boolean;
+}): readonly IndexKeyOperand[] | undefined;
+/** Parse the CREATE INDEX header without interpreting any scalar expression. */
+export declare function extractStandaloneIndexKeys({ definition, index, postgres }: {
+    readonly definition: string;
+    readonly index: string;
+    readonly postgres?: boolean;
+}): readonly IndexKeyOperand[] | undefined;
+/** SQLite source spelling is the evidence; CAST alone never proves a plain Decimal key. */
+export declare function extractSqliteIndexKeys({ definition, index }: {
+    readonly definition: string;
+    readonly index: string;
+}): readonly IndexKeyOperand[] | undefined;
+//# sourceMappingURL=sqlite-index-expressions.d.ts.map