@vibeorm/sql 2.5.0 → 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeORM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ast.d.ts

@@ -1,4 +1,5 @@
 import type { NativeEnumArrayParameter } from "./native-enum-parameter.ts";
+import type { JsonListParameter } from "./json-list-parameter.ts";
 import type { SqlFragment } from "./composable.ts";
 import type { RlsReadinessQuery } from "./dialects/postgres-rls-readiness.ts";
 /**
@@ -15,13 +16,20 @@ export type ColRef = {
     readonly table?: string;
     readonly name: string;
     /**
-     * Projection-only wire transform, postgres lateral joins only (SQL review
-     * B3): raw `to_jsonb` would ship BigInt/Decimal as float64 JSON numbers and
-     * Bytes as `\x` hex text, so the subselect casts instead — `castText`
-     * renders `"col"::text AS "col"`, `encodeBase64` renders
-     * `encode("col", 'base64') AS "col"`. Never set on filter/order refs.
+     * Projection-only wire transform. `jsonText` uses the dialect's JSON text
+     * projection to preserve SQL NULL versus the JSON document `null` before
+     * driver parsing, without converting a postgres `json` column to `jsonb`.
+     * The other transforms are postgres only. `castText` renders
+     * `"col"::text AS "col"`, `encodeBase64` renders
+     * `encode("col", 'base64') AS "col"`. Two 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
+     * printed with an exponent and json arrays holding integers beyond int32;
+     * the runtime parses the array literal text itself). Never set on
+     * filter/order refs.
      */
-    readonly transform?: "castText" | "encodeBase64";
+    readonly transform?: "castText" | "encodeBase64" | "jsonText";
     /**
      * Comparison/order/aggregate cast, sqlite Decimal only (SQL review B4):
      * Decimal stores as exact TEXT there and text comparison is lexicographic —
@@ -30,6 +38,14 @@ export type ColRef = {
      * storage and read-back stay the exact text.
      */
     readonly castReal?: boolean;
+    /**
+     * Order/distinct/compare cast, postgres `json` columns only (`Json @db.Json`,
+     * release-3.0 D3): `json` has no ordering or equality operator, so ORDER BY,
+     * DISTINCT ON and comparison sites render `"col"::jsonb` (`"col"::jsonb[]`
+     * for a `json[]` list column) — the order and distinctness of a jsonb
+     * column. Never set on projections, so read-back keeps the stored text.
+     */
+    readonly castJsonb?: "jsonb" | "jsonb[]";
     /**
      * Projection alias: renders `ref AS "alias"`. PROJECTION-ONLY — filter,
      * order and correlation refs never set it (the renderer ignores it outside
@@ -93,6 +109,11 @@ export type SqlExpr = {
     readonly column: ColRef;
     readonly values: readonly unknown[];
     readonly negate?: boolean;
+    /**
+     * The column holds a time of day (`@db.Time(n)` / `@db.Timetz(n)`): the
+     * dialect renders the membership per `SqlDialect.timeOfDayInStrategy`.
+     */
+    readonly timeOfDay?: boolean;
 }
 /**
  * ORDERED-TUPLE membership: `("a", "b") IN ((?, ?), (?, ?))`. The composite
@@ -183,13 +204,13 @@ export type SqlExpr = {
  | {
     readonly kind: "arrayContainsAll";
     readonly column: ColRef;
-    readonly values: readonly unknown[] | string | NativeEnumArrayParameter;
+    readonly values: readonly unknown[] | string | NativeEnumArrayParameter | JsonListParameter;
 }
 /** Scalar-list overlap: `"col" && $n` (one array param) — Prisma's `hasSome`. Postgres only. */
  | {
     readonly kind: "arrayOverlaps";
     readonly column: ColRef;
-    readonly values: readonly unknown[] | string | NativeEnumArrayParameter;
+    readonly values: readonly unknown[] | string | NativeEnumArrayParameter | JsonListParameter;
 }
 /**
  * Scalar-list emptiness via `array_length("col", 1) IS [NOT] NULL` — the v1
@@ -216,6 +237,15 @@ export type SqlExpr = {
     readonly value: unknown;
     readonly insensitive?: boolean;
     readonly negate?: boolean;
+    /**
+     * The column's postgres type: absent (or `jsonb`) for the default
+     * `jsonb`, `json` for `Json @db.Json`. Postgres defines `=`, `<>` and
+     * `@>` for jsonb only, so on a `json` column every op casts the
+     * EXTRACTED value to jsonb (the string ops then read it as text), which
+     * gives a jsonb column's answer. Sqlite and mysql have one JSON type
+     * and ignore it.
+     */
+    readonly storage?: "jsonb" | "json";
 }
 /**
  * A bound extension fragment: literal text, bound parameters and quoted
@@ -369,6 +399,24 @@ export type LateralJoin = {
     /** The correlated child select — may reference outer columns via table-qualified refs. */
     readonly select: SelectStatement;
 };
