turbine-orm 0.50.0 → 0.51.0

package/dist/cjs/client.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * turbine-orm — TurbineClient
+ * turbine-orm, TurbineClient
  *
  * The main entry point for the Turbine TypeScript SDK.
  * Manages connection pooling and provides typed table accessors.
@@ -94,12 +94,12 @@ const READ_OPERATIONS = new Set([
 /**
  * Internal marker on the config object that tells the `TurbineClient`
  * constructor to build a lightweight "primary-only" view sharing an existing
- * client's primary pool, dialect, query options, and middleware — instead of
+ * client's primary pool, dialect, query options, and middleware, instead of
  * creating a fresh pool. Produced solely by `$primary()`; never public.
  */
 const PRIMARY_VIEW = Symbol('turbine.primaryView');
 // ---------------------------------------------------------------------------
-// TransactionClient — provides typed table accessors within a transaction
+// TransactionClient, provides typed table accessors within a transaction
 // ---------------------------------------------------------------------------
 /**
  * A transaction-scoped client that provides the same table accessor API as TurbineClient.
@@ -114,7 +114,7 @@ class TransactionClient {
     sourcePool;
     tableCache = new Map();
     savepointCounter = 0;
-    /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
+    /** Active SQL dialect, owns savepoint keywords and raw-SQL placeholders. */
     dialect;
     constructor(client, schema, middlewares, queryOptions, 
     /**
@@ -243,14 +243,14 @@ exports.TransactionClient = TransactionClient;
 // TurbineClient
 // ---------------------------------------------------------------------------
 class TurbineClient {
-    /** The underlying pg.Pool — exposed for escape hatches */
+    /** The underlying pg.Pool, exposed for escape hatches */
     pool;
     /** The schema metadata this client was built from */
     schema;
     static int8ParserRegistered = false;
     static utcTimestampParserRegistered = false;
     logging;
-    /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
+    /** Active SQL dialect, owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     dialect;
     tableCache = new Map();
     middlewares = [];
@@ -259,7 +259,7 @@ class TurbineClient {
     errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     ownsPool = true;
-    /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
+    /** Active LISTEN subscriptions, torn down on disconnect() so it never hangs */
     activeSubscriptions = new Set();
     /**
      * Read-replica pools in round-robin order. Empty when no replicas are
@@ -355,7 +355,7 @@ class TurbineClient {
          */
         // Only register the int8 parser when the PRIMARY pool is Turbine-owned.
         // External pools (Neon HTTP, Vercel Postgres) may ship their own pg-types
-        // fork and rely on their own parser configuration — registration is
+        // fork and rely on their own parser configuration, registration is
         // process-global, so flipping it because a string replica exists alongside
         // an external primary would silently change the external primary's parsing
         // too. String replicas configured next to an external primary therefore
@@ -372,8 +372,8 @@ class TurbineClient {
         // Parse `timestamp` (OID 1114) as UTC instead of server-local time. The
         // pg driver's default hands back a Date built in the process's local zone,
         // so the same row yields a different instant per deployment region. The
-        // ORM convention (Prisma, Rails, Django) — and the only interpretation
-        // that round-trips what Postgres stores — is UTC. Same ownership rule as
+        // ORM convention (Prisma, Rails, Django), and the only interpretation
+        // that round-trips what Postgres stores, is UTC. Same ownership rule as
         // the int8 parser: never mutate parser state on external pools.
         if (ownsAnyPool && config.utcTimestamps !== false && !TurbineClient.utcTimestampParserRegistered) {
             pg_1.default.types.setTypeParser(1114, (val) => new Date(`${val.replace(' ', 'T')}Z`));
@@ -389,6 +389,7 @@ class TurbineClient {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
             utcTimestamps: config.utcTimestamps,
+            scopedConnect: config.scopedConnect,
             relationLoadStrategy: config.relationLoadStrategy,
             stableRelationOrder: config.stableRelationOrder,
             implicitPkOrdering: config.implicitPkOrdering,
@@ -420,17 +421,17 @@ class TurbineClient {
                 }
             },
         };
-        // Apply NotFoundError message redaction mode (default: safe — values are
+        // Apply NotFoundError message redaction mode (default: safe, values are
         // stripped from messages to avoid leaking PII into error logs).
         if (config.errorMessages) {
             (0, errors_js_1.setErrorMessageMode)(config.errorMessages);
         }
         if (config.pool) {
-            // External pool — use directly. Turbine doesn't manage its lifecycle.
+            // External pool, use directly. Turbine doesn't manage its lifecycle.
             this.pool = config.pool;
             this.ownsPool = false;
             if (this.logging) {
-                console.log(`[turbine] Using external pool — ${Object.keys(schema.tables).length} tables`);
+                console.log(`[turbine] Using external pool, ${Object.keys(schema.tables).length} tables`);
             }
         }
         else {
@@ -474,7 +475,7 @@ class TurbineClient {
                 console.error('[turbine] Unexpected pool error:', err.message);
             });
             if (this.logging) {
-                console.log(`[turbine] Pool created — max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
+                console.log(`[turbine] Pool created, max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
             }
         }
         // Build read-replica pools (if any). String entries become owned pg.Pools
@@ -522,14 +523,14 @@ class TurbineClient {
         }
     }
     // -------------------------------------------------------------------------
-    // Middleware — intercept all queries
+    // Middleware, intercept all queries
     // -------------------------------------------------------------------------
     /**
      * Register a middleware function that runs around every query.
      *
      * Middleware can inspect and log query parameters, measure timing, and
      * transform the result returned by `next()`. Note: query SQL is generated
-     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * BEFORE middleware runs, `params.args` is a read-only snapshot, and
      * mutating it does NOT change the executed SQL. Cross-cutting filters
      * (e.g. soft deletes) belong in the query itself: pass an explicit
      * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
@@ -544,7 +545,7 @@ class TurbineClient {
      *   return result;
      * });
      *
-     * // Result transformation middleware — redact a field on the way out
+     * // Result transformation middleware, redact a field on the way out
      * db.$use(async (params, next) => {
      *   const result = await next(params);
      *   if (params.model === 'users' && Array.isArray(result)) {
@@ -566,7 +567,7 @@ class TurbineClient {
             cache.clear();
     }
     // -------------------------------------------------------------------------
-    // Event emitter — subscribe to query lifecycle events
+    // Event emitter, subscribe to query lifecycle events
     // -------------------------------------------------------------------------
     $on(_event, listener) {
         this.queryListeners.add(listener);
@@ -575,7 +576,7 @@ class TurbineClient {
         this.queryListeners.delete(listener);
     }
     // -------------------------------------------------------------------------
-    // Observability — automatic metrics collection
+    // Observability, automatic metrics collection
     // -------------------------------------------------------------------------
     observeEngine;
     async $observe(config) {
@@ -597,16 +598,16 @@ class TurbineClient {
         };
     }
     // -------------------------------------------------------------------------
-    // Table accessor — creates QueryInterface for any table
+    // Table accessor, creates QueryInterface for any table
     // -------------------------------------------------------------------------
     /**
      * Get a QueryInterface for a table.
-     * Results are cached — calling `table('users')` twice returns the same instance.
+     * Results are cached, calling `table('users')` twice returns the same instance.
      *
      * When read replicas are configured, this returns a thin routing proxy: the
      * read-only operations in {@link READ_OPERATIONS} are dispatched to a
-     * round-robin replica-bound QueryInterface (so an entire read — base rows and
-     * any batched sub-queries — runs against a single consistent replica), while
+     * round-robin replica-bound QueryInterface (so an entire read, base rows and
+     * any batched sub-queries, runs against a single consistent replica), while
      * writes and every other member fall through to the primary-bound instance.
      * With no replicas the original single-pool instance is returned directly.
      */
@@ -681,7 +682,7 @@ class TurbineClient {
         });
     }
     /**
-     * Return a view of this client that pins EVERY operation — reads included —
+     * Return a view of this client that pins EVERY operation, reads included -
      * to the primary pool, bypassing replica routing. Use it to read your own
      * write without replication lag, or for any read that must see the latest
      * committed data.
@@ -689,7 +690,7 @@ class TurbineClient {
      * The view shares the primary pool, schema, dialect, query options, and
      * middleware; it owns nothing, so its `disconnect()` is a no-op. When no
      * replicas are configured this simply returns the client itself (already
-     * primary-only). The view is cached — repeated calls return the same instance.
+     * primary-only). The view is cached, repeated calls return the same instance.
      *
      * @example
      * ```ts
@@ -707,14 +708,14 @@ class TurbineClient {
         return this.primaryView;
     }
     // -------------------------------------------------------------------------
-    // Pipeline — batch multiple queries into one round-trip
+    // Pipeline, batch multiple queries into one round-trip
     // -------------------------------------------------------------------------
     /**
      * Execute multiple queries in a single database round-trip.
      *
      * Two call styles:
-     *   - `db.pipeline(q1, q2, q3)` — rest params (backward-compatible)
-     *   - `db.pipeline([q1, q2, q3], { transactional: false })` — array + options
+     *   - `db.pipeline(q1, q2, q3)`, rest params (backward-compatible)
+     *   - `db.pipeline([q1, q2, q3], { transactional: false })`, array + options
      *
      * On pg.Pool-backed connections with TCP, this uses the real Postgres
      * extended-query pipeline protocol (one TCP flush, one round-trip).
@@ -736,7 +737,7 @@ class TurbineClient {
             queries = args;
         }
         if (this.logging) {
-            console.log(`[turbine] Pipeline: ${queries.length} queries — ${queries.map((q) => q.tag).join(', ')}`);
+            console.log(`[turbine] Pipeline: ${queries.length} queries, ${queries.map((q) => q.tag).join(', ')}`);
         }
         return (0, pipeline_js_1.executePipeline)(this.pool, queries, options);
     }
@@ -749,7 +750,7 @@ class TurbineClient {
         return (0, pipeline_js_1.pipelineSupported)(this.pool);
     }
     // -------------------------------------------------------------------------
-    // Raw SQL — tagged template literal escape hatch
+    // Raw SQL, tagged template literal escape hatch
     // -------------------------------------------------------------------------
     /**
      * Execute a raw SQL query with parameter interpolation via tagged templates.
@@ -783,7 +784,7 @@ class TurbineClient {
         }
     }
     /**
-     * Execute a **typed** raw SQL query — Turbine's answer to Prisma's TypedSQL.
+     * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
      *
      * Like {@link raw}, every interpolated `${value}` becomes a `$N` parameter
      * (never string-concatenated), so it is injection-safe by construction. The
@@ -791,7 +792,7 @@ class TurbineClient {
      * returned {@link TypedSqlQuery} can be `await`ed directly for `T[]`, or
      * refined with `.one()` (→ `T | null`) or `.scalar<V>()` (→ `V | null`).
      *
-     * Rows are returned as-is — no snake→camel mapping (matching `raw()`). Alias
+     * Rows are returned as-is, no snake→camel mapping (matching `raw()`). Alias
      * columns in SQL if you want camelCase keys.
      *
      * @example
@@ -817,7 +818,7 @@ class TurbineClient {
         return new typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging);
     }
     // -------------------------------------------------------------------------
-    // Transaction support (raw — legacy)
+    // Transaction support (raw, legacy)
     // -------------------------------------------------------------------------
     /**
      * Execute a function within a database transaction (raw pg.PoolClient).
@@ -836,7 +837,7 @@ class TurbineClient {
          * Only true once BEGIN has actually succeeded. If BEGIN itself throws
          * (e.g. a single-writer engine's transaction gate times out or rejects a
          * re-entrant begin), issuing a "best-effort" ROLLBACK would be a stray
-         * statement from a context that never opened a transaction — on a driver
+         * statement from a context that never opened a transaction, on a driver
          * with one shared engine handle (PowDB embedded) it would roll back a
          * DIFFERENT caller's open transaction.
          */
@@ -859,7 +860,7 @@ class TurbineClient {
                     await client.query(this.dialect.rollbackStatement());
                 }
                 catch {
-                    // Best-effort rollback — the connection may have died mid-query.
+                    // Best-effort rollback, the connection may have died mid-query.
                 }
             }
             throw err;
@@ -891,21 +892,21 @@ class TurbineClient {
                 client.release(err);
             }
             catch {
-                // pg may throw if the client is already released — swallow.
+                // pg may throw if the client is already released, swallow.
             }
         };
         let timedOut = false;
         /**
-         * Only true once BEGIN has actually succeeded. If BEGIN itself throws —
+         * Only true once BEGIN has actually succeeded. If BEGIN itself throws -
          * e.g. a single-writer engine's transaction gate times out in its FIFO
-         * queue or rejects a re-entrant begin (PowDB, E002/E017) — this context
+         * queue or rejects a re-entrant begin (PowDB, E002/E017), this context
          * never opened a transaction, so the catch below must NOT issue its
          * best-effort ROLLBACK: on a driver with one shared engine handle that
          * stray ROLLBACK would tear down a DIFFERENT caller's open transaction.
          */
         let began = false;
         try {
-            // BEGIN with optional isolation level — the dialect owns the keyword and
+            // BEGIN with optional isolation level, the dialect owns the keyword and
             // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
             const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
             await client.query(this.dialect.beginStatement(isolationSql));
@@ -914,15 +915,15 @@ class TurbineClient {
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
             // user fn. Any error here propagates to the catch below and rolls back
             // like any other transaction failure. We use set_config(name, value,
-            // is_local=true) — the parameterizable, transaction-scoped equivalent of
-            // SET LOCAL — so both name and value are BOUND params, never interpolated.
+            // is_local=true), the parameterizable, transaction-scoped equivalent of
+            // SET LOCAL, so both name and value are BOUND params, never interpolated.
             if (options?.sessionContext) {
                 if (!this.dialect.supportsRLS) {
                     throw new errors_js_1.UnsupportedFeatureError('sessionContext (RLS session GUCs)', this.dialect.name, 'set_config-based row-level-security context requires PostgreSQL.');
                 }
                 for (const [name, value] of Object.entries(options.sessionContext)) {
                     if (!GUC_NAME_REGEX.test(name)) {
-                        throw new errors_js_1.ValidationError(`[turbine] Invalid session-context GUC name "${name}" — must match ` +
+                        throw new errors_js_1.ValidationError(`[turbine] Invalid session-context GUC name "${name}", must match ` +
                             '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
                     }
                     const cfg = this.dialect.buildSetSessionConfig(name, String(value));
@@ -952,7 +953,7 @@ class TurbineClient {
             const runCallback = () => (wrap ? wrap.call(client, () => fn(tx)) : fn(tx));
             if (timeout) {
                 // Race between the function and a timeout. If the timeout fires we
-                // need to actually abort the in-flight query — otherwise the backend
+                // need to actually abort the in-flight query, otherwise the backend
                 // keeps running until pg's own timeout, holding a pool slot the whole
                 // time. The simplest reliable cancellation is to destroy the
                 // connection: passing a truthy argument to client.release() tells the
@@ -966,7 +967,7 @@ class TurbineClient {
                         // Destroy the connection to abort the in-flight backend query.
                         // We do this BEFORE rejecting so the socket is gone by the time
                         // the caller's catch block runs.
-                        releaseOnce(new Error('[turbine] Transaction timeout — connection destroyed'));
+                        releaseOnce(new Error('[turbine] Transaction timeout, connection destroyed'));
                         reject(new errors_js_1.TimeoutError(timeout, 'Transaction'));
                     }, timeout);
                 });
@@ -987,11 +988,11 @@ class TurbineClient {
             return result;
         }
         catch (err) {
-            // If the timeout fired we already destroyed the connection — issuing a
+            // If the timeout fired we already destroyed the connection, issuing a
             // ROLLBACK on a released client would throw "Client has already been
             // released". Skip the rollback in that case (the backend rolled back
             // when its socket was closed). Likewise skip it when BEGIN never
-            // succeeded (`began` false) — there is no transaction to roll back and
+            // succeeded (`began` false), there is no transaction to roll back and
             // the stray statement could hit another caller's transaction on a
             // shared-handle engine.
             if (began && !timedOut && !released) {
@@ -999,7 +1000,7 @@ class TurbineClient {
                     await client.query(this.dialect.rollbackStatement());
                 }
                 catch {
-                    // Best-effort rollback — the connection may have died mid-query.
+                    // Best-effort rollback, the connection may have died mid-query.
                 }
             }
             if (this.logging) {
@@ -1025,7 +1026,7 @@ class TurbineClient {
      *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
      *     concurrent calls and completes them in FIFO submission order), all
      *     statements are dispatched in one write burst and the replies are
-     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     collected in order, ~1 round trip plus server time. Only taken when
      *     the dialect's writes surface rows directly (`resultStrategy` !==
      *     'reselect'): a reselect plan is itself a sequential write+read pair.
      *
@@ -1095,7 +1096,7 @@ class TurbineClient {
         return this.$transaction(fn, { sessionContext: context });
     }
     // -------------------------------------------------------------------------
-    // LISTEN / NOTIFY — Postgres realtime pub/sub
+    // LISTEN / NOTIFY, Postgres realtime pub/sub
     // -------------------------------------------------------------------------
     /**
      * Subscribe to a Postgres NOTIFY channel. The handler fires with each
@@ -1110,12 +1111,12 @@ class TurbineClient {
      *
      * The channel name CANNOT be a bound parameter (`LISTEN $1` is a syntax
      * error), so it is validated against a strict identifier regex AND quoted via
-     * `quoteIdent` before interpolation — it is the only identifier this method
+     * `quoteIdent` before interpolation, it is the only identifier this method
      * places into SQL text.
      *
      * **Serverless caveat:** LISTEN needs a persistent connection that can push
      * async notifications. Stateless HTTP drivers (Neon HTTP, Vercel Postgres)
-     * cannot do this — `$listen` throws a `ConnectionError` rather than hang.
+     * cannot do this, `$listen` throws a `ConnectionError` rather than hang.
      * `$notify` works on every driver.
      *
      * @example
@@ -1146,7 +1147,7 @@ class TurbineClient {
     /**
      * Send a Postgres NOTIFY on `channel` with an optional payload string.
      *
-     * Issued as `SELECT pg_notify($1, $2)` — both the channel and payload are
+     * Issued as `SELECT pg_notify($1, $2)`, both the channel and payload are
      * BOUND parameters (no quoting/injection concern). The channel is still
      * validated against the identifier regex for parity with `$listen` and to
      * catch typos loudly. Works on every driver, including serverless HTTP pools.
@@ -1172,7 +1173,7 @@ class TurbineClient {
         }
     }
     // -------------------------------------------------------------------------
-    // Retry — automatic retry for retryable errors (deadlock, serialization)
+    // Retry, automatic retry for retryable errors (deadlock, serialization)
     // -------------------------------------------------------------------------
     /**
      * Execute an async function with automatic retry on retryable errors.
@@ -1215,7 +1216,7 @@ class TurbineClient {
      * Gracefully shut down the connection pool.
      *
      * If Turbine was given an external pool via `TurbineConfig.pool`, this
-     * method is a no-op — the caller is responsible for the pool's lifecycle.
+     * method is a no-op, the caller is responsible for the pool's lifecycle.
      */
     async disconnect() {
         // Tear down any live LISTEN subscriptions first. Each holds a dedicated
@@ -1234,7 +1235,7 @@ class TurbineClient {
             this.activeSubscriptions.clear();
         }
         // Close owned (string-configured) replica pools regardless of whether the
-        // primary is owned — external replica pools are left untouched (caller owns
+        // primary is owned, external replica pools are left untouched (caller owns
         // their lifecycle), same contract as an external primary.
         for (const replicaPool of this.ownedReplicaPools) {
             try {
@@ -1248,7 +1249,7 @@ class TurbineClient {
         }
         if (!this.ownsPool) {
             if (this.logging) {
-                console.log('[turbine] disconnect() skipped — external primary pool is not owned by Turbine');
+                console.log('[turbine] disconnect() skipped, external primary pool is not owned by Turbine');
             }
             return;
         }

package/dist/cjs/dialect.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — SQL dialect contract
+ * turbine-orm, SQL dialect contract
  *
  * Phase-1 seam for future database packages. The current package remains
  * PostgreSQL-native by default, but query generation now depends on this
@@ -40,6 +40,28 @@ export interface BulkInsertStatementInput {
     skipDuplicates?: boolean;
     /** Optional SQL-ready RETURNING selection. */
     returning?: ReturningSelection;
+    /**
+     * Force the row-major `VALUES (…), (…)` form even on a dialect that would
+     * otherwise batch column-major.
+     *
+     * Set when any target column is ARRAY-typed: PostgreSQL's `UNNEST` transpose
+     * flattens a nested array, so an array-valued column cannot survive it. The
+     * flag costs one placeholder per cell rather than per column, which is why
+     * it is opt-in rather than the default. Dialects that already emit `VALUES`
+     * ignore it.
+     */
+    requireRowValues?: boolean;
+}
+/**
+ * The cast/decode pair for one JSON-divergent column type. See
+ * {@link Dialect.jsonWireRule}. The two halves MUST agree: a cast with no
+ * matching decode silently returns text where a value is expected.
+ */
+export interface JsonWireRule {
+    /** The SQL expression to place in the JSON builder, given the column reference. */
+    sql(columnRef: string): string;
+    /** Turn the JSON-carried value back into the driver's representation. */
+    decode(value: unknown): unknown;
 }
 export interface BuiltStatement {
     sql: string;
@@ -58,7 +80,7 @@ export interface UpsertStatementInput {
     updateSetClauses: string[];
     /**
      * Optional SQL-ready predicate (no `WHERE` keyword) restricting the
-     * conflict-UPDATE to matching rows — used by global filters (soft-delete /
+     * conflict-UPDATE to matching rows, used by global filters (soft-delete /
      * multi-tenancy) so an upsert never resurrects/steals a row outside the
      * filter. Only honored by dialects that set
      * {@link Dialect.supportsUpsertUpdateWhere}; others must never receive it.
@@ -107,13 +129,13 @@ export interface CreateIndexStatementInput {
 /**
  * How a dialect surfaces the row(s) produced by an INSERT/UPDATE/DELETE/upsert.
  *
- *  - `'returning'` — a trailing `RETURNING *` clause returns the affected rows
+ *  - `'returning'`, a trailing `RETURNING *` clause returns the affected rows
  *    in the same statement (PostgreSQL, SQLite ≥ 3.35). The executor reads them
  *    directly from the statement result.
- *  - `'output'` — the statement itself emits the rows in a non-RETURNING shape
+ *  - `'output'`, the statement itself emits the rows in a non-RETURNING shape
  *    (SQL Server `OUTPUT INSERTED.*`). Executed exactly like `'returning'`: the
  *    rows come back on the statement result.
- *  - `'reselect'` — the engine cannot return rows from a write (MySQL). The
+ *  - `'reselect'`, the engine cannot return rows from a write (MySQL). The
  *    executor runs the write, then issues a follow-up `SELECT` (by primary
  *    key / unique / where predicate) to fetch the affected row(s). The build
  *    method supplies the {@link DeferredQuery} `reselect` plan that owns the
@@ -144,7 +166,7 @@ export interface OpenStreamOptions {
     ambientTransaction?: boolean;
 }
 /**
- * Inputs for {@link Dialect.buildUpdateStatement} — full UPDATE assembly. Used by
+ * Inputs for {@link Dialect.buildUpdateStatement}, full UPDATE assembly. Used by
  * engines whose returning shape is injected MID-statement rather than as a trailing
  * clause (SQL Server `OUTPUT INSERTED.*` lands between `SET …` and `WHERE …`).
  */
@@ -159,7 +181,7 @@ export interface UpdateStatementInput {
     returning?: ReturningSelection;
 }
 /**
- * Inputs for {@link Dialect.buildDeleteStatement} — full DELETE assembly. SQL Server
+ * Inputs for {@link Dialect.buildDeleteStatement}, full DELETE assembly. SQL Server
  * injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and `WHERE …`.
  */
 export interface DeleteStatementInput {
@@ -171,10 +193,10 @@ export interface DeleteStatementInput {
     returning?: ReturningSelection;
 }
 /**
- * Inputs for {@link Dialect.buildLimitOffset} — the trailing pagination clause of an
+ * Inputs for {@link Dialect.buildLimitOffset}, the trailing pagination clause of an
  * outer SELECT. PostgreSQL/MySQL/SQLite use `LIMIT x [OFFSET y]`; SQL Server has no
  * `LIMIT` and uses `[ORDER BY …] OFFSET y ROWS [FETCH NEXT x ROWS ONLY]` (which
- * requires an ORDER BY — a stable default is injected when {@link hasOrderBy} is false).
+ * requires an ORDER BY, a stable default is injected when {@link hasOrderBy} is false).
  */
 export interface LimitOffsetInput {
     /** SQL-ready placeholder/literal for the row LIMIT, or undefined for no limit. */
@@ -190,13 +212,13 @@ export interface LimitOffsetInput {
  * `json_agg(json_build_object(...))` (SQL Server's `FOR JSON PATH` expresses the
  * object shape through the child SELECT's column ALIASES rather than an explicit
  * `JSON_OBJECT`, so it cannot be assembled from {@link Dialect.buildJsonObject} /
- * {@link Dialect.buildJsonArrayAgg} primitives — see {@link Dialect.buildRelationSubquery}).
+ * {@link Dialect.buildJsonArrayAgg} primitives, see {@link Dialect.buildRelationSubquery}).
  *
  * The query builder pre-resolves the parts that are engine-independent (alias,
  * select/omit-resolved columns, recursion + param threading) and hands them to the
  * dialect. **Param-push ordering contract:** the override MUST push values to
  * {@link params} in the same order the builder's collect path expects so the SQL
- * cache and pipeline batching stay in sync —
+ * cache and pipeline batching stay in sync -
  *   - to-many with `limit`/`orderBy` (the "wrap" path) and manyToMany:
  *     `buildWhere(...)` → push `limit` → `recurse(...)` for each nested relation;
  *   - everything else (to-one, unordered/unlimited to-many): `recurse(...)` for each
@@ -207,7 +229,7 @@ export interface RelationSubqueryContext {
     relDef: RelationDef;
     /** The `with` spec for this relation: `true`, or a {@link WithOptions} object. */
     spec: true | WithOptions;
-    /** Shared parameter array — push BOUND values here in the order described above. */
+    /** Shared parameter array, push BOUND values here in the order described above. */
     params: unknown[];
     /** Parent alias or table name (RAW identifier, not quoted) to correlate against. */
     parentRef: string;
@@ -258,12 +280,12 @@ export interface Dialect {
     /** Build a JSON object expression from output keys and SQL expressions. */
     buildJsonObject(pairs: [key: string, expr: string][]): string;
     /**
-     * Build a positional JSON ARRAY expression from ordered SQL expressions —
+     * Build a positional JSON ARRAY expression from ordered SQL expressions -
      * the key-less counterpart to {@link buildJsonObject} used by the opt-in
      * `jsonEncoding: 'positional'` mode. Emitting `json_build_array(v1, v2, …)`
      * instead of `json_build_object('k1', v1, …)` drops every repeated key name
      * from every nested object of every row (the decode side maps positions back
-     * to keys via a build-time shape descriptor). Postgres-only in v1 — other
+     * to keys via a build-time shape descriptor). Postgres-only in v1, other
      * engines never reach this because the builder gates positional encoding to
      * `dialect.name === 'postgresql'`, so the method is optional on the contract.
      */
@@ -303,7 +325,7 @@ export interface Dialect {
      * (a predicate on the conflict-UPDATE, e.g. Postgres `ON CONFLICT … DO UPDATE
      * SET … WHERE …`). Global filters only push a conflict-UPDATE predicate when
      * this is true, so engines whose upsert cannot express one (MySQL
-     * `ON DUPLICATE KEY UPDATE`) never receive an orphaned parameter. Optional —
+     * `ON DUPLICATE KEY UPDATE`) never receive an orphaned parameter. Optional -
      * absent is treated as `false`.
      */
     readonly supportsUpsertUpdateWhere?: boolean;
@@ -374,6 +396,28 @@ export interface Dialect {
     buildJsonPathExtract(column: string, pathParamRef: string): string;
     /** Build a correlation clause across single or composite keys. */
     buildCorrelation(leftRef: string, leftColumns: string | string[], rightRef: string, rightColumns: string | string[]): string;
+    /**
+     * How a column whose JSON rendering DIVERGES from the driver's own value
+     * should be carried through a `with` subquery, or `undefined` when the
+     * column's JSON form already matches.
+     *
+     * A nested-relation subquery builds JSON (`json_build_object`,
+     * `json_group_array`, …) and the JSON number grammar is not the wire
+     * grammar: PostgreSQL renders `numeric` as a JSON number, SQLite renders a
+     * 64-bit INTEGER as one, and a JSON number is an IEEE double. So the same
+     * column read at top level and read through a relation came back as
+     * different values, LOSSILY past 2^53, and because `auto` picks between the
+     * join and batched strategies by row count, the same query could return
+     * either. The fix is to carry the value as text and decode it back with the
+     * engine's own rule, which is what this hook pairs up: `sql` must emit an
+     * expression the JSON builder can hold, and `decode` must turn that back
+     * into exactly what the driver would have produced.
+     *
+     * Omitting the hook keeps a dialect on the old behavior (no cast, no
+     * decode), which is correct for any engine whose JSON rendering agrees with
+     * its wire format.
+     */
+    jsonWireRule?(columnType: string): JsonWireRule | undefined;
     /** Optional type mapping hook for code generation/introspection. */
     typeToTypeScript?(dialectType: string, nullable: boolean): string;
     /**
@@ -469,7 +513,7 @@ export interface Dialect {
     buildLimitOffset?(input: LimitOffsetInput): string;
     /**
      * Assemble a full UPDATE statement. Optional: omitted by engines whose returning
-     * shape is a trailing clause (PG/SQLite `RETURNING`, MySQL none) — the builder
+     * shape is a trailing clause (PG/SQLite `RETURNING`, MySQL none), the builder
      * falls back to `UPDATE <t> SET <set> <where><returningClause>`. SQL Server
      * implements this to inject `OUTPUT INSERTED.*` between `SET …` and `WHERE …`.
      */
@@ -483,7 +527,7 @@ export interface Dialect {
      * OVERRIDE nested-relation subquery generation entirely. Optional: when a dialect
      * omits it, the builder uses its native `json_agg(json_build_object(...))` path
      * (PG) routed through {@link buildJsonObject} / {@link buildJsonArrayAgg} /
-     * {@link wrapJsonSubresult} — so MySQL and SQLite, which only swap those
+     * {@link wrapJsonSubresult}, so MySQL and SQLite, which only swap those
      * primitives, produce identical output and never define this hook. SQL Server
      * defines it to emit `FOR JSON PATH` correlated subqueries (its JSON aggregate
      * is expressed through the child SELECT's column aliases, which does not map onto
@@ -503,7 +547,7 @@ export interface IntrospectOptions {
 }
 /**
  * @deprecated Migration locking is owned by the {@link DatabaseAdapter} seam
- * (`src/adapters/index.ts` — `acquireLock`/`releaseLock`/`statementTimeout`),
+ * (`src/adapters/index.ts`, `acquireLock`/`releaseLock`/`statementTimeout`),
  * which is the single canonical locking seam. This interface was never
  * implemented or wired and is retained only for type back-compat; new engines
  * MUST provide a `DatabaseAdapter` instead. Will be removed in a future major.