turbine-orm 0.65.0 → 0.66.0

package/dist/cli/studio.js

@@ -49,6 +49,7 @@ import { QueryInterface, quoteIdent } from '../query/index.js';
 // `ownLookup` is not re-exported from the query barrel, so it is imported from
 // its defining leaf module rather than duplicated here.
 import { ownLookup, registerUtcTemporalParsers } from '../query/utils.js';
+import { assertNoPiiPredicates as assertNoPiiPredicatesShared } from './pii-predicate-guard.js';
 import { applyPiiTags, loadPiiTags } from './pii-tags.js';
 import { callerKey, checkRateLimit } from './rate-limit.js';
 import { createDemoContext } from './studio-demo.js';
@@ -478,7 +479,7 @@ export function relationLinksForTable(table, metadata, showPii) {
     const referencedBy = [];
     const seenFkColumns = new Set();
     for (const [name, rel] of Object.entries(table.relations)) {
-        const target = metadata.tables[rel.to];
+        const target = ownLookup(metadata.tables, rel.to);
         if (!target)
             continue;
         if (rel.type === 'belongsTo') {
@@ -780,18 +781,6 @@ function parseTableFilters(raw, table, redactedPii) {
 // ---------------------------------------------------------------------------
 // API: /api/builder: Turbine ORM findMany spec runner
 // ---------------------------------------------------------------------------
-/** Relation-filter wrappers whose body is a clause against the relation's target. */
-const RELATION_FILTER_WRAPPERS = ['some', 'none', 'every', 'is', 'isNot'];
-/**
- * Recursion bound for the PII guard walk.
- *
- * This number is NOT the security boundary: reaching it REFUSES the request
- * (see `assertWithinDepth`). It only bounds the walk on a pathological payload.
- * It sits well above the query builder's own depth-10 relation cap
- * (`CircularRelationError`) and far above any hand-composed boolean nesting, so
- * nothing the builder would accept is refused here for depth alone.
- */
-const PII_GUARD_MAX_DEPTH = 32;
 /**
  * Refuse a builder query that FILTERS, SORTS, PAGES, or DE-DUPLICATES on a
  * redacted PII column.
@@ -805,111 +794,39 @@ const PII_GUARD_MAX_DEPTH = 32;
  * already refuses its own equivalents (`parseTableFilters`); the builder route
  * has to refuse all of them too.
  *
- * Walks the whole args tree: `where`, `orderBy` (object AND array form),
- * `cursor`, `distinct`, boolean combinators, relation filters, and each `with`
- * level against that relation's target table. `select` / `omit` are NOT
- * refused: they return values, and those values are redacted on the way out.
+ * The WALK lives in `cli/pii-predicate-guard.ts`, shared with the MCP server's
+ * `explain_query`, which asks the same question of the same arg tree. It used to
+ * be a second hand-written copy here, and the two drifted exactly the way copies
+ * do: a hole opened in both and could only have been closed in one. What stays
+ * here is the part that is genuinely Studio's: WHICH columns are hidden (a
+ * code-first `pii` tag, unless `--show-pii`), and what a refusal looks like (a
+ * `ValidationError`, which `/api/builder` renders as a 400).
  *
- * Every depth check FAILS CLOSED. Returning quietly at the cap (what this used
- * to do) meant padding a payload with, for example, eleven nested `NOT`
- * wrappers walked the guard off the end of its own recursion and then handed
- * the untouched predicate to the builder.
+ * `select` / `omit` are NOT refused: they return values, and those values are
+ * redacted on the way out.
  */
 function assertNoPiiPredicates(args, tableName, metadata, showPii) {
     if (showPii)
         return;
-    const assertWithinDepth = (depth) => {
-        if (depth <= PII_GUARD_MAX_DEPTH)
-            return;
-        throw new ValidationError(`[turbine] Query is nested more than ${PII_GUARD_MAX_DEPTH} levels deep, which is past the point where ` +
-            `Studio can prove it does not filter or sort on a PII-tagged and redacted column, so it is refused. ` +
-            `Flatten the query, or restart Studio with --show-pii.`);
-    };
-    const refuse = (table, column) => {
-        throw new ValidationError(`[turbine] Column "${column}" on "${table.name}" is PII-tagged and redacted, so it cannot be used ` +
-            `in a where, orderBy, cursor, or distinct: filtering, sorting, paging, or de-duplicating on a hidden ` +
-            `value reveals it. Restart Studio with --show-pii to query it.`);
-    };
-    const visitClause = (node, table, depth) => {
-        assertWithinDepth(depth);
-        if (!table || node === null || typeof node !== 'object')
-            return;
-        // `orderBy` accepts a Prisma-style array of single-key objects, and so does
-        // a `NOT` list. Element order carries no nesting, so the depth is unchanged.
-        if (Array.isArray(node)) {
-            for (const item of node)
-                visitClause(item, table, depth);
-            return;
-        }
-        for (const [key, value] of Object.entries(node)) {
-            if (key === 'AND' || key === 'OR' || key === 'NOT') {
-                visitClause(value, table, depth + 1);
-                continue;
-            }
-            const relation = Object.hasOwn(table.relations, key) ? table.relations[key] : undefined;
-            if (relation) {
-                visitRelationValue(value, metadata.tables[relation.to], depth + 1);
-                continue;
-            }
-            const column = ownLookup(table.columnMap, key) ?? key;
-            if (isRedactedColumn(table, column, showPii))
-                refuse(table, column);
-        }
-    };
-    /**
-     * A relation predicate arrives in one of two shapes, and BOTH resolve against
-     * the relation's target table: bare (`{ user: { email: {...} } }`) or wrapped
-     * in a cardinality / to-one operator (`{ user: { is: { email: {...} } } }`,
-     * likewise `some` / `none` / `every` / `isNot`). Handing the wrapper straight
-     * to `visitClause` walked its keys as if `is` were a column of the target, so
-     * the inner clause was never visited and a PII predicate slipped through.
-     * Descend into every wrapper member AND into the value itself.
-     */
-    const visitRelationValue = (value, target, depth) => {
-        assertWithinDepth(depth);
-        if (!target || value === null || typeof value !== 'object')
-            return;
-        const node = value;
-        for (const wrapper of RELATION_FILTER_WRAPPERS) {
-            if (Object.hasOwn(node, wrapper))
-                visitClause(node[wrapper], target, depth + 1);
-        }
-        visitClause(node, target, depth);
-    };
-    /** Field-name lists (`distinct`) name columns directly rather than in a clause. */
-    const visitFieldList = (value, table) => {
-        if (!Array.isArray(value))
-            return;
-        for (const field of value) {
-            if (typeof field !== 'string')
-                continue;
-            const column = ownLookup(table.columnMap, field) ?? field;
-            if (isRedactedColumn(table, column, showPii))
-                refuse(table, column);
-        }
-    };
-    const visitLevel = (level, table, depth) => {
-        assertWithinDepth(depth);
-        if (!table)
-            return;
-        visitClause(level.where, table, depth);
-        visitClause(level.orderBy, table, depth);
-        // `cursor` is a flat `{ field: value }` seek key that the builder turns into
-        // a WHERE range comparison against the sort key, so it reads exactly like a
-        // where on the same column.
-        visitClause(level.cursor, table, depth);
-        visitFieldList(level.distinct, table);
-        const withClause = level.with;
-        if (!withClause || typeof withClause !== 'object')
-            return;
-        for (const [relName, spec] of Object.entries(withClause)) {
-            const relation = Object.hasOwn(table.relations, relName) ? table.relations[relName] : undefined;
-            if (!relation || spec === true || spec === null || typeof spec !== 'object')
-                continue;
-            visitLevel(spec, metadata.tables[relation.to], depth + 1);
-        }
-    };
-    visitLevel(args, metadata.tables[tableName], 0);
+    assertNoPiiPredicatesShared(args, ownLookup(metadata.tables, tableName), {
+        metadata,
+        hiddenReason: (table, column) => (isRedactedColumn(table, column, showPii) ? 'is PII-tagged and redacted' : null),
+        refuseColumn: (table, column, reason) => {
+            throw new ValidationError(`[turbine] Column "${column}" on "${table.name}" ${reason}, so it cannot be used ` +
+                `in a where, orderBy, cursor, or distinct: filtering, sorting, paging, or de-duplicating on a hidden ` +
+                `value reveals it. Restart Studio with --show-pii to query it.`);
+        },
+        refuseDepth: (maxDepth) => {
+            throw new ValidationError(`[turbine] Query is nested more than ${maxDepth} levels deep, which is past the point where ` +
+                `Studio can prove it does not filter or sort on a PII-tagged and redacted column, so it is refused. ` +
+                `Flatten the query, or restart Studio with --show-pii.`);
+        },
+        refuseShape: (table, key) => {
+            throw new ValidationError(`[turbine] Studio does not recognize "${key}" in a query on "${table.name}", so it cannot prove the ` +
+                `query does not filter or sort on a PII-tagged and redacted column, and refuses it rather than ` +
+                `guessing. Remove it, or restart Studio with --show-pii.`);
+        },
+    });
 }
 export async function apiBuilder(req, res, ctx) {
     const body = await readJsonBody(req);
@@ -940,7 +857,7 @@ export async function apiBuilder(req, res, ctx) {
     // here (the user named the columns, and the values are redacted on the way
     // out); only the empty default projection is refused, with a reason instead
     // of a syntax error.
-    const target = ctx.metadata.tables[tableName];
+    const target = ownLookup(ctx.metadata.tables, tableName);
     if (target && !ctx.showPii && args.select === undefined && target.columns.every((c) => c.pii === true)) {
         sendJson(res, 400, {
             error: `Every column of "${tableName}" is PII-tagged, so the default projection is empty. Name the columns you ` +
@@ -974,7 +891,17 @@ export async function apiBuilder(req, res, ctx) {
             // the connection's search_path. Pin it to the configured --schema so the
             // Query tab reads the same schema as the Data tab (set_config is
             // transaction-local and fully parameterized). Demo has no schemas.
-            await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
+            //
+            // The VALUE is bound as a parameter, but Postgres parses the contents of
+            // search_path as an identifier LIST, so a name that needs quoting has to
+            // carry its own. Passing `My.Schema` raw makes Postgres read it as a
+            // two-part token that matches nothing: `current_schemas(false)` came back
+            // `{}` and the very next query died with `relation "widgets" does not
+            // exist` (measured on PG 16). A schema whose name merely differs in CASE
+            // is worse than that, because it silently folds to a DIFFERENT existing
+            // schema instead of failing. quoteIdent applies exactly the doubling rule
+            // the GUC parser expects.
+            await client.query(`SELECT set_config('search_path', $1, true)`, [quoteIdent(ctx.options.schema)]);
         }
         const started = Date.now();
         const result = await client.query(deferred.sql, deferred.params);
@@ -1173,7 +1100,11 @@ export async function apiRowWrite(req, res, ctx, op) {
         await client.query('BEGIN');
         if (!ctx.demo) {
             await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
-            await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
+            // Quoted for the same reason as the read path above: the bound value is
+            // parsed as an identifier list, so an unquoted mixed-case or dotted schema
+            // name pins search_path to nothing. On THIS path that would mean a write
+            // aimed at a non-default schema resolving somewhere else entirely.
+            await client.query(`SELECT set_config('search_path', $1, true)`, [quoteIdent(ctx.options.schema)]);
         }
         const returnedRows = [];
         let rowCount = 0;
@@ -1323,7 +1254,7 @@ export async function apiCreateSavedQuery(req, res, ctx) {
     const body = await readJsonBody(req);
     const table = typeof body?.table === 'string' ? body.table : '';
     const name = typeof body?.name === 'string' ? body.name.trim() : '';
-    if (!table || !ctx.metadata.tables[table]) {
+    if (!table || !ownLookup(ctx.metadata.tables, table)) {
         sendJson(res, 400, { error: unknownTableMessage(table, ctx) });
         return;
     }
@@ -1432,7 +1363,7 @@ function redactFlatRow(row, piiKeys) {
  * arrive as parsed json objects keyed by camelCase field names).
  */
 function redactBuilderRows(rows, tableName, withClause, metadata) {
-    const table = metadata.tables[tableName];
+    const table = ownLookup(metadata.tables, tableName);
     if (!table)
         return rows;
     const piiKeys = piiKeysForTable(table);

package/dist/cli/ui.d.ts

@@ -33,7 +33,7 @@ export declare const symbols: {
     readonly info: "i" | "ℹ";
     readonly warning: "⚠" | "!";
     readonly dot: "." | "∙";
-    readonly line: "─" | "-";
+    readonly line: "-" | "─";
     readonly vertLine: "|" | "│";
     readonly topLeft: "+" | "╭";
     readonly topRight: "+" | "╮";

package/dist/client.d.ts

@@ -724,6 +724,15 @@ export declare class TurbineClient {
     private readonly queryListeners;
     private queryOptions;
     private readonly errorMessagesSafe;
+    /**
+     * THIS client's error-message mode. Not the process default: see
+     * {@link registerClientErrorMessageMode}. Used to scope every operation
+     * issued through this client, but only once two clients in the process have
+     * asked for different modes.
+     */
+    private readonly errorMessageMode;
+    /** Per-table mode-scoping accessors, built lazily (see {@link table}). */
+    private readonly errorScopedTableCache;
     /** Whether `$on('query')` events carry real params (see `logQueryParams`). */
     private readonly queryParamsVisible;
     /** True when Turbine created the pool and is responsible for tearing it down */
@@ -913,6 +922,39 @@ export declare class TurbineClient {
      * With no replicas the original single-pool instance is returned directly.
      */
     table<T extends object = Record<string, unknown>>(name: string): QueryInterface<T>;
+    /** Get (and cache) the replica-routing accessor for a table. */
+    private routingAccessor;
+    /**
+     * Wrap a table accessor so every operation called through it runs with THIS
+     * client's `errorMessages` mode in force, whatever another client set as the
+     * process default.
+     *
+     * A proxy rather than a wrapper object: the QueryInterface mutates its own
+     * instance state during a query, so methods must run with the real instance
+     * as `this` (the same reason {@link createRoutingAccessor} is built this
+     * way). Method wrappers are memoized per property so a hot loop allocates one
+     * closure per operation NAME, not per call.
+     *
+     * The divergence test lives in the wrapper body, evaluated when the operation
+     * is CALLED. That placement is the point: an accessor minted before a second
+     * client diverges still scopes correctly once it does, and while no client has
+     * diverged the module default is already this client's mode, so the wrapper
+     * calls straight through and no AsyncLocalStorage scope is established at all.
+     */
+    private createErrorModeAccessor;
+    /**
+     * Run `fn` with this client's `errorMessages` mode in force, or directly when
+     * no other client in the process has diverged from it (the common case, which
+     * costs nothing). Used by the entry points that do not go through
+     * {@link table}: transactions, raw SQL, `pipeline`, and the typed-SQL builder.
+     *
+     * The typed-SQL builder is the one that cannot be covered by wrapping the
+     * call, because it is lazy: `sql` hands this function to `TypedSqlQuery` so
+     * the scope reaches the EXECUTION rather than the template. This docstring
+     * listed it as covered before 0.66 and it was not, which is the reason the
+     * mechanism is spelled out here instead of just named.
+     */
+    private withErrorMode;
     /** Get (and cache) the primary-pool-bound QueryInterface for a table. */
     private primaryTableQI;
     /**
@@ -1065,6 +1107,7 @@ export declare class TurbineClient {
      * ```
      */
     $transaction<T extends readonly DeferredQuery<unknown>[]>(queries: readonly [...T]): Promise<PipelineResults<T>>;
+    private runTransaction;
     /**
      * Execute a batch of {@link DeferredQuery} objects atomically inside one
      * transaction. Backs the `$transaction([...])` array overload. Reuses the raw

package/dist/client.js

@@ -23,7 +23,7 @@
  */
 import pg from 'pg';
 import { postgresDialect } from './dialect.js';
-import { ConnectionError, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+import { ConnectionError, errorMessageModesDiverged, registerClientErrorMessageMode, runWithErrorMessageMode, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
@@ -640,6 +640,15 @@ export class TurbineClient {
     queryListeners = new Set();
     queryOptions;
     errorMessagesSafe;
+    /**
+     * THIS client's error-message mode. Not the process default: see
+     * {@link registerClientErrorMessageMode}. Used to scope every operation
+     * issued through this client, but only once two clients in the process have
+     * asked for different modes.
+     */
+    errorMessageMode;
+    /** Per-table mode-scoping accessors, built lazily (see {@link table}). */
+    errorScopedTableCache = new Map();
     /** Whether `$on('query')` events carry real params (see `logQueryParams`). */
     queryParamsVisible;
     /** True when Turbine created the pool and is responsible for tearing it down */
@@ -677,6 +686,7 @@ export class TurbineClient {
             this.logging = parent.logging;
             this.dialect = parent.dialect;
             this.errorMessagesSafe = parent.errorMessagesSafe;
+            this.errorMessageMode = parent.errorMessageMode;
             this.queryParamsVisible = parent.queryParamsVisible;
             this.queryOptions = parent.queryOptions;
             this.middlewares = parent.middlewares; // shared reference: $use on parent flows through
@@ -830,7 +840,8 @@ export class TurbineClient {
         this.schema = schema;
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
-        this.errorMessagesSafe = (config.errorMessages ?? 'safe') === 'safe';
+        this.errorMessageMode = config.errorMessages ?? 'safe';
+        this.errorMessagesSafe = this.errorMessageMode === 'safe';
         // Query-event param visibility. One derived boolean, so the two config
         // spellings can never disagree: `logQueryParams` wins when set, otherwise
         // `errorMessages` keeps deciding exactly as it always has.
@@ -878,6 +889,16 @@ export class TurbineClient {
         };
         // Apply NotFoundError message redaction mode (default: safe, values are
         // stripped from messages to avoid leaking PII into error logs).
+        //
+        // The process-wide default keeps being set here, unchanged, so a directly
+        // constructed error and any single-client process behave exactly as before.
+        // What is new is the REGISTRATION: a second client asking for a different
+        // mode makes both of them scope their own operations, instead of the last
+        // constructor silently deciding for everyone (see
+        // registerClientErrorMessageMode). Registration uses the client's effective
+        // mode, defaulted, because two clients only agree if their EFFECTIVE modes
+        // agree, and an omitted `errorMessages` is an effective 'safe'.
+        registerClientErrorMessageMode(this.errorMessageMode);
         if (config.errorMessages) {
             setErrorMessageMode(config.errorMessages);
         }
@@ -1219,6 +1240,11 @@ export class TurbineClient {
         this.routingProxyCache.clear();
         for (const cache of this.replicaTableCaches)
             cache.clear();
+        // The errorMessages accessors too: each proxy holds its target by closure,
+        // so a stale one keeps handing back the pre-$use QueryInterface. Every
+        // cache `table()` reads through has to be listed here, and this one is the
+        // OUTERMOST, so leaving it out silently defeats all three above.
+        this.errorScopedTableCache.clear();
     }
     // -------------------------------------------------------------------------
     // Event emitter, subscribe to query lifecycle events
@@ -1266,9 +1292,31 @@ export class TurbineClient {
      * With no replicas the original single-pool instance is returned directly.
      */
     table(name) {
-        if (this.replicaPools.length === 0) {
-            return this.primaryTableQI(name);
+        const base = this.replicaPools.length === 0 ? this.primaryTableQI(name) : this.routingAccessor(name);
+        // The errorMessages accessor is built ALWAYS, not only once two clients have
+        // diverged. It used to be conditional here, and the condition was wrong in
+        // the one direction that leaks: divergence is a property of the PROCESS over
+        // time, while a table accessor is handed out once and kept. An application
+        // that does `const users = db.users` at module load, then constructs a
+        // second client with `errorMessages: 'verbose'` later (an analytics client,
+        // a per-suite test harness), held a bare unscoped reference forever, so the
+        // safe client's `findUniqueOrThrow` misses started rendering row values.
+        // Building the proxy unconditionally is what makes the mode a property of
+        // the client rather than of the construction order.
+        //
+        // The divergence check did not disappear, it moved INSIDE the wrapper, so it
+        // is asked when the operation runs rather than when the accessor is minted.
+        // While every client agrees the wrapper still establishes no scope and the
+        // query path still pays nothing but one proxy trap.
+        let scoped = this.errorScopedTableCache.get(name);
+        if (!scoped) {
+            scoped = this.createErrorModeAccessor(base);
+            this.errorScopedTableCache.set(name, scoped);
         }
+        return scoped;
+    }
+    /** Get (and cache) the replica-routing accessor for a table. */
+    routingAccessor(name) {
         let proxy = this.routingProxyCache.get(name);
         if (!proxy) {
             proxy = this.createRoutingAccessor(name);
@@ -1276,6 +1324,58 @@ export class TurbineClient {
         }
         return proxy;
     }
+    /**
+     * Wrap a table accessor so every operation called through it runs with THIS
+     * client's `errorMessages` mode in force, whatever another client set as the
+     * process default.
+     *
+     * A proxy rather than a wrapper object: the QueryInterface mutates its own
+     * instance state during a query, so methods must run with the real instance
+     * as `this` (the same reason {@link createRoutingAccessor} is built this
+     * way). Method wrappers are memoized per property so a hot loop allocates one
+     * closure per operation NAME, not per call.
+     *
+     * The divergence test lives in the wrapper body, evaluated when the operation
+     * is CALLED. That placement is the point: an accessor minted before a second
+     * client diverges still scopes correctly once it does, and while no client has
+     * diverged the module default is already this client's mode, so the wrapper
+     * calls straight through and no AsyncLocalStorage scope is established at all.
+     */
+    createErrorModeAccessor(target) {
+        const mode = this.errorMessageMode;
+        const wrapped = new Map();
+        return new Proxy(target, {
+            get(t, prop, receiver) {
+                const value = Reflect.get(t, prop, receiver);
+                if (typeof value !== 'function' || typeof prop !== 'string')
+                    return value;
+                let fn = wrapped.get(prop);
+                if (!fn) {
+                    fn = (...args) => {
+                        const call = () => value.apply(t, args);
+                        return errorMessageModesDiverged() ? runWithErrorMessageMode(mode, call) : call();
+                    };
+                    wrapped.set(prop, fn);
+                }
+                return fn;
+            },
+        });
+    }
+    /**
+     * Run `fn` with this client's `errorMessages` mode in force, or directly when
+     * no other client in the process has diverged from it (the common case, which
+     * costs nothing). Used by the entry points that do not go through
+     * {@link table}: transactions, raw SQL, `pipeline`, and the typed-SQL builder.
+     *
+     * The typed-SQL builder is the one that cannot be covered by wrapping the
+     * call, because it is lazy: `sql` hands this function to `TypedSqlQuery` so
+     * the scope reaches the EXECUTION rather than the template. This docstring
+     * listed it as covered before 0.66 and it was not, which is the reason the
+     * mechanism is spelled out here instead of just named.
+     */
+    withErrorMode(fn) {
+        return errorMessageModesDiverged() ? runWithErrorMessageMode(this.errorMessageMode, fn) : fn();
+    }
     /** Get (and cache) the primary-pool-bound QueryInterface for a table. */
     primaryTableQI(name) {
         let qi = this.tableCache.get(name);
@@ -1393,7 +1493,14 @@ export class TurbineClient {
         if (this.logging) {
             console.log(`[turbine] Pipeline: ${queries.length} queries, ${queries.map((q) => q.tag).join(', ')}`);
         }
-        return executePipeline(this.pool, queries, options);
+        // Scoped like every other entry point. A pipeline builds NotFoundErrors (a
+        // `buildFindUniqueOrThrow` slot) and wraps driver errors into
+        // `PipelineError.results[i]`, and none of that went through a mode scope
+        // before, so a safe client's miss inside a pipeline rendered the caller's
+        // where VALUES as soon as any verbose client existed in the process. The
+        // scope is established around the await, so every continuation of the batch
+        // resolves this client's mode.
+        return this.withErrorMode(() => executePipeline(this.pool, queries, options));
     }
     /**
      * Check whether the underlying pool supports the real pipeline protocol.
@@ -1434,7 +1541,7 @@ export class TurbineClient {
             return result.rows;
         }
         catch (err) {
-            throw wrapPgError(err);
+            throw this.withErrorMode(() => wrapPgError(err));
         }
     }
     /**
@@ -1469,7 +1576,13 @@ export class TurbineClient {
      */
     sql(strings, ...values) {
         const { sql, params } = buildTypedSql(strings, values, this.dialect);
-        return new TypedSqlQuery(this.pool, sql, params, this.logging);
+        // The scope has to be handed to the BUILDER, not wrapped around this call.
+        // `TypedSqlQuery` is lazy (it runs on `await` / `.one()` / `.scalar()`), so
+        // a scope opened here would close before any row was fetched. The
+        // `withErrorMode` docstring already claimed to cover the typed-SQL builder
+        // and did not, which left two raw-SQL entry points disagreeing about the
+        // same statement, since the adjacent `raw` tag WAS scoped.
+        return new TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn));
     }
     // -------------------------------------------------------------------------
     // Transaction support (raw, legacy)
@@ -1524,6 +1637,12 @@ export class TurbineClient {
         }
     }
     async $transaction(fnOrQueries, options) {
+        // Scope the WHOLE call, so the transaction-scoped QueryInterfaces built
+        // inside TransactionClient.table() inherit this client's mode without
+        // needing their own accessor.
+        return this.withErrorMode(() => this.runTransaction(fnOrQueries, options));
+    }
+    async runTransaction(fnOrQueries, options) {
         // Batch overload: an array of DeferredQuery objects runs atomically inside
         // one BEGIN…COMMIT, reusing the raw transaction machinery below.
         if (Array.isArray(fnOrQueries)) {