+/**
+ * One correlated scalar `COUNT(*)` projected into a select list:
+ * `(SELECT COUNT(*) FROM … WHERE <correlation>) AS "alias"` — the relation
+ * `_count` of the round-trip campaign's R-03b, which saves the separate grouped
+ * count statement. Portable: postgres, sqlite and mysql all evaluate a
+ * correlated scalar subquery once per output row; the runtime wraps a paged
+ * root in a derived table first, so the subqueries run only for the page.
+ * The select must be ONE ungrouped `COUNT(*)` (`columns: []`, `selectExpr`
+ * countAll, no grouping, paging, distinct or lock) — anything else is refused
+ * at render. Its parameters join the statement's single sequence in text order
+ * (the select list renders before FROM).
+ */
+export type CountSubquery = {
+    /** Output column the count is exposed under (`__vibe_count_0`). */
+    readonly alias: string;
+    /** The correlated count select — references outer columns via table-qualified refs. */
+    readonly select: SelectStatement;
+};
 /**
  * One `INNER JOIN "table" AS alias ON left = right [AND …]` clause — plain
  * equality joins only, portable across all dialects. Added for the
@@ -384,6 +432,75 @@ export type InnerJoin = {
         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
+ * column's OWN collation decides `=` — the equality `col IN (?, …)` uses.
+ * `integer` and `decimal` cast the parameter into the column's numeric family:
+ * BigInt and Decimal values travel as strings, and a derived-table string
+ * compared with a numeric column goes through a double (measured on mysql:
+ * `9007199254740993` matched `9007199254740992`).
+ *
+ * `integer` renders `CAST(? AS SIGNED)`. `decimal` renders
+ * `CAST(? AS DECIMAL(65, scale))` with the tested column's own scale: 65 is
+ * MySQL's maximum precision, so the cast holds every value a
+ * `DECIMAL(p, scale)` column can hold. A fixed `DECIMAL(65,30)` held only 35
+ * integer digits and clipped a `Decimal(65, 0)` key onto its maximum, which
+ * matched nothing (review finding 1); the column's own precision would clip a
+ * wider value onto the column's maximum and pair it with a row it does not
+ * equal (measured: `CAST('100000' AS DECIMAL(5,0))` is `99999`). `scale` is
+ * 0–30, MySQL's range.
+ *
+ * `citext` (postgres only) renders `CAST($n AS citext)`: a postgres `citext`
+ * key compares case-insensitively, and a bare VALUES parameter would be
+ * `text`, whose `=` against a citext column is the case-sensitive text
+ * operator. A VALUES cell has no column to infer a type from, so every member
+ * of a postgres key table binds typed: `citext`, `text` (`CAST($n AS text)`,
+ * a text or varchar column) or `integer` (`CAST($n AS bigint)`, exact against
+ * any integer column) — any other member refuses on postgres. `text` is
+ * postgres-only; mysql binds text members as `value`.
+ */
+export type KeyTableMember = {
+    readonly kind: "value";
+} | {
+    readonly kind: "integer";
+} | {
+    readonly kind: "decimal";
+    readonly scale: number;
+} | {
+    readonly kind: "citext";
+} | {
+    readonly kind: "text";
+};
+/**
+ * The batch's key tuples as a derived table, each tagged with its ORDINAL
+ * (row `i` carries `i`), INNER JOINed on the tested columns — mysql:
+ * `INNER JOIN (VALUES ROW(?, 0), ROW(?, 1)) AS \`alias\` (\`__vibe_k0\`, \`ordinal\`)
+ * ON col = \`alias\`.\`__vibe_k0\``; postgres only over `citext` members
+ * (`(VALUES (CAST($1 AS citext), 0), …)`, release 3.0 nested writes).
+ * Member columns are named `__vibe_k<i>` (a reserved prefix, so unqualified
+ * child columns never collide with them).
+ *
+ * Why it exists (EPIC R): a relation load used to stitch children to parents
+ * by comparing decoded keys in JavaScript, while mysql's collations equate
+ * spellings (`acme` = `Acme` = `ACME`, `cafe` = `Café`, `x ` = `x`) that
+ * JavaScript keeps apart — the foreign key and the `IN` filter accepted the
+ * child, the stitch dropped it. Joined this way the DATABASE pairs every child
+ * row with every batch key it considers equal, and the projected ordinal names
+ * the key; the join is also the membership filter.
+ */
+export type KeyTableJoin = {
+    /** Derived-table alias (`__vibe_keys`); the ordinal projects as `alias.ordinalAlias`. */
+    readonly alias: string;
+    /** The statement's columns, compared member by member (`=`), in tuple order. */
+    readonly columns: readonly ColRef[];
+    /** How each member binds, in tuple order — see {@link KeyTableMember}. */
+    readonly members: readonly KeyTableMember[];
+    /** Encoded key tuples; never empty, each as long as `columns`. */
+    readonly rows: readonly (readonly unknown[])[];
+    /** Output name of the ordinal column. */
+    readonly ordinalAlias: string;
+};
 /**
  * A `ROW_NUMBER() OVER (PARTITION BY … [ORDER BY …]) AS "alias"` projection,
  * appended after `columns` — the distinct emulation on dialects without
@@ -413,6 +530,8 @@ export type SelectStatement = {
      * combined with `selectExpr`.
      */
     readonly aggregates?: readonly AggSelect[];
+    /** Correlated `COUNT(*)` subqueries, rendered after `aggregates` — see {@link CountSubquery}. */
+    readonly countSubqueries?: readonly CountSubquery[];
     /**
      * `SELECT DISTINCT ON (cols)` — postgres only (`capabilities.distinctOn`;
      * other dialects refuse at render time and the runtime emulates client-side
@@ -430,6 +549,8 @@ export type SelectStatement = {
     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;
     /** ROW_NUMBER window projection — see {@link RowNumberProjection}. */
     readonly rowNumber?: RowNumberProjection;
     readonly where?: SqlExpr;
@@ -482,14 +603,21 @@ export declare function isSqlDefaultCell(value: unknown): boolean;
  * Sqlite/mysql render the bare placeholder — their Json transport is already
  * plain text. The COLLECTED parameter is the plain text either way: this
  * wrapper never crosses the wire.
+ *
+ * `storage: "json"` marks a postgres `json` column (`Json @db.Json`): the cell
+ * renders `$n::text::json`, so the column stores the text as written (key
+ * order and spelling kept) instead of jsonb's normalized text (release-3.0
+ * D3). Absent = jsonb; dialects without a param cast ignore it.
  */
 export type JsonParamCell = {
     readonly __jsonParam: true;
     readonly text: string;
+    readonly storage?: "json";
 };
 /** Wrap a Json column's encoded (stringified) parameter for cast-site rendering. */
 export declare function jsonParamCell(params: {
     text: string;
+    storage?: "json";
 }): JsonParamCell;
 /** Is this VALUES/SET cell a {@link JsonParamCell}? */
 export declare function isJsonParamCell(value: unknown): value is JsonParamCell;
@@ -511,6 +639,21 @@ export declare function excludedRef(params: {
 }): ExcludedRef;
 /** Is this SET cell an {@link ExcludedRef}? */
 export declare function isExcludedRef(value: unknown): value is ExcludedRef;
