turbine-orm 0.78.0-next.4bd3c8f → 0.78.0-next.b792a6a

package/dist/cjs/powql.d.ts

@@ -155,6 +155,34 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * the two can never disagree about which limit is in force.
      */
     private effectiveLimit;
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    private childOptions?;
+    private loaderChildOptions;
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    private static pageOf;
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -623,9 +651,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
     private joinEligible;
     /**

package/dist/cjs/powql.js

@@ -393,6 +393,42 @@ class PowqlInterface {
     effectiveLimit(args) {
         return args.limit ?? this.defaultLimit;
     }
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    childOptions;
+    loaderChildOptions() {
+        this.childOptions ??= { ...this.options, defaultLimit: undefined, warnOnUnlimited: false };
+        return this.childOptions;
+    }
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    static pageOf(rows, limit, offset) {
+        if (limit === undefined && !offset)
+            return rows;
+        const start = offset ?? 0;
+        return rows.slice(start, limit === undefined ? undefined : start + limit);
+    }
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -974,7 +1010,7 @@ class PowqlInterface {
         const childCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const localField = this.meta.reverseColumnMap[localCol] ?? localCol;
         const childField = targetMeta.reverseColumnMap[childCol] ?? childCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collect = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -1013,7 +1049,7 @@ class PowqlInterface {
         const sourceRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
         const sourceRefColMeta = this.meta.columns.find((c) => c.name === sourceRefCol);
         const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collectTargetPks = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -1725,7 +1761,7 @@ class PowqlInterface {
             const rel = this.meta.relations[relName];
             if (!rel)
                 throw new errors_js_1.ValidationError(`Unknown relation "${relName}" on "${this.table}".`);
-            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
+            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args)) {
                 if (this.capabilities.serverJoins) {
                     await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
                     continue;
@@ -1748,7 +1784,19 @@ class PowqlInterface {
                 throw new errors_js_1.UnsupportedFeatureError('composite-key nested reads', 'PowDB', `relation "${relName}"`);
             }
             const options = (opt === true ? {} : opt);
-            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+            // The relation's own page, applied PER PARENT at stitch time (see pageOf),
+            // never on the flat fetch below.
+            const relLimit = options.limit;
+            const relOffset = options.offset;
+            this.assertPagination(relLimit, relOffset, `relation "${relName}"`);
+            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+            if (relLimit === 0) {
+                // `[]` on every parent by construction: nothing to fetch.
+                for (const parent of parents)
+                    parent[relName] = single ? null : [];
+                continue;
+            }
+            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
             const targetMeta = this.schema.tables[rel.to];
             // Local key on the parent, remote key on the target child.
             const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
@@ -1806,6 +1854,9 @@ class PowqlInterface {
                 };
                 const children = (await targetQi.findMany({
                     ...fetchOptions,
+                    // Unbounded: the relation limit/offset are per parent, applied below.
+                    limit: undefined,
+                    offset: undefined,
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
@@ -1832,11 +1883,12 @@ class PowqlInterface {
                         delete child[childKeyField];
                 }
             }
-            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
             for (const parent of parents) {
                 const k = this.joinKey(parent[parentKeyField]);
                 const matches = (k == null ? undefined : childByKey.get(k)) ?? [];
-                parent[relName] = single ? (matches[0] ?? null) : matches;
+                parent[relName] = single
+                    ? (matches[0] ?? null)
+                    : PowqlInterface.pageOf(matches, relLimit, relOffset);
             }
         }
     }
@@ -1902,7 +1954,13 @@ class PowqlInterface {
         }
         // (2) Target rows by PK, honouring the relation's own where/with/select/…
         const options = (opt === true ? {} : opt);
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
+        if (options.limit === 0) {
+            for (const parent of parents)
+                parent[relName] = [];
+            return;
+        }
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         // This loader stitches on the TARGET's own primary key, so the PK has to be
         // in the fetch even when the caller's select/omit excludes it, and has to
         // come back off afterwards. Exactly the shape `loadRelation` uses for its
@@ -1939,6 +1997,11 @@ class PowqlInterface {
             }
         }
         const targetByPk = new Map();
+        // Position of each target in the fetch, i.e. its rank under the relation's
+        // `orderBy`; the stitch below sorts a parent's children by it when an
+        // orderBy was given, so `limit` keeps that parent's top-N and not its first
+        // N junction rows. Across fetch CHUNKS the rank is fetch order.
+        const targetRank = new Map();
         const targetValList = [...allTargetVals].map((v) => targetPkColMeta ? coerceScalar(v, targetPkColMeta.tsType) : v);
         const targetChunk = this.keyChunkSize(targetMeta, targetPkCol);
         for (let i = 0; i < targetValList.length; i += targetChunk) {
@@ -1949,14 +2012,21 @@ class PowqlInterface {
             };
             const targets = (await targetQi.findMany({
                 ...fetchOptions,
+                // Unbounded: the relation limit/offset are per parent, applied in the stitch.
+                limit: undefined,
+                offset: undefined,
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
                 // Public findMany, so the sentinel form. See loadRelation above.
                 includePii: includePii ? types_js_1.UNSAFE : undefined,
             }));
-            for (const t of targets)
-                targetByPk.set(String(t[targetPkField]), t);
+            for (const t of targets) {
+                const pk = String(t[targetPkField]);
+                targetByPk.set(pk, t);
+                if (!targetRank.has(pk))
+                    targetRank.set(pk, targetRank.size);
+            }
         }
         // (3) Stitch: each parent → its junction targets (m2m is always a list).
         for (const parent of parents) {
@@ -1968,7 +2038,11 @@ class PowqlInterface {
                 if (child)
                     children.push(child);
             }
-            parent[relName] = children;
+            if (options.orderBy) {
+                const rank = (t) => targetRank.get(String(t[targetPkField])) ?? 0;
+                children.sort((a, b) => rank(a) - rank(b));
+            }
+            parent[relName] = PowqlInterface.pageOf(children, options.limit, options.offset);
         }
         // Stitching is done: take the forced PK back off. Iterating the map rather
         // than the stitched lists is deliberate, one target can be linked from many
@@ -2012,11 +2086,12 @@ class PowqlInterface {
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
-    joinEligible(rel, opt, args, parentCount) {
+    joinEligible(rel, opt, args) {
         const effLimit = args.limit ?? this.defaultLimit;
         if (effLimit !== undefined || args.offset)
             return false;
@@ -2057,9 +2132,8 @@ class PowqlInterface {
             return false;
         }
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
-        if ((options.limit !== undefined || options.offset) && (single || parentCount > MAX_RELATION_KEYS)) {
+        if ((options.limit !== undefined || options.offset) && single)
             return false;
-        }
         // A `limit 0` relation stays off the join statement for the same reason it
         // stays off a nested projection: PowDB answered `limit 0` with one row below
         // engine 0.20. The loader resolves it client-side, correctly on every version.
@@ -2106,13 +2180,13 @@ class PowqlInterface {
         const { cols: childCols, forcedPk: childForcedPk } = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
         const order = targetQi.buildOrder(options.orderBy, params, 'c');
+        // No limit/offset clause: on the join they would bound the TOTAL child
+        // count across every parent. The relation's page is per parent (pageOf).
         this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
-        const limitClause = options.limit !== undefined ? ` limit ${this.param(options.limit, params)}` : '';
-        const offsetClause = options.offset ? ` offset ${this.param(options.offset, params)}` : '';
         const proj = this.joinProjection(childCols, `p.${(0, powdb_shared_js_1.quotePowqlIdent)(parentKeyCol)}`, 'c');
         const powql = `${targetQi.qt} as c join ${this.qt} as p ` +
             `on c.${(0, powdb_shared_js_1.quotePowqlIdent)(childKeyCol)} = p.${(0, powdb_shared_js_1.quotePowqlIdent)(parentKeyCol)}` +
-            `${filter}${order}${limitClause}${offsetClause} ${proj}`;
+            `${filter}${order} ${proj}`;
         // A READ: thread a read-shaped action through the exec seam.
         const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
@@ -2120,7 +2194,9 @@ class PowqlInterface {
         for (const p of parents) {
             const key = this.joinKey(p[parentKeyField]);
             const matches = (key == null ? undefined : byKey.get(key)) ?? [];
-            p[relName] = single ? (matches[0] ?? null) : matches;
+            p[relName] = single
+                ? (matches[0] ?? null)
+                : PowqlInterface.pageOf(matches, options.limit, options.offset);
         }
     }
     /**

package/dist/powql.d.ts

@@ -155,6 +155,34 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * the two can never disagree about which limit is in force.
      */
     private effectiveLimit;
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    private childOptions?;
+    private loaderChildOptions;
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    private static pageOf;
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -623,9 +651,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
     private joinEligible;
     /**

package/dist/powql.js

@@ -357,6 +357,42 @@ export class PowqlInterface {
     effectiveLimit(args) {
         return args.limit ?? this.defaultLimit;
     }
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    childOptions;
+    loaderChildOptions() {
+        this.childOptions ??= { ...this.options, defaultLimit: undefined, warnOnUnlimited: false };
+        return this.childOptions;
+    }
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    static pageOf(rows, limit, offset) {
+        if (limit === undefined && !offset)
+            return rows;
+        const start = offset ?? 0;
+        return rows.slice(start, limit === undefined ? undefined : start + limit);
+    }
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -938,7 +974,7 @@ export class PowqlInterface {
         const childCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const localField = this.meta.reverseColumnMap[localCol] ?? localCol;
         const childField = targetMeta.reverseColumnMap[childCol] ?? childCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collect = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -977,7 +1013,7 @@ export class PowqlInterface {
         const sourceRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
         const sourceRefColMeta = this.meta.columns.find((c) => c.name === sourceRefCol);
         const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collectTargetPks = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -1689,7 +1725,7 @@ export class PowqlInterface {
             const rel = this.meta.relations[relName];
             if (!rel)
                 throw new ValidationError(`Unknown relation "${relName}" on "${this.table}".`);
-            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
+            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args)) {
                 if (this.capabilities.serverJoins) {
                     await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
                     continue;
@@ -1712,7 +1748,19 @@ export class PowqlInterface {
                 throw new UnsupportedFeatureError('composite-key nested reads', 'PowDB', `relation "${relName}"`);
             }
             const options = (opt === true ? {} : opt);
-            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+            // The relation's own page, applied PER PARENT at stitch time (see pageOf),
+            // never on the flat fetch below.
+            const relLimit = options.limit;
+            const relOffset = options.offset;
+            this.assertPagination(relLimit, relOffset, `relation "${relName}"`);
+            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+            if (relLimit === 0) {
+                // `[]` on every parent by construction: nothing to fetch.
+                for (const parent of parents)
+                    parent[relName] = single ? null : [];
+                continue;
+            }
+            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
             const targetMeta = this.schema.tables[rel.to];
             // Local key on the parent, remote key on the target child.
             const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
@@ -1770,6 +1818,9 @@ export class PowqlInterface {
                 };
                 const children = (await targetQi.findMany({
                     ...fetchOptions,
+                    // Unbounded: the relation limit/offset are per parent, applied below.
+                    limit: undefined,
+                    offset: undefined,
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
@@ -1796,11 +1847,12 @@ export class PowqlInterface {
                         delete child[childKeyField];
                 }
             }
-            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
             for (const parent of parents) {
                 const k = this.joinKey(parent[parentKeyField]);
                 const matches = (k == null ? undefined : childByKey.get(k)) ?? [];
-                parent[relName] = single ? (matches[0] ?? null) : matches;
+                parent[relName] = single
+                    ? (matches[0] ?? null)
+                    : PowqlInterface.pageOf(matches, relLimit, relOffset);
             }
         }
     }
@@ -1866,7 +1918,13 @@ export class PowqlInterface {
         }
         // (2) Target rows by PK, honouring the relation's own where/with/select/…
         const options = (opt === true ? {} : opt);
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
+        if (options.limit === 0) {
+            for (const parent of parents)
+                parent[relName] = [];
+            return;
+        }
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         // This loader stitches on the TARGET's own primary key, so the PK has to be
         // in the fetch even when the caller's select/omit excludes it, and has to
         // come back off afterwards. Exactly the shape `loadRelation` uses for its
@@ -1903,6 +1961,11 @@ export class PowqlInterface {
             }
         }
         const targetByPk = new Map();
+        // Position of each target in the fetch, i.e. its rank under the relation's
+        // `orderBy`; the stitch below sorts a parent's children by it when an
+        // orderBy was given, so `limit` keeps that parent's top-N and not its first
+        // N junction rows. Across fetch CHUNKS the rank is fetch order.
+        const targetRank = new Map();
         const targetValList = [...allTargetVals].map((v) => targetPkColMeta ? coerceScalar(v, targetPkColMeta.tsType) : v);
         const targetChunk = this.keyChunkSize(targetMeta, targetPkCol);
         for (let i = 0; i < targetValList.length; i += targetChunk) {
@@ -1913,14 +1976,21 @@ export class PowqlInterface {
             };
             const targets = (await targetQi.findMany({
                 ...fetchOptions,
+                // Unbounded: the relation limit/offset are per parent, applied in the stitch.
+                limit: undefined,
+                offset: undefined,
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
                 // Public findMany, so the sentinel form. See loadRelation above.
                 includePii: includePii ? UNSAFE : undefined,
             }));
-            for (const t of targets)
-                targetByPk.set(String(t[targetPkField]), t);
+            for (const t of targets) {
+                const pk = String(t[targetPkField]);
+                targetByPk.set(pk, t);
+                if (!targetRank.has(pk))
+                    targetRank.set(pk, targetRank.size);
+            }
         }
         // (3) Stitch: each parent → its junction targets (m2m is always a list).
         for (const parent of parents) {
@@ -1932,7 +2002,11 @@ export class PowqlInterface {
                 if (child)
                     children.push(child);
             }
-            parent[relName] = children;
+            if (options.orderBy) {
+                const rank = (t) => targetRank.get(String(t[targetPkField])) ?? 0;
+                children.sort((a, b) => rank(a) - rank(b));
+            }
+            parent[relName] = PowqlInterface.pageOf(children, options.limit, options.offset);
         }
         // Stitching is done: take the forced PK back off. Iterating the map rather
         // than the stitched lists is deliberate, one target can be linked from many
@@ -1976,11 +2050,12 @@ export class PowqlInterface {
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
-    joinEligible(rel, opt, args, parentCount) {
+    joinEligible(rel, opt, args) {
         const effLimit = args.limit ?? this.defaultLimit;
         if (effLimit !== undefined || args.offset)
             return false;
@@ -2021,9 +2096,8 @@ export class PowqlInterface {
             return false;
         }
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
-        if ((options.limit !== undefined || options.offset) && (single || parentCount > MAX_RELATION_KEYS)) {
+        if ((options.limit !== undefined || options.offset) && single)
             return false;
-        }
         // A `limit 0` relation stays off the join statement for the same reason it
         // stays off a nested projection: PowDB answered `limit 0` with one row below
         // engine 0.20. The loader resolves it client-side, correctly on every version.
@@ -2070,13 +2144,13 @@ export class PowqlInterface {
         const { cols: childCols, forcedPk: childForcedPk } = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
         const order = targetQi.buildOrder(options.orderBy, params, 'c');
+        // No limit/offset clause: on the join they would bound the TOTAL child
+        // count across every parent. The relation's page is per parent (pageOf).
         this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
-        const limitClause = options.limit !== undefined ? ` limit ${this.param(options.limit, params)}` : '';
-        const offsetClause = options.offset ? ` offset ${this.param(options.offset, params)}` : '';
         const proj = this.joinProjection(childCols, `p.${quotePowqlIdent(parentKeyCol)}`, 'c');
         const powql = `${targetQi.qt} as c join ${this.qt} as p ` +
             `on c.${quotePowqlIdent(childKeyCol)} = p.${quotePowqlIdent(parentKeyCol)}` +
-            `${filter}${order}${limitClause}${offsetClause} ${proj}`;
+            `${filter}${order} ${proj}`;
         // A READ: thread a read-shaped action through the exec seam.
         const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
@@ -2084,7 +2158,9 @@ export class PowqlInterface {
         for (const p of parents) {
             const key = this.joinKey(p[parentKeyField]);
             const matches = (key == null ? undefined : byKey.get(key)) ?? [];
-            p[relName] = single ? (matches[0] ?? null) : matches;
+            p[relName] = single
+                ? (matches[0] ?? null)
+                : PowqlInterface.pageOf(matches, options.limit, options.offset);
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.78.0-next.4bd3c8f",
+  "version": "0.78.0-next.b792a6a",
   "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": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",