turbine-orm 0.50.0 → 0.51.0

package/dist/mssql.js

@@ -1,8 +1,8 @@
 /**
- * turbine-orm/mssql — Microsoft SQL Server engine (driver-injected, optional peer)
+ * turbine-orm/mssql, Microsoft SQL Server engine (driver-injected, optional peer)
  *
  * Binds Turbine to SQL Server 2016+ via the `mssql` driver (which wraps
- * `tedious`). `mssql` is **not** a root dependency — it is an **optional peer**:
+ * `tedious`). `mssql` is **not** a root dependency, it is an **optional peer**:
  * `npm i turbine-orm` pulls nothing extra, and only consumers who
  * `import 'turbine-orm/mssql'` install `mssql` themselves. The factory loads it
  * through a dynamic `import('mssql')` so importing this module never crashes when
@@ -33,14 +33,14 @@
  *     real JSON instead of being escaped as a string. `INCLUDE_NULL_VALUES`
  *     keeps NULL columns present (matching PostgreSQL `json_build_object`).
  *  3. **No `LIMIT`.** Paging is `ORDER BY … OFFSET n ROWS FETCH NEXT m ROWS ONLY`,
- *     which requires an ORDER BY — a stable `ORDER BY (SELECT NULL)` is injected
+ *     which requires an ORDER BY, a stable `ORDER BY (SELECT NULL)` is injected
  *     when the query has none (`Dialect.buildLimitOffset`).
  *
  * ## Named `@pN` placeholders (no positional `?`)
  *
  * `mssqlDialect.paramPlaceholder = (i) => '@p' + i`. The driver shim binds via
  * `request.input('p' + i, value)`, so binding is by NAME and independent of where
- * each placeholder lands in the SQL text — exactly the guarantee PostgreSQL's
+ * each placeholder lands in the SQL text, exactly the guarantee PostgreSQL's
  * numbered `$N` gives. (SQL Server is naturally named-param friendly, sidestepping
  * the positional-`?` mis-bind bug the SQLite/MySQL phases hit.)
  *
@@ -48,12 +48,12 @@
  *
  * - **Single query nested relations preserved** via `FOR JSON PATH` (SQL Server
  *   2016+). Ordered/limited to-many uses `ORDER BY … OFFSET/FETCH` inside the FOR
- *   JSON subquery (no inner-subquery rewrite needed — FOR JSON aggregates AFTER
+ *   JSON subquery (no inner-subquery rewrite needed, FOR JSON aggregates AFTER
  *   the row selection).
  * - **Result strategy `'output'`:** create/update/delete/upsert return their rows
  *   from the same statement. `createMany` returns the inserted rows via
  *   `OUTPUT INSERTED.*` on the multi-row VALUES insert (≤ 1000 rows / 2100 params
- *   per statement — exceeding either throws a clear `ValidationError`; chunk
+ *   per statement, exceeding either throws a clear `ValidationError`; chunk
  *   yourself or use single `create`s).
  * - **MERGE concurrency caveat:** `MERGE` is the upsert primitive; under high
  *   concurrency a `MERGE` can still race (it is NOT a substitute for a unique
@@ -62,20 +62,20 @@
  *   loser of a race.
  * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
  *   LISTEN/NOTIFY (`$listen`/`$notify`), RLS `sessionContext` (sp_set_session_context
- *   exists but is connection-scoped, not transaction-local, so it is not wired —
+ *   exists but is connection-scoped, not transaction-local, so it is not wired -
  *   throws rather than silently leaking context across pooled connections).
  * - **Advisory-lock migration locking** is available in principle via
  *   `sp_getapplock`/`sp_releaseapplock` (`supportsAdvisoryLock = true`); the
  *   migrate CLI is still PostgreSQL-only, so this flag documents intent for a
  *   future adapter.
- * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)` — deterministic
+ * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)`, deterministic
  *   regardless of the column's collation (note this can defeat an index unless a
  *   computed/persisted `LOWER()` index exists).
  * - **bignum:** the shim applies the same safe-int policy Turbine uses for Postgres
  *   `int8` (number when it fits in 2^53, decimal string otherwise) WITHOUT mutating
  *   any global driver state. `DECIMAL`/`NUMERIC`/`MONEY` come back as strings;
  *   `BIT` binds/returns booleans.
- * - **`DISTINCT ON`** is PostgreSQL-only and is not translated — avoid `distinct`
+ * - **`DISTINCT ON`** is PostgreSQL-only and is not translated, avoid `distinct`
  *   on SQL Server.
  *
  * ## Example
@@ -112,7 +112,7 @@ function sortedRelEntries(obj) {
 /**
  * Coerce an arbitrary JS value into something `mssql` can bind. `BIT` accepts JS
  * booleans directly; `undefined`/`null` → NULL; `bigint` follows the safe-int
- * policy (number when it fits in 2^53, else a decimal string — no precision
+ * policy (number when it fits in 2^53, else a decimal string, no precision
  * loss); `Date`/`Uint8Array` pass through; any remaining object/array → JSON text
  * (matches how Turbine already pre-serializes JSON filter / `IN`-list params).
  */
@@ -152,7 +152,7 @@ function shapeResult(result) {
  * driver returns BIGINT as a string to avoid precision loss, so a BIGINT IDENTITY
  * `id` would otherwise surface as `'1'` instead of `1`. Values outside the safe
  * range are left as strings (same as the Postgres path). Nested relations are
- * unaffected — `FOR JSON PATH` already renders BIGINT as a JSON number.
+ * unaffected, `FOR JSON PATH` already renders BIGINT as a JSON number.
  */
 function coerceBigIntColumns(rows, columns) {
     if (!columns || rows.length === 0)
@@ -275,12 +275,12 @@ class MssqlTxClient {
         const { text: rawSql, params } = normalizeQueryArgs(text, values);
         const sql = rawSql.trim();
         // RELEASE SAVEPOINT has no SQL Server equivalent (savepoints auto-persist until
-        // the outer commit/rollback) — releaseSavepointStatement() returns '' → no-op.
+        // the outer commit/rollback), releaseSavepointStatement() returns '' → no-op.
         if (sql === '')
             return EMPTY_RESULT;
         // The dialect composes `SET TRANSACTION ISOLATION LEVEL …; BEGIN TRANSACTION`
         // (SQL Server cannot take an inline isolation level on BEGIN). Split and run
-        // the parts in order — same pattern as the MySQL shim. Gated on the exact
+        // the parts in order, same pattern as the MySQL shim. Gated on the exact
         // transaction-control prefix so no builder/user SQL is ever split.
         if (/^SET TRANSACTION ISOLATION LEVEL /i.test(sql) && sql.includes('; ')) {
             let last = EMPTY_RESULT;
@@ -341,7 +341,7 @@ class MssqlTxClient {
  * physical connection.
  */
 export class MssqlPool {
-    /** The underlying `mssql` ConnectionPool — exposed as an escape hatch (seed / DDL / advanced ops). */
+    /** The underlying `mssql` ConnectionPool, exposed as an escape hatch (seed / DDL / advanced ops). */
     pool;
     sqlNS;
     closed = false;
@@ -446,7 +446,7 @@ function mssqlColumnType(type, maxLength) {
     return type;
 }
 // ---------------------------------------------------------------------------
-// mssqlDialect — the full Dialect contract for SQL Server 2016+
+// mssqlDialect, the full Dialect contract for SQL Server 2016+
 // ---------------------------------------------------------------------------
 /**
  * Render the SQL Server `OUTPUT` clause for a write's returning selection.
@@ -519,6 +519,27 @@ export const mssqlDialect = {
         return `[${name.replace(/]/g, ']]')}]`;
     },
     // SQL Server aggregate casts: COUNT → INT, AVG/float → FLOAT.
+    jsonWireRule(columnType) {
+        const t = columnType.toLowerCase();
+        // FOR JSON PATH renders BIGINT as a JSON number, which is an IEEE double:
+        // a stored 9007199254740993 came back 9007199254740992 through the join
+        // strategy, while a top-level read and the batched loader both returned
+        // the exact decimal string. The tedious driver returns BIGINT as a STRING
+        // unconditionally (verified for both small and large values), so carrying
+        // text and keeping it reproduces the driver exactly.
+        if (t === 'bigint') {
+            return { sql: (ref) => `CAST(${ref} AS NVARCHAR(50))`, decode: (value) => value };
+        }
+        // Binary columns come out of FOR JSON PATH as BASE64 text ("AQL/") rather
+        // than bytes. Style 2 converts to bare hex, which rebuilds exactly.
+        if (t === 'binary' || t === 'varbinary' || t === 'image') {
+            return {
+                sql: (ref) => `CONVERT(VARCHAR(MAX), ${ref}, 2)`,
+                decode: (value) => (typeof value === 'string' ? Uint8Array.from(Buffer.from(value, 'hex')) : value),
+            };
+        }
+        return undefined;
+    },
     castAggregate(expr, target) {
         return `CAST(${expr} AS ${target === 'int' ? 'INT' : 'FLOAT'})`;
     },
@@ -533,7 +554,7 @@ export const mssqlDialect = {
     inClauseParam(values) {
         return JSON.stringify(values ?? []);
     },
-    // OUTPUT replaces RETURNING — injected mid-statement by the statement builders,
+    // OUTPUT replaces RETURNING, injected mid-statement by the statement builders,
     // never as a trailing clause.
     buildReturningClause() {
         return '';
@@ -543,7 +564,7 @@ export const mssqlDialect = {
         return `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES (${input.valuePlaceholders.join(', ')})`;
     },
     buildBulkInsertStatement(input) {
-        // No UNNEST in SQL Server — emit multi-row VALUES with flattened, named `@pN`
+        // No UNNEST in SQL Server, emit multi-row VALUES with flattened, named `@pN`
         // placeholders. Enforce the engine's 1000-row / 2100-param statement limits.
         const rowCount = input.rowValues.length;
         const paramCount = input.rowValues.reduce((n, row) => n + row.length, 0);
@@ -573,7 +594,7 @@ export const mssqlDialect = {
     },
     buildUpsertStatement(input) {
         // MERGE is the SQL Server upsert. The MERGE statement MUST end with `;`.
-        // CONCURRENCY CAVEAT: MERGE is not a substitute for a UNIQUE/PK constraint —
+        // CONCURRENCY CAVEAT: MERGE is not a substitute for a UNIQUE/PK constraint -
         // keep the conflict columns backed by one and rely on UniqueConstraintError
         // (2627/2601 → E008) for a concurrent loser.
         const on = input.conflictColumns.map((c) => `T.${c} = S.${c}`).join(' AND ');
@@ -588,7 +609,7 @@ export const mssqlDialect = {
             `${out};`);
     },
     // UPDATE/DELETE inject OUTPUT mid-statement (between SET and WHERE / FROM and
-    // WHERE) — a trailing clause would be invalid T-SQL.
+    // WHERE), a trailing clause would be invalid T-SQL.
     buildUpdateStatement(input) {
         const out = mssqlOutput(input.returning, 'INSERTED');
         return `UPDATE ${input.table} SET ${input.setClauses.join(', ')}${out}${input.whereSql}`;
@@ -597,7 +618,7 @@ export const mssqlDialect = {
         const out = mssqlOutput(input.returning, 'DELETED');
         return `DELETE FROM ${input.table}${out}${input.whereSql}`;
     },
-    // SQL Server has no LIMIT — emit OFFSET/FETCH, injecting a stable ORDER BY when
+    // SQL Server has no LIMIT, emit OFFSET/FETCH, injecting a stable ORDER BY when
     // the outer query has none (OFFSET/FETCH requires an ORDER BY).
     buildLimitOffset(input) {
         const { limitPlaceholder, offsetPlaceholder, hasOrderBy } = input;
@@ -623,7 +644,7 @@ export const mssqlDialect = {
     },
     // SQL Server has no JSON_CONTAINS. Emulate "the JSON array column contains the
     // scalar value" via OPENJSON (documented `limited`: object-containment and deep
-    // paths are not supported — use a generated column + index for those).
+    // paths are not supported, use a generated column + index for those).
     buildJsonContains(column, paramRef) {
         return `EXISTS (SELECT 1 FROM OPENJSON(${column}) WHERE [value] = ${paramRef})`;
     },
@@ -702,7 +723,7 @@ export const mssqlDialect = {
         return `SAVE TRANSACTION ${name}`;
     },
     releaseSavepointStatement() {
-        // SQL Server has no RELEASE SAVEPOINT — savepoints persist until the outer
+        // SQL Server has no RELEASE SAVEPOINT, savepoints persist until the outer
         // commit/rollback. The shim treats the empty statement as a no-op.
         return '';
     },
@@ -760,10 +781,21 @@ function buildForJsonSubquery(dialect, ctx) {
     const orderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
     const hasOrder = orderEntries.length > 0;
     const hasLimit = spec !== true && spec.limit !== undefined;
-    /** `<alias>.<col> AS [<field>]` selection for the FOR JSON object keys. */
+    /**
+     * `<alias>.<col> AS [<field>]` selection for the FOR JSON object keys.
+     *
+     * A column whose FOR JSON rendering diverges from the driver's own value is
+     * wrapped by the dialect's {@link Dialect.jsonWireRule} cast, exactly as the
+     * shared `json_build_object` path does, this generator is an override, so it
+     * has to opt in explicitly or BIGINT silently loses precision and a binary
+     * column arrives as base64 text.
+     */
     const colSelect = (a) => targetColumns.map((col) => {
         const field = targetMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-        return `${a}.${q(col)} AS ${q(field)}`;
+        const ref = `${a}.${q(col)}`;
+        const type = targetMeta.pgTypes?.[col];
+        const expr = (type && dialect.jsonWireRule?.(type)?.sql(ref)) ?? ref;
+        return `${expr} AS ${q(field)}`;
     });
     /** Build nested relations as `JSON_QUERY((<subquery>)) AS [<name>]` columns (pushes their params). */
     const buildNested = (parentAlias) => {
@@ -921,7 +953,7 @@ const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
  * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
  * `addAutoManyToManyRelations` in introspect.ts), so this engine derives
  * IDENTICAL relation names to `turbine generate` against Postgres for the
- * same logical schema — legacy-first naming, per-column disambiguation, and
+ * same logical schema, legacy-first naming, per-column disambiguation, and
  * collision resolution against scalar column fields included.
  */
 function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, columnsByTable) {
@@ -1109,7 +1141,7 @@ export async function introspectMssqlWith(exec, schema = 'dbo', options = {}) {
             indexes: indexesByTable.get(tableName) ?? [],
         };
     }
-    // SQL Server has no first-class enum type — enums are CHECK constraints; left empty.
+    // SQL Server has no first-class enum type, enums are CHECK constraints; left empty.
     return { tables, enums: {} };
 }
 /**
@@ -1125,7 +1157,10 @@ export async function introspectMssql(options) {
     try {
         const mp = new MssqlPool(pool, sqlNS);
         const exec = async (sql, params) => (await mp.query(sql, params)).rows;
-        return introspectMssqlWith(exec, options.schema ?? 'dbo', {
+        // `await` is LOAD-BEARING: `return somePromise` inside a try/finally runs
+        // the finally BEFORE the promise settles, so `pool.close()` would tear the
+        // connection down underneath the introspection queries.
+        return await introspectMssqlWith(exec, options.schema ?? 'dbo', {
             include: options.include,
             exclude: options.exclude,
         });
@@ -1166,7 +1201,7 @@ async function loadMssql() {
     let mod;
     try {
         // `mssql` ships no bundled type declarations (it needs @types/mssql, which
-        // Turbine deliberately does not depend on) — the structural MssqlModule
+        // Turbine deliberately does not depend on), the structural MssqlModule
         // above is our typed surface; the helper returns `unknown` so no TS7016.
         // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
         // import() even if a future mssql major goes ESM-only (the CommonJS pass
@@ -1204,7 +1239,7 @@ function isMssqlPool(x) {
  * Pass one of:
  *  - a connection string (`'mssql://sa:pass@host:1433/db'`),
  *  - an `mssql` config object (`{ server, user, password, database, options }`),
- *  - an existing `MssqlPool` (injection — you own its lifecycle, `disconnect()` is
+ *  - an existing `MssqlPool` (injection, you own its lifecycle, `disconnect()` is
  *    a no-op).
  *
  * When Turbine builds the pool (string/config), it probes

package/dist/mysql.d.ts

@@ -1,8 +1,8 @@
 /**
- * turbine-orm/mysql — MySQL 8 engine (driver-injected, optional peer)
+ * turbine-orm/mysql, MySQL 8 engine (driver-injected, optional peer)
  *
  * Binds Turbine to MySQL 8 via the `mysql2` driver. `mysql2` is **not** a root
- * dependency — it is an **optional peer**: `npm i turbine-orm` pulls nothing
+ * dependency, it is an **optional peer**: `npm i turbine-orm` pulls nothing
  * extra, and only consumers who `import 'turbine-orm/mysql'` install `mysql2`
  * themselves. The factory loads it through a dynamic `import('mysql2/promise')`
  * so importing this module never crashes when `mysql2` is absent for a consumer
@@ -21,7 +21,7 @@
  *     (e.g. a `with`-relation `LIMIT` lands in the SELECT list, ahead of the
  *     outer `WHERE`). Postgres reconciles this via numbered `$N`; positional `?`
  *     silently mis-binds. So `mysqlDialect` uses **mysql2 named placeholders**
- *     (`:p1`, `:p2`, …) and the driver shim binds via a `{ p1, p2, … }` object —
+ *     (`:p1`, `:p2`, …) and the driver shim binds via a `{ p1, p2, … }` object -
  *     exactly mirroring `$N` semantics regardless of text order. (See
  *     `turbine-orm/sqlite` for the same fix.)
  *
@@ -42,10 +42,10 @@
  * - **Advisory-lock migration locking** is available in principle via
  *   `GET_LOCK`/`RELEASE_LOCK` (`supportsAdvisoryLock = true`); the migrate CLI is
  *   still PostgreSQL-only, so this flag documents intent for a future adapter.
- * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)` — note this
+ * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)`, note this
  *   can defeat indexes unless a functional/generated index exists.
  * - **bignum:** mysql2 is configured `supportBigNumbers:true, bigNumberStrings:false`
- *   — the same safe-int policy Turbine uses for Postgres `int8` (number when it
+ *   - the same safe-int policy Turbine uses for Postgres `int8` (number when it
  *   fits, decimal string otherwise). `DECIMAL` comes back as a string; `TINYINT(1)`
  *   binds booleans as 1/0. No global parser state is mutated.
  * - **Version:** MySQL **8.0+** required (5.7 lacks `JSON_ARRAYAGG`); MariaDB is
@@ -92,7 +92,7 @@ type QueryArg = string | {
  * `SAVEPOINT` nesting all run on the same physical connection.
  */
 export declare class MysqlPool implements PgCompatPool {
-    /** The underlying mysql2 pool — exposed as an escape hatch (seed / DDL / advanced ops). */
+    /** The underlying mysql2 pool, exposed as an escape hatch (seed / DDL / advanced ops). */
     readonly pool: Mysql2Pool;
     private closed;
     constructor(pool: Mysql2Pool);
@@ -109,7 +109,7 @@ export declare class MysqlPool implements PgCompatPool {
 export declare function mysqlTypeToTs(dialectType: string, nullable: boolean, columnType?: string): string;
 /**
  * MySQL 8 implementation of the {@link Dialect} contract. Backtick identifier
- * quoting, named `:pN` placeholders (NOT positional `?` — see the module
+ * quoting, named `:pN` placeholders (NOT positional `?`, see the module
  * docstring), `JSON_OBJECT` / `JSON_ARRAYAGG` for the single-query nested
  * relation engine (`CAST(… AS JSON)`-wrapped nested subresults), no `RETURNING`
  * (`resultStrategy = 'reselect'`), `INSERT … ON DUPLICATE KEY UPDATE` upserts,
@@ -156,7 +156,7 @@ export interface TurbineMysqlOptions extends Pick<TurbineConfig, 'logging' | 'de
  * Pass one of:
  *  - a connection string (`'mysql://user:pass@host:3306/db'`),
  *  - a mysql2 connection config object (`{ host, user, password, database }`), or
- *  - an existing mysql2 pool / {@link MysqlPool} (injection — you own its lifecycle,
+ *  - an existing mysql2 pool / {@link MysqlPool} (injection, you own its lifecycle,
  *    `disconnect()` is a no-op, advanced config like SSL lives here).
  *
  * When Turbine builds the pool (string/config), it pins the correct mysql2 flags

package/dist/mysql.js

@@ -1,8 +1,8 @@
 /**
- * turbine-orm/mysql — MySQL 8 engine (driver-injected, optional peer)
+ * turbine-orm/mysql, MySQL 8 engine (driver-injected, optional peer)
  *
  * Binds Turbine to MySQL 8 via the `mysql2` driver. `mysql2` is **not** a root
- * dependency — it is an **optional peer**: `npm i turbine-orm` pulls nothing
+ * dependency, it is an **optional peer**: `npm i turbine-orm` pulls nothing
  * extra, and only consumers who `import 'turbine-orm/mysql'` install `mysql2`
  * themselves. The factory loads it through a dynamic `import('mysql2/promise')`
  * so importing this module never crashes when `mysql2` is absent for a consumer
@@ -21,7 +21,7 @@
  *     (e.g. a `with`-relation `LIMIT` lands in the SELECT list, ahead of the
  *     outer `WHERE`). Postgres reconciles this via numbered `$N`; positional `?`
  *     silently mis-binds. So `mysqlDialect` uses **mysql2 named placeholders**
- *     (`:p1`, `:p2`, …) and the driver shim binds via a `{ p1, p2, … }` object —
+ *     (`:p1`, `:p2`, …) and the driver shim binds via a `{ p1, p2, … }` object -
  *     exactly mirroring `$N` semantics regardless of text order. (See
  *     `turbine-orm/sqlite` for the same fix.)
  *
@@ -42,10 +42,10 @@
  * - **Advisory-lock migration locking** is available in principle via
  *   `GET_LOCK`/`RELEASE_LOCK` (`supportsAdvisoryLock = true`); the migrate CLI is
  *   still PostgreSQL-only, so this flag documents intent for a future adapter.
- * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)` — note this
+ * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)`, note this
  *   can defeat indexes unless a functional/generated index exists.
  * - **bignum:** mysql2 is configured `supportBigNumbers:true, bigNumberStrings:false`
- *   — the same safe-int policy Turbine uses for Postgres `int8` (number when it
+ *   - the same safe-int policy Turbine uses for Postgres `int8` (number when it
  *   fits, decimal string otherwise). `DECIMAL` comes back as a string; `TINYINT(1)`
  *   binds booleans as 1/0. No global parser state is mutated.
  * - **Version:** MySQL **8.0+** required (5.7 lacks `JSON_ARRAYAGG`); MariaDB is
@@ -98,7 +98,7 @@ function toMysqlParam(value) {
 /**
  * Bind the positional `params[]` (in 1-indexed generation order) to the named
  * `:p1`, `:p2`, … placeholders the dialect emits. Mapping by NAME makes binding
- * independent of where each placeholder lands in the SQL text — the same
+ * independent of where each placeholder lands in the SQL text, the same
  * guarantee Postgres' numbered `$N` gives. Returns `undefined` for parameter-less
  * statements (BEGIN/COMMIT/DDL) so they bind nothing.
  */
@@ -132,7 +132,7 @@ function shapeResult(result) {
  * deadlock / lock-wait-timeout become retryable (E012/E013). The original mysql2
  * error (with its real message) is preserved as the wrapped error's `.cause`
  * downstream. Returns the value unchanged when it is not a recognizable mysql2
- * error. We only annotate here — `wrapPgError` (invoked downstream in the query
+ * error. We only annotate here, `wrapPgError` (invoked downstream in the query
  * executor / transaction proxy) does the actual translation.
  */
 function augmentMysqlError(err) {
@@ -215,7 +215,7 @@ async function execOne(runner, sql, params) {
  * emits `SET TRANSACTION ISOLATION LEVEL <level>; START TRANSACTION`. mysql2 runs
  * one statement per call (multi-statements stay OFF by design), so split exactly
  * that dialect-generated compound and run the parts in order. Gated on the precise
- * transaction-control prefix — the query builder never emits `SET TRANSACTION
+ * transaction-control prefix, the query builder never emits `SET TRANSACTION
  * ISOLATION LEVEL`, so no builder/user SQL is ever split.
  */
 async function runOnConnection(conn, sql, params) {
@@ -237,7 +237,7 @@ async function runOnConnection(conn, sql, params) {
  * `SAVEPOINT` nesting all run on the same physical connection.
  */
 export class MysqlPool {
-    /** The underlying mysql2 pool — exposed as an escape hatch (seed / DDL / advanced ops). */
+    /** The underlying mysql2 pool, exposed as an escape hatch (seed / DDL / advanced ops). */
     pool;
     closed = false;
     constructor(pool) {
@@ -348,11 +348,11 @@ function mysqlColumnType(type, maxLength) {
     return type;
 }
 // ---------------------------------------------------------------------------
-// mysqlDialect — the full Dialect contract for MySQL 8
+// mysqlDialect, the full Dialect contract for MySQL 8
 // ---------------------------------------------------------------------------
 /**
  * MySQL 8 implementation of the {@link Dialect} contract. Backtick identifier
- * quoting, named `:pN` placeholders (NOT positional `?` — see the module
+ * quoting, named `:pN` placeholders (NOT positional `?`, see the module
  * docstring), `JSON_OBJECT` / `JSON_ARRAYAGG` for the single-query nested
  * relation engine (`CAST(… AS JSON)`-wrapped nested subresults), no `RETURNING`
  * (`resultStrategy = 'reselect'`), `INSERT … ON DUPLICATE KEY UPDATE` upserts,
@@ -396,7 +396,7 @@ export const mysqlDialect = {
     jsonPathSupport: 'function',
     emptyJsonArrayLiteral: 'JSON_ARRAY()',
     nullJsonLiteral: 'NULL',
-    // Named placeholders (`:p1`, `:p2`, …) — NOT positional `?`. Turbine pushes
+    // Named placeholders (`:p1`, `:p2`, …), NOT positional `?`. Turbine pushes
     // params in 1-indexed generation order but may EMIT them in a different SQL
     // text position; positional `?` mis-binds. mysql2 named parameters bind by
     // name, so `:pN` ↔ `params[N-1]` mirrors Postgres' `$N` regardless of text
@@ -433,7 +433,7 @@ export const mysqlDialect = {
      * Wrap a nested correlated subquery for embedding inside a parent `JSON_OBJECT`.
      * MySQL double-encodes a scalar subquery result as a JSON *string* unless it is
      * explicitly typed JSON, so `CAST((subquery) AS JSON)` forces the nested value
-     * to be embedded as real JSON (objects/arrays), not a quoted string — the same
+     * to be embedded as real JSON (objects/arrays), not a quoted string, the same
      * intent as SQLite's `json(...)` wrap. The fallback (`JSON_ARRAY()` / `NULL`) is
      * already JSON-typed.
      */
@@ -442,6 +442,40 @@ export const mysqlDialect = {
     },
     // MySQL aggregate casts: COUNT → SIGNED (BIGINT, comes back as a JS number when
     // safe), AVG/float → DECIMAL (string, the aggregate transform Number()-coerces).
+    jsonWireRule(columnType) {
+        const t = columnType.toLowerCase();
+        // JSON_OBJECT renders these as JSON numbers, which are IEEE doubles, so a
+        // relation read through the join strategy disagreed with a top-level read
+        // and with the batched loader, LOSSILY. Measured: BIGINT 9007199254740993
+        // came back 9007199254740992, and DECIMAL '1000.50' came back 1000.5.
+        // mysql2 hands both back as STRINGS at top level (supportBigNumbers, and
+        // DECIMAL is always a string), so carry the text and keep it.
+        if (t === 'bigint') {
+            return {
+                sql: (ref) => `CAST(${ref} AS CHAR)`,
+                decode: (value) => {
+                    // Same policy as the driver's supportBigNumbers/bigNumberStrings:false.
+                    if (typeof value !== 'string' || !/^-?\d+$/.test(value))
+                        return value;
+                    const asNumber = Number(value);
+                    return Number.isSafeInteger(asNumber) ? asNumber : value;
+                },
+            };
+        }
+        if (t === 'decimal' || t === 'numeric') {
+            return { sql: (ref) => `CAST(${ref} AS CHAR)`, decode: (value) => value };
+        }
+        // Binary columns are worse than lossy: JSON_OBJECT emits MySQL's internal
+        // `base64:type15:…` marker string, so the caller got that text instead of
+        // bytes. Carry hex and rebuild the buffer.
+        if (t === 'binary' || t === 'varbinary' || t.endsWith('blob')) {
+            return {
+                sql: (ref) => `HEX(${ref})`,
+                decode: (value) => (typeof value === 'string' ? Uint8Array.from(Buffer.from(value, 'hex')) : value),
+            };
+        }
+        return undefined;
+    },
     castAggregate(expr, target) {
         return `CAST(${expr} AS ${target === 'int' ? 'SIGNED' : 'DECIMAL(65,30)'})`;
     },
@@ -457,7 +491,7 @@ export const mysqlDialect = {
     inClauseParam(values) {
         return JSON.stringify(values ?? []);
     },
-    // No RETURNING — resultStrategy 'reselect' re-fetches the row.
+    // No RETURNING, resultStrategy 'reselect' re-fetches the row.
     buildReturningClause() {
         return '';
     },
@@ -465,7 +499,7 @@ export const mysqlDialect = {
         return `INSERT INTO ${input.table} (${input.columns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})`;
     },
     buildBulkInsertStatement(input) {
-        // No UNNEST in MySQL — emit multi-row VALUES with flattened, named
+        // No UNNEST in MySQL, emit multi-row VALUES with flattened, named
         // placeholders (`:p1`, `:p2`, …) matching the flat param order.
         let n = 0;
         const placeholders = input.rowValues
@@ -480,7 +514,7 @@ export const mysqlDialect = {
         };
     },
     buildUpsertStatement(input) {
-        // MySQL ignores the explicit conflict target — ON DUPLICATE KEY UPDATE keys
+        // MySQL ignores the explicit conflict target, ON DUPLICATE KEY UPDATE keys
         // off the table's PK/unique indexes. The `where`-derived conflictColumns
         // (input.conflictColumns) must therefore correspond to a real unique/PK index
         // for the upsert to target the intended row (plan §4 / R9).
@@ -589,7 +623,7 @@ const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
  * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
  * `addAutoManyToManyRelations` in introspect.ts), so this engine derives
  * IDENTICAL relation names to `turbine generate` against Postgres for the
- * same logical schema — legacy-first naming, per-column disambiguation, and
+ * same logical schema, legacy-first naming, per-column disambiguation, and
  * collision resolution against scalar column fields included.
  */
 function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, columnsByTable) {
@@ -776,9 +810,13 @@ export async function introspectMysql(options) {
             schemaName = rows[0]?.db ?? '';
         }
         if (!schemaName) {
-            throw new ConnectionError('[turbine] Could not determine the MySQL database to introspect — pass a database in the connection string or a `schema` option.');
+            throw new ConnectionError('[turbine] Could not determine the MySQL database to introspect, pass a database in the connection string or a `schema` option.');
         }
-        return introspectMysqlWith(exec, schemaName, { include: options.include, exclude: options.exclude });
+        // `await` is LOAD-BEARING, not stylistic: `return somePromise` inside a
+        // try/finally runs the finally BEFORE the promise settles, so `pool.end()`
+        // closed the pool out from under every introspection query and the whole
+        // call failed with mysql2's "Pool is closed".
+        return await introspectMysqlWith(exec, schemaName, { include: options.include, exclude: options.exclude });
     }
     finally {
         await pool.end();
@@ -789,7 +827,7 @@ export async function introspectMysql(options) {
 // ---------------------------------------------------------------------------
 /** mysql2 connection flags Turbine pins for correct behavior. */
 const MYSQL_DRIVER_FLAGS = {
-    // Named placeholders (`:pN`) — see paramPlaceholder + toNamedBinding.
+    // Named placeholders (`:pN`), see paramPlaceholder + toNamedBinding.
     namedPlaceholders: true,
     // Safe-int policy matching Postgres int8: number when it fits, decimal string
     // otherwise. DECIMAL always comes back as a string. No global state mutated.
@@ -875,7 +913,7 @@ function isMysql2Pool(x) {
  * Pass one of:
  *  - a connection string (`'mysql://user:pass@host:3306/db'`),
  *  - a mysql2 connection config object (`{ host, user, password, database }`), or
- *  - an existing mysql2 pool / {@link MysqlPool} (injection — you own its lifecycle,
+ *  - an existing mysql2 pool / {@link MysqlPool} (injection, you own its lifecycle,
  *    `disconnect()` is a no-op, advanced config like SSL lives here).
  *
  * When Turbine builds the pool (string/config), it pins the correct mysql2 flags
@@ -907,12 +945,12 @@ export async function turbineMysql(target, schema, options = {}) {
         });
         // Every NEW physical connection: disable backslash string escaping so the
         // builder's `LIKE … ESCAPE '\'` clause (a single literal backslash) is valid
-        // MySQL — by default MySQL would parse `'\'` as an escaped quote (syntax
+        // MySQL, by default MySQL would parse `'\'` as an escaped quote (syntax
         // error). This also makes string-literal semantics match Postgres. Turbine
         // parameterizes every value, so no behavior depends on backslash escaping.
         //
         // NOTE: even on a `mysql2/promise` pool, the 'connection' event yields the
-        // *raw* (callback-style) connection — its `.query()` returns a non-thenable
+        // *raw* (callback-style) connection, its `.query()` returns a non-thenable
         // `Query`, so `.catch()`/`await` on it throws "result of query that is not a
         // promise". Use the callback form here (fire-and-forget): if the SET fails we
         // fall back to MySQL's default escaping, harmless since every value is a param.

package/dist/nested-write.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Nested write engine
+ * turbine-orm, Nested write engine
  *
  * Tree-walking create/update that resolves relation fields in `data` into
  * batched SQL operations within a transaction. Supports create, connect,
@@ -8,7 +8,7 @@
  *
  * This module is imported by `query/builder.ts` when the `data` argument
  * of `create()` or `update()` contains relation fields. It never imports
- * `client.ts` directly — the transaction handle is passed in via
+ * `client.ts` directly, the transaction handle is passed in via
  * `NestedWriteContext`.
  */
 import type { RelationDef, SchemaMetadata, TableMetadata } from './schema.js';
@@ -22,6 +22,25 @@ export interface ExtractedFields {
  */
 export interface NestedWriteContext {
     schema: SchemaMetadata;
+    /**
+     * Refuse a `connect` / `connectOrCreate` that would RE-PARENT a to-many
+     * child already owned by a different parent. Off by default.
+     *
+     * `connect: { id: 42 }` on a to-many relation means "make row 42 mine", and
+     * it does that unconditionally: if another parent owns row 42, the row is
+     * silently taken from them. A handler that forwards a client-supplied id
+     * into a nested connect therefore hands any caller a cross-tenant write
+     * primitive, and the only defense is a hand-rolled ownership check at every
+     * call site. With this on, connecting a child whose foreign key already
+     * points at a DIFFERENT parent raises E003; connecting an unowned child
+     * (null FK) or one this parent already owns still succeeds, so the
+     * legitimate uses are untouched.
+     *
+     * Applies to `hasMany` / `hasOne` only. A `belongsTo` connect points the row
+     * being written at a parent, which takes nothing from anyone, and a
+     * many-to-many connect adds a junction row rather than moving one.
+     */
+    scopedConnect?: boolean;
     tx: {
         table<T extends object>(name: string): {
             create(args: {