@vibeorm/sql 4.2.0 → 5.0.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;
@@ -22,7 +22,13 @@ export type ColRef = {
      * `castText` renders a dialect text cast and preserves `alias ?? name`,
      * including timestamp identity before driver Date truncation. PostgreSQL
      * uses `"col"::text`; SQLite/MySQL use CAST AS TEXT/CHAR. `encodeBase64`
-     * is postgres-only and renders `encode("col", 'base64')`. Other users:
+     * is postgres-only and renders `encode("col", 'base64')`.
+     * `encodeArrayBase64` is postgres-only and renders
+     * `encode(array_send("col"), 'base64')` — a `bytea[]` column's binary array
+     * form (dimensions, NULL elements, raw element bytes) as base64: faithful
+     * whatever the session's `bytea_output`, keeping a NULL column (`NULL`), an
+     * empty array and NULL elements distinct (5.0 lane V; the lateral subselect's
+     * `Bytes[]` form, decoded by the runtime's JSON-transport plan). Other users:
      * the lateral subselect (SQL review B3: raw `to_jsonb` would ship BigInt/Decimal as float64 JSON
      * numbers and Bytes as `\x` hex text), and every row projection of a
      * `Float[]`/`Json[]` column (bun:sql's array parser refuses float arrays
@@ -30,7 +36,7 @@ export type ColRef = {
      * the runtime parses the array literal text itself). Never set on
      * filter/order refs.
      */
-    readonly transform?: "castText" | "encodeBase64" | "jsonText";
+    readonly transform?: "castText" | "encodeBase64" | "encodeArrayBase64" | "jsonText";
     /**
      * Comparison/order/aggregate cast, sqlite Decimal only (SQL review B4):
      * Decimal stores as exact TEXT there and text comparison is lexicographic —
@@ -88,6 +94,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 +166,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;
@@ -367,7 +462,11 @@ export type OrderTerm = OrderByColumn | OrderByAggregate | OrderBySubquery;
 /**
  * One `LEFT JOIN LATERAL (…) AS alias ON true` clause aggregating a correlated
  * subquery into a single JSON value per outer row — the "join" relation-loading
- * strategy (postgres/pglite only; gated on `capabilities.lateralJoin`).
+ * strategy (postgres/pglite, and MySQL 8.0.14+ since lane J; gated on
+ * `capabilities.lateralJoin` and rendered through `SqlDialect.lateralJson`).
+ * MySQL renders positional rows only (`JSON_ARRAY`, `JSON_ARRAYAGG`, `ON
+ * true`); its aggregate cannot order, so an ordered list level carries a
+ * `select.rowNumber` without partition — rendered as the row's last slot.
  *
  * Renders (agg `jsonArray`):
  *   `LEFT JOIN LATERAL (SELECT COALESCE(json_agg(to_json("__sub".*)), '[]'::json)
@@ -435,6 +534,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 +653,82 @@ 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;
+};
+/**
+ * Statement-count pass EPIC 4 (round-3 ST-07): bound key tuples as the FROM
+ * of a select (`SelectStatement.fromKeys`) — a derived table named
+ * `table.name` whose columns are `columns`, one row per tuple. The write
+ * follow-up puts it where the parent table would be: the find path's laterals
+ * correlate to `"<table.name>"."<column>"` exactly as over the table, but read
+ * the RETURNED key values instead of the parent row (a deleted row, or a
+ * native-RLS parent whose SELECT policy the per-relation loads never met).
+ *
+ * Renders where `SqlDialect.keyListStrategy` is `unnest` (postgres) as the
+ * typed form of a `VALUES` list — one array per column, typed like the
+ * key-list filter's members (`postgresKeyListElementType`), so the text does
+ * not depend on the tuple count: `FROM unnest($1::text[], $2::int4[]) AS
+ * "Post" ("id", "authorId")`. A `DateTime` member without a declared native
+ * type (`keyListBindsUntypedRows`) and every other dialect refuse with
+ * `VIBE_UNSUPPORTED_CAPABILITY` — those dialects have no lateral joins either.
+ */
+export type KeyRows = {
+    /** Output column names of the derived table, in member order. */
+    readonly columns: readonly string[];
+    /** How each column binds, in column order — see {@link KeyListMember}. */
+    readonly members: readonly KeyListMember[];
+    /** Encoded tuples; never empty, each exactly `columns.length` long. */
+    readonly rows: readonly (readonly unknown[])[];
+};
 export type SelectStatement = {
     readonly kind: "select";
     readonly table: TableRef;
@@ -548,20 +754,56 @@ 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
      * by aggregate-over-a-subset shapes (`aggregate({ take, skip, orderBy })`).
      */
     readonly fromSelect?: SelectStatement;
-    /** Lateral JSON-aggregation joins — postgres-only, see {@link LateralJoin}. */
+    /** Lateral JSON-aggregation joins — postgres and MySQL 8.0.14+, see {@link LateralJoin}. */
     readonly lateralJoins?: readonly LateralJoin[];
     /** Plain equality INNER JOINs — portable, see {@link InnerJoin}. */
     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[];
+    /**
+     * Statement-count pass EPIC 4 (ST-07): derived-table FROM over bound key
+     * tuples, named `table.name` with the listed column names — see
+     * {@link KeyRows}. Never together with `fromSelect`, `keyPage`, `fromUnion`,
+     * a `table.alias` or a `rowLock`.
+     */
+    readonly fromKeys?: KeyRows;
     readonly where?: SqlExpr;
     readonly groupBy?: readonly ColRef[];
     /** HAVING predicate — grouped selects; may contain `aggCmp` expressions. */
@@ -597,6 +839,19 @@ export type RowLock = {
 export declare const SQL_DEFAULT_CELL: {
     readonly __sqlDefault: true;
 };
+/**
+ * Sentinel update-arm cell: the column keeps its current value —
+ * `` `col` = `table`.`col` `` (V8, the insert-if-missing upsert). Valid only in
+ * an {@link OnConflictUpdate} `update` set, where MySQL's `ON DUPLICATE KEY
+ * UPDATE` needs at least one assignment: a self-assignment changes nothing on a
+ * duplicate and, unlike `INSERT IGNORE`, leaves every other error an error.
+ * Refused in a plain UPDATE's SET list.
+ */
+export declare const SQL_KEEP_CELL: {
+    readonly __sqlKeep: true;
+};
+/** Is this update cell the {@link SQL_KEEP_CELL} sentinel? */
+export declare function isSqlKeepCell(value: unknown): boolean;
 /** Is this VALUES cell the {@link SQL_DEFAULT_CELL} sentinel? */
 export declare function isSqlDefaultCell(value: unknown): boolean;
 /**
@@ -674,6 +929,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 = {
@@ -705,11 +980,28 @@ export type OnConflictUpdate = {
 };
 /**
  * Conflicting rows are skipped (`createMany({ skipDuplicates: true })`).
- * An empty/absent target means "any conflict" — the mysql form (INSERT IGNORE)
- * can only express that, so it ignores a bare `columns` target (documented
- * degradation) and REFUSES the refined targets below.
+ * An empty/absent target means "any conflict" — the mysql form
+ * (`ON DUPLICATE KEY UPDATE k = t.k`, dialect `doNothingForm:
+ * "duplicateKeyKeep"`) can only express that, so it ignores a bare `columns`
+ * target (documented degradation) and REFUSES the refined targets below.
  */
 export type OnConflictDoNothing = {
+    /**
+     * MySQL form only (`duplicateKeyKeep`): the column the duplicate arm assigns
+     * to itself (`` `k` = `t`.`k` ``, a no-op). Absent = the first inserted
+     * column; an all-default row (no column) must name one.
+     */
+    readonly keepColumn?: string;
+    /**
+     * MySQL form only, single-row statements: a decimal literal S (digits only).
+     * The keep assignment becomes `` `k` = IF(LAST_INSERT_ID(S), `t`.`k`, `t`.`k`) ``,
+     * so a skipped duplicate reports S as the statement's insert id (an inserted
+     * row reports its own id, or 0) — the exact skipped verdict that the
+     * affected count cannot give with CLIENT_FOUND_ROWS (an unchanged duplicate
+     * counts 1, like an insert). The builder picks S unequal to the row's
+     * explicit AUTO_INCREMENT value.
+     */
+    readonly duplicateFlag?: string;
     readonly columns?: readonly string[];
     /**
      * Partial-index target predicate, RAW SQL: `ON CONFLICT (cols) WHERE pred
@@ -727,7 +1019,13 @@ export type OnConflictClause = OnConflictUpdate | OnConflictDoNothing;
 export type UpdateStatement = {
     readonly kind: "update";
     readonly table: TableRef;
-    /** Column → parameter value, or an atomic {@link SetOperation}. */
+    /**
+     * Column → parameter value, or an atomic {@link SetOperation}. As a
+     * {@link ChainStep} only (statement-maxx lane C3), a value may be a
+     * {@link StepColumnRef} to an EARLIER step: `"col" = (SELECT "c" FROM
+     * "step")` — the step must return at most one row (an owner resolved by a
+     * unique where, or an owner INSERT of one row).
+     */
     readonly set: Readonly<Record<string, unknown>>;
     readonly where?: SqlExpr;
     readonly returning?: readonly ReturningColumn[];
@@ -777,6 +1075,12 @@ export type RlsContextStatement = {
     readonly kind: "rlsContext";
     readonly context: RlsContextIR;
     readonly values: Readonly<Record<string, string | null>>;
+    /** PGlite: bind this trusted runtime role first, in the same statement. */
+    readonly role?: string;
+    /** Switch the transaction to READ ONLY in the same statement, after the claims. */
+    readonly readOnly?: boolean;
+    /** Report the backend as `"backendPid"` / `"backendStart"` text columns. */
+    readonly backend?: boolean;
 };
 /** Trusted pre-existing PGlite execution role; never a request-supplied principal. */
 export type RlsRoleStatement = {
@@ -865,6 +1169,15 @@ export type InsertSelectStatement = {
      */
     readonly source?: ChainRowSource;
     readonly where?: SqlExpr;
+    /**
+     * `ON CONFLICT (<columns>) DO NOTHING` (statement-maxx lane C2): a row whose
+     * conflict target already exists is skipped and not returned — the implicit
+     * many-to-many join INSERT, where re-connecting an existing pair is a no-op.
+     * Postgres form only (the chain renders nowhere else); at least one column.
+     */
+    readonly conflictDoNothing?: {
+        readonly columns: readonly string[];
+    };
     readonly returning?: readonly ReturningColumn[];
 };
 /**

package/dist/codecs.d.ts

@@ -20,6 +20,7 @@
  * Database enums ride the String codec. String-backed enums use the field-bound
  * membership codec below; their wire values are still strings on every dialect.
  */
+import { VibeError } from "@vibeorm/schema";
 import type { Dialect, ScalarType } from "@vibeorm/schema";
 /**
  * One scalar type's transport rules for one dialect. Both directions see only
@@ -66,6 +67,23 @@ export type WireFidelity = {
     readonly json?: "parsed" | "text";
     /** Int/Float columns arrive as JS numbers (`"native"`) or as text (`"text"`). */
     readonly numbers?: "native" | "text";
+    /**
+     * Bytes columns arrive as Node `Buffer` instances (`"buffer"`: node-postgres,
+     * bun:sql); absent means a plain `Uint8Array` (PGlite). Never prunes a
+     * decoder: the runtime's JSON-transport plan reads it, so a `"join"`
+     * relation child's bytes (base64 on the wire) materialize in the same class
+     * the driver hands the `"query"` strategy — value identity (5.0 lane V).
+     */
+    readonly bytes?: "buffer";
+    /**
+     * Zone-less date-time text (MySQL DATETIME / TIMESTAMP / DATE) is read as a
+     * UTC instant by the driver (`"utc"`: mysql2 with `timezone: "Z"`). Absent
+     * means another or an unknown zone (another `timezone` option, an injected
+     * pool). Never prunes a decoder: the runtime reads it to decide whether a
+     * dialect default of `"join"` keeps value identity — the JSON transport
+     * decodes that text as UTC (`lateralJson.requiresUtcDateTimeWire`, lane J).
+     */
+    readonly zoneLessDateTime?: "utc";
 };
 /**
  * Is this scalar type's DECODE a no-op under the declared wire fidelity?
@@ -113,6 +131,32 @@ export declare function decodeIsNoop(params: {
 export declare function parseDateTimeText(params: {
     text: string;
 }): Date | undefined;
+/**
+ * PostgreSQL date/time text with a year of five or more digits or a ` BC` era,
+ * in the row text form and the JSON form: `12345-06-07 08:09:10.111+00`,
+ * `12345-06-07T08:09:10.111` (zone-less), `0044-03-15T12:00:00.5+00:00 BC`,
+ * `0044-03-15 BC` (`date`). ECMA-262 parses none of them (an expanded year
+ * needs `+012345`), and a value near the end of year 9999 reaches them
+ * through the session zone alone (`9999-12-31 23:59+00` prints as
+ * `10000-01-01 00:59+01` east of UTC). Built from its fields, by the rules of
+ * {@link parseDateTimeText}: the BC year astronomically (`1 BC` = year 0, the
+ * reading of node-postgres), zone-less text as UTC, the fraction truncated to
+ * milliseconds, an offset with seconds applied exactly.
+ *
+ * `undefined` for every other text — a 4-digit AD value keeps the parse it
+ * had — and for an instant outside the `Date` range. Exported for the adapters
+ * whose zone-less driver parsers fall back to it (one rule, rule 6).
+ */
+export declare function parseExtendedDateTimeText(params: {
+    text: string;
+}): Date | undefined;
+/**
+ * The decode refusal of a non-finite or unparseable DateTime — one error for
+ * every DateTime codec. Exported so a statement that refuses such a value
+ * itself (the runtime's in-statement value guard, round-trip follow-up D1)
+ * reports exactly this error.
+ */
+export declare function decodedDateTimeRefusal(): VibeError;
 /**
  * The time-of-day codec for a DateTime field's native type, or `undefined`
  * when the native type is not `time`/`timetz` (the DateTime table row
@@ -122,6 +166,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