turbine-orm 0.32.2 → 0.34.0

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
@@ -4354,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 ?? ''})`;
@@ -4371,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.
@@ -4414,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)) {
@@ -4508,7 +4527,18 @@ class QueryInterface {
         const extract = this.dialect.buildJsonPathExtract(`${prefix}${this.q(col)}`, this.p(params.length));
         const lhs = spec.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        return `${lhs} ${dir}${this.nullsSuffix(spec.nulls)}`;
+        // Rows whose document lacks the path extract to NULL. Without a nulls
+        // clause, Postgres DESC defaults to NULLS FIRST, which both diverges from
+        // pick-row ordering (NULLS LAST both directions since 0.33) and from
+        // engines whose path ordering is nulls-last in both directions. Default to
+        // NULLS LAST in BOTH directions 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'
+                : '';
+        return `${lhs} ${dir}${nullsSql}`;
     }
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed
@@ -4523,7 +4553,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;
@@ -4539,7 +4569,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') {
@@ -4631,6 +4661,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
@@ -4649,36 +4698,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}`;
         }
@@ -4686,21 +4782,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/schema-builder.js

@@ -25,6 +25,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.camelToSnake = exports.column = exports.ColumnBuilder = void 0;
+exports.isDocFieldIndexDef = isDocFieldIndexDef;
 exports.defineSchema = defineSchema;
 exports.table = table;
 exports.applyManyToManyRelations = applyManyToManyRelations;
@@ -102,6 +103,10 @@ function resolveColumn(def) {
         check: def.check ?? null,
     };
 }
+/** Type guard: is this index declaration a doc-field expression index? */
+function isDocFieldIndexDef(idx) {
+    return 'docField' in idx && typeof idx.docField === 'string';
+}
 /** Check if a value is a TableDef (from legacy table() builder) */
 function isTableDef(v) {
     return typeof v === 'object' && v !== null && 'columns' in v && 'name' in v;
@@ -145,7 +150,17 @@ function defineSchema(input, options) {
             let pk;
             let m2m;
             let checks;
+            let indexes;
             for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'indexes') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "indexes" must be an array of index declarations`);
+                        }
+                        indexes = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
@@ -205,6 +220,7 @@ function defineSchema(input, options) {
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
                 ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
                 ...(checks && checks.length > 0 ? { checks } : {}),
+                ...(indexes && indexes.length > 0 ? { indexes } : {}),
             };
         }
     }

package/dist/cjs/schema-metadata.js

@@ -25,10 +25,12 @@
  *     the same conservative auto-`manyToMany` treatment as introspection.
  *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
  *     {@link applyManyToManyRelations} (additive, never clobbering).
- *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
- *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
- *     and the dev-mode missing-index warning stay silent instead of
- *     producing blanket false positives.
+ *   - `indexes` carries any declared `TableDef.indexes` (plain column and/or
+ *     PowDB doc-field expression indexes); a table with none declared gets
+ *     `[]`, which keeps `schemaHasIndexInfo()` false so the index advisor and
+ *     the dev-mode missing-index warning stay silent instead of producing
+ *     blanket false positives. Doc-field (docPath) indexes are ignored by the
+ *     advisor, so a doc-only index set never flips `schemaHasIndexInfo()`.
  *
  * @example
  * ```ts
@@ -45,6 +47,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.schemaDefToMetadata = schemaDefToMetadata;
+const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
 const schema_js_1 = require("./schema.js");
 const schema_builder_js_1 = require("./schema-builder.js");
@@ -97,6 +100,67 @@ function resolveColumnName(raw, target) {
     return (0, schema_js_1.camelToSnake)(raw);
 }
 // ---------------------------------------------------------------------------
+// Index declarations → IndexMetadata
+// ---------------------------------------------------------------------------
+/**
+ * Render a doc-field JSON path into an illustrative PowQL fragment for the
+ * `IndexMetadata.definition` field (debuggability only; the authoritative,
+ * lexer-exact emission lives in `powqlSchemaDDL`). String segments are shown
+ * double-quoted, integer array indexes bare.
+ */
+function docPathFragment(column, path) {
+    const segs = path.map((s) => (typeof s === 'number' ? `->${s}` : `->"${s}"`)).join('');
+    return `(.${column}${segs})`;
+}
+/**
+ * Convert a table's {@link SchemaIndexDef} list into {@link IndexMetadata}.
+ * A doc-field index carries `docPath` and `columns: [<json column>]`; a plain
+ * column index carries its snake_case column list and no `docPath`. Names are
+ * auto-derived (`<table>_<cols>_idx`) when not supplied.
+ */
+function mapIndexes(tableDef, declared) {
+    if (!declared || declared.length === 0)
+        return [];
+    const out = [];
+    for (const idx of declared) {
+        if ((0, schema_builder_js_1.isDocFieldIndexDef)(idx)) {
+            const column = (0, schema_js_1.camelToSnake)(idx.docField);
+            const segPart = idx.path.map((s) => (typeof s === 'number' ? String(s) : s)).join('_');
+            const name = idx.name ?? `${tableDef.name}_${column}_${segPart}_idx`;
+            // Validate numeric (array-index) segments up front: PowDB rejects a
+            // negative / fractional / NaN JSON-path index at migration time with an
+            // opaque parse error, so fail here with a typed ValidationError naming the
+            // index instead of emitting malformed PowQL later.
+            for (const seg of idx.path) {
+                if (typeof seg === 'number' && (!Number.isInteger(seg) || seg < 0)) {
+                    throw new errors_js_1.ValidationError(`[turbine] Doc-field index "${name}" on "${tableDef.name}": array-index path segment ${seg} must be a ` +
+                        'non-negative integer (a JSON array index). Use a string for an object key.');
+                }
+            }
+            out.push({
+                name,
+                columns: [column],
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}${docPathFragment(column, idx.path)}`,
+                docPath: [...idx.path],
+                declared: true,
+            });
+        }
+        else {
+            const columns = idx.columns.map(schema_js_1.camelToSnake);
+            const name = idx.name ?? `${tableDef.name}_${columns.join('_')}_idx`;
+            out.push({
+                name,
+                columns,
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}(${columns.join(', ')})`,
+                declared: true,
+            });
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
 // The converter
 // ---------------------------------------------------------------------------
 /**
@@ -122,10 +186,14 @@ function resolveColumnName(raw, target) {
  *   - Explicit `manyToMany` declarations → merged additively.
  *   - Schema-level `enums`.
  *
+ * What maps (continued):
+ *   - `indexes` → declared `TableDef.indexes` become `IndexMetadata` (plain
+ *     column indexes and PowDB doc-field expression indexes, the latter
+ *     carrying `docPath`). A table with no declared indexes gets `[]`, keeping
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no false
+ *     positives on index-less code-first metadata.
+ *
  * What SchemaDef cannot express (and how it degrades):
- *   - Indexes → every table gets `indexes: []`, which keeps
- *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
- *     false positives on code-first metadata.
  *   - Views → never marked (`isView` is introspection-only).
  *   - Composite foreign keys → `references:` is single-column by design.
  */
@@ -302,9 +370,12 @@ function schemaDefToMetadata(def) {
             primaryKey: pk,
             uniqueColumns,
             relations: relationsByTable.get(tableDef.name) ?? {},
-            // SchemaDef cannot express indexes. An empty list keeps
-            // schemaHasIndexInfo() false → no index-advisor false positives.
-            indexes: [],
+            // Declared `indexes` (plain column + doc-field expression) carry through;
+            // an undeclared table gets `[]`, which keeps schemaHasIndexInfo() false so
+            // the index advisor stays silent. Doc-field (docPath) indexes are ignored
+            // by the advisor entirely (see index-advisor.ts), so a doc-only index set
+            // never flips schemaHasIndexInfo() and never produces FK false positives.
+            indexes: mapIndexes(tableDef, tableDef.indexes),
         };
     }
     const enums = {};

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/index-advisor.d.ts

@@ -58,7 +58,21 @@ export declare function isProbeIndexed(meta: TableMetadata, columns: string[]):
  * should gate on {@link schemaHasIndexInfo} to avoid blanket false positives.
  */
 export declare function findMissingRelationIndexes(schema: SchemaMetadata): MissingRelationIndex[];
-/** True when at least one table in the schema carries index metadata. */
+/**
+ * True when at least one table in the schema carries real, DB-backed index
+ * metadata (i.e. from introspection).
+ *
+ * Excluded (so they never flip the flag, keeping the schema "index-info
+ * unknown"):
+ *   - doc-field expression indexes (`docPath`): they carry no FK-coverage info;
+ *   - code-first DECLARED indexes (`declared`): the SQL DDL generators do NOT
+ *     emit `TableDef.indexes` yet, so a declared index does not reflect a real
+ *     index on the SQL engines. Counting one would arm blanket FK false
+ *     positives (the FK auto-index the push path DID create is then reported
+ *     "missing") and, inversely, suppress warnings for indexes never created.
+ *     A pure code-first schema therefore stays silent exactly as it did before
+ *     `TableDef.indexes` existed.
+ */
 export declare function schemaHasIndexInfo(schema: SchemaMetadata): boolean;
 /**
  * Single-relation check for the dev-mode runtime warning: the (table, columns)

package/dist/index.d.ts

@@ -47,7 +47,7 @@ export { type AggregateArgs, type AggregateResult, type ArrayFilter, type Column
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
-export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, defineSchema, type ManyToManyDef, type ReferenceDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnIndexDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, type DocFieldIndexDef, defineSchema, isDocFieldIndexDef, type ManyToManyDef, type ReferenceDef, type SchemaDef, type SchemaIndexDef, type TableDef, table, } from './schema-builder.js';
 export { schemaDefToMetadata } from './schema-metadata.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';

package/dist/index.js

@@ -53,7 +53,7 @@ export { validateChannel } from './realtime.js';
 // Schema utilities
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 // Schema builder — define schemas in TypeScript
-export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, 
+export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, isDocFieldIndexDef, 
 // Legacy compat (deprecated — use object format with defineSchema)
 table, } from './schema-builder.js';
 // Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB

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/optional-peer-import.cjs

@@ -86,4 +86,32 @@ async function importOptionalPeer(specifier, allowEsmFallback = true) {
         return esmCapableCopy(specifier, false);
     }
 }
+/**
+ * Merged namespace so callers can reach {@link peerPackageVersion} off the same
+ * default import (`importOptionalPeer.peerPackageVersion(...)`). Lives in this
+ * `.cts` file for the same reason the dynamic import does: a `.cts` compiles to
+ * CommonJS in BOTH build passes, so `require` / `require.resolve` are natively
+ * available and `import.meta` is never emitted (which would break the CJS build
+ * and crash CJS consumers, see `resolveEmbeddedVersion` in powdb.ts).
+ */
+(function (importOptionalPeer) {
+    /**
+     * Resolve an optional peer's declared `package.json` version WITHOUT loading
+     * the package itself (so an ESM-only peer never trips `require`). `require` is
+     * anchored on THIS module's location (inside the published `dist/`), so bare
+     * resolution walks up `node_modules` and finds the peer exactly where
+     * `import.meta.url` used to point, but it compiles under `module: CommonJS`
+     * too. Returns `null` when the peer / its package.json cannot be resolved.
+     */
+    function peerPackageVersion(specifier) {
+        try {
+            const pkg = require(`${specifier}/package.json`);
+            return typeof pkg.version === 'string' ? pkg.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    importOptionalPeer.peerPackageVersion = peerPackageVersion;
+})(importOptionalPeer || (importOptionalPeer = {}));
 module.exports = importOptionalPeer;