+/**
+ * One RETURNING column: a bare column name renders `"col"`; `castText` renders
+ * `"col"::text AS "col"` (postgres only) for `Float[]`/`Json[]`. `jsonText`
+ * applies the dialect's JSON text projection, as {@link ColRef.transform} does
+ * for SELECT. Dialects without RETURNING still omit the clause and flag it.
+ */
+export type ReturningColumn = string | {
+    readonly name: string;
+    readonly castText: true;
+} | {
+    readonly name: string;
+    readonly transform: "jsonText";
+};
+/** The column name a {@link ReturningColumn} exposes in the result row. */
+export declare function returningColumnName(column: ReturningColumn): string;
 export type InsertStatement = {
     readonly kind: "insert";
     readonly table: TableRef;
@@ -520,7 +663,7 @@ export type InsertStatement = {
     /** Upsert clause: ON CONFLICT (pg/sqlite) or ON DUPLICATE KEY (mysql). */
     readonly onConflict?: OnConflictClause;
     /** Rendered as RETURNING where the dialect supports it, else omitted+flagged. */
-    readonly returning?: readonly string[];
+    readonly returning?: readonly ReturningColumn[];
 };
 /** Conflicting rows are updated with these column values. */
 export type OnConflictUpdate = {
@@ -577,13 +720,13 @@ export type UpdateStatement = {
     /** Column → parameter value, or an atomic {@link SetOperation}. */
     readonly set: Readonly<Record<string, unknown>>;
     readonly where?: SqlExpr;
-    readonly returning?: readonly string[];
+    readonly returning?: readonly ReturningColumn[];
 };
 export type DeleteStatement = {
     readonly kind: "delete";
     readonly table: TableRef;
     readonly where?: SqlExpr;
-    readonly returning?: readonly string[];
+    readonly returning?: readonly ReturningColumn[];
 };
 /** Native RLS DDL, kept distinct from ordinary row-query expressions. */
 export type RlsEnableStatement = {
@@ -663,7 +806,191 @@ export type AdvisoryLockStatement = {
 };
 /** The column an advisory try-lock projects its verdict into. */
 export declare const ADVISORY_LOCK_RESULT_COLUMN: string;
-export type SqlStatement = SelectStatement | InsertStatement | UpdateStatement | DeleteStatement | RlsEnableStatement | RlsForceStatement | RlsDisableStatement | RlsNoForceStatement | RlsDropPolicyStatement | RlsPolicyStatement | RlsContextStatement | RlsRoleStatement | AdvisoryLockStatement;
+/**
+ * A cell of an {@link InsertSelectStatement} that reads a column of an EARLIER
+ * chain step: `"step"."column"`. A column reference, not a parameter — the
+ * value comes from the step's rows inside the same statement (a child row
+ * taking its parent's key from the parent step, round-trip campaign EPIC F).
+ * The step must be named in the insert's `from` list.
+ */
+export type StepColumnRef = {
+    readonly __stepColumn: true;
+    readonly step: string;
+    readonly column: string;
+};
+/** Reference `column` of the earlier chain step `step` from an INSERT … SELECT cell. */
+export declare function stepColumnRef(params: {
+    step: string;
+    column: string;
+}): StepColumnRef;
+/** Is this INSERT … SELECT cell a {@link StepColumnRef}? */
+export declare function isStepColumnRef(value: unknown): value is StepColumnRef;
+/**
+ * `INSERT INTO t (cols) SELECT <cells> [FROM "step", …] [WHERE <expr>]
+ * [RETURNING …]` — an INSERT whose ONE row is a SELECT list instead of a
+ * VALUES row, so a WHERE can veto the write inside the statement and cells can
+ * read earlier steps. Valid ONLY as a {@link ChainStep} statement.
+ *
+ * Cells take the same forms as a VALUES cell — a codec-encoded value, a
+ * {@link JsonParamCell}, a {@link DbNowMarker} — plus {@link StepColumnRef}.
+ * The {@link SQL_DEFAULT_CELL} is refused: `DEFAULT` is not allowed in a SELECT
+ * list; an omitted column takes its default by being absent from `columns`.
+ *
+ * Parameter typing (O-03, probed on PostgreSQL): a bare parameter in this
+ * one-row SELECT list takes the TARGET column's type, exactly as in VALUES.
+ */
+export type InsertSelectStatement = {
+    readonly kind: "insertSelect";
+    readonly table: TableRef;
+    readonly columns: readonly string[];
+    /** One cell per column, aligned to `columns` — deterministic parameter order. */
+    readonly cells: readonly unknown[];
+    /** Earlier chain steps the SELECT reads FROM, in order (absent: a one-row SELECT without FROM). */
+    readonly from?: readonly string[];
+    /**
+     * Several source rows (round-trip campaign EPIC F): the SELECT reads them
+     * from a derived table `alias`, joined after the `from` steps, and the
+     * `cells` read its columns through `stepColumnRef({ step: alias, column })`.
+     * See {@link ChainRowSource} for how the rows are typed.
+     */
+    readonly source?: ChainRowSource;
+    readonly where?: SqlExpr;
+    readonly returning?: readonly ReturningColumn[];
+};
+/**
+ * Rows an {@link InsertSelectStatement} inserts, as ONE derived table:
+ * `(SELECT <cols> FROM (VALUES (<typed NULL row>), ($1, $2), …) AS "alias"
+ * (<cols>) OFFSET 1) AS "alias"`.
+ *
+ * Why the typed NULL row (review O-03): a bare parameter outside the INSERT's
+ * own VALUES has no type, and PostgreSQL resolves an all-parameter column of a
+ * VALUES list or UNION in FROM as `text` ("column is of type integer but
+ * expression is of type text"). The first row is one `(SELECT "col" FROM
+ * <typedBy> WHERE FALSE)` per column — a NULL of the TARGET column's exact
+ * type (enums, `numeric(p,s)`, `varchar(n)`, domains and arrays included) —
+ * so every parameter below takes that type, with no cast map anywhere;
+ * `OFFSET 1` drops the row. (A `UNION ALL` of one-row SELECTs types the same
+ * way but costs ~10× the planning time at 1000 rows — EPIC F shape gate.)
+ *
+ * Cells take the VALUES forms: a codec-encoded value, a {@link JsonParamCell}
+ * or a {@link DbNowMarker}; the DEFAULT cell is refused (a homogeneous row set
+ * omits the column instead). A cell carrying its OWN type (the Json cast, the
+ * clock) must agree with the column's type under VALUES' common-type rules,
+ * which are stricter than INSERT's assignment casts — the builder keeps such
+ * columns out (EPIC F eligibility). Rows are read in list order, which is the
+ * order the INSERT consumes them.
+ */
+export type ChainRowSource = {
+    readonly alias: string;
+    /** The table whose columns type the rows — normally the INSERT's own table. */
+    readonly typedBy: TableRef;
+    readonly columns: readonly string[];
+    /** At least one row, each aligned to `columns`. */
+    readonly rows: readonly (readonly unknown[])[];
+};
+/** What one chain step may be: a read, or a data-modifying statement with RETURNING. */
+export type ChainStepStatement = SelectStatement | InsertStatement | InsertSelectStatement | UpdateStatement | DeleteStatement;
+/**
+ * One named step: rendered `"name" AS (<statement>)`. Later steps and the
+ * result read it as a table (`FROM "name"`, `EXISTS (SELECT 1 FROM "name" …)`,
+ * a {@link StepColumnRef}). A data-modifying step contributes the rows its
+ * RETURNING list names.
+ */
+export type ChainStep = {
+    readonly name: string;
+    readonly statement: ChainStepStatement;
+};
+/**
+ * The chain's final SELECT: the rows of `rowsFrom` (in that order, `UNION
+ * ALL`), each projecting `columns`.
+ *
+ * `verdict` adds one column `alias` = `expr` to every row, AND guarantees a
+ * row: when the `rowsFrom` steps return nothing, the result is exactly ONE
+ * verdict row whose `columns` are all NULL. A caller recognizes it by NULL in
+ * a column the steps never return as NULL (a primary key). Accounting
+ * consequence: such a statement returns one row per written row OR one
+ * verdict row — a caller that counts returned rows as row changes must undo a
+ * verdict-row outcome (the upsert fold always rolls it back).
+ */
+export type ChainResult = {
+    readonly rowsFrom: readonly string[];
+    readonly columns: readonly string[];
+    readonly verdict?: {
+        readonly alias: string;
+        readonly expr: SqlExpr;
+    };
+    /**
+     * In-statement vetoes (round-trip campaign EPIC F), checked in order: when
+     * `step` returned no row (fewer than `minRows`, EPIC W), the STATEMENT FAILS — so the database undoes every
+     * effect of every step, trigger writes included — with an error whose
+     * message carries `__vibe_veto:<token>:<nonce>:` ({@link CHAIN_VETO_PREFIX},
+     * {@link chainVetoToken}). Requires `tally`: the veto is the tally column's
+     * guard, so it is evaluated exactly once, on the one guaranteed result row.
+     */
+    readonly veto?: readonly ChainVeto[];
+    /**
+     * One column `alias` on every result row: the number of rows the listed
+     * data-modifying steps returned (their RETURNING rows = their direct
+     * effects). Guarantees one row like `verdict`. Row-change accounting reads
+     * it instead of counting result rows (effect `writeTally`).
+     */
+    readonly tally?: ChainTally;
+};
+/**
+ * Fail the statement when `step` returned no row; `token` names the veto in the
+ * error. `nonce` is bound as a PARAMETER into the marker (never SQL text): a
+ * per-call random value the caller requires back in the error, so a user value
+ * that merely looks like a marker is never read as a veto.
+ *
+ * `minRows` (EPIC W) makes the veto count-sensitive: the statement fails when
+ * `step` returned FEWER rows than that (a multi-row INSERT a trigger shortened).
+ * Omitted or 1 = "no row". A positive safe integer, rendered as SQL text.
+ */
+export type ChainVeto = {
+    readonly step: string;
+    readonly token: string;
+    readonly nonce: string;
+    readonly minRows?: number;
+};
+/** Count the RETURNING rows of `steps` into the result column `alias`. */
+export type ChainTally = {
+    readonly alias: string;
+    readonly steps: readonly string[];
+};
+/** Marker every chain veto error message carries, followed by `<token>:<nonce>:`. */
+export declare const CHAIN_VETO_PREFIX: string;
+/** Allowed veto tokens: lower-case words — they are rendered into SQL text. */
+export declare const CHAIN_VETO_TOKEN_PATTERN: RegExp;
+/**
+ * The veto token a database error message carries for this `nonce`, or
+ * `undefined`. Matches the marker anywhere in the text, so a localized server
+ * message (`lc_messages`) still yields it: the marker is the invalid VALUE the
+ * message quotes. A marker without the caller's nonce is not a veto.
+ */
+export declare function chainVetoToken(params: {
+    message: string;
+    nonce: string;
+}): string | undefined;
+/**
+ * ONE statement made of an ordered chain of named steps — reads (a locked
+ * probe) and data-modifying statements with RETURNING — ending in a final
+ * SELECT over them (round-trip campaign EPIC 4, reused by EPIC F). Renders as
+ * `WITH "a" AS (…), "b" AS (…) SELECT …` on a dialect whose
+ * `statementChain` strategy names the form (postgres); every other dialect
+ * refuses at render time (`VIBE_UNSUPPORTED_CAPABILITY`) — callers gate on
+ * the strategy first and keep their multi-statement path there.
+ *
+ * PostgreSQL semantics the builder relies on: every step sees ONE snapshot
+ * (a step never sees another step's writes — only its RETURNING rows), steps
+ * that reference a step run after it, and the statement is atomic: an error in
+ * any step undoes every step's effects, trigger writes included.
+ */
+export type ChainStatement = {
+    readonly kind: "chain";
+    readonly steps: readonly ChainStep[];
+    readonly result: ChainResult;
+};
+export type SqlStatement = SelectStatement | InsertStatement | UpdateStatement | DeleteStatement | RlsEnableStatement | RlsForceStatement | RlsDisableStatement | RlsNoForceStatement | RlsDropPolicyStatement | RlsPolicyStatement | RlsContextStatement | RlsRoleStatement | AdvisoryLockStatement | ChainStatement;
 /** Readiness statements remain distinct from application queries. */
 export type RlsReadinessStatement = {
     readonly kind: "rlsReadiness";

package/dist/codecs.d.ts

@@ -113,6 +113,63 @@ export declare function decodeIsNoop(params: {
 export declare function parseDateTimeText(params: {
     text: string;
 }): Date | undefined;
+/**
+ * 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
+ * applies). The one native-type rule is `timeOfDayType` in @vibeorm/schema,
+ * shared with the dialect refusal in schema validation.
+ */
+export declare function timeOfDayCodec(params: {
+    nativeType: string | undefined;
+}): ScalarCodec | undefined;
+/**
+ * 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
+ * or the native parser cause. Without context, legacy codec errors are unchanged.
+ */
+export declare function parseJsonText(params: {
+    text: string;
+    context?: Readonly<Record<string, unknown>>;
+}): unknown;
+/**
+ * The SHORTEST decimal that round-trips through float32 to the same value as
+ * `value` — what postgres itself prints for a `real` (`0.1`, `3.4028235e+38`).
+ *
+ * A driver that reads a `real` in BINARY format (bun:sql with named
+ * statements) hands back the float32 widened to float64:
+ * `0.10000000149011612` for a stored `0.1`. Text-format drivers already give
+ * the short form, and for those this is the identity — the shortest form of a
+ * short value is itself — so it is safe on every driver. Smallest `p` in 1..9
+ * with `fround(toPrecision(p)) === fround(value)`; nine significant digits
+ * always identify a float32. `±0`, NaN and ±Infinity pass through.
+ */
+export declare function shortestFloat32(params: {
+    value: number;
+}): number;
+/**
+ * `Float @db.Real` — a refinement of the Float codec keyed by the native type,
+ * not by the scalar type, so it is not a table row: the runtime routes a
+ * field with `nativeType: "Real"` here. Decode = {@link numberCodec} then
+ * {@link shortestFloat32}. Real aggregates that postgres returns as `real`
+ * (`min`/`max`/`sum`) use it too; `avg` returns double precision and must not.
+ */
+export declare const float32Codec: ScalarCodec;
+/**
+ * Element decoders for a postgres array that arrived as its TEXT literal
+ * (`{1e-07,NULL}`, `{"{\"a\": 1}"}`) — the runtime projects `Float[]`/`Json[]`
+ * as `::text`, and drivers return arrays whose type OID they do not know
+ * (`uuid[]` on bun:sql; `xml[]`, `bit[]`, `citext[]` on node-postgres) as the
+ * literal. Each element is postgres's text output for its type:
+ *
+ * - Boolean `t`/`f`, Bytes `\x` hex and Json text need their own conversion;
+ * - every other scalar's regular postgres codec already accepts the text form
+ *   (`Number("1e-07")`, `Number("NaN")`, `Number("-0")`, BigInt/Decimal text,
+ *   `parseDateTimeText` for `2024-06-01 12:34:56.789+00`), so `null` means
+ *   "decode with the field's own codec".
+ */
+export declare function postgresArrayElementFromText(params: {
+    scalarType: ScalarType;
+}): ((text: string) => unknown) | null;
 /** postgres (and pglite — same wire behaviour). */
 export declare const POSTGRES_CODECS: CodecTable;
 /** sqlite — no boolean, date or json types; everything rides TEXT/INTEGER. */

package/dist/dialect.d.ts

@@ -72,6 +72,14 @@ export type ConflictKeyEquality = {
      * created otherwise, and sqlite's default collating sequence is BINARY);
      * mysql does not, because its server default `utf8mb4_0900_ai_ci` ignores
      * case and accents.
+     *
+     * Consumers: the batched upsert's duplicate-key check
+     * (packages/runtime/src/bulk-upsert.ts) and the relation loader
+     * (packages/runtime/src/relation-loader.ts, `associatesInDatabase`). Where
+     * this is false, a relation key with a `String` member is paired with its
+     * parents by the DATABASE through a key table (`SelectStatement.keyTable`,
+     * mysql only) instead of by JavaScript string equality, which would drop
+     * children whose key the collation equates (`acme` under `Acme`).
      */
     readonly textIsBinaryByDefault: boolean;
     /** Character capacity of the default String column, if bounded. Also consumed by migrate. */
@@ -100,6 +108,15 @@ export type SqlDialect = {
      * member, so composite membership always chunks against `paramBudget`.
      */
     readonly tupleInStrategy: "rowValue" | "expand";
+    /**
+     * 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
+     * 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.
+     */
+    readonly timeOfDayInStrategy: "in" | "equalities";
     /** Upsert clause form. */
     readonly upsertForm: "onConflict" | "onDuplicateKey";
     /** Which equality decides a duplicate conflict key here (batched upsert). */
@@ -136,6 +153,20 @@ export type SqlDialect = {
      * non-native dialects — documented in docs/dialect-notes.md.
      */
     readonly strictMatchStrategy: "native" | "glob" | "binary";
+    /**
+     * `sql.greatest` (NULL-ignoring two-operand maximum): `native` renders
+     * `GREATEST(l, r)`, whose PostgreSQL semantics already ignore NULL; `frame`
+     * binds both operands once in a correlated derived table and compares the
+     * bound columns with CASE (MySQL's GREATEST returns NULL on any NULL, and
+     * SQLite has none). `wrapped-frame` is the frame with each operand in its own
+     * scalar subquery: MySQL 8.4 refuses a derived-table select list that holds a
+     * nested frame beside a direct outer column reference (ER_ILLEGAL_REFERENCE
+     * 1247). In both frames a bare NULL value operand renders as the NULL
+     * literal. Only a node with a nested greatest operand uses a frame; a node
+     * without one keeps the 2.x CASE form (2.x semantics, types and aggregate
+     * scope), which repeats its two operands, so nesting stays linear.
+     */
+    readonly greatestForm: "native" | "frame" | "wrapped-frame";
     /** ORDER BY NULLS FIRST/LAST: native clause or `col IS NULL` emulation term. */
     readonly orderByNullsMode: "native" | "emulate";
     /** Dialects where OFFSET requires a LIMIT clause declare the filler literal. */
@@ -167,6 +198,8 @@ export type SqlDialect = {
      * {@link JsonParamCell} cells and the json-filter operands.
      */
     readonly jsonParamCast: string;
+    /** Physical types for standalone validated scalar values, without column inference. */
+    readonly valueCastTypes: Readonly<Record<ScalarType, string>>;
     /**
      * Statement that reads back the id generated by the previous INSERT, for
      * dialects without RETURNING. `null` where RETURNING covers it. The single
@@ -197,6 +230,19 @@ export type SqlDialect = {
      * rows are grouped by column set into separate statements there (M4).
      */
     readonly rowDefaultKeyword: boolean;
+    /**
+     * 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
+     * `null` where the dialect cannot run one as a single statement.
+     * `dataModifyingCte` is PostgreSQL's `WITH "step" AS (INSERT/UPDATE/DELETE …
+     * RETURNING …) SELECT …` (PGlite included). SQLite and MySQL accept only
+     * SELECT inside WITH, so they are `null`: the runtime keeps its
+     * multi-statement path there (an optimisation, not a feature — plan D4) and
+     * the renderer refuses a chain with `VIBE_UNSUPPORTED_CAPABILITY`. An
+     * internal SQL-shape strategy, deliberately NOT in the public capability
+     * table (review O-11).
+     */
+    readonly statementChain: "dataModifyingCte" | null;
     /**
      * Conservative bound-parameter budget per statement (M7). Hard limits:
      * sqlite errors past SQLITE_MAX_VARIABLE_NUMBER (32766 by default), mysql
@@ -239,6 +285,14 @@ export type SqlDialect = {
     placeholder(params: {
         index: number;
     }): string;
+    /**
+     * Project a JSON document as text while preserving SQL NULL. PostgreSQL
+     * casts to text, MySQL casts to CHAR and SQLite keeps its stored text. The
+     * expression is already rendered SQL, not an identifier or a bound value.
+     */
+    jsonTextProjection(params: {
+        expression: string;
+    }): string;
     /**
      * The database-clock expression for `DbNowMarker` sites: `now()` on
      * postgres, `NOW(6)` on mysql, and on sqlite an ISO-8601 `strftime` whose

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

@@ -5,5 +5,6 @@ import type { RenderedQuery } from "../render.ts";
 export declare function renderPostgresIndexKeys(params: {
     dialect: SqlDialect;
     table?: QualifiedSqlName;
+    namespaces?: readonly string[];
 }): RenderedQuery;
 //# sourceMappingURL=postgres-index-keys.d.ts.map