@vibeorm/sql 5.8.0 → 5.10.0

package/README.md

@@ -18,6 +18,7 @@ Most users never install this directly — it ships as a dependency of [`vibeorm
 - **Dialects**: `postgresDialect`, `sqliteDialect`, `mysqlDialect`, the `SqlDialect` type, and the registry `SQL_DIALECTS` / `getSqlDialect`. A dialect carries `quoteIdent` plus the strategy switches: `= ANY` versus `IN` expansion, `ILIKE` versus `LOWER(...) LIKE LOWER(...)`, the upsert form, `ESCAPE` clause presence, `RETURNING` availability.
 - **Capability tables**: `DIALECT_CAPABILITIES`, `POSTGRES_CAPABILITIES`, `SQLITE_CAPABILITIES`, `MYSQL_CAPABILITIES` — frozen objects consumed by the runtime, migrate, the generator and the E2E harness. A feature a dialect cannot express throws `VIBE_UNSUPPORTED_CAPABILITY` rather than degrading.
 - **Codec tables**: `DIALECT_CODECS`, `POSTGRES_CODECS`, `SQLITE_CODECS`, `MYSQL_CODECS`, `decodeIsNoop`, and the `CodecTable` / `ScalarCodec` / `WireFidelity` types. All per-dialect value encode and decode lives here, in one place, instead of scattered through query builders.
+- **Column types**: `canonicalColumnType({ dialect, scalar, nativeType })` names the column type migrate creates for a field, in the one spelling migrate compares column types by (`"integer"` for `Int`, `@db.Int4` and `@db.Integer` on PostgreSQL); `normalizePostgresNativeType` / `normalizeMysqlNativeType`, the tables `POSTGRES_SCALAR_COLUMN_TYPES`, `MYSQL_SCALAR_COLUMN_TYPES`, `SQLITE_SCALAR_STORAGE_CLASSES` and `POSTGRES_EXACT_EQUIVALENTS` are the pieces. `describeSchema` (`@vibeorm/runtime`) reports each field's `nativeType` with it.
 - **Rendering**: `renderStatement({ dialect, statement })` returns `RenderedQuery` (`{ text, values, returning }`); `renderExpr` and `renderFragment` render sub-parts against a shared `ParamCollector`. Placeholders always come from `ParamCollector`, never from hand-written `$1` or `?`.
 - **LIKE helpers**: `escapeLikePattern`, `escapeGlobPattern`, `containsPattern`, `startsWithPattern`, `endsWithPattern`, `strictMatchPattern`.
 

package/dist/ast.d.ts

@@ -66,6 +66,25 @@ export type ColRef = {
      * without the `dateTruncation` capability refuse it when rendering.
      */
     readonly truncate?: DateTruncation;
+    /**
+     * A `groupBy` expression key read from the column ({@link GroupKeyExpression}):
+     * the text at a JSON path, or a string's leading characters. Like
+     * {@link ColRef.truncate} it is set on the projection (with `alias`, the
+     * key's result name), GROUP BY and ORDER BY refs of one key, which repeat
+     * the identical text: every operand is a validated literal, never a bound
+     * parameter, so PostgreSQL and MySQL match the GROUP BY expression.
+     */
+    readonly groupKey?: GroupKeyExpression;
+    /**
+     * The first non-NULL of these references — `COALESCE("a", "b")` — instead
+     * of the column `name`: the value of an `orderBy: { _coalesce: … }` term.
+     * Each member renders as its own reference, casts included (a sqlite
+     * Decimal member as `CAST(… AS REAL)`, a mysql native enum as its member
+     * index). Set on ORDER BY and comparison refs only. `name` is then
+     * {@link COALESCE_REF_NAME}, never a column of a table, so a reader that
+     * looks a column up by name finds none.
+     */
+    readonly coalesce?: readonly ColRef[];
     /**
      * Projection alias: renders `ref AS "alias"`. PROJECTION-ONLY — filter,
      * order and correlation refs never set it (the renderer ignores it outside
@@ -74,6 +93,15 @@ export type ColRef = {
      */
     readonly alias?: string;
 };
+/**
+ * The `name` of a {@link ColRef.coalesce} reference. The `__vibe_` column
+ * prefix is reserved by schema validation, so no model column carries it.
+ */
+export declare const COALESCE_REF_NAME: string;
+/** A {@link ColRef.coalesce} reference over `members`. */
+export declare function coalesceRef(params: {
+    members: readonly ColRef[];
+}): ColRef;
 /** A {@link ColRef.truncate} request: the calendar unit, the zone that defines the calendar, and the column's storage form. */
 export type DateTruncation = {
     readonly unit: DateTruncationUnit;
@@ -81,6 +109,24 @@ export type DateTruncation = {
     readonly timeZone: string;
     readonly storage: DateTruncationStorage;
 };
+/**
+ * A {@link ColRef.groupKey} expression.
+ *
+ * - `jsonPathText`: the text at an object-key path of a JSON column — a JSON
+ *   string unquoted, a number or boolean in its JSON spelling, JSON `null` and
+ *   a missing path SQL NULL, an object or array its JSON text. Each step reads
+ *   an object member only. `storage: "json"` marks a postgres `json` column,
+ *   read through jsonb like the JSON filters.
+ * - `prefix`: the first `length` characters of a string column.
+ */
+export type GroupKeyExpression = {
+    readonly kind: "jsonPathText";
+    readonly path: readonly string[];
+    readonly storage?: "json";
+} | {
+    readonly kind: "prefix";
+    readonly length: number;
+};
 export type TableRef = {
     readonly name: string;
     /** Explicit fixed PostgreSQL placement; absence preserves existing SQL. */
@@ -92,11 +138,19 @@ export type AggFn = "count" | "avg" | "sum" | "min" | "max";
 /** Reference to an aggregate expression: `COUNT(*)` or `FN("col")`. */
 export type AggRef = {
     readonly fn: "countAll";
+    readonly filter?: SqlExpr;
 } | {
     readonly fn: AggFn;
     readonly column: ColRef;
     /** Native enum MIN/MAX: projections and HAVING return the database label; order keys keep its ordinal. */
     readonly enumOrder?: "value" | "ordinal";
+    /**
+     * Aggregate only the rows the predicate admits: `AGG(x) FILTER (WHERE …)`
+     * or `AGG(CASE WHEN … THEN x END)` per the dialect's
+     * `filteredAggregates` capability. Its parameters bind each time the
+     * aggregate renders (projection, HAVING, ORDER BY), in text order.
+     */
+    readonly filter?: SqlExpr;
 };
 /**
  * One aggregate projection: `FN("col") AS "alias"`. The alias is part of the
@@ -111,10 +165,13 @@ export type AggSelect = {
 };
 /**
  * JSON path predicates (Prisma's Json filter surface). `not` is `equals` with
- * `negate` — there is no separate op. Which ops a dialect can express is
+ * `negate` — there is no separate op. `exists` takes a boolean `value`: the
+ * member at the path (object keys only) is present (its value may be JSON
+ * `null`) or, for `false`, the document is present and the member is not; a
+ * SQL NULL column is unknown for both. Which ops a dialect can express is
  * declared on `SqlDialect.supportedJsonOps` and enforced at render time too.
  */
-export type JsonFilterOp = "equals" | "string_contains" | "string_starts_with" | "string_ends_with" | "array_contains" | "array_starts_with" | "array_ends_with";
+export type JsonFilterOp = "equals" | "exists" | "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
@@ -250,6 +307,8 @@ export type SqlExpr = {
     /** The tested columns, in the subquery's projection order. */
     readonly columns: readonly ColRef[];
     readonly select: SelectStatement;
+    /** The subquery yields at most one row: one column, rendered `"fk" = (SELECT …)`. */
+    readonly single?: true;
 } | {
     readonly kind: "like";
     readonly column: ColRef;
@@ -393,12 +452,20 @@ export type SqlExpr = {
  *
  * `one` renders the constant `1` — the conventional EXISTS projection; it
  * cannot be combined with a column list.
+ *
+ * `exists` asks whether the statement's own FROM and WHERE match a row:
+ * `SELECT EXISTS (SELECT 1 FROM … WHERE …) AS "alias"` — one row, one
+ * boolean-valued column (PostgreSQL `boolean`, SQLite and MySQL `0`/`1`). It
+ * takes no column list, aggregate, grouping, order, paging, lock or join.
  */
 export type SelectExpr = {
     readonly kind: "countAll";
     readonly alias?: string;
 } | {
     readonly kind: "one";
+} | {
+    readonly kind: "exists";
+    readonly alias: string;
 };
 /** Arithmetic applied to a column's current value in an UPDATE ... SET. */
 export type SetOperator = "increment" | "decrement" | "multiply" | "divide";
@@ -517,10 +584,18 @@ export type OrderTerm = OrderByColumn | OrderByAggregate | OrderBySubquery;
 export type LateralJoin = {
     /** Join alias (`__lat_0`) — the outer projection selects `alias.columnAlias`. */
     readonly alias: string;
-    /** Column the aggregated JSON value is exposed under (`__rel_posts`). */
+    /**
+     * Column the aggregated JSON value is exposed under (`__rel_posts`). An
+     * `aggregate` lateral exposes one column per entry of its select's
+     * `aggregates` instead, under each entry's alias.
+     */
     readonly columnAlias: string;
-    /** jsonArray: many rows; jsonObject: one row or NULL; count: a scalar COUNT(*) lateral. */
-    readonly agg: "jsonArray" | "jsonObject" | "count";
+    /**
+     * jsonArray: many rows; jsonObject: one row or NULL; count: a scalar COUNT(*)
+     * lateral; aggregate: one ungrouped row of `aggregates` (no columns), which
+     * an aggregate without GROUP BY returns even over zero rows.
+     */
+    readonly agg: "jsonArray" | "jsonObject" | "count" | "aggregate";
     /**
      * Object output is the SQL-layer default. Positional rows follow the exact
      * select.columns order, using explicit output names (never SELECT *).
@@ -529,6 +604,13 @@ export type LateralJoin = {
      * slot. Consumers must use the SAME projection to decode the payload.
      */
     readonly rowFormat?: "object" | "positional";
+    /**
+     * Positional rows only: output names of `select.columns` the subselect
+     * projects for the statement's own use (an order key the aggregate's ORDER
+     * BY reads, a key a nested lateral correlates on) but the JSON row leaves
+     * out. The row is the remaining columns in `select.columns` order.
+     */
+    readonly hidden?: readonly string[];
     /** The correlated child select — may reference outer columns via table-qualified refs. */
     readonly select: SelectStatement;
 };
@@ -771,6 +853,20 @@ export type KeyRows = {
     /** Encoded tuples; never empty, each exactly `columns.length` long. */
     readonly rows: readonly (readonly unknown[])[];
 };
+/**
+ * `GROUP BY GROUPING SETS (…)` over a select's `groupBy` columns. Each set
+ * lists indexes into `groupBy`; `()` is the grand total. The projection gains
+ * `CASE GROUPING(<every groupBy column>) WHEN <mask> THEN <set index> … END AS
+ * "<indexAlias>"` after the aggregates, so a row names the set that produced
+ * it, and an ORDER BY term may name `indexAlias` as a bare column (an output
+ * column). Dialect `groupingSets` capability: `"groupingSets"` renders any
+ * list, `"rollup"` only the rollup chain of `groupBy` in order (`GROUP BY a,
+ * b WITH ROLLUP`), `"none"` refuses.
+ */
+export type GroupingSets = {
+    readonly sets: readonly (readonly number[])[];
+    readonly indexAlias: string;
+};
 export type SelectStatement = {
     readonly kind: "select";
     readonly table: TableRef;
@@ -850,6 +946,8 @@ export type SelectStatement = {
     readonly fromKeys?: KeyRows;
     readonly where?: SqlExpr;
     readonly groupBy?: readonly ColRef[];
+    /** Grouping sets over `groupBy` — see {@link GroupingSets}. */
+    readonly groupingSets?: GroupingSets;
     /** HAVING predicate — grouped selects; may contain `aggCmp` expressions. */
     readonly having?: SqlExpr;
     readonly orderBy?: readonly OrderTerm[];
@@ -971,7 +1069,37 @@ export type ReturningColumn = string | {
 } | {
     readonly name: string;
     readonly transform: "jsonText";
-} | CaptureReturningColumn;
+} | CaptureReturningColumn | OtherRowReturningColumn | ServerVersionReturningColumn;
+/**
+ * The server's `server_version_num` as text, exposed as `alias`:
+ * `pg_catalog.current_setting('server_version_num') AS "alias"`. Rides a write
+ * whose client does not know the server version yet, so the next statement can
+ * take the form that version allows without a read of its own. Dialects with
+ * the `rowCapture` capability only (the version decides whether it applies).
+ */
+export type ServerVersionReturningColumn = {
+    readonly serverVersion: true;
+    readonly alias: string;
+};
+/**
+ * A RETURNING column read from a row OTHER than the one the statement wrote,
+ * exposed as `alias` and projected like the written row's own column
+ * (`projection`), so one codec decodes both:
+ *
+ * - `from: "old"` — the row as it was before the statement (capability
+ *   `rowCapture`, PostgreSQL 18): `old."col" AS "alias"`, NULL in every column
+ *   for a row the statement inserted;
+ * - `from: { source }` — the joined source of an `UPDATE … FROM` by its alias
+ *   (capability `returningReadsJoinedSource`): `"source"."col" AS "alias"`.
+ */
+export type OtherRowReturningColumn = {
+    readonly from: "old" | {
+        readonly source: string;
+    };
+    readonly name: string;
+    readonly alias: string;
+    readonly projection?: "castText" | "jsonText";
+};
 /**
  * A row-capture RETURNING column (`$transaction(…, { capture })`, dialects with
  * the `rowCapture` capability: PostgreSQL 18, where RETURNING names the row
@@ -982,15 +1110,71 @@ export type ReturningColumn = string | {
  *   inserted row, `new` for a deleted one);
  * - `"inserted"`: `(old."col" IS NULL) AS "alias"` — the arm of an `INSERT …
  *   ON CONFLICT DO UPDATE` row, true when it was inserted (`col` must be a
- *   column no stored row holds NULL in: a primary-key column).
+ *   column no stored row holds NULL in: a primary-key column);
+ * - `"old"` / `"new"` with `hop`: the related row's column, read in the same
+ *   statement — `(SELECT "__vibe_h"."col"::text FROM "Related" AS "__vibe_h"
+ *   WHERE "__vibe_h"."id" = new."relatedId") AS "alias"` (see {@link CaptureHop});
+ * - `"key"`: `old."col" AS "alias"` in the column's own type, for a chain's
+ *   {@link CaptureCascade} to match child rows on;
+ * - `"cascade"` ({@link CaptureCascadeReturningColumn}): the images of the
+ *   child rows a referential action of this row changes.
  */
 export type CaptureReturningColumn = {
-    readonly capture: "old" | "new" | "inserted";
+    readonly capture: "old" | "new" | "inserted" | "key";
     readonly name: string;
     readonly alias: string;
+    /** With `"old"` / `"new"`: read `name` from the related row instead of this one. */
+    readonly hop?: CaptureHop;
+} | CaptureCascadeReturningColumn;
+/**
+ * A to-one hop of a capture cell: the row of `table` whose `on[i].target`
+ * columns equal the reading row's `on[i].source` columns. The target columns
+ * must be a unique key (a scalar subquery that found two rows would fail the
+ * statement); no row, or a NULL source column, reads NULL.
+ */
+export type CaptureHop = {
+    readonly table: TableRef;
+    readonly on: readonly {
+        readonly target: string;
+        readonly source: string;
+    }[];
+};
+/** One cell of a {@link CaptureCascade} image: a child column, or a column of its related row. */
+export type CaptureCell = {
+    readonly name: string;
+    readonly hop?: CaptureHop;
+};
+/**
+ * The distinct images of the child rows of `table` whose `on[i].child` columns
+ * equal a written parent row's `on[i].parent` columns: `(SELECT
+ * array_agg("__vibe_i")::text FROM (SELECT DISTINCT ARRAY[<cells>] AS "__vibe_i"
+ * FROM "Child" AS "__vibe_c" WHERE <match> LIMIT $n) AS "__vibe_d")`, NULL when
+ * no child matched. Read inside the parent's statement, whose snapshot still
+ * holds the rows its foreign keys' referential actions remove or rewrite at
+ * the statement's end. `limit` is bound as a parameter.
+ */
+export type CaptureCascade = {
+    readonly table: TableRef;
+    readonly on: readonly {
+        readonly child: string;
+        readonly parent: string;
+    }[];
+    readonly cells: readonly CaptureCell[];
+    readonly limit: number;
+};
+/**
+ * A per-row {@link CaptureCascade} in RETURNING: `parent` columns are read from
+ * `old.` (`"__vibe_c"."child" = old."parent"`).
+ */
+export type CaptureCascadeReturningColumn = {
+    readonly capture: "cascade";
+    readonly alias: string;
+    readonly cascade: CaptureCascade;
 };
 /** The column name a {@link ReturningColumn} exposes in the result row. */
 export declare function returningColumnName(column: ReturningColumn): string;
+/** Is this RETURNING column read from another row ({@link OtherRowReturningColumn})? */
+export declare function isOtherRowReturningColumn(column: ReturningColumn): column is OtherRowReturningColumn;
 /** Is this RETURNING column a row-capture column ({@link CaptureReturningColumn})? */
 export declare function isCaptureReturningColumn(column: ReturningColumn): column is CaptureReturningColumn;
 export type InsertStatement = {
@@ -1053,6 +1237,42 @@ export type OnConflictUpdate = {
      * mysql's ODKU has no WHERE and refuses it (`VIBE_UNSUPPORTED_CAPABILITY`).
      */
     readonly updateWhere?: SqlExpr;
+    /**
+     * Skip-unchanged guard: the conflicting row is updated only when at least
+     * one of these columns' stored value differs, NULL counting as a value,
+     * from the value its `update` assignment would write (each column must have
+     * one). Rendered as the first member of the update arm's `WHERE`, AND-ed
+     * with {@link OnConflictUpdate.updateWhere}; a skipped row writes nothing
+     * and returns nothing. On ON DUPLICATE KEY UPDATE (no WHERE) the columns it
+     * leaves out are assigned first, keeping their stored value when nothing
+     * else would change, and the dialect itself skips the unchanged row.
+     * Needs `upsertSkipUnchanged`.
+     */
+    readonly skipUnchanged?: readonly UnchangedColumn[];
+    /**
+     * The table's native row-security predicate, RAW SQL without parameters
+     * (the managed policy's check, columns qualified by the target table's
+     * name). With a guard on the arm ({@link OnConflictUpdate.updateWhere} or
+     * {@link OnConflictUpdate.skipUnchanged}) the arm's `WHERE` becomes
+     * `(<policy>) IS NOT TRUE OR (<guard>)`: PostgreSQL evaluates that `WHERE`
+     * before its row-security check of the conflicting row, so a row the policy
+     * hides must always take the update path and fail that check, whatever its
+     * values. Ignored when the arm has no guard; refused by a dialect without
+     * `nativeRowLevelSecurity`.
+     */
+    readonly rowPolicy?: string;
+    /**
+     * MySQL only, a single-row statement: the duplicate arm also runs
+     * `` `column` = IF(LAST_INSERT_ID(flag), `t`.`column`, `t`.`column`) `` (a
+     * self-assignment, rendered last), so the statement reports `flag` as its
+     * insert id exactly when the row took the update arm — the one signal that
+     * tells an inserted row from an unchanged one when the driver reports no
+     * `Duplicates:` info. `flag` is a decimal literal.
+     */
+    readonly duplicateFlag?: {
+        readonly column: string;
+        readonly flag: string;
+    };
     /**
      * MySQL only (`upsertForm: "onDuplicateKey"`): append
      * `` `col` = LAST_INSERT_ID(`col`) `` to the update list so the UPDATE arm
@@ -1062,6 +1282,41 @@ export type OnConflictUpdate = {
      */
     readonly lastInsertIdColumn?: string;
 };
+/**
+ * One column a skip-unchanged conflict arm compares. `json`: a Json column,
+ * compared as `jsonb` on postgres (its `json` type has no equality operator;
+ * `"list"` for a Json list).
+ */
+export type UnchangedColumn = {
+    readonly column: string;
+    readonly json?: "scalar" | "list";
+    /**
+     * A column whose SQL equality can be coarser than "the stored value would
+     * not change"; the renderer compares it exactly where the dialect needs it.
+     * See {@link UnchangedExactness}.
+     */
+    readonly bytes?: UnchangedExactness;
+    /**
+     * A text column the schema declares with a folding type or collation
+     * (`citext`, a `@collation` that is not byte-ordered): its equality may call
+     * `'x'` and `'X'` equal on any dialect, not only under MySQL's default.
+     */
+    readonly folds?: true;
+    /** The column is a list of `bytes`'s kind (a postgres array). */
+    readonly list?: true;
+};
+/**
+ * Why a compared column's own equality may call two different stored values
+ * equal:
+ * - `"text"`: a text column; MySQL's default `_ai_ci` collation folds case
+ *   and accents (and see `folds`).
+ * - `"decimal"`: a Decimal column without a declared scale (PostgreSQL's bare
+ *   `numeric` keeps `1.50` and `1.5` apart, its equality does not).
+ * - `"float"`: a float column (`-0` equals `0`).
+ * - `"other"`: a Json or list column, or a text-like column of another
+ *   declared type, compared by its bytes on MySQL.
+ */
+export type UnchangedExactness = "text" | "decimal" | "float" | "other";
 /**
  * Conflicting rows are skipped (`createMany({ skipDuplicates: true })`).
  * An empty/absent target means "any conflict" — the mysql form
@@ -1236,11 +1491,24 @@ export declare function stepColumnRef(params: {
     column: string;
 }): StepColumnRef;
 /** The joined relation of an {@link UpdateStatement}: its table, alias and join condition. */
-export type UpdateSource = {
+export type UpdateSource = UpdateTableSource | UpdateSelectSource;
+/** A joined table: `FROM "table" AS alias` (`updateMany({ from })`). */
+export type UpdateTableSource = {
     readonly table: TableRef;
     readonly alias: string;
     readonly on: SqlExpr;
 };
+/**
+ * A joined subquery: `FROM (SELECT …) AS alias`, PostgreSQL only. With a
+ * locking read of the target table it is the row as it was before the write,
+ * and an {@link OtherRowReturningColumn} `from: { source: alias }` returns its
+ * values (`update({ previous })`, capability `returningReadsJoinedSource`).
+ */
+export type UpdateSelectSource = {
+    readonly select: SelectStatement;
+    readonly alias: string;
+    readonly on: SqlExpr;
+};
 /** An UPDATE set value read from the joined source's `column` (`UPDATE … FROM`). */
 export type SourceColumnRef = {
     readonly __sourceColumn: true;
@@ -1367,6 +1635,15 @@ export type ChainResult = {
      * guard, so it is evaluated exactly once, on the one guaranteed result row.
      */
     readonly veto?: readonly ChainVeto[];
+    /**
+     * A step whose rows every veto depends on: when it returned no row, no veto
+     * is checked and the statement succeeds, answering the one guaranteed row
+     * with NULL columns and the tally (rendered as the first CASE arm, `WHEN NOT
+     * EXISTS (SELECT 1 FROM "step") THEN <tally>`). A nested write whose
+     * missing parent is an answer, not an error, gates its children's vetoes on
+     * the parent step this way. Requires `tally` and at least one veto.
+     */
+    readonly vetoGate?: string;
     /**
      * One column `alias` on every result row: the number of rows the listed
      * data-modifying steps returned (their RETURNING rows = their direct
@@ -1412,6 +1689,13 @@ export type ChainCapture = {
     readonly after?: readonly string[];
     /** The most distinct images one image column returns: a positive safe integer, bound as a parameter. */
     readonly limit: number;
+    /**
+     * Child images of the step's rows, one result column `<alias>_c<j>` each: a
+     * {@link CaptureCascade} whose `parent` columns name columns the step
+     * RETURNS, matched by `EXISTS (SELECT 1 FROM "step" AS "__vibe_k" WHERE
+     * "__vibe_k"."parent" = "__vibe_c"."child")`.
+     */
+    readonly cascades?: readonly CaptureCascade[];
 };
 /**
  * Fail the statement when `step` returned no row; `token` names the veto in the

package/dist/codecs.d.ts

@@ -76,15 +76,30 @@ export type WireFidelity = {
      */
     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).
+     * The zone the driver reads zone-less date-time text in (MySQL DATETIME /
+     * TIMESTAMP / DATE): `"utc"` (mysql2 with `timezone: "Z"`), a fixed offset
+     * in minutes east of UTC, or `"local"` (the process zone, read the way
+     * mysql2 builds a local `Date`). The MySQL DateTime decoders read the same
+     * text in the same zone wherever it arrives as text (the join strategy's
+     * JSON, a page key, `exactDates`), so one stored cell is one instant on every
+     * path; the adapter writes a bound parameter in it. Absent reads as UTC.
+     * Never prunes a decoder. `"utc"` alone also lets a dialect default of
+     * `"join"` apply (`lateralJson.requiresUtcDateTimeWire`): it is declared only
+     * where the zone is known to be UTC.
      */
-    readonly zoneLessDateTime?: "utc";
+    readonly zoneLessDateTime?: DateTimeZone;
 };
+/** A zone zone-less date-time text is read in: UTC, a fixed offset in minutes east of UTC, or the process's local zone. */
+export type DateTimeZone = "utc" | "local" | {
+    readonly offsetMinutes: number;
+};
+/**
+ * The cache-key fragment of a wire's date-time zone: `""` when zone-less text
+ * reads as UTC, so every UTC plan keeps its key; else `"local"` or the offset.
+ */
+export declare function dateTimeZoneKey(params: {
+    wire: WireFidelity | undefined;
+}): string;
 /**
  * Is this scalar type's DECODE a no-op under the declared wire fidelity?
  * Provable against the decode implementations in this file, identically on
@@ -115,7 +130,8 @@ export declare function decodeIsNoop(params: {
     wire: WireFidelity | undefined;
 }): boolean;
 /**
- * Parse date-time text into a `Date`, reading ZONE-LESS text as **UTC**.
+ * Parse date-time text into a `Date`, reading ZONE-LESS text as **UTC** — for
+ * text a CALLER wrote (a filter or data value, a validator's check).
  *
  * ECMA-262 reads `2026-01-15T12:00:00` as process-LOCAL time, so the same
  * stored value would decode to a different instant on every host time zone,
@@ -124,9 +140,12 @@ export declare function decodeIsNoop(params: {
  * that yields ONE instant everywhere (MYSQL-2, live-proven; the postgres
  * `timestamp` case is proven by apps/tests `timestamp-zones.e2e`). Text with
  * an explicit `Z`/offset and date-only text parse as ECMA-262 already reads
- * them (as written / UTC midnight); anything unparseable is `undefined` so the
- * caller keeps its own fallback. Fractions beyond milliseconds are truncated —
- * `Date` has no finer resolution and engines differ on longer fractions.
+ * them (as written / UTC midnight); any other form the engine reads
+ * (`Jan 15 2026 12:00 GMT`) is accepted as the engine reads it, and
+ * anything unparseable is `undefined` so the caller keeps its own fallback.
+ * Fractions beyond milliseconds are truncated — `Date` has no finer
+ * resolution and engines differ on longer fractions. Text from the DATABASE
+ * never takes that last, guessing step ({@link parseDatabaseDateTime}).
  */
 export declare function parseDateTimeText(params: {
     text: string;
@@ -144,11 +163,14 @@ export declare function parseDateTimeText(params: {
  * 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
+ * had, unless `anyYear` (the database-text parser, after its other forms
+ * declined: an offset with seconds) — 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;
+    anyYear?: boolean;
 }): Date | undefined;
 /**
  * The decode refusal of a non-finite or unparseable DateTime — one error for
@@ -157,6 +179,78 @@ export declare function parseExtendedDateTimeText(params: {
  * reports exactly this error.
  */
 export declare function decodedDateTimeRefusal(): VibeError;
+/**
+ * The refusal of database date-time text no decoder reads, by its cause —
+ * each with its own `meta.reason`, so the message names the right remedy:
+ *
+ * - `"zero-date"`: a MySQL zero date or a zero month or day, which has no
+ *   instant (mysql2 renders a binary zero `DATETIME` as `undefined 00:00:00`);
+ * - `"datetime-out-of-range"`: ISO-shaped text with no `Date` (a year past
+ *   ±275760, `294276-12-31` in PostgreSQL, or a day the calendar lacks);
+ * - `"datetime-text-layout"`: any other layout; on PostgreSQL its cause is a
+ *   `DateStyle` other than ISO, and the error names that remedy
+ *   ({@link dateTimeTextLayoutError}).
+ *
+ * The text itself is never included.
+ */
+export declare function undecodableDateTimeText(params: {
+    text: string;
+    dialect: Dialect;
+}): VibeError;
+/**
+ * The refusal for database DateTime text outside the ISO layouts. On
+ * PostgreSQL its cause is a `DateStyle` other than ISO, set by the server,
+ * the database or the role; the message and `meta.fix` name the remedies.
+ * The text itself is never included.
+ */
+export declare function dateTimeTextLayoutError(): VibeError;
+/**
+ * The codec of a DateTime field whose native type is a date-only column on
+ * `dialect`, or `undefined` (the DateTime table row applies): MySQL's
+ * `@db.Date` ({@link mysqlDateOnlyCodec}). PostgreSQL's `date` input and
+ * SQLite's text need none.
+ */
+export declare function dateOnlyCodec(params: {
+    dialect: Dialect;
+    nativeType: string | undefined;
+}): ScalarCodec | undefined;
+/**
+ * The instant of zone-less date-time text a MySQL server printed (`DATETIME`,
+ * `DATE`, a `TIMESTAMP` in the session zone), read in `zone`, the zone mysql2
+ * reads the same cell in; the years 0-99 keep their year. `undefined` for any
+ * other text. For the adapter's raw path; ORM reads take the codec table.
+ */
+export declare function parseZoneLessDateTime(params: {
+    text: string;
+    zone: DateTimeZone | undefined;
+}): Date | undefined;
+/**
+ * `codec` as it reads under the adapter's declared zone
+ * (`wire.zoneLessDateTime`): a MySQL DateTime or date-only codec reads
+ * zone-less text in that zone when it is not UTC; every other codec, and every
+ * codec under UTC, is returned unchanged. Encode is never changed: a `Date`
+ * goes to the driver, which writes it in the same zone.
+ */
+export declare function zonedCodec(params: {
+    dialect: Dialect;
+    codec: ScalarCodec;
+    wire: WireFidelity | undefined;
+}): ScalarCodec;
+/**
+ * The text a MySQL adapter writes for a parameter the DateTime codec bound
+ * exactly (a `Date` read from the server's text, which carries more fraction
+ * digits than a `Date` holds): the wall clock it was read from when that text,
+ * read in `zone`, is this instant (so a wall clock in a daylight-saving gap
+ * under `"local"` addresses its own cell); else the instant's wall clock in
+ * `zone` (text with an offset, or read in another zone). Every fraction digit
+ * is kept, and at least three are written. `undefined` for every other value,
+ * which the driver writes as it always did. A keyset position over such a
+ * value carries the same text.
+ */
+export declare function mysqlBoundTimestampText(params: {
+    value: unknown;
+    zone: DateTimeZone | undefined;
+}): string | 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