turbine-orm 0.32.1 → 0.33.0

package/dist/cjs/dialect.js

@@ -58,6 +58,7 @@ exports.postgresDialect = {
     supportsListenNotify: true,
     supportsRLS: true,
     supportsAdvisoryLock: true,
+    supportsLateralJoin: true,
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/cjs/mssql.js

@@ -478,6 +478,9 @@ exports.mssqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // SQL Server has OUTER APPLY, not FROM-clause LATERAL: the lateral pick plan
+    // is Postgres-only (out of scope here).
+    supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.

package/dist/cjs/mysql.js

@@ -379,6 +379,9 @@ exports.mysqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // MySQL 8.0.14+ supports LATERAL, but the opt-in lateral pick plan stays
+    // Postgres-only in this release (flipping it on is a one-line change + tests).
+    supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery

package/dist/cjs/powdb.js

@@ -142,6 +142,9 @@ exports.powdbDialect = {
     supportsRLS: false,
     supportsAdvisoryLock: false,
     supportsILike: false,
+    // PowQL has no LATERAL construct; PowqlInterface refuses pick ordering
+    // earlier, this override keeps the flag truthful if a future path consults it.
+    supportsLateralJoin: false,
     beginStatement: () => 'begin',
     commitStatement: () => 'commit',
     rollbackStatement: () => 'rollback',

package/dist/cjs/powql.js

@@ -1216,6 +1216,17 @@ class PowqlInterface {
                 proj.push(`${a.alias}: ${a.fn}(${a.field ? this.ref(a.field) : `.${this.meta.primaryKey[0]}`})`);
             }
             const having = this.buildHaving(args.having, params);
+            // groupBy aggregate ordering (`_count` / `_sum` / … keys) has no PowQL
+            // equivalent here: `buildOrder` treats an `orderBy` key as a field ref, so
+            // a bare `_count: 'desc'` would silently emit an invalid `._count` sort.
+            // Refuse those keys explicitly; plain by-field ordering still flows through.
+            if (args.orderBy) {
+                for (const key of Object.keys(args.orderBy)) {
+                    if (key === '_count' || key === '_sum' || key === '_avg' || key === '_min' || key === '_max') {
+                        throw new errors_js_1.UnsupportedFeatureError('groupBy ordering by an aggregate', 'PowDB', `orderBy key "${key}"`);
+                    }
+                }
+            }
             const order = this.buildOrder(args.orderBy);
             const powql = `${this.qt}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
             const { rows } = await this.exec(powql, params, args.timeout);

package/dist/cjs/query/builder.js

@@ -995,14 +995,22 @@ class QueryInterface {
             else {
                 selectClause = `${qt}.*`;
             }
-            let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
+            // Piece-then-assemble. The join-sink between FROM and WHERE carries any
+            // `plan: 'lateral'` pick joins; it is populated during the ORDER BY build
+            // below and spliced in at final assembly. Empty for every other query
+            // shape → the assembled SQL is byte-identical to the incremental-append
+            // form for the default plan (asserted by the byte-equality snapshot test).
+            const lateralJoins = [];
+            // WHERE + cursor conditions accumulate into `tail`, pushing params in
+            // where → cursor order (the collect path mirrors this exactly).
+            let tail = freshWhereSql;
             if (args?.cursor) {
                 // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = (0, filters_js_1.sortedEntries)(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
-                        // orderBy values can be the { sort, nulls } spec form — normalize
+                        // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
                         const dir = args.orderBy?.[k];
                         const desc = (0, filters_js_1.isOrderBySpec)(dir) ? dir.sort === 'desc' : dir === 'desc';
@@ -1010,33 +1018,38 @@ class QueryInterface {
                         freshParams.push(v);
                         return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
                     });
-                    if (freshWhereSql) {
-                        sql += ` AND ${cursorConditions.join(' AND ')}`;
-                    }
-                    else {
-                        sql += ` WHERE ${cursorConditions.join(' AND ')}`;
-                    }
+                    tail += freshWhereSql ? ` AND ${cursorConditions.join(' AND ')}` : ` WHERE ${cursorConditions.join(' AND ')}`;
                 }
             }
-            if (args?.orderBy) {
-                if (distinctPrefix) {
-                    // Postgres requires DISTINCT ON expressions to lead the ORDER BY.
-                    // Prisma semantics ("first row per combination, result in the user's
-                    // order") need two levels: inner DISTINCT ON ordered by the distinct
-                    // columns then the user's order (picks the right representative row),
-                    // outer re-ordered by the user's order alone.
-                    if (Object.values(args.orderBy).some((d) => (0, filters_js_1.isVectorOrderBy)(d))) {
-                        throw new errors_js_1.ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
-                    }
-                    const userOrder = this.buildOrderBy(args.orderBy, freshParams);
-                    sql += ` ORDER BY ${distinctCols.map((c) => `${c} ASC`).join(', ')}, ${userOrder}`;
-                    sql = `SELECT * FROM (${sql}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
-                }
-                else {
-                    // Pass freshParams so vector KNN ordering binds its `$n::vector` query
-                    // vector at the correct position (after cursor params, before LIMIT).
-                    sql += ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams)}`;
+            // ORDER BY is built AFTER the cursor pushes (param order
+            // where → with → cursor → orderBy → limit → offset) and BEFORE final
+            // assembly (so the lateral sink is filled before the FROM clause is
+            // written). distinct + relation orderBy is refused up front, so a lateral
+            // pick can never reach the distinct branch (lateralJoins stays empty).
+            let sql;
+            if (args?.orderBy && distinctPrefix) {
+                // Postgres requires DISTINCT ON expressions to lead the ORDER BY. Prisma
+                // semantics ("first row per combination, result in the user's order")
+                // need two levels: inner DISTINCT ON ordered by the distinct columns then
+                // the user's order (picks the right representative row), outer re-ordered
+                // by the user's order alone.
+                if (Object.values(args.orderBy).some((d) => (0, filters_js_1.isVectorOrderBy)(d))) {
+                    throw new errors_js_1.ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
                 }
+                const userOrder = this.buildOrderBy(args.orderBy, freshParams);
+                const inner = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${tail} ORDER BY ${distinctCols
+                    .map((c) => `${c} ASC`)
+                    .join(', ')}, ${userOrder}`;
+                sql = `SELECT * FROM (${inner}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
+            }
+            else {
+                // Pass freshParams so vector KNN ordering binds its `$n::vector` query
+                // vector at the correct position (after cursor params, before LIMIT), and
+                // lateralJoins so a lateral pick splices its join into the FROM clause.
+                const orderBySql = args?.orderBy
+                    ? ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams, lateralJoins)}`
+                    : '';
+                sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${lateralJoins.join('')}${tail}${orderBySql}`;
             }
             // Pagination — push params in the same order the collect path mirrors
             // (limit before offset); the SQL TEXT shape is dialect-owned via
@@ -1854,6 +1867,15 @@ class QueryInterface {
         const selectExprs = [];
         /** by entries in order: how to read each group key off the result row. */
         const byReaders = [];
+        // ORDER BY registries: map each key the groupBy RESULT actually contains to
+        // the exact SELECT expression that produced it, so `orderBy` re-emits that
+        // expression (never a SELECT alias, since not every dialect accepts alias
+        // references in ORDER BY, and re-emitting mirrors HAVING's `jsonAggExprs`).
+        // `byOrderExprs`: plain by-field name / JSON group-key alias → column or
+        // extract expression. `aggOrderExprs`: `${aggKey}:${field}` → aggregate
+        // expression (including any already-bound JSON-path placeholder, reused
+        // exactly like HAVING since ORDER BY is appended after all other params).
+        const byOrderExprs = new Map();
         const usedResultKeys = new Set();
         const claimResultKey = (key, what) => {
             if (key === '_count' || usedResultKeys.has(key)) {
@@ -1874,6 +1896,7 @@ class QueryInterface {
                 groupExprs.push(this.q(col));
                 selectExprs.push(this.q(col));
                 byReaders.push({ resultKey: entry, rowKey: col, raw: false });
+                byOrderExprs.set(entry, this.q(col));
             }
             else {
                 const col = this.resolveJsonPathTarget('group key', entry.field, entry.path);
@@ -1885,13 +1908,24 @@ class QueryInterface {
                 selectExprs.push(`(${extract}) AS ${this.q(alias)}`);
                 groupExprs.push(extract);
                 byReaders.push({ resultKey: alias, rowKey: alias, raw: true });
+                // ORDER BY by this JSON alias re-emits the extract expression (with its
+                // already-bound $n): the same reuse HAVING does for JSON aggregates.
+                byOrderExprs.set(alias, extract);
             }
         }
         // _count
-        if (args._count === true || args._count === undefined) {
+        const countSelected = args._count === true || args._count === undefined;
+        if (countSelected) {
             // default: always include count
             selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
+        // ORDER BY aggregate expressions, keyed `${aggKey}:${field}` (plus a bare
+        // `_count`). Populated alongside the SELECT list below so `orderBy` can only
+        // reference an aggregate that is actually requested. `COUNT(*)` (uncast) is
+        // the ordering expression (the SELECT cast is only for the returned value).
+        const aggOrderExprs = new Map();
+        if (countSelected)
+            aggOrderExprs.set('_count', 'COUNT(*)');
         // _sum / _avg / _min / _max: `true` keeps the plain-column behavior; a
         // {@link JsonPathAggregateTarget} aggregates a JSON path under the arg key
         // as alias. `jsonAggFields` routes each JSON-aggregate row key back to its
@@ -1914,6 +1948,7 @@ class QueryInterface {
                     const inner = `${sqlFn}(${this.q(col)})`;
                     const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
                     selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${col}`)}`);
+                    aggOrderExprs.set(`${aggKey}:${key}`, expr);
                     continue;
                 }
                 const col = this.resolveJsonPathTarget(`${aggKey} target "${key}"`, target.field, target.path);
@@ -1931,6 +1966,7 @@ class QueryInterface {
                 selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${key}`)}`);
                 jsonAggFields.set(`${aggKey}_${key}`, { field: key, numeric });
                 jsonAggExprs.set(`${key}:${aggKey}`, expr);
+                aggOrderExprs.set(`${aggKey}:${key}`, expr);
             }
         };
         buildAggregates('_sum', 'SUM', args._sum);
@@ -1947,9 +1983,12 @@ class QueryInterface {
                 sql += ` HAVING ${havingClauses.join(' AND ')}`;
             }
         }
-        // ORDER BY
+        // ORDER BY, over the groupBy RESULT columns (by-fields, JSON aliases, and
+        // requested aggregates), not the table's physical columns.
         if (args.orderBy) {
-            sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
+            const orderSql = this.buildGroupByOrderBy(args.orderBy, byOrderExprs, aggOrderExprs);
+            if (orderSql)
+                sql += ` ORDER BY ${orderSql}`;
         }
         return {
             sql,
@@ -2014,6 +2053,74 @@ class QueryInterface {
             tag: `${this.table}.groupBy`,
         };
     }
+    /**
+     * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+     * ({@link buildOrderBy}, which validates keys against the table's physical
+     * columns), groupBy ordering targets the columns the RESULT actually
+     * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+     * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+     * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+     * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+     * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+     * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+     * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+     * by-key, throws {@link ValidationError} E003 listing the valid keys.
+     */
+    buildGroupByOrderBy(orderBy, byOrderExprs, aggOrderExprs) {
+        const aggBlocks = new Set(['_count', '_sum', '_avg', '_min', '_max']);
+        /** Human-readable list of every key this call can order by (for E003). */
+        const validKeys = () => {
+            const keys = [...byOrderExprs.keys()];
+            for (const k of aggOrderExprs.keys()) {
+                keys.push(k.includes(':') ? k.replace(':', '.') : k);
+            }
+            return keys.join(', ') || '(none)';
+        };
+        const parts = [];
+        for (const [key, value] of Object.entries(orderBy)) {
+            if (value === undefined)
+                continue;
+            // Aggregate ordering blocks.
+            if (aggBlocks.has(key)) {
+                if (key === '_count') {
+                    const expr = aggOrderExprs.get('_count');
+                    if (!expr) {
+                        throw new errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "_count" on table "${this.table}": _count is not selected. ` +
+                            `Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                    continue;
+                }
+                // `_sum` / `_avg` / `_min` / `_max`: an object of field → direction/spec.
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new errors_js_1.ValidationError(`[turbine] Invalid groupBy orderBy for "${key}" on table "${this.table}": ` +
+                        `expected a field map like { ${key}: { amount: 'desc' } }.`);
+                }
+                for (const [field, dirSpec] of Object.entries(value)) {
+                    if (dirSpec === undefined)
+                        continue;
+                    const expr = aggOrderExprs.get(`${key}:${field}`);
+                    if (!expr) {
+                        throw new errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${this.table}": ` +
+                            `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirSpec);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                }
+                continue;
+            }
+            // Plain by-field name or JSON group-key alias.
+            const expr = byOrderExprs.get(key);
+            if (!expr) {
+                throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". ` +
+                    `Orderable keys: ${validKeys()}.`);
+            }
+            const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
+            parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+        }
+        return parts.join(', ');
+    }
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a
@@ -4260,7 +4367,13 @@ class QueryInterface {
             const pickWhere = d.pick?.where
                 ? `;pw=${this.fingerprintAliasWhere(d.pick.where, targetTable)}`
                 : '';
-            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere})`;
+            // Plan discriminator: the lateral plan emits DIFFERENT SQL (a FROM-clause
+            // join + a qualified order term) so a warm cache must never serve one
+            // plan's SQL for the other. Emitted ONLY for `'lateral'`: absent means
+            // the default subquery plan, keeping every pre-existing cache key
+            // byte-identical (no cold-cache churn on upgrade).
+            const planTag = d.plan === 'lateral' ? ';plan=lat' : '';
+            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere}${planTag})`;
         }
         if ((0, filters_js_1.isOrderBySpec)(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
@@ -4277,7 +4390,7 @@ class QueryInterface {
         }
         return String(d);
     }
-    buildOrderBy(orderBy, params) {
+    buildOrderBy(orderBy, params, lateralSink) {
         // Dev-only: validate that orderBy fields exist in the table schema. Relation
         // orderBy keys (object values that are neither a vector nor an OrderBySpec)
         // are validated in the relation branch below, so skip them here.
@@ -4320,7 +4433,7 @@ class QueryInterface {
             // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
             // { name: 'asc' } }`).
             if (this.isRelationOrderByValue(value)) {
-                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params);
+                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params, undefined, lateralSink);
             }
             // Scalar column ordering — a plain direction or an OrderBySpec (nulls).
             if (meta && !(key in meta.columnMap)) {
@@ -4429,7 +4542,7 @@ class QueryInterface {
      * subquery's orderBy the relations live on the TARGET table's metadata and
      * the correlation parent is the relation's alias, not `this.table`.
      */
-    buildRelationOrderBy(relName, value, alias, params, ctx) {
+    buildRelationOrderBy(relName, value, alias, params, ctx, lateralSink) {
         const ownerMeta = ctx?.meta ?? this.tableMeta;
         const ownerTable = ctx?.table ?? this.table;
         const parentRef = ctx?.parentRef ?? this.table;
@@ -4445,7 +4558,7 @@ class QueryInterface {
         // scope errors, shared with the cache-hit collect mirror.
         if ((0, filters_js_1.isRelationPickOrderBy)(value)) {
             this.validatePickOrderBy(relName, relDef, value, ctx !== undefined);
-            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params);
+            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params, lateralSink);
         }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
@@ -4537,6 +4650,25 @@ class QueryInterface {
             throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`by\`: a target column name ` +
                 "or a JSON-path spec ({ field: 'data', path: ['title'] }).");
         }
+        // Physical plan gate. A typo like `plan: 'latreal'` must never silently run
+        // the subquery plan (a silent plan change wearing a validation gap). Shared
+        // by build and cache-hit collect so a warmed cache throws identically.
+        if (spec.plan !== undefined && spec.plan !== 'subquery' && spec.plan !== 'lateral') {
+            throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" has an invalid \`plan\`: ` +
+                `${JSON.stringify(spec.plan)}. Use 'subquery' (default) or 'lateral'.`);
+        }
+        if (spec.plan === 'lateral') {
+            if (!this.dialect.supportsLateralJoin) {
+                throw new errors_js_1.UnsupportedFeatureError("pick-row ordering with plan: 'lateral'", this.dialect.name, "LATERAL joins are only available on PostgreSQL. Omit `plan` (or use 'subquery').");
+            }
+            // The lateral exposes one reserved output column, `__turbine_pick`. A
+            // parent column with that exact name would make the unqualified WHERE
+            // reference ambiguous once the join is in scope; refuse it explicitly.
+            if (this.tableMeta.allColumns.includes('__turbine_pick')) {
+                throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' cannot be used: table "${this.tableMeta.name}" ` +
+                    'has a column named "__turbine_pick", which the lateral join output reserves.');
+            }
+        }
     }
     /**
      * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
@@ -4555,36 +4687,83 @@ class QueryInterface {
      * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
-    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params) {
+    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params, lateralSink) {
         if (!params) {
             throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" is only supported in a top-level findMany orderBy.`);
         }
         const targetMeta = this.schema.tables[relDef.to];
         if (!targetMeta)
             throw new errors_js_1.RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        const limitOne = this.buildPagination('1', undefined, true);
+        // Parents with ZERO surviving related rows have no row to pick: the
+        // correlated subquery yields NULL, and the LEFT JOIN LATERAL null-extends
+        // its single row identically. Without a nulls clause, Postgres DESC
+        // defaults to NULLS FIRST (every childless parent tops a "highest first"
+        // sort). Default to NULLS LAST in BOTH directions (deterministic across
+        // engines: SQLite's NULL-is-smallest default diverges from Postgres) unless
+        // the caller set `nulls` explicitly; the grammar gate matches nullsSuffix.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        // Lateral plan: splice a `LEFT JOIN LATERAL (... LIMIT 1) ON true` into the
+        // FROM clause (via the sink) and order by its single reserved output column.
+        // Param push order is IDENTICAL to the subquery plan (compilePickPieces is
+        // shared), so the cache-hit collect mirror needs no changes. Scope +
+        // capability were already enforced by validatePickOrderBy (shared with the
+        // collect path); the missing-sink guard catches a non-findMany build
+        // context and hard-fails rather than silently emitting a subquery.
+        if (spec.plan === 'lateral') {
+            if (!lateralSink) {
+                throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' on relation "${relName}" is only supported ` +
+                    'in a top-level findMany orderBy.');
+            }
+            const childAlias = `${alias}i`;
+            const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params);
+            lateralSink.push(` LEFT JOIN LATERAL (SELECT ${byExpr} AS ${this.q('__turbine_pick')} FROM ${this.q(relDef.to)} ${childAlias}` +
+                ` WHERE ${where}${orderClause}${limitOne}) ${alias} ON true`);
+            return `${alias}.${this.q('__turbine_pick')} ${dir}${nullsSql}`;
+        }
+        // Subquery plan (default): a correlated scalar subquery in ORDER BY.
+        const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, alias, parentRef, params);
+        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+    }
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params) {
         // The value surfaced from the picked row (SELECT list: its param binds first).
         let byExpr;
         if (typeof spec.by === 'string') {
             const col = this.resolveOrderByColumn(relDef.to, targetMeta, spec.by);
-            byExpr = `${alias}.${this.q(col)}`;
+            byExpr = `${childAlias}.${this.q(col)}`;
         }
         else {
             const col = this.validateJsonPathOrderBy(relDef.to, targetMeta, spec.by.field, {
                 path: spec.by.path,
             });
             params.push(this.jsonPathParam(spec.by.path));
-            const extract = this.dialect.buildJsonPathExtract(`${alias}.${this.q(col)}`, this.p(params.length));
+            const extract = this.dialect.buildJsonPathExtract(`${childAlias}.${this.q(col)}`, this.p(params.length));
             byExpr = spec.by.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         }
         // Correlation to the parent row, then the target's global filter (a
         // soft-deleted / other-tenant row must never be picked: matches the
         // `with` subquery and to-one relation-orderBy semantics), then pick.where.
-        let where = this.dialect.buildCorrelation(alias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
-        const gf = this.targetGlobalFilterAlias(relDef.to, alias, params);
+        let where = this.dialect.buildCorrelation(childAlias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
+        const gf = this.targetGlobalFilterAlias(relDef.to, childAlias, params);
         if (gf)
             where += ` AND ${gf}`;
         if (spec.pick.where) {
-            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, alias, spec.pick.where, params);
+            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, childAlias, spec.pick.where, params);
             if (pickWhere)
                 where += ` AND ${pickWhere}`;
         }
@@ -4592,21 +4771,8 @@ class QueryInterface {
         // (plain columns, OrderBySpec nulls, JSON-path specs); a nested pick in
         // here routes back through buildRelationOrderBy with ctx set and throws
         // the top-level-only E003.
-        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, alias, Object.entries(spec.pick.orderBy), params);
-        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        const limitOne = this.buildPagination('1', undefined, true);
-        // Parents with ZERO surviving related rows make the correlated subquery
-        // yield NULL. Without a nulls clause, Postgres DESC defaults to NULLS
-        // FIRST — every childless parent would top a "highest first" sort. Default
-        // to NULLS LAST in BOTH directions (deterministic across engines: SQLite's
-        // NULL-is-smallest default diverges from Postgres) unless the caller set
-        // `nulls` explicitly; the grammar gate matches nullsSuffix (PG + SQLite).
-        const nullsSql = spec.nulls
-            ? this.nullsSuffix(spec.nulls)
-            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
-                ? ' NULLS LAST'
-                : '';
-        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, childAlias, Object.entries(spec.pick.orderBy), params);
+        return { byExpr, where, orderClause };
     }
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same

package/dist/cjs/query/filters.js

@@ -319,9 +319,9 @@ function isJsonPathOrderBy(value) {
 }
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`
@@ -339,7 +339,7 @@ function isRelationPickOrderBy(value) {
     if (typeof v.pick !== 'object' || v.pick === null || Array.isArray(v.pick) || !('orderBy' in v.pick))
         return false;
     for (const key of Object.keys(v)) {
-        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls')
+        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls' && key !== 'plan')
             return false;
     }
     return true;

package/dist/cjs/sqlite.js

@@ -378,6 +378,8 @@ exports.sqliteDialect = {
     supportsListenNotify: false,
     supportsRLS: false,
     supportsAdvisoryLock: false,
+    // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
+    supportsLateralJoin: false,
     // json_group_array / json_object have no inline ORDER BY argument, so every
     // ordered to-many relation is forced through the inner-subquery rewrite.
     aggSupportsInlineOrderBy: false,

package/dist/dialect.d.ts

@@ -295,6 +295,13 @@ export interface Dialect {
     readonly supportsRLS: boolean;
     /** Whether this dialect/engine supports advisory-lock-style migration locking. */
     readonly supportsAdvisoryLock: boolean;
+    /**
+     * Whether this dialect supports `LEFT JOIN LATERAL (...) ON true` in the FROM
+     * clause. Gates the opt-in `plan: 'lateral'` pick-row ordering. Optional:
+     * absent is treated as `false`, so only dialects that set it true admit the
+     * lateral plan (else E017). PostgreSQL only in this release.
+     */
+    readonly supportsLateralJoin?: boolean;
     /** Build a dialect-specific RETURNING clause. Return an empty string when unsupported. */
     buildReturningClause(selection?: string): string;
     /** Build a single-row INSERT statement. Inputs are SQL-ready quoted fragments. */

package/dist/dialect.js

@@ -22,6 +22,7 @@ export const postgresDialect = {
     supportsListenNotify: true,
     supportsRLS: true,
     supportsAdvisoryLock: true,
+    supportsLateralJoin: true,
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/mssql.js

@@ -467,6 +467,9 @@ export const mssqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // SQL Server has OUTER APPLY, not FROM-clause LATERAL: the lateral pick plan
+    // is Postgres-only (out of scope here).
+    supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.

package/dist/mysql.js

@@ -368,6 +368,9 @@ export const mysqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // MySQL 8.0.14+ supports LATERAL, but the opt-in lateral pick plan stays
+    // Postgres-only in this release (flipping it on is a one-line change + tests).
+    supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery

package/dist/powdb.js

@@ -92,6 +92,9 @@ export const powdbDialect = {
     supportsRLS: false,
     supportsAdvisoryLock: false,
     supportsILike: false,
+    // PowQL has no LATERAL construct; PowqlInterface refuses pick ordering
+    // earlier, this override keeps the flag truthful if a future path consults it.
+    supportsLateralJoin: false,
     beginStatement: () => 'begin',
     commitStatement: () => 'commit',
     rollbackStatement: () => 'rollback',

package/dist/powql.js

@@ -1180,6 +1180,17 @@ export class PowqlInterface {
                 proj.push(`${a.alias}: ${a.fn}(${a.field ? this.ref(a.field) : `.${this.meta.primaryKey[0]}`})`);
             }
             const having = this.buildHaving(args.having, params);
+            // groupBy aggregate ordering (`_count` / `_sum` / … keys) has no PowQL
+            // equivalent here: `buildOrder` treats an `orderBy` key as a field ref, so
+            // a bare `_count: 'desc'` would silently emit an invalid `._count` sort.
+            // Refuse those keys explicitly; plain by-field ordering still flows through.
+            if (args.orderBy) {
+                for (const key of Object.keys(args.orderBy)) {
+                    if (key === '_count' || key === '_sum' || key === '_avg' || key === '_min' || key === '_max') {
+                        throw new UnsupportedFeatureError('groupBy ordering by an aggregate', 'PowDB', `orderBy key "${key}"`);
+                    }
+                }
+            }
             const order = this.buildOrder(args.orderBy);
             const powql = `${this.qt}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
             const { rows } = await this.exec(powql, params, args.timeout);

package/dist/query/builder.d.ts

@@ -382,6 +382,20 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    /**
+     * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+     * ({@link buildOrderBy}, which validates keys against the table's physical
+     * columns), groupBy ordering targets the columns the RESULT actually
+     * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+     * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+     * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+     * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+     * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+     * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+     * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+     * by-key, throws {@link ValidationError} E003 listing the valid keys.
+     */
+    private buildGroupByOrderBy;
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a
@@ -815,6 +829,17 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
     private buildRelationPickOrderBy;
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    private compilePickPieces;
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same
      * validation (a warmed cache can never skip it), then pushes in the same

package/dist/query/builder.js

@@ -959,14 +959,22 @@ export class QueryInterface {
             else {
                 selectClause = `${qt}.*`;
             }
-            let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
+            // Piece-then-assemble. The join-sink between FROM and WHERE carries any
+            // `plan: 'lateral'` pick joins; it is populated during the ORDER BY build
+            // below and spliced in at final assembly. Empty for every other query
+            // shape → the assembled SQL is byte-identical to the incremental-append
+            // form for the default plan (asserted by the byte-equality snapshot test).
+            const lateralJoins = [];
+            // WHERE + cursor conditions accumulate into `tail`, pushing params in
+            // where → cursor order (the collect path mirrors this exactly).
+            let tail = freshWhereSql;
             if (args?.cursor) {
                 // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
-                        // orderBy values can be the { sort, nulls } spec form — normalize
+                        // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
                         const dir = args.orderBy?.[k];
                         const desc = isOrderBySpec(dir) ? dir.sort === 'desc' : dir === 'desc';
@@ -974,33 +982,38 @@ export class QueryInterface {
                         freshParams.push(v);
                         return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
                     });
-                    if (freshWhereSql) {
-                        sql += ` AND ${cursorConditions.join(' AND ')}`;
-                    }
-                    else {
-                        sql += ` WHERE ${cursorConditions.join(' AND ')}`;
-                    }
+                    tail += freshWhereSql ? ` AND ${cursorConditions.join(' AND ')}` : ` WHERE ${cursorConditions.join(' AND ')}`;
                 }
             }
-            if (args?.orderBy) {
-                if (distinctPrefix) {
-                    // Postgres requires DISTINCT ON expressions to lead the ORDER BY.
-                    // Prisma semantics ("first row per combination, result in the user's
-                    // order") need two levels: inner DISTINCT ON ordered by the distinct
-                    // columns then the user's order (picks the right representative row),
-                    // outer re-ordered by the user's order alone.
-                    if (Object.values(args.orderBy).some((d) => isVectorOrderBy(d))) {
-                        throw new ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
-                    }
-                    const userOrder = this.buildOrderBy(args.orderBy, freshParams);
-                    sql += ` ORDER BY ${distinctCols.map((c) => `${c} ASC`).join(', ')}, ${userOrder}`;
-                    sql = `SELECT * FROM (${sql}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
-                }
-                else {
-                    // Pass freshParams so vector KNN ordering binds its `$n::vector` query
-                    // vector at the correct position (after cursor params, before LIMIT).
-                    sql += ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams)}`;
+            // ORDER BY is built AFTER the cursor pushes (param order
+            // where → with → cursor → orderBy → limit → offset) and BEFORE final
+            // assembly (so the lateral sink is filled before the FROM clause is
+            // written). distinct + relation orderBy is refused up front, so a lateral
+            // pick can never reach the distinct branch (lateralJoins stays empty).
+            let sql;
+            if (args?.orderBy && distinctPrefix) {
+                // Postgres requires DISTINCT ON expressions to lead the ORDER BY. Prisma
+                // semantics ("first row per combination, result in the user's order")
+                // need two levels: inner DISTINCT ON ordered by the distinct columns then
+                // the user's order (picks the right representative row), outer re-ordered
+                // by the user's order alone.
+                if (Object.values(args.orderBy).some((d) => isVectorOrderBy(d))) {
+                    throw new ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
                 }
+                const userOrder = this.buildOrderBy(args.orderBy, freshParams);
+                const inner = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${tail} ORDER BY ${distinctCols
+                    .map((c) => `${c} ASC`)
+                    .join(', ')}, ${userOrder}`;
+                sql = `SELECT * FROM (${inner}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
+            }
+            else {
+                // Pass freshParams so vector KNN ordering binds its `$n::vector` query
+                // vector at the correct position (after cursor params, before LIMIT), and
+                // lateralJoins so a lateral pick splices its join into the FROM clause.
+                const orderBySql = args?.orderBy
+                    ? ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams, lateralJoins)}`
+                    : '';
+                sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${lateralJoins.join('')}${tail}${orderBySql}`;
             }
             // Pagination — push params in the same order the collect path mirrors
             // (limit before offset); the SQL TEXT shape is dialect-owned via
@@ -1818,6 +1831,15 @@ export class QueryInterface {
         const selectExprs = [];
         /** by entries in order: how to read each group key off the result row. */
         const byReaders = [];
+        // ORDER BY registries: map each key the groupBy RESULT actually contains to
+        // the exact SELECT expression that produced it, so `orderBy` re-emits that
+        // expression (never a SELECT alias, since not every dialect accepts alias
+        // references in ORDER BY, and re-emitting mirrors HAVING's `jsonAggExprs`).
+        // `byOrderExprs`: plain by-field name / JSON group-key alias → column or
+        // extract expression. `aggOrderExprs`: `${aggKey}:${field}` → aggregate
+        // expression (including any already-bound JSON-path placeholder, reused
+        // exactly like HAVING since ORDER BY is appended after all other params).
+        const byOrderExprs = new Map();
         const usedResultKeys = new Set();
         const claimResultKey = (key, what) => {
             if (key === '_count' || usedResultKeys.has(key)) {
@@ -1838,6 +1860,7 @@ export class QueryInterface {
                 groupExprs.push(this.q(col));
                 selectExprs.push(this.q(col));
                 byReaders.push({ resultKey: entry, rowKey: col, raw: false });
+                byOrderExprs.set(entry, this.q(col));
             }
             else {
                 const col = this.resolveJsonPathTarget('group key', entry.field, entry.path);
@@ -1849,13 +1872,24 @@ export class QueryInterface {
                 selectExprs.push(`(${extract}) AS ${this.q(alias)}`);
                 groupExprs.push(extract);
                 byReaders.push({ resultKey: alias, rowKey: alias, raw: true });
+                // ORDER BY by this JSON alias re-emits the extract expression (with its
+                // already-bound $n): the same reuse HAVING does for JSON aggregates.
+                byOrderExprs.set(alias, extract);
             }
         }
         // _count
-        if (args._count === true || args._count === undefined) {
+        const countSelected = args._count === true || args._count === undefined;
+        if (countSelected) {
             // default: always include count
             selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
+        // ORDER BY aggregate expressions, keyed `${aggKey}:${field}` (plus a bare
+        // `_count`). Populated alongside the SELECT list below so `orderBy` can only
+        // reference an aggregate that is actually requested. `COUNT(*)` (uncast) is
+        // the ordering expression (the SELECT cast is only for the returned value).
+        const aggOrderExprs = new Map();
+        if (countSelected)
+            aggOrderExprs.set('_count', 'COUNT(*)');
         // _sum / _avg / _min / _max: `true` keeps the plain-column behavior; a
         // {@link JsonPathAggregateTarget} aggregates a JSON path under the arg key
         // as alias. `jsonAggFields` routes each JSON-aggregate row key back to its
@@ -1878,6 +1912,7 @@ export class QueryInterface {
                     const inner = `${sqlFn}(${this.q(col)})`;
                     const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
                     selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${col}`)}`);
+                    aggOrderExprs.set(`${aggKey}:${key}`, expr);
                     continue;
                 }
                 const col = this.resolveJsonPathTarget(`${aggKey} target "${key}"`, target.field, target.path);
@@ -1895,6 +1930,7 @@ export class QueryInterface {
                 selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${key}`)}`);
                 jsonAggFields.set(`${aggKey}_${key}`, { field: key, numeric });
                 jsonAggExprs.set(`${key}:${aggKey}`, expr);
+                aggOrderExprs.set(`${aggKey}:${key}`, expr);
             }
         };
         buildAggregates('_sum', 'SUM', args._sum);
@@ -1911,9 +1947,12 @@ export class QueryInterface {
                 sql += ` HAVING ${havingClauses.join(' AND ')}`;
             }
         }
-        // ORDER BY
+        // ORDER BY, over the groupBy RESULT columns (by-fields, JSON aliases, and
+        // requested aggregates), not the table's physical columns.
         if (args.orderBy) {
-            sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
+            const orderSql = this.buildGroupByOrderBy(args.orderBy, byOrderExprs, aggOrderExprs);
+            if (orderSql)
+                sql += ` ORDER BY ${orderSql}`;
         }
         return {
             sql,
@@ -1978,6 +2017,74 @@ export class QueryInterface {
             tag: `${this.table}.groupBy`,
         };
     }
+    /**
+     * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+     * ({@link buildOrderBy}, which validates keys against the table's physical
+     * columns), groupBy ordering targets the columns the RESULT actually
+     * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+     * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+     * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+     * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+     * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+     * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+     * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+     * by-key, throws {@link ValidationError} E003 listing the valid keys.
+     */
+    buildGroupByOrderBy(orderBy, byOrderExprs, aggOrderExprs) {
+        const aggBlocks = new Set(['_count', '_sum', '_avg', '_min', '_max']);
+        /** Human-readable list of every key this call can order by (for E003). */
+        const validKeys = () => {
+            const keys = [...byOrderExprs.keys()];
+            for (const k of aggOrderExprs.keys()) {
+                keys.push(k.includes(':') ? k.replace(':', '.') : k);
+            }
+            return keys.join(', ') || '(none)';
+        };
+        const parts = [];
+        for (const [key, value] of Object.entries(orderBy)) {
+            if (value === undefined)
+                continue;
+            // Aggregate ordering blocks.
+            if (aggBlocks.has(key)) {
+                if (key === '_count') {
+                    const expr = aggOrderExprs.get('_count');
+                    if (!expr) {
+                        throw new ValidationError(`[turbine] Cannot order groupBy by "_count" on table "${this.table}": _count is not selected. ` +
+                            `Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = normalizeOrderBy(value);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                    continue;
+                }
+                // `_sum` / `_avg` / `_min` / `_max`: an object of field → direction/spec.
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new ValidationError(`[turbine] Invalid groupBy orderBy for "${key}" on table "${this.table}": ` +
+                        `expected a field map like { ${key}: { amount: 'desc' } }.`);
+                }
+                for (const [field, dirSpec] of Object.entries(value)) {
+                    if (dirSpec === undefined)
+                        continue;
+                    const expr = aggOrderExprs.get(`${key}:${field}`);
+                    if (!expr) {
+                        throw new ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${this.table}": ` +
+                            `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = normalizeOrderBy(dirSpec);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                }
+                continue;
+            }
+            // Plain by-field name or JSON group-key alias.
+            const expr = byOrderExprs.get(key);
+            if (!expr) {
+                throw new ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". ` +
+                    `Orderable keys: ${validKeys()}.`);
+            }
+            const { dir, nulls } = normalizeOrderBy(value);
+            parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+        }
+        return parts.join(', ');
+    }
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a
@@ -4224,7 +4331,13 @@ export class QueryInterface {
             const pickWhere = d.pick?.where
                 ? `;pw=${this.fingerprintAliasWhere(d.pick.where, targetTable)}`
                 : '';
-            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere})`;
+            // Plan discriminator: the lateral plan emits DIFFERENT SQL (a FROM-clause
+            // join + a qualified order term) so a warm cache must never serve one
+            // plan's SQL for the other. Emitted ONLY for `'lateral'`: absent means
+            // the default subquery plan, keeping every pre-existing cache key
+            // byte-identical (no cold-cache churn on upgrade).
+            const planTag = d.plan === 'lateral' ? ';plan=lat' : '';
+            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere}${planTag})`;
         }
         if (isOrderBySpec(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
@@ -4241,7 +4354,7 @@ export class QueryInterface {
         }
         return String(d);
     }
-    buildOrderBy(orderBy, params) {
+    buildOrderBy(orderBy, params, lateralSink) {
         // Dev-only: validate that orderBy fields exist in the table schema. Relation
         // orderBy keys (object values that are neither a vector nor an OrderBySpec)
         // are validated in the relation branch below, so skip them here.
@@ -4284,7 +4397,7 @@ export class QueryInterface {
             // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
             // { name: 'asc' } }`).
             if (this.isRelationOrderByValue(value)) {
-                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params);
+                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params, undefined, lateralSink);
             }
             // Scalar column ordering — a plain direction or an OrderBySpec (nulls).
             if (meta && !(key in meta.columnMap)) {
@@ -4393,7 +4506,7 @@ export class QueryInterface {
      * subquery's orderBy the relations live on the TARGET table's metadata and
      * the correlation parent is the relation's alias, not `this.table`.
      */
-    buildRelationOrderBy(relName, value, alias, params, ctx) {
+    buildRelationOrderBy(relName, value, alias, params, ctx, lateralSink) {
         const ownerMeta = ctx?.meta ?? this.tableMeta;
         const ownerTable = ctx?.table ?? this.table;
         const parentRef = ctx?.parentRef ?? this.table;
@@ -4409,7 +4522,7 @@ export class QueryInterface {
         // scope errors, shared with the cache-hit collect mirror.
         if (isRelationPickOrderBy(value)) {
             this.validatePickOrderBy(relName, relDef, value, ctx !== undefined);
-            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params);
+            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params, lateralSink);
         }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
@@ -4501,6 +4614,25 @@ export class QueryInterface {
             throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`by\`: a target column name ` +
                 "or a JSON-path spec ({ field: 'data', path: ['title'] }).");
         }
+        // Physical plan gate. A typo like `plan: 'latreal'` must never silently run
+        // the subquery plan (a silent plan change wearing a validation gap). Shared
+        // by build and cache-hit collect so a warmed cache throws identically.
+        if (spec.plan !== undefined && spec.plan !== 'subquery' && spec.plan !== 'lateral') {
+            throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" has an invalid \`plan\`: ` +
+                `${JSON.stringify(spec.plan)}. Use 'subquery' (default) or 'lateral'.`);
+        }
+        if (spec.plan === 'lateral') {
+            if (!this.dialect.supportsLateralJoin) {
+                throw new UnsupportedFeatureError("pick-row ordering with plan: 'lateral'", this.dialect.name, "LATERAL joins are only available on PostgreSQL. Omit `plan` (or use 'subquery').");
+            }
+            // The lateral exposes one reserved output column, `__turbine_pick`. A
+            // parent column with that exact name would make the unqualified WHERE
+            // reference ambiguous once the join is in scope; refuse it explicitly.
+            if (this.tableMeta.allColumns.includes('__turbine_pick')) {
+                throw new ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' cannot be used: table "${this.tableMeta.name}" ` +
+                    'has a column named "__turbine_pick", which the lateral join output reserves.');
+            }
+        }
     }
     /**
      * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
@@ -4519,36 +4651,83 @@ export class QueryInterface {
      * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
-    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params) {
+    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params, lateralSink) {
         if (!params) {
             throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" is only supported in a top-level findMany orderBy.`);
         }
         const targetMeta = this.schema.tables[relDef.to];
         if (!targetMeta)
             throw new RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        const limitOne = this.buildPagination('1', undefined, true);
+        // Parents with ZERO surviving related rows have no row to pick: the
+        // correlated subquery yields NULL, and the LEFT JOIN LATERAL null-extends
+        // its single row identically. Without a nulls clause, Postgres DESC
+        // defaults to NULLS FIRST (every childless parent tops a "highest first"
+        // sort). Default to NULLS LAST in BOTH directions (deterministic across
+        // engines: SQLite's NULL-is-smallest default diverges from Postgres) unless
+        // the caller set `nulls` explicitly; the grammar gate matches nullsSuffix.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        // Lateral plan: splice a `LEFT JOIN LATERAL (... LIMIT 1) ON true` into the
+        // FROM clause (via the sink) and order by its single reserved output column.
+        // Param push order is IDENTICAL to the subquery plan (compilePickPieces is
+        // shared), so the cache-hit collect mirror needs no changes. Scope +
+        // capability were already enforced by validatePickOrderBy (shared with the
+        // collect path); the missing-sink guard catches a non-findMany build
+        // context and hard-fails rather than silently emitting a subquery.
+        if (spec.plan === 'lateral') {
+            if (!lateralSink) {
+                throw new ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' on relation "${relName}" is only supported ` +
+                    'in a top-level findMany orderBy.');
+            }
+            const childAlias = `${alias}i`;
+            const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params);
+            lateralSink.push(` LEFT JOIN LATERAL (SELECT ${byExpr} AS ${this.q('__turbine_pick')} FROM ${this.q(relDef.to)} ${childAlias}` +
+                ` WHERE ${where}${orderClause}${limitOne}) ${alias} ON true`);
+            return `${alias}.${this.q('__turbine_pick')} ${dir}${nullsSql}`;
+        }
+        // Subquery plan (default): a correlated scalar subquery in ORDER BY.
+        const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, alias, parentRef, params);
+        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+    }
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params) {
         // The value surfaced from the picked row (SELECT list: its param binds first).
         let byExpr;
         if (typeof spec.by === 'string') {
             const col = this.resolveOrderByColumn(relDef.to, targetMeta, spec.by);
-            byExpr = `${alias}.${this.q(col)}`;
+            byExpr = `${childAlias}.${this.q(col)}`;
         }
         else {
             const col = this.validateJsonPathOrderBy(relDef.to, targetMeta, spec.by.field, {
                 path: spec.by.path,
             });
             params.push(this.jsonPathParam(spec.by.path));
-            const extract = this.dialect.buildJsonPathExtract(`${alias}.${this.q(col)}`, this.p(params.length));
+            const extract = this.dialect.buildJsonPathExtract(`${childAlias}.${this.q(col)}`, this.p(params.length));
             byExpr = spec.by.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         }
         // Correlation to the parent row, then the target's global filter (a
         // soft-deleted / other-tenant row must never be picked: matches the
         // `with` subquery and to-one relation-orderBy semantics), then pick.where.
-        let where = this.dialect.buildCorrelation(alias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
-        const gf = this.targetGlobalFilterAlias(relDef.to, alias, params);
+        let where = this.dialect.buildCorrelation(childAlias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
+        const gf = this.targetGlobalFilterAlias(relDef.to, childAlias, params);
         if (gf)
             where += ` AND ${gf}`;
         if (spec.pick.where) {
-            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, alias, spec.pick.where, params);
+            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, childAlias, spec.pick.where, params);
             if (pickWhere)
                 where += ` AND ${pickWhere}`;
         }
@@ -4556,21 +4735,8 @@ export class QueryInterface {
         // (plain columns, OrderBySpec nulls, JSON-path specs); a nested pick in
         // here routes back through buildRelationOrderBy with ctx set and throws
         // the top-level-only E003.
-        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, alias, Object.entries(spec.pick.orderBy), params);
-        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        const limitOne = this.buildPagination('1', undefined, true);
-        // Parents with ZERO surviving related rows make the correlated subquery
-        // yield NULL. Without a nulls clause, Postgres DESC defaults to NULLS
-        // FIRST — every childless parent would top a "highest first" sort. Default
-        // to NULLS LAST in BOTH directions (deterministic across engines: SQLite's
-        // NULL-is-smallest default diverges from Postgres) unless the caller set
-        // `nulls` explicitly; the grammar gate matches nullsSuffix (PG + SQLite).
-        const nullsSql = spec.nulls
-            ? this.nullsSuffix(spec.nulls)
-            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
-                ? ' NULLS LAST'
-                : '';
-        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, childAlias, Object.entries(spec.pick.orderBy), params);
+        return { byExpr, where, orderClause };
     }
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same

package/dist/query/filters.d.ts

@@ -156,9 +156,9 @@ export declare function isOrderBySpec(value: unknown): value is OrderBySpec;
 export declare function isJsonPathOrderBy(value: unknown): value is JsonPathOrderBy;
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`

package/dist/query/filters.js

@@ -296,9 +296,9 @@ export function isJsonPathOrderBy(value) {
 }
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`
@@ -316,7 +316,7 @@ export function isRelationPickOrderBy(value) {
     if (typeof v.pick !== 'object' || v.pick === null || Array.isArray(v.pick) || !('orderBy' in v.pick))
         return false;
     for (const key of Object.keys(v)) {
-        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls')
+        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls' && key !== 'plan')
             return false;
     }
     return true;

package/dist/query/types.d.ts

@@ -657,6 +657,37 @@ export interface GroupByDistinctOn<T> {
     /** Which row survives per combination (required for determinism). */
     orderBy: Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy>;
 }
+/** A per-field aggregate ordering block: field/alias → direction or sort spec. */
+export type GroupByAggregateOrderBy = Record<string, OrderDirection | OrderBySpec>;
+/**
+ * {@link GroupByArgs.orderBy}: order the result groups by any column the
+ * groupBy result contains.
+ *
+ * - A plain **by-column** field name, or a **JSON group-key alias** (explicit
+ *   `alias`, else the last path segment): `{ region: 'asc' }`.
+ * - An **aggregate block**: `_count` takes a direction/spec directly
+ *   (`{ _count: 'desc' }`); `_sum`/`_avg`/`_min`/`_max` take a field map keyed
+ *   by a requested aggregate field/alias (`{ _sum: { amount: 'desc' } }`).
+ *
+ * An aggregate ordering that references an aggregate not requested in the same
+ * call (or an unknown by-key) throws {@link ValidationError} (E003). Every
+ * value accepts an {@link OrderBySpec} for `NULLS FIRST/LAST` placement
+ * (PostgreSQL / SQLite only).
+ */
+export interface GroupByOrderBy {
+    /** Order by the group's row count (requires `_count` to be selected). */
+    _count?: OrderDirection | OrderBySpec;
+    /** Order by a requested `_sum` aggregate, keyed by its field/alias. */
+    _sum?: GroupByAggregateOrderBy;
+    /** Order by a requested `_avg` aggregate, keyed by its field/alias. */
+    _avg?: GroupByAggregateOrderBy;
+    /** Order by a requested `_min` aggregate, keyed by its field/alias. */
+    _min?: GroupByAggregateOrderBy;
+    /** Order by a requested `_max` aggregate, keyed by its field/alias. */
+    _max?: GroupByAggregateOrderBy;
+    /** A by-column field name or JSON group-key alias → direction or sort spec. */
+    [key: string]: OrderDirection | OrderBySpec | GroupByAggregateOrderBy | undefined;
+}
 export interface GroupByArgs<T> {
     /** Group keys: plain column field names and/or JSON-path keys ({@link JsonPathGroupKey}). */
     by: ((keyof T & string) | JsonPathGroupKey)[];
@@ -678,8 +709,15 @@ export interface GroupByArgs<T> {
     _max?: GroupByAggregateSpec<T>;
     /** Filter whole groups by their aggregate values (SQL HAVING). JSON-path aggregates key by their alias. */
     having?: HavingClause<T>;
-    /** Order groups (supports {@link OrderBySpec} for NULLS placement). */
-    orderBy?: Record<string, OrderDirection | OrderBySpec>;
+    /**
+     * Order the result groups. Keys may be any column the groupBy result actually
+     * contains: a plain by-column field name, a JSON group-key alias (explicit
+     * `alias`, or the last path segment when unaliased), or an aggregate block
+     * (`_count`, or `_sum`/`_avg`/`_min`/`_max` mapping a requested field/alias to
+     * its direction). Every value supports {@link OrderBySpec} for NULLS
+     * placement. See {@link GroupByOrderBy}.
+     */
+    orderBy?: GroupByOrderBy;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
@@ -941,6 +979,17 @@ export interface RelationPickOrderBy {
      * "highest first" sort). Set `nulls` explicitly to override.
      */
     nulls?: 'first' | 'last';
+    /**
+     * Physical plan for the pick. `'subquery'` (default) compiles a correlated
+     * scalar subquery in ORDER BY. `'lateral'` (PostgreSQL only, E017 elsewhere)
+     * compiles a `LEFT JOIN LATERAL (... LIMIT 1) ON true` and orders by the
+     * joined value. Identical results; the lateral form can be significantly
+     * faster on large parent sets where the ordering subquery dominates the plan.
+     * Never falls back silently: contexts that cannot take a lateral (non-Postgres
+     * engines, `distinct`, nested `with` orderBy, a parent column literally named
+     * `__turbine_pick`) throw.
+     */
+    plan?: 'subquery' | 'lateral';
 }
 /**
  * An orderBy clause maps each key to one of:

package/dist/sqlite.js

@@ -370,6 +370,8 @@ export const sqliteDialect = {
     supportsListenNotify: false,
     supportsRLS: false,
     supportsAdvisoryLock: false,
+    // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
+    supportsLateralJoin: false,
     // json_group_array / json_object have no inline ORDER BY argument, so every
     // ordered to-many relation is forced through the inner-subquery rewrite.
     aggSupportsInlineOrderBy: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {