@vibeorm/sql 2.0.0-alpha.1

package/README.md

@@ -0,0 +1,58 @@
+# @vibeorm/sql
+
+> Part of **[VibeORM](https://github.com/vibeorm/vibeorm)** — a type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
+
+The dialect-aware SQL layer. Every decision about SQL *text* — quoting, placeholders, per-dialect strategy switches, value encoding — lives in this package, so the runtime and migrate build a dialect-neutral AST and never concatenate SQL themselves.
+
+```bash
+bun add @vibeorm/sql@alpha
+```
+
+> **Pre-release.** `2.0.0-alpha.x`, published under the `alpha` dist-tag. `npm i vibeorm` still resolves to the stable v1 line.
+
+Most users never install this directly — it ships as a dependency of [`vibeorm`](https://www.npmjs.com/package/vibeorm). Reach for it when you are building tooling on the IR or SQL layer.
+
+## What it exports
+
+- **SQL AST**: `SqlStatement` (`SelectStatement`, `InsertStatement`, `UpdateStatement`, `DeleteStatement`) and `SqlExpr`, plus the supporting node types `ColRef`, `TableRef`, `SelectExpr`, `OrderTerm`, `AggRef`, `AggSelect`, `LateralJoin`, `InnerJoin`, `OnConflictClause`, `SetOperation`, `ListSetOperation`, `RowNumberProjection`. Guards: `isSetOperation`, `isListSetOperation`, `isSqlDefaultCell`, and the `SQL_DEFAULT_CELL` marker.
+- **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.
+- **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`.
+
+## Rendering an AST
+
+```ts
+import { postgresDialect, renderStatement, sqliteDialect } from "@vibeorm/sql";
+import type { SqlStatement } from "@vibeorm/sql";
+
+const statement: SqlStatement = {
+  kind: "select",
+  table: { name: "User" },
+  columns: [{ name: "id" }, { name: "email" }],
+  where: { kind: "cmp", op: "eq", column: { name: "id" }, value: 1 },
+};
+
+renderStatement({ dialect: postgresDialect, statement });
+// { text: `SELECT "id", "email" FROM "User" WHERE "id" = $1`, values: [1], ... }
+
+renderStatement({ dialect: sqliteDialect, statement });
+// { text: `SELECT "id", "email" FROM "User" WHERE "id" = ?`, values: [1], ... }
+```
+
+The `returning` field reports `"native"` when `RETURNING` was rendered, `"omitted"` when it was requested but the dialect lacks it (the caller re-selects), and `"none"` when it was not requested.
+
+## Reviewable SQL
+
+Every statement shape this package can emit is pinned to its exact SQL text and parameters, per dialect, in [`sql-catalog.md`](https://github.com/vibeorm/vibeorm/blob/master/sql-catalog.md). The file is generated from test-asserted cases (`tests/catalog/cases.ts`), so it cannot drift from the renderers.
+
+Adding or changing a rendering means adding or updating a catalog case in the same change; `bun run catalog:check` enforces that in CI. Reviewing the catalog diff is how wrong quoting, bad placeholder order or dialect drift becomes visible without running a database.
+
+## Links
+
+- [Documentation](https://github.com/vibeorm/vibeorm/tree/master/docs)
+- [Getting started](https://github.com/vibeorm/vibeorm/blob/master/docs/getting-started.md)
+- [Dialect support tables](https://github.com/vibeorm/vibeorm/blob/master/docs/dialects.md)
+- [Repository and issues](https://github.com/vibeorm/vibeorm)
+- MIT licensed

package/dist/ast.d.ts

@@ -0,0 +1,474 @@
+/**
+ * The SQL AST — the small statement language the runtime and migrate packages
+ * build and dialects render.
+ *
+ * Deliberately minimal at P0 (single-table statements, no joins/subqueries);
+ * 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 { SqlFragmentSpec } from "@vibeorm/schema";
+/** A column reference, optionally table-qualified. */
+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.
+     */
+    readonly transform?: "castText" | "encodeBase64";
+    /**
+     * Comparison/order/aggregate cast, sqlite Decimal only (SQL review B4):
+     * Decimal stores as exact TEXT there and text comparison is lexicographic —
+     * compare, ORDER BY and aggregate sites render `CAST("col" AS REAL)` (with
+     * NUMBER operands) instead. Never set on projections or GROUP BY keys, so
+     * storage and read-back stay the exact text.
+     */
+    readonly castReal?: boolean;
+    /**
+     * Projection alias: renders `ref AS "alias"`. PROJECTION-ONLY — filter,
+     * order and correlation refs never set it (the renderer ignores it outside
+     * a projection list). Used by the single-statement M2M join to expose the
+     * join table's parent-key column under a reserved name (`__vibe_parent`).
+     */
+    readonly alias?: string;
+};
+export type TableRef = {
+    readonly name: string;
+    readonly alias?: string;
+};
+/** Aggregate functions applied to one column. */
+export type AggFn = "count" | "avg" | "sum" | "min" | "max";
+/** Reference to an aggregate expression: `COUNT(*)` or `FN("col")`. */
+export type AggRef = {
+    readonly fn: "countAll";
+} | {
+    readonly fn: AggFn;
+    readonly column: ColRef;
+};
+/**
+ * One aggregate projection: `FN("col") AS "alias"`. The alias is part of the
+ * catalog contract — the runtime derives result keys from it deterministically
+ * (`_count___all`, `_avg__score`), never by parsing the SQL text back.
+ */
+export type AggSelect = {
+    readonly agg: AggRef;
+    readonly alias: string;
+};
+/**
+ * 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
+ * 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 ComparisonOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+export type SqlExpr = {
+    readonly kind: "cmp";
+    readonly op: ComparisonOp;
+    readonly column: ColRef;
+    readonly value: unknown;
+}
+/** Column-to-column comparison — the correlation predicate of EXISTS/lateral subqueries. */
+ | {
+    readonly kind: "cmpCol";
+    readonly op: ComparisonOp;
+    readonly left: ColRef;
+    readonly right: ColRef;
+} | {
+    readonly kind: "isNull";
+    readonly column: ColRef;
+    readonly negate?: boolean;
+} | {
+    readonly kind: "inArray";
+    readonly column: ColRef;
+    readonly values: readonly unknown[];
+    readonly negate?: boolean;
+} | {
+    readonly kind: "like";
+    readonly column: ColRef;
+    /** Pre-built pattern (see like.ts helpers for escaping). */
+    readonly pattern: string;
+    readonly insensitive?: boolean;
+    readonly negate?: boolean;
+}
+/**
+ * Case-SENSITIVE string match (`mode: "strict"`, board #20). `value` is the
+ * RAW operand — pattern building happens at render time because escaping
+ * differs per strategy (LIKE's `%`/`_`/`\` vs GLOB's `*`/`?`/`[`). Renders
+ * per `SqlDialect.strictMatchStrategy`: plain `=`/`LIKE` on postgres
+ * (already byte-sensitive — a deliberate, documented no-op), `=`/`GLOB` on
+ * sqlite, `= CAST(? AS BINARY)`/`LIKE CAST(? AS BINARY)` on mysql. The
+ * non-native forms defeat plain indexes; docs/dialect-notes.md carries the
+ * cost and the functional/`_bin`-index mitigation.
+ */
+ | {
+    readonly kind: "strictMatch";
+    readonly column: ColRef;
+    readonly op: "equals" | "contains" | "startsWith" | "endsWith";
+    readonly value: string;
+    readonly negate?: boolean;
+} | {
+    readonly kind: "and";
+    readonly operands: readonly SqlExpr[];
+} | {
+    readonly kind: "or";
+    readonly operands: readonly SqlExpr[];
+} | {
+    readonly kind: "not";
+    readonly operand: SqlExpr;
+}
+/**
+ * Correlated subquery test: `[NOT] EXISTS (SELECT …)`. The inner select
+ * correlates to the outer scope through table-qualified `cmpCol` predicates;
+ * its parameters merge into the statement's single parameter sequence in
+ * render order. Relation filters (`some`/`every`/`none`/`is`/`isNot`)
+ * compile to this shape.
+ */
+ | {
+    readonly kind: "exists";
+    readonly select: SelectStatement;
+    readonly negate?: boolean;
+}
+/** Aggregate comparison — the HAVING predicate: `COUNT("col") > $n`. */
+ | {
+    readonly kind: "aggCmp";
+    readonly op: ComparisonOp;
+    readonly agg: AggRef;
+    readonly value: unknown;
+}
+/**
+ * Scalar-list membership: `$n = ANY("col")` — Prisma's `has`. Postgres only
+ * (`capabilities.scalarArrays`); other dialects refuse at render time.
+ */
+ | {
+    readonly kind: "arrayHas";
+    readonly column: ColRef;
+    readonly value: unknown;
+    readonly negate?: boolean;
+}
+/** Scalar-list superset: `"col" @> $n` (one array param) — Prisma's `hasEvery`. Postgres only. */
+ | {
+    readonly kind: "arrayContainsAll";
+    readonly column: ColRef;
+    readonly values: readonly unknown[];
+}
+/** Scalar-list overlap: `"col" && $n` (one array param) — Prisma's `hasSome`. Postgres only. */
+ | {
+    readonly kind: "arrayOverlaps";
+    readonly column: ColRef;
+    readonly values: readonly unknown[];
+}
+/**
+ * Scalar-list emptiness via `array_length("col", 1) IS [NOT] NULL` — the v1
+ * semantics kept deliberately: `empty: true` matches NULL **and** empty
+ * arrays, `empty: false` matches only rows with at least one element.
+ */
+ | {
+    readonly kind: "arrayIsEmpty";
+    readonly column: ColRef;
+    readonly empty: boolean;
+}
+/**
+ * JSON path predicate. The path is always BOUND as a parameter (a `text[]`
+ * on postgres, a `$.a.b[0]` path string on sqlite/mysql) — path segments
+ * never become SQL text. `value` is the RAW JS operand; each dialect decides
+ * its wire form (JSON.stringify for jsonb/json comparisons, LIKE patterns
+ * for the string ops). `insensitive` applies to the string ops only.
+ */
+ | {
+    readonly kind: "jsonFilter";
+    readonly column: ColRef;
+    readonly path: readonly (string | number)[];
+    readonly op: JsonFilterOp;
+    readonly value: unknown;
+    readonly insensitive?: boolean;
+    readonly negate?: boolean;
+}
+/**
+ * A bound extension fragment: literal text, bound parameters and quoted
+ * identifiers in order (extensions.md §3 sql plane — trgm operators, rank
+ * and distance terms). Parameters flow through the shared ParamCollector,
+ * identifiers through dialect.quoteIdent — never hand-written.
+ */
+ | {
+    readonly kind: "fragment";
+    readonly fragment: SqlFragmentSpec;
+}
+/** Escape hatch for dialect-reviewed fragments. Text only — no parameters. */
+ | {
+    readonly kind: "raw";
+    readonly text: string;
+};
+/**
+ * An aggregate projection.
+ *
+ * `countAll` renders `COUNT(*)`. The alias matters for portability: postgres
+ * names the bare column `count`, sqlite and mysql name it `COUNT(*)` — callers
+ * that must read the value back always pass an alias. Combined with a
+ * non-empty `columns` list (grouped counts, `SELECT "fk", COUNT(*) … GROUP
+ * BY "fk"`), it renders AFTER the columns.
+ *
+ * `one` renders the constant `1` — the conventional EXISTS projection; it
+ * cannot be combined with a column list.
+ */
+export type SelectExpr = {
+    readonly kind: "countAll";
+    readonly alias?: string;
+} | {
+    readonly kind: "one";
+};
+/** Arithmetic applied to a column's current value in an UPDATE ... SET. */
+export type SetOperator = "increment" | "decrement" | "multiply" | "divide";
+/**
+ * An atomic update expression: `"col" = "col" <op> $n`.
+ *
+ * Recognised structurally inside `UpdateStatement.set`, so the marker key is
+ * deliberately unlikely (`__op`). Three layers keep a user's JSON payload from
+ * ever being mistaken for one: the Json codec stringifies JSON values before
+ * they reach the AST, the query builder only emits this shape for numeric
+ * fields, and {@link isSetOperation} demands an exact two-key object.
+ */
+export type SetOperation = {
+    readonly __op: SetOperator;
+    readonly value: number;
+};
+/** Narrow an UPDATE set value to an atomic {@link SetOperation}. */
+export declare function isSetOperation(value: unknown): value is SetOperation;
+/**
+ * A scalar-list update expression (Prisma's `{ push: … }` on list columns):
+ * `append` is one element (`"col" = array_append("col", $n)`), `concat` an
+ * array of elements (`"col" = "col" || $n`). Postgres only — the query builder
+ * gates on `capabilities.scalarArrays` at build time and the renderer refuses
+ * too. Same structural-marker discipline as {@link SetOperation}: the key is
+ * unlikely, the shape exact, and Json payloads are stringified before they
+ * could ever reach an UPDATE set.
+ */
+export type ListSetOperation = {
+    readonly __listOp: "append" | "concat";
+    readonly value: unknown;
+};
+/** Narrow an UPDATE set value to a {@link ListSetOperation}. */
+export declare function isListSetOperation(value: unknown): value is ListSetOperation;
+/** ORDER BY a column, with optional NULLS placement (native or emulated per dialect). */
+export type OrderByColumn = {
+    readonly column: ColRef;
+    readonly direction: "asc" | "desc";
+    /** NULLS placement; rendered natively or emulated per dialect. */
+    readonly nulls?: "first" | "last";
+};
+/** ORDER BY an aggregate expression — grouped selects ordering by `COUNT("col")`. */
+export type OrderByAggregate = {
+    readonly agg: AggRef;
+    readonly direction: "asc" | "desc";
+};
+/**
+ * ORDER BY a correlated scalar subquery — relation orderBy
+ * (`orderBy: { posts: { _count: "desc" } }` → `(SELECT COUNT(*) …)` /
+ * `orderBy: { author: { email: "asc" } }` → `(SELECT "email" …)`).
+ * Portable: all three dialects order by scalar subqueries. The subquery
+ * correlates to the outer scope through table-qualified `cmpCol` predicates,
+ * exactly like `exists`; its parameters merge into the statement's single
+ * sequence in render order. NULLS placement is deliberately unsupported here
+ * (emulating it would render the subquery twice and duplicate its params) —
+ * missing relations sort at each engine's native NULL position.
+ */
+export type OrderBySubquery = {
+    readonly select: SelectStatement;
+    readonly direction: "asc" | "desc";
+};
+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`).
+ *
+ * Renders (agg `jsonArray`):
+ *   `LEFT JOIN LATERAL (SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb)
+ *    AS "columnAlias" FROM (<select>) AS "__sub") AS "alias" ON true`
+ * and (agg `jsonObject`):
+ *   `LEFT JOIN LATERAL (SELECT to_jsonb("__sub".*) AS "columnAlias"
+ *    FROM (<select>) AS "__sub") AS "alias" ON true`
+ *
+ * `to_jsonb` over a subselect (not `json_build_object`) sidesteps postgres's
+ * 100-argument function limit on wide models (v1 lesson). The inner select's
+ * ORDER BY drives the aggregate's element order. Consumers must run the codec
+ * table over the parsed JSON children: `to_jsonb` turns timestamps into
+ * strings and loses BigInt-ness (LEARNINGS).
+ */
+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`). */
+    readonly columnAlias: string;
+    /** `jsonArray` for to-many (aggregated array), `jsonObject` for to-one (LIMIT 1 row or NULL). */
+    readonly agg: "jsonArray" | "jsonObject";
+    /** The correlated child select — may reference 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
+ * single-statement implicit-M2M load (child rows joined to their join-table
+ * membership rows); extra join-table columns project through the statement's
+ * `columns` list with a table qualifier + `alias`.
+ */
+export type InnerJoin = {
+    readonly table: TableRef;
+    /** Equality pairs ANDed into the ON clause; never empty. */
+    readonly on: readonly {
+        readonly left: ColRef;
+        readonly right: ColRef;
+    }[];
+};
+/**
+ * A `ROW_NUMBER() OVER (PARTITION BY … [ORDER BY …]) AS "alias"` projection,
+ * appended after `columns` — the distinct emulation on dialects without
+ * `DISTINCT ON` (sqlite ≥3.25, mysql ≥8.0 both have window functions): the
+ * outer statement filters `alias = 1` on the derived table, restoring
+ * SQL-side take/skip and bounded transfer (N10).
+ */
+export type RowNumberProjection = {
+    readonly partitionBy: readonly ColRef[];
+    /** Intra-partition order picking the representative row; may be empty. */
+    readonly orderBy: readonly OrderTerm[];
+    readonly alias: string;
+};
+export type SelectStatement = {
+    readonly kind: "select";
+    readonly table: TableRef;
+    /** Empty array renders as `SELECT *` (unless `selectExpr` replaces it). */
+    readonly columns: readonly ColRef[];
+    /**
+     * Aggregate projection. Replaces the column list when `columns` is empty;
+     * a `countAll` with columns renders after them (grouped counts).
+     */
+    readonly selectExpr?: SelectExpr;
+    /**
+     * Aliased aggregate projections (`AVG("col") AS "_avg__col"`), rendered
+     * after `columns` — the aggregate/groupBy/count-select shapes. Cannot be
+     * combined with `selectExpr`.
+     */
+    readonly aggregates?: readonly AggSelect[];
+    /**
+     * `SELECT DISTINCT ON (cols)` — postgres only (`capabilities.distinctOn`;
+     * other dialects refuse at render time and the runtime emulates client-side
+     * instead). ORDER BY must lead with these columns; the query builder
+     * guarantees that arrangement.
+     */
+    readonly distinctOn?: readonly ColRef[];
+    /**
+     * 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}. */
+    readonly lateralJoins?: readonly LateralJoin[];
+    /** Plain equality INNER JOINs — portable, see {@link InnerJoin}. */
+    readonly innerJoins?: readonly InnerJoin[];
+    /** ROW_NUMBER window projection — see {@link RowNumberProjection}. */
+    readonly rowNumber?: RowNumberProjection;
+    readonly where?: SqlExpr;
+    readonly groupBy?: readonly ColRef[];
+    /** HAVING predicate — grouped selects; may contain `aggCmp` expressions. */
+    readonly having?: SqlExpr;
+    readonly orderBy?: readonly OrderTerm[];
+    readonly limit?: number;
+    readonly offset?: number;
+    /**
+     * Row-locking read (`SELECT … FOR UPDATE`) — the overlay flows on dialects
+     * without RETURNING read a row they are about to write. Rendered only where
+     * the dialect names a lock clause (`dialect.selectForUpdate`); sqlite has
+     * none and needs none — its write transactions already exclude each other.
+     */
+    readonly lockForUpdate?: boolean;
+};
+/**
+ * Sentinel VALUES cell: render the `DEFAULT` keyword instead of a placeholder
+ * (M4) — a heterogeneous createMany row that omits a field lets the COLUMN
+ * default apply (or NULL on a defaultless nullable column), exactly like a
+ * single-row insert that omits it. Postgres/mysql only
+ * (`dialect.rowDefaultKeyword`); sqlite groups rows instead.
+ */
+export declare const SQL_DEFAULT_CELL: {
+    readonly __sqlDefault: true;
+};
+/** Is this VALUES cell the {@link SQL_DEFAULT_CELL} sentinel? */
+export declare function isSqlDefaultCell(value: unknown): boolean;
+/**
+ * VALUES/SET cell carrying a Json column's parameter (the codec's JSON text).
+ *
+ * Why it exists: OID-typed drivers (bun:sql) resolve each parameter's postgres
+ * type and re-serialize the JS value AS that type — a pre-stringified Json
+ * param bound straight into a bare jsonb slot arrives DOUBLE-ENCODED (a jsonb
+ * string holding the document; live-proven on Bun 1.3.14). The postgres
+ * renderer pins the parameter's type instead (`$n::text::jsonb`,
+ * `SqlDialect.jsonParamCast`), so every driver sends the text through and the
+ * SERVER parses it; text-param drivers (node-postgres, pglite) are unaffected.
+ * 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.
+ */
+export type JsonParamCell = {
+    readonly __jsonParam: true;
+    readonly text: string;
+};
+/** Wrap a Json column's encoded (stringified) parameter for cast-site rendering. */
+export declare function jsonParamCell(params: {
+    text: string;
+}): JsonParamCell;
+/** Is this VALUES/SET cell a {@link JsonParamCell}? */
+export declare function isJsonParamCell(value: unknown): value is JsonParamCell;
+export type InsertStatement = {
+    readonly kind: "insert";
+    readonly table: TableRef;
+    readonly columns: readonly string[];
+    /** Row values aligned to `columns` — deterministic parameter order. */
+    readonly rows: readonly (readonly unknown[])[];
+    /** 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[];
+};
+/** Conflicting rows are updated with these column values. */
+export type OnConflictUpdate = {
+    /** Conflict target columns (ignored by the mysql form). */
+    readonly columns: readonly string[];
+    readonly update: Readonly<Record<string, unknown>>;
+    /**
+     * MySQL only (`upsertForm: "onDuplicateKey"`): append
+     * `` `col` = LAST_INSERT_ID(`col`) `` to the update list so the UPDATE arm
+     * records the addressed row's key — without it `LAST_INSERT_ID()` is stale
+     * on the update arm and the read-back can resolve a wrong, unrelated row
+     * (SQL review B2, live-proven on 8.4). Only meaningful for integer keys.
+     */
+    readonly lastInsertIdColumn?: string;
+};
+/**
+ * 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 `columns` entirely.
+ */
+export type OnConflictDoNothing = {
+    readonly columns?: readonly string[];
+    readonly doNothing: true;
+};
+export type OnConflictClause = OnConflictUpdate | OnConflictDoNothing;
+export type UpdateStatement = {
+    readonly kind: "update";
+    readonly table: TableRef;
+    /** Column → parameter value, or an atomic {@link SetOperation}. */
+    readonly set: Readonly<Record<string, unknown>>;
+    readonly where?: SqlExpr;
+    readonly returning?: readonly string[];
+};
+export type DeleteStatement = {
+    readonly kind: "delete";
+    readonly table: TableRef;
+    readonly where?: SqlExpr;
+    readonly returning?: readonly string[];
+};
+export type SqlStatement = SelectStatement | InsertStatement | UpdateStatement | DeleteStatement;
+//# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Per-dialect capability tables — the frozen feature contract.
+ *
+ * Mirrored verbatim by tests/capabilities.test.ts: changing a value here forces
+ * a reviewed test change. Runtime fallbacks, migrate DDL, generator output and
+ * E2E `skipUnlessCapability()` all read these same objects.
+ */
+import type { Dialect, DialectCapabilities } from "@vibeorm/schema";
+export declare const POSTGRES_CAPABILITIES: DialectCapabilities;
+export declare const SQLITE_CAPABILITIES: DialectCapabilities;
+export declare const MYSQL_CAPABILITIES: DialectCapabilities;
+export declare const DIALECT_CAPABILITIES: Readonly<Record<Dialect, DialectCapabilities>>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEpE,eAAO,MAAM,qBAAqB,EAAE,mBAanC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,mBAajC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,mBAahC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAI/E,CAAC"}

package/dist/codecs.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The pure codec tables — constitution rule 6.
+ *
+ * ONE place defines how a JS value becomes a driver parameter (`encode`) and
+ * how a driver value becomes a JS value (`decode`), per dialect × scalar type.
+ * Nothing else in any package may coerce: v1's BigInt-as-string, enum-array and
+ * timestamp bugs all came from coercion scattered across query builders and
+ * relation loaders (LEARNINGS.md).
+ *
+ * These tables are PURE — dialect × scalar type only, no schema/model
+ * awareness. The FieldMeta-aware entry points (`getCodec`/`encodeValue`/
+ * `decodeValue`/`decodeRow`/`decodeRows`) live in @vibeorm/runtime, which
+ * re-exports these tables so existing consumers keep one import site.
+ *
+ * The two rules that make it work:
+ *   - EVERY parameter bound by the query builder passes through `encode`.
+ *   - EVERY row materialized by the client passes through `decode` — including
+ *     every relation-loaded child row (the v1 lesson).
+ *
+ * Enum fields ride the String codec: enum values are plain strings on the wire
+ * on all three dialects.
+ */
+import type { Dialect, ScalarType } from "@vibeorm/schema";
+/**
+ * One scalar type's transport rules for one dialect. Both directions see only
+ * non-null values — the runtime's `encodeValue`/`decodeValue` short-circuit
+ * null/undefined.
+ */
+export type ScalarCodec = {
+    readonly encode: (value: unknown) => unknown;
+    readonly decode: (value: unknown) => unknown;
+};
+export type CodecTable = Readonly<Record<ScalarType, ScalarCodec>>;
+/**
+ * What a DRIVER actually delivers for NON-LIST **base-table storage** columns
+ * on its result path — declared per adapter (`DatabaseAdapter.wire`), verified
+ * live per driver, and consumed by the runtime's decode plans to skip decoders
+ * that are provably no-ops for that driver. The claims hold because base-table
+ * storage types follow the declared field types by construction (migrate's
+ * mappings); VIEW columns can hide any expression type under a declared field
+ * type (mysql `COUNT(*)` is BIGINT-as-string under an `Int` field), so the
+ * runtime exempts views from pruning entirely.
+ *
+ * Why it exists: the codec tables above are keyed per DIALECT, but wire forms
+ * differ per DRIVER (node-postgres hands `Date` objects where a text-mode
+ * driver hands strings). Without a declaration every DateTime/Json/Int column
+ * pays an idempotency probe per row per read; with one, the decode plan keeps
+ * only decoders that do real work. The codec DEFINITIONS stay right here —
+ * rule 6 — only plan membership changes, and only under a declaration.
+ *
+ * An adapter that declares nothing gets the full idempotency-guarded plan
+ * (today's behaviour). Declarations are PROMISES: declare only what the
+ * driver verifiably does.
+ */
+export type WireFidelity = {
+    /** DateTime columns arrive as JS `Date` instances (`"native"`) or as text/number (`"text"`). */
+    readonly dateTime?: "native" | "text";
+    /** Json columns arrive already parsed (`"parsed"`) or as raw JSON text (`"text"`). */
+    readonly json?: "parsed" | "text";
+    /** Int/Float columns arrive as JS numbers (`"native"`) or as text (`"text"`). */
+    readonly numbers?: "native" | "text";
+};
+/**
+ * Is this scalar type's DECODE a no-op under the declared wire fidelity?
+ * Provable against the decode implementations in this file, identically on
+ * every dialect table:
+ *
+ * - `DateTime` + `dateTime: "native"` — every DateTime decode
+ *   (postgres/sqlite/mysql all share {@link dateNativeCodec}'s decode) returns
+ *   a `Date` instance unchanged.
+ * - `Json` + `json: "parsed"` — {@link jsonCodec}'s decode returns non-strings
+ *   unchanged. (For a driver that pre-parses, skipping is also the CORRECT
+ *   reading of a stored top-level JSON **string**: the driver hands a bare JS
+ *   string, which the guarded decode would wrongly re-parse.)
+ * - `Int`/`Float` + `numbers: "native"` — {@link numberCodec}'s decode returns
+ *   numbers unchanged.
+ *
+ * Everything else always decodes: BigInt (string→BigInt is real work on every
+ * driver that can't send int64), Decimal (mysql pads), Boolean (0/1→boolean),
+ * Bytes, and every LIST field (array wire forms differ per driver and are not
+ * covered by the declaration).
+ */
+export declare function decodeIsNoop(params: {
+    scalarType: ScalarType;
+    wire: WireFidelity | undefined;
+}): boolean;
+/** postgres (and pglite — same wire behaviour). */
+export declare const POSTGRES_CODECS: CodecTable;
+/** sqlite — no boolean, date or json types; everything rides TEXT/INTEGER. */
+export declare const SQLITE_CODECS: CodecTable;
+/** mysql — native DATETIME and JSON, booleans stored as TINYINT(1). */
+export declare const MYSQL_CODECS: CodecTable;
+/** The whole table, keyed by dialect. */
+export declare const DIALECT_CODECS: Readonly<Record<Dialect, CodecTable>>;
+//# sourceMappingURL=codecs.d.ts.map

package/dist/codecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../src/codecs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAI3D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACtC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAClC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAA;CAAE,GAAG,OAAO,CAOxG;AAiKD,mDAAmD;AACnD,eAAO,MAAM,eAAe,EAAE,UAU7B,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,aAAa,EAAE,UAU3B,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,YAAY,EAAE,UAU1B,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAIhE,CAAC"}