turbine-orm 0.49.0 → 0.50.0

package/dist/cli/studio.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm CLI — Studio
+ * turbine-orm CLI: Studio
  *
  * A local web UI for browsing databases, exploring relations, and composing
  * queries visually. ORM-native since v0.19: there is no raw-SQL input surface.
@@ -46,7 +46,11 @@ import pg from 'pg';
 import { ValidationError } from '../errors.js';
 import { introspect } from '../introspect.js';
 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 } from '../query/utils.js';
 import { applyPiiTags, loadPiiTags } from './pii-tags.js';
+import { callerKey, checkRateLimit } from './rate-limit.js';
 import { createDemoContext } from './studio-demo.js';
 import { STUDIO_HTML } from './studio-ui.generated.js';
 // ---------------------------------------------------------------------------
@@ -84,10 +88,10 @@ export async function startStudio(options) {
         // seam in client.ts); the cast keeps one typed pool field for both modes.
         pool = new pg.Pool({
             connectionString: options.url,
-            max: 4, // small pool — single-user tool
+            max: 4, // small pool, single-user tool
             idleTimeoutMillis: 10_000,
         });
-        // Verify connectivity before starting the server — fail fast.
+        // Verify connectivity before starting the server, fail fast.
         const probe = await pool.connect();
         try {
             await probe.query('SELECT 1');
@@ -182,7 +186,7 @@ function originFor(host, port) {
 // ---------------------------------------------------------------------------
 export async function handleRequest(req, res, ctx) {
     const expectedOrigin = originFor(ctx.options.host, ctx.options.port);
-    // CORS: not needed — same-origin only. Explicitly refuse cross-origin.
+    // CORS: not needed, same-origin only. Explicitly refuse cross-origin.
     const origin = req.headers.origin;
     if (origin && origin !== expectedOrigin) {
         sendJson(res, 403, { error: 'cross-origin requests not allowed' });
@@ -211,26 +215,32 @@ export async function handleRequest(req, res, ctx) {
         sendHtml(res, 200, STUDIO_HTML, cspNonce());
         return;
     }
-    // Favicon — answered before the auth gate so the browser's automatic request
+    // Favicon: answered before the auth gate so the browser's automatic request
     // doesn't 401/404 on every load. No icon body needed (204).
     if (pathname === '/favicon.ico') {
         res.writeHead(204, { 'Content-Length': '0' });
         res.end();
         return;
     }
-    // API routes — all require auth.
-    if (!isAuthorized(req, ctx.authToken)) {
-        sendJson(res, 401, { error: 'unauthorized — use the URL printed in the terminal' });
-        return;
-    }
-    // Rate limiting — 100 requests per 60 seconds per authenticated session.
-    const rateLimitResult = checkRateLimit(ctx.rateLimiter, ctx.authToken);
+    // Rate limiting: 100 requests per 60 seconds, applied BEFORE the auth gate so
+    // an unauthenticated caller is throttled too (it used to run after, leaving
+    // token guessing unmetered). Keyed per caller rather than on `ctx.authToken`:
+    // that token is a single constant, so keying on it made one global bucket that
+    // every session shared. Authenticated and unauthenticated callers get separate
+    // buckets so a probing client cannot spend the real session's budget.
+    const authorized = isAuthorized(req, ctx.authToken);
+    const rateLimitResult = checkRateLimit(ctx.rateLimiter, `${authorized ? 'session' : 'anon'}:${callerKey(req)}`);
     if (!rateLimitResult.allowed) {
         const retryAfter = Math.ceil((rateLimitResult.resetAt - Date.now()) / 1000);
         res.setHeader('Retry-After', String(retryAfter));
         sendJson(res, 429, { error: 'Rate limit exceeded', retryAfter });
         return;
     }
+    // API routes: all require auth.
+    if (!authorized) {
+        sendJson(res, 401, { error: 'unauthorized: use the URL printed in the terminal' });
+        return;
+    }
     if (pathname === '/api/schema' && req.method === 'GET') {
         return apiSchema(res, ctx);
     }
@@ -313,32 +323,15 @@ function isAuthorized(req, expectedToken) {
         return true;
     }
     const cookieHeader = req.headers.cookie ?? '';
-    const match = /turbine_studio_token=([a-f0-9]+)/.exec(cookieHeader);
+    // Anchored on a cookie boundary: unanchored, a decoy cookie named
+    // `x_turbine_studio_token=...` matched first and the real cookie was never
+    // compared, locking the legitimate session out of its own Studio.
+    const match = /(?:^|;\s*)turbine_studio_token=([a-f0-9]+)/.exec(cookieHeader);
     if (match?.[1] && constantTimeEqual(match[1], expectedToken)) {
         return true;
     }
     return false;
 }
-// ---------------------------------------------------------------------------
-// Rate limiting
-// ---------------------------------------------------------------------------
-const RATE_LIMIT_WINDOW_MS = 60_000; // 60 seconds
-const RATE_LIMIT_MAX_REQUESTS = 100;
-function checkRateLimit(limiter, token) {
-    const now = Date.now();
-    const entry = limiter.get(token);
-    if (!entry || now >= entry.resetAt) {
-        // Start a new window
-        const resetAt = now + RATE_LIMIT_WINDOW_MS;
-        limiter.set(token, { count: 1, resetAt });
-        return { allowed: true, resetAt };
-    }
-    entry.count++;
-    if (entry.count > RATE_LIMIT_MAX_REQUESTS) {
-        return { allowed: false, resetAt: entry.resetAt };
-    }
-    return { allowed: true, resetAt: entry.resetAt };
-}
 function constantTimeEqual(a, b) {
     // Hash both inputs to fixed-length 32-byte SHA-256 digests before comparing.
     // This makes the comparison constant-length (timingSafeEqual never throws on a
@@ -418,10 +411,6 @@ async function apiSchema(res, ctx) {
         demo: ctx.demo === true,
     });
 }
-/** Own-property lookup: a key like `constructor` must not resolve off the prototype. */
-function ownLookup(map, key) {
-    return Object.hasOwn(map, key) ? map[key] : undefined;
-}
 /** True when `columnName` on `table` is PII-tagged and currently redacted. */
 function isRedactedColumn(table, columnName, showPii) {
     if (showPii)
@@ -507,7 +496,9 @@ export function relationLinksForTable(table, metadata, showPii) {
 // API: /api/tables/:name?limit=&offset=&orderBy=&dir=
 // ---------------------------------------------------------------------------
 export async function apiTableRows(res, ctx, rawTableName, params) {
-    const table = ctx.metadata.tables[rawTableName];
+    // Own-property lookup: `/api/tables/constructor` must 404 like any other
+    // unknown table rather than resolving Object.prototype and crashing.
+    const table = ownLookup(ctx.metadata.tables, rawTableName);
     if (!table) {
         sendJson(res, 404, { error: unknownTableMessage(rawTableName, ctx) });
         return;
@@ -516,7 +507,7 @@ export async function apiTableRows(res, ctx, rawTableName, params) {
     const offset = clampInt(params.get('offset'), 0, 0, 10_000_000);
     const orderByRaw = params.get('orderBy');
     const dir = params.get('dir')?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-    // orderBy — accept either the Postgres column name (snake) or the TS field
+    // orderBy: accept either the Postgres column name (snake) or the TS field
     // name (camel). Always emit the Postgres column in the SQL.
     // When redaction is on, PII columns are excluded from orderBy (and from the
     // search OR-set below): a redacted value must not be inferable through sort
@@ -543,7 +534,7 @@ export async function apiTableRows(res, ctx, rawTableName, params) {
     // Per-column filters: `filters` is a JSON array of { column, op, value }
     // composed by the Data tab's filter bar. Every column is validated against
     // the metadata, every op against a fixed whitelist, and every value is a
-    // parameter — same discipline as the builder route.
+    // parameter, same discipline as the builder route.
     let filters;
     try {
         filters = parseTableFilters(params.get('filters'), table, redactedPii);
@@ -682,7 +673,7 @@ const FILTER_OPS = {
     lte: '<=',
 };
 const FILTER_OP_NAMES = new Set([...Object.keys(FILTER_OPS), 'contains', 'isNull', 'notNull']);
-/** Hard cap on filter clauses per request — the UI never composes more. */
+/** Hard cap on filter clauses per request; the UI never composes more. */
 const MAX_TABLE_FILTERS = 10;
 /**
  * Parse + validate the Data tab's `filters` query param. Throws with a clear
@@ -742,53 +733,127 @@ function parseTableFilters(raw, table, redactedPii) {
     return out;
 }
 // ---------------------------------------------------------------------------
-// API: /api/builder — Turbine ORM findMany spec runner
+// 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 or SORTS on a redacted PII column.
+ * Refuse a builder query that FILTERS, SORTS, PAGES, or DE-DUPLICATES on a
+ * redacted PII column.
  *
  * Redacting the cells is not enough on its own: `where: { email: { startsWith:
  * 'a' } }` answers a question about the hidden value, and so does an `isNull`,
- * and so does an `orderBy`. The Data tab already refuses all three
- * (`parseTableFilters`); the builder route accepted them, which mattered the
- * moment PII tags actually started reaching Studio's metadata.
+ * and so does an `orderBy`. So does a `cursor`, which compiles into a WHERE
+ * range comparison (`"email" > $1`) and gives a clean binary search over the
+ * byte range even though every returned cell is redacted. So, more weakly, does
+ * `distinct`, which reports the cardinality of the hidden values. The Data tab
+ * 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.
  *
- * Walks the whole args tree: top-level `where` / `orderBy`, boolean
- * combinators, and each `with` level against that relation's target table.
- * `select` is NOT refused: it returns values, and those values are redacted on
- * the way out.
+ * 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.
  */
 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) => {
-        if (!table || depth > 10 || node === null || typeof node !== 'object')
+        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') {
-                for (const item of Array.isArray(value) ? value : [value])
-                    visitClause(item, table, depth + 1);
+                visitClause(value, table, depth + 1);
                 continue;
             }
             const relation = Object.hasOwn(table.relations, key) ? table.relations[key] : undefined;
             if (relation) {
-                // some / none / every / is / isNot wrappers all resolve against the target.
-                visitClause(value, metadata.tables[relation.to], depth + 1);
+                visitRelationValue(value, metadata.tables[relation.to], depth + 1);
                 continue;
             }
             const column = ownLookup(table.columnMap, key) ?? key;
-            if (isRedactedColumn(table, column, showPii)) {
-                throw new ValidationError(`[turbine] Column "${column}" on "${table.name}" is PII-tagged and redacted, so it cannot be used ` +
-                    `in a where or orderBy: filtering or sorting on a hidden value reveals it. ` +
-                    `Restart Studio with --show-pii to query it.`);
-            }
+            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) => {
-        if (!table || depth > 10)
+        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;
@@ -805,7 +870,7 @@ export async function apiBuilder(req, res, ctx) {
     const body = await readJsonBody(req);
     const tableName = typeof body?.table === 'string' ? body.table : '';
     const args = (body?.args ?? {});
-    if (!tableName || !ctx.metadata.tables[tableName]) {
+    if (!tableName || !ownLookup(ctx.metadata.tables, tableName)) {
         sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
         return;
     }
@@ -884,18 +949,18 @@ export async function apiBuilder(req, res, ctx) {
 // from those PK values alone, so a statement can only ever touch one row.
 //
 // Bulk form (insert/delete only): pass `rows: [...]` instead of `data`/`where`
-// — an array of data objects (insert) or PK-where objects (delete). Each entry
+// (an array of data objects for insert, or PK-where objects for delete). Each entry
 // goes through the exact same per-row validation and compiles to its own
 // single-row statement; all statements run in ONE transaction (all-or-nothing,
 // capped at MAX_BULK_ROWS). Predicate-based bulk writes stay deliberately
-// unsupported — every row is still addressed by its full primary key.
+// unsupported: every row is still addressed by its full primary key.
 // ---------------------------------------------------------------------------
 /** Hard cap on rows per bulk insert/delete request (matches the max page size). */
 const MAX_BULK_ROWS = 500;
 export async function apiRowWrite(req, res, ctx, op) {
     const body = await readJsonBody(req);
     const tableName = typeof body?.table === 'string' ? body.table : '';
-    const table = ctx.metadata.tables[tableName];
+    const table = ownLookup(ctx.metadata.tables, tableName);
     if (!table) {
         sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
         return;
@@ -1119,7 +1184,7 @@ function savedQueriesPath(ctx) {
 /** One-shot flag so the legacy saved-query notice isn't logged on every request. */
 let legacyDropNoticeShown = false;
 function loadSavedQueries(ctx) {
-    // Demo mode: in-memory only — never read the user's real saved-query file.
+    // Demo mode: in-memory only, never read the user's real saved-query file.
     if (ctx.demo) {
         if (!ctx.memorySavedQueries)
             ctx.memorySavedQueries = { version: 1, queries: [] };
@@ -1133,14 +1198,14 @@ function loadSavedQueries(ctx) {
         const parsed = JSON.parse(raw);
         if (!parsed.queries || !Array.isArray(parsed.queries))
             return { version: 1, queries: [] };
-        // Drop any legacy raw-SQL entries — Studio is builder-only now. Tell the
+        // Drop any legacy raw-SQL entries: Studio is builder-only now. Tell the
         // user instead of silently discarding their saved work (the file on disk
         // is only rewritten when a new query is saved, so this is recoverable).
         const queries = parsed.queries.filter((q) => q && q.kind === 'builder');
         const dropped = parsed.queries.length - queries.length;
         if (dropped > 0 && !legacyDropNoticeShown) {
             legacyDropNoticeShown = true;
-            console.warn(`[turbine studio] Ignoring ${dropped} legacy raw-SQL saved quer${dropped === 1 ? 'y' : 'ies'} in ${file} — ` +
+            console.warn(`[turbine studio] Ignoring ${dropped} legacy raw-SQL saved quer${dropped === 1 ? 'y' : 'ies'} in ${file}. ` +
                 'Studio is builder-only since v0.19. The entries remain in the file until a new query is saved.');
         }
         return { version: 1, queries };
@@ -1150,7 +1215,7 @@ function loadSavedQueries(ctx) {
     }
 }
 function writeSavedQueries(ctx, data) {
-    // Demo mode: in-memory only — nothing is ever written to disk.
+    // Demo mode: in-memory only, nothing is ever written to disk.
     if (ctx.demo) {
         ctx.memorySavedQueries = data;
         return;
@@ -1452,6 +1517,6 @@ function openUrl(url) {
         child.unref();
     }
     catch {
-        // Non-fatal — user can click the URL manually.
+        // Non-fatal: user can click the URL manually.
     }
 }

package/dist/cli/ui.d.ts

@@ -35,7 +35,7 @@ export declare const symbols: {
     readonly dot: "." | "∙";
     readonly line: "-" | "─";
     readonly vertLine: "|" | "│";
-    readonly topLeft: "╭" | "+";
+    readonly topLeft: "+" | "╭";
     readonly topRight: "+" | "╮";
     readonly bottomLeft: "+" | "╰";
     readonly bottomRight: "+" | "╯";

package/dist/cli/ui.js

@@ -211,16 +211,58 @@ export function stripAnsi(s) {
 // Redact password from connection URL
 // ---------------------------------------------------------------------------
 export function redactUrl(url) {
-    return (url
-        // Userinfo credentials. Anchored on `<scheme>://<user>:` and consuming up
-        // to the LAST `@` before the next `/` (or end of authority), because a
-        // password may legally contain `:`, `/`, and even `@` in percent-decoded
-        // form. The previous `:([^@/:]+)@` could not span any of those, so
-        // `postgres://u:pa/ss@host/db` came through completely unredacted and
-        // `postgres://u:a@b@host/db` leaked the tail. Global: one string may
-        // carry several URLs (a primary + replica pair).
-        .replace(/(\w+:\/\/[^/@\s]*?:)[^\s]*?@(?=[^@\s]*(?:[/?#]|$))/g, '$1***@')
+    return (redactUserinfo(url)
         // Query-string password params: `password=`, `sslpassword=`, and similar,
         // case-insensitive. Value runs up to the next `&`, `#`, or end of string.
         .replace(/([?&][^=&#]*password)=([^&#]*)/gi, '$1=***'));
 }
+/**
+ * Replace `<scheme>://<user>:<password>@` with `<scheme>://<user>:***@`, for
+ * every occurrence in the string (one message may carry a primary + replica
+ * pair). A password may legally contain `:`, `/`, and even `@` in
+ * percent-decoded form, so the credential runs to the LAST `@` of the authority.
+ *
+ * Deliberately a single forward scan rather than one regex: the previous
+ * `(\w+:\/\/[^/@\s]*?:)[^\s]*?@(?=[^@\s]*(?:[/?#]|$))` nested two lazy
+ * quantifiers under a lookahead and backtracked quadratically on input with no
+ * `@` at all (a 60 KB error message took ~16s). `redactUrl` runs on error text
+ * echoed back from Postgres, so that stalled the CLI. This version visits every
+ * character at most once.
+ */
+function redactUserinfo(input) {
+    const scheme = /\w+:\/\//g;
+    let out = '';
+    let copied = 0;
+    for (let m = scheme.exec(input); m; m = scheme.exec(input)) {
+        const start = m.index + m[0].length;
+        // Scan the run of non-whitespace characters that could hold userinfo,
+        // remembering the last `@`. A `/`, `?`, or `#` only ends the run once an `@`
+        // has been seen, so a password containing one is still covered; a URL with
+        // no credentials simply reaches the end of the run with no `@` recorded.
+        let i = start;
+        let lastAt = -1;
+        for (; i < input.length; i++) {
+            const ch = input.charAt(i);
+            if (/\s/.test(ch))
+                break;
+            if (ch === '@') {
+                lastAt = i;
+            }
+            else if (lastAt !== -1 && (ch === '/' || ch === '?' || ch === '#')) {
+                break;
+            }
+        }
+        if (lastAt !== -1) {
+            const colon = input.slice(start, lastAt).indexOf(':');
+            if (colon !== -1) {
+                out += `${input.slice(copied, start + colon + 1)}***@`;
+                copied = lastAt + 1;
+            }
+        }
+        // Resume after the scanned run. Every character in it has been accounted
+        // for, and a credential cannot span whitespace, so nothing is missed and the
+        // total work stays linear however many `scheme://` prefixes the input holds.
+        scheme.lastIndex = Math.max(i, start);
+    }
+    return copied === 0 ? input : out + input.slice(copied);
+}

package/dist/client.d.ts

@@ -216,6 +216,46 @@ export interface TurbineConfig {
      * when off). SQL engines only. See {@link RelationLoadStrategy}.
      */
     stableRelationOrder?: boolean;
+    /**
+     * When `true`, a `findMany` that paginates (`limit` / `take` / `offset`) but
+     * declares no `orderBy` is ordered by the table's primary key ascending
+     * (every column of a composite PK, in declaration order). An unordered
+     * `LIMIT` is non-deterministic: the same query can return different rows once
+     * the heap changes underneath it, so a row may appear on two pages or on
+     * none. An explicit `orderBy` always wins, PK-less tables are left alone, and
+     * `distinct` / `cursor` shapes are skipped.
+     *
+     * Default `false` in core, because switching it on would add an `ORDER BY` to
+     * SQL that existing applications already emit, changing both the rows a page
+     * returns and the plan the engine picks: a silent behavior change that waits
+     * for a major. `turbine-orm/prisma-compat` defaults it ON instead, since
+     * reproducing Prisma's semantics is that layer's contract. With it off the
+     * emitted SQL is byte-identical to before, and a dev-mode warning points at
+     * the affected queries.
+     */
+    implicitPkOrdering?: boolean;
+    /**
+     * Parent-row ceiling for the `relationLoadStrategy: 'auto'` to-one rule: a
+     * to-one relation stays in the single-statement join when the query's `limit`
+     * bounds the parent set at or under this many rows, and loads batched when the
+     * query is unbounded or bounded above it. Defaults to 1000 (see
+     * `AUTO_TO_ONE_JOIN_MAX_ROWS`). Only consulted under `'auto'`.
+     */
+    autoToOneJoinMaxRows?: number;
+    /**
+     * Round-trip time to the database, in milliseconds, used to DERIVE the
+     * `relationLoadStrategy: 'auto'` to-one threshold instead of guessing a row
+     * count. Prefer this over `autoToOneJoinMaxRows`: the break-even between the
+     * single-statement join and the batched follow-up is
+     * `roundTripMs / AUTO_JOIN_PENALTY_MS_PER_ROW`, and measurement shows the
+     * per-row penalty is a constant of the plan while the break-even moves ~17x
+     * between a loopback link and a 2.7ms one. Set it to what `ping` says (a
+     * Unix socket is ~0.05, same-region managed Postgres ~0.5-2, cross-region
+     * ~30-60). Defaults to `AUTO_ASSUMED_ROUND_TRIP_MS` (0.7ms, same-region),
+     * which reproduces the historical 1000-row threshold exactly. Overridden by
+     * an explicit `autoToOneJoinMaxRows`; only consulted under `'auto'`.
+     */
+    autoRoundTripMs?: number;
     /**
      * How nested-relation subqueries encode each row's JSON.
      *

package/dist/client.js

@@ -383,6 +383,9 @@ export class TurbineClient {
             utcTimestamps: config.utcTimestamps,
             relationLoadStrategy: config.relationLoadStrategy,
             stableRelationOrder: config.stableRelationOrder,
+            implicitPkOrdering: config.implicitPkOrdering,
+            autoToOneJoinMaxRows: config.autoToOneJoinMaxRows,
+            autoRoundTripMs: config.autoRoundTripMs,
             jsonEncoding: config.jsonEncoding,
             globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),

package/dist/dialect.d.ts

@@ -132,6 +132,17 @@ export interface StreamableConnection {
         rows: Record<string, unknown>[];
     }>;
 }
+/** Options for {@link Dialect.openStream}. */
+export interface OpenStreamOptions {
+    /**
+     * The connection is already inside a caller-owned transaction. Dialects that
+     * would otherwise wrap the stream in their own transaction MUST emit no
+     * BEGIN / COMMIT / ROLLBACK when this is true: the caller opened the
+     * transaction and owns ending it. Cursor cleanup (`CLOSE`) still runs, since
+     * the cursor lives on the caller's connection until their transaction ends.
+     */
+    ambientTransaction?: boolean;
+}
 /**
  * Inputs for {@link Dialect.buildUpdateStatement} — full UPDATE assembly. Used by
  * engines whose returning shape is injected MID-statement rather than as a trailing
@@ -435,8 +446,13 @@ export interface Dialect {
      * row batches of up to `batchSize`. PostgreSQL uses a `DECLARE CURSOR` /
      * `FETCH` / `CLOSE` loop inside a transaction; other engines use their
      * driver's native streaming iterator.
+     *
+     * `opts.ambientTransaction` tells the dialect the connection is ALREADY inside
+     * a caller-owned transaction, so it must not emit its own BEGIN / COMMIT /
+     * ROLLBACK (doing so would commit or discard the caller's uncommitted work
+     * mid-stream). Engines that emit no transaction control here ignore it.
      */
-    openStream(connection: StreamableConnection, sql: string, params: unknown[], batchSize: number): AsyncGenerator<Record<string, unknown>[], void, undefined>;
+    openStream(connection: StreamableConnection, sql: string, params: unknown[], batchSize: number, opts?: OpenStreamOptions): AsyncGenerator<Record<string, unknown>[], void, undefined>;
     /**
      * Schema introspector for this engine. `introspect()` routes through it so
      * engines can override the catalog SQL. PostgreSQL wraps the

package/dist/dialect.js

@@ -202,13 +202,18 @@ export const postgresDialect = {
             params: [name, value],
         };
     },
-    async *openStream(connection, sql, params, batchSize) {
-        // Cursors require a single connection inside a transaction. Identical SQL
-        // sequence to the historical inline implementation: BEGIN → DECLARE … NO
-        // SCROLL CURSOR FOR → FETCH n (loop) → CLOSE → COMMIT; ROLLBACK on error.
+    async *openStream(connection, sql, params, batchSize, opts) {
+        // Cursors require a single connection inside a transaction: BEGIN → DECLARE
+        // … NO SCROLL CURSOR FOR → FETCH n (loop) → CLOSE → COMMIT; ROLLBACK on
+        // error. Under an ambient (caller-owned) transaction the three transaction
+        // statements are skipped, but the cursor is still CLOSEd: it would otherwise
+        // sit open on the caller's connection until their transaction ends.
+        const ambient = opts?.ambientTransaction === true;
         const cursorName = `turbine_cursor_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
         const quotedCursor = this.quoteIdentifier(cursorName);
-        await connection.query(this.beginStatement());
+        if (!ambient)
+            await connection.query(this.beginStatement());
+        let failed = false;
         try {
             await connection.query(`DECLARE ${quotedCursor} NO SCROLL CURSOR FOR ${sql}`, params);
             while (true) {
@@ -219,18 +224,38 @@ export const postgresDialect = {
                 if (batch.rows.length < batchSize)
                     break;
             }
-            await connection.query(`CLOSE ${quotedCursor}`);
-            await connection.query(this.commitStatement());
         }
         catch (err) {
-            try {
-                await connection.query(this.rollbackStatement());
-            }
-            catch {
-                // Connection may already be broken — ignore rollback error.
+            // The transaction is aborted, so CLOSE would fail too: skip cleanup and
+            // let the rollback (ours, or the caller's on an ambient transaction) drop
+            // the cursor. Never let a cleanup failure mask this error.
+            failed = true;
+            if (!ambient) {
+                try {
+                    await connection.query(this.rollbackStatement());
+                }
+                catch {
+                    // Connection may already be broken, ignore rollback error.
+                }
             }
             throw err;
         }
+        finally {
+            // Reached on normal completion AND on early exit (`break` from the
+            // consumer's `for await` runs the generator's return path through here),
+            // which is the case the old try-only cleanup leaked.
+            if (!failed) {
+                try {
+                    await connection.query(`CLOSE ${quotedCursor}`);
+                }
+                catch {
+                    // Best-effort: a broken CLOSE must not replace a clean drain with an
+                    // error. Ending the transaction drops the cursor regardless.
+                }
+                if (!ambient)
+                    await connection.query(this.commitStatement());
+            }
+        }
     },
     // Postgres introspection wraps the information_schema / pg_catalog reader in
     // introspect.ts. A dynamic import keeps the static graph acyclic (introspect.ts