@c9up/atlas 0.2.0 → 0.2.1

package/dist/ModelQuery.js

@@ -15,7 +15,11 @@ import { assertNotPromise, BaseRepository, wrapAdapterError, } from "./BaseRepos
 import { ensureEntityMetadata, getColumnMetadata, getDateColumnConfig, getPrimaryKey, getRelationMetadata, hasSoftDeletes, } from "./decorators/entity.js";
 import { fireHooks } from "./decorators/hooks.js";
 import { getNamingStrategy } from "./naming/NamingStrategy.js";
-import { compileStatementNative, getAtlasDialect, } from "./query/native.js";
+import { DmlBuilder } from "./query/DmlBuilder.js";
+import { compiledStatement, interpolateQuery, } from "./query/interpolate.js";
+import { compileStatementNative, getAtlasDialect, normalizeDialect, } from "./query/native.js";
+import { negateOperator } from "./query/operators.js";
+import { RawSql } from "./query/QueryBuilder.js";
 import { camelToSnake, snakeToCamel } from "./utils/casing.js";
 /**
  * Comparison operators allowed in `whereExpr`'s raw 4-arg form (where
@@ -405,10 +409,27 @@ export class ModelQuery {
     #orderBys = [];
     #select = ["*"];
     #limit;
+    /** Top-N-per-parent limit for a has-many preload (Lucid `groupLimit`). */
+    #groupLimit;
+    /** ORDER BY for the per-parent window (Lucid `groupOrderBy`). */
+    #groupOrderBy;
     #offset;
     #preloads = new Map();
+    // Per-query row transformers (Adonis Lucid `rowTransformer`). Stored via a
+    // method-signature wrapper (not a bare `(row: T) => void` property) so T stays
+    // in a bivariant position — a function-typed property would force ModelQuery<T>
+    // invariant and break the `this: ModelClass<T>` bound on every static finder.
+    #rowTransformers = [];
     /** Correlated subquery projections (withCount / withAggregate). */
     #selectSubqueries = [];
+    /** Raw / subquery SELECT fragments carrying their own params (Lucid `select(raw)`, `select(subquery.as())`). */
+    #selectRaw = [];
+    /** Caller-facing statement timeout in ms (Lucid `timeout(ms)`), applied via a race in exec. */
+    #timeoutMs;
+    /** `timeout(ms, { cancel: true })` — also apply a SERVER-side statement timeout. */
+    #cancelTimeout = false;
+    /** Columns from a chainable `.returning(...)` on a lazy DML builder. */
+    #dmlReturning = [];
     /** Alias stored by `.as()` — consumed when this query is used as a withCount/withAggregate sub-builder. */
     #subqueryAlias;
     /** Raw JOIN fragments — Story 29.4. */
@@ -421,6 +442,10 @@ export class ModelQuery {
     #sideloaded = null;
     /** Per-query debug flag — Story 29.11. */
     #debugFlag = false;
+    /** Metadata attached to the db:query event (Adonis Lucid `reporterData`). */
+    #reporterData;
+    /** SQL comments prepended to the compiled query (Lucid/Knex `comment`). */
+    #comments = [];
     /** Distinct flag — Story 29.5. */
     #distinct = false;
     #distinctOn = [];
@@ -434,6 +459,8 @@ export class ModelQuery {
     #unions = [];
     /** m2m pivot-table WHERE constraints — applied to the pivot lookup, not the related query. */
     #pivotWheres = [];
+    /** Extra pivot columns requested at query time (Lucid `pivotColumns([...])`). */
+    #extraPivotColumns = [];
     /**
      * Deferred builder for a lazy m2m `related().query()` EXISTS predicate. Set by
      * the relation proxy's scoped query; invoked at `#buildSpec()` time with the
@@ -469,6 +496,24 @@ export class ModelQuery {
         this.#softScope = "only-trashed";
         return this;
     }
+    /**
+     * Apply the first `[guard, callback]` whose guard is truthy (Adonis Lucid
+     * `match`); a trailing bare callback is the default, run when none matched.
+     */
+    match(...blocks) {
+        for (const block of blocks) {
+            if (typeof block === "function") {
+                block(this);
+                return this;
+            }
+            const [guard, callback] = block;
+            if (guard) {
+                callback(this);
+                return this;
+            }
+        }
+        return this;
+    }
     /**
      * Eager-load a relation (AdonisJS-style).
      * Relations are never loaded automatically — you must call .preload() explicitly.
@@ -481,14 +526,80 @@ export class ModelQuery {
         this.#preloads.set(relationName, callback);
         return this;
     }
-    /** Select specific columns (default: `*`). Accepts a comma-separated string or an array. */
-    select(columns) {
-        const list = Array.isArray(columns)
-            ? columns
-            : columns.split(",").map((c) => c.trim());
-        this.#select = list.map((c) => this.#resolveSelect(c));
+    /**
+     * Eager-load a relation only if it hasn't been registered yet (Adonis Lucid
+     * `preloadOnce`) — a later `preload`/`preloadOnce` for the same relation is
+     * ignored, so a shared scope can safely add a preload without clobbering one
+     * the caller already set.
+     */
+    preloadOnce(relationName, callback) {
+        if (!this.#preloads.has(relationName)) {
+            this.#preloads.set(relationName, callback);
+        }
+        return this;
+    }
+    /**
+     * Register a callback run for every hydrated instance after loading (preloads
+     * included) but before the query resolves (Adonis Lucid `rowTransformer`). The
+     * callback mutates the instance in place — decorate rows with per-query
+     * computed values without a model hook/accessor. Multiple transformers run in
+     * registration order.
+     */
+    rowTransformer(callback) {
+        this.#rowTransformers.push({ run: callback });
+        return this;
+    }
+    /**
+     * Select columns (default: `*`). The model query builder extends the database
+     * query builder's `select` surface (Lucid parity): bare names, multiple args,
+     * a comma-separated string, an array, an `{ alias: 'column' }` object map, a
+     * `db.raw(...)` fragment, and a named subquery — `select(subquery.as('x'))`.
+     * Plain columns are resolved to their DB column (honouring `@Column`).
+     */
+    select(...columns) {
+        const plain = [];
+        for (const col of columns) {
+            if (typeof col === "string") {
+                plain.push(...col.split(",").map((c) => c.trim()));
+            }
+            else if (Array.isArray(col)) {
+                plain.push(...col);
+            }
+            else if (col instanceof RawSql) {
+                // Lucid `select(db.raw(sql, bindings))` — verbatim fragment + params.
+                this.#selectRaw.push({ sql: col.sql, params: [...col.params] });
+            }
+            else if (col instanceof _a) {
+                // Lucid `select(subquery.as('alias'))` — a correlated subquery column.
+                const alias = col.#subqueryAlias;
+                if (!alias) {
+                    throw new Error("select(subquery) requires the subquery to be named with .as('alias')");
+                }
+                const { sql, params } = col.#compiledNative();
+                this.#selectRaw.push({
+                    sql: `(${sql}) AS ${this.#quoteAliasName(alias)}`,
+                    params,
+                });
+            }
+            else {
+                for (const [alias, expr] of Object.entries(col)) {
+                    plain.push(`${expr} AS ${alias}`);
+                }
+            }
+        }
+        if (plain.length > 0) {
+            this.#select = plain.map((c) => this.#resolveSelect(c));
+        }
         return this;
     }
+    /** Validate + dialect-quote a bare alias identifier. */
+    #quoteAliasName(alias) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid alias '${alias}' — expected a bare identifier.`);
+        }
+        const q = this.#dialect === "mysql" ? "`" : '"';
+        return `${q}${alias}${q}`;
+    }
     /**
      * Resolve a bare model-property select/returning target to its DB column
      * (honouring `@Column({ columnName })`), leaving expressions / aliases /
@@ -588,33 +699,73 @@ export class ModelQuery {
     andWhereColumn(left, operator, right) {
         return this.whereColumn(left, operator, right);
     }
-    /** `WHERE col != ?` — negation of `where`. */
-    whereNot(column, value) {
+    whereNot(columnOrCbOrObj, operatorOrValue, value) {
+        if (typeof columnOrCbOrObj === "function") {
+            this.#wheres.push({
+                ...this.#buildGroup("and", columnOrCbOrObj),
+                negated: true,
+            });
+            return this;
+        }
+        if (typeof columnOrCbOrObj === "object") {
+            for (const [col, val] of Object.entries(columnOrCbOrObj)) {
+                this.#wheres.push({
+                    type: "and",
+                    column: this.#resolveColumn(col),
+                    operator: "!=",
+                    value: this.#prep(col, val),
+                });
+            }
+            return this;
+        }
+        if (value === undefined) {
+            this.#wheres.push({
+                type: "and",
+                column: this.#resolveColumn(columnOrCbOrObj),
+                operator: "!=",
+                value: this.#prep(columnOrCbOrObj, operatorOrValue),
+            });
+            return this;
+        }
+        // (column, operator, value): NOT (col <op> value) via a negated group so any
+        // operator negates correctly without an operator-inversion table.
+        const col = columnOrCbOrObj;
+        const op = operatorOrValue;
         this.#wheres.push({
-            type: "and",
-            column: this.#resolveColumn(column),
-            operator: "!=",
-            value: this.#prep(column, value),
+            ...this.#buildGroup("and", (q) => q.where(col, op, value)),
+            negated: true,
         });
         return this;
     }
-    /** `WHERE col IN (...)` — accepts an array of values OR a `ModelQuery` subquery source. */
-    whereIn(column, source) {
+    whereIn(columnOrColumns, source) {
+        // Tuple form (Lucid `whereIn(['id','email'], [[1,'a@b.com']])`).
+        if (Array.isArray(columnOrColumns)) {
+            const cols = columnOrColumns.map((c) => this.#resolveColumn(c));
+            const rows = (Array.isArray(source) ? source : []).map((r) => (Array.isArray(r) ? r : [r]).map((v, j) => this.#prep(cols[j] ?? "", v)));
+            this.#wheres.push({
+                type: "and",
+                kind: "inTuple",
+                columns: cols,
+                rows,
+                negated: false,
+            });
+            return this;
+        }
         if (source instanceof _a) {
             this.#wheres.push({
                 type: "and",
                 kind: "inSub",
                 negated: false,
-                column: this.#resolveColumn(column),
+                column: this.#resolveColumn(columnOrColumns),
                 subquery: source.#buildSpec(),
             });
             return this;
         }
         this.#wheres.push({
             type: "and",
-            column: this.#resolveColumn(column),
+            column: this.#resolveColumn(columnOrColumns),
             operator: "IN",
-            value: this.#prep(column, [...source]),
+            value: this.#prep(columnOrColumns, [...source]),
         });
         return this;
     }
@@ -976,28 +1127,48 @@ export class ModelQuery {
     orWhereNotExists(subquery) {
         return this.#pushExists("or", true, subquery);
     }
-    // ─── JSON ─────────────────────────────────────────────────
-    //
-    // Every value crosses the boundary as a bound param — the path and the
-    // compared value both. Only the column is a quoted identifier. Path access
-    // and containment are each spelled per dialect, and SQLite has no
-    // containment operator, so `*JsonSupersetOf`/`*JsonSubsetOf` refuse there.
+    whereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
+    }
+    andWhereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
+    }
+    orWhereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPathArgs("or", column, path, operatorOrValue, value);
+    }
+    /** Resolve the optional-operator JSONPath form, then push (default op `=`). */
+    #pushJsonPathArgs(type, column, path, operatorOrValue, value) {
+        const [operator, val] = value === undefined
+            ? ["=", operatorOrValue]
+            : [String(operatorOrValue), value];
+        return this.#pushJson(type, false, "path", column, val, path, String(operator));
+    }
     /**
-     * `WHERE <col at path> <op> ?` — compare a value inside a JSON column
-     * (Lucid/Knex `whereJsonPath`). `path` is a JSONPath (`$.a.b`, `$.items[0]`).
-     *
-     *     query.whereJsonPath('data', '$.address.city', '=', 'Paris')
+     * Structural JSON match (Lucid `whereJson`) — the column's JSON must equal
+     * `value` (canonical comparison on Postgres/MySQL). AND is the default.
      */
-    whereJsonPath(column, path, operator, value) {
-        return this.#pushJson("and", false, "path", column, value, path, operator);
+    whereJson(column, value) {
+        return this.#pushJson("and", false, "equals", column, value);
+    }
+    /** Alias of {@link whereJson} (Lucid `andWhereJson`). */
+    andWhereJson(column, value) {
+        return this.#pushJson("and", false, "equals", column, value);
+    }
+    /** OR form of {@link whereJson} (Lucid `orWhereJson`). */
+    orWhereJson(column, value) {
+        return this.#pushJson("or", false, "equals", column, value);
     }
-    /** Alias of {@link whereJsonPath} (Lucid parity). */
-    andWhereJsonPath(column, path, operator, value) {
-        return this.#pushJson("and", false, "path", column, value, path, operator);
+    /** WHERE NOT structural JSON match (Lucid `whereNotJson`). */
+    whereNotJson(column, value) {
+        return this.#pushJson("and", true, "equals", column, value);
     }
-    /** `OR <col at path> <op> ?` (Lucid parity). */
-    orWhereJsonPath(column, path, operator, value) {
-        return this.#pushJson("or", false, "path", column, value, path, operator);
+    /** Alias of {@link whereNotJson} (Lucid `andWhereNotJson`). */
+    andWhereNotJson(column, value) {
+        return this.#pushJson("and", true, "equals", column, value);
+    }
+    /** OR NOT structural JSON match (Lucid `orWhereNotJson`). */
+    orWhereNotJson(column, value) {
+        return this.#pushJson("or", true, "equals", column, value);
     }
     /**
      * `WHERE <col> @> ?` — the JSON column contains `value` (Lucid/Knex
@@ -1048,6 +1219,47 @@ export class ModelQuery {
     orWhereNotJsonSubsetOf(column, value) {
         return this.#pushJson("or", true, "subset", column, value);
     }
+    // Lucid's canonical containment names drop the `Of` suffix — kept as aliases.
+    /** Lucid `whereJsonSuperset` (alias of {@link whereJsonSupersetOf}). */
+    whereJsonSuperset(column, value) {
+        return this.#pushJson("and", false, "superset", column, value);
+    }
+    /** Lucid `andWhereJsonSuperset`. */
+    andWhereJsonSuperset(column, value) {
+        return this.#pushJson("and", false, "superset", column, value);
+    }
+    /** Lucid `orWhereJsonSuperset`. */
+    orWhereJsonSuperset(column, value) {
+        return this.#pushJson("or", false, "superset", column, value);
+    }
+    /** Lucid `whereNotJsonSuperset`. */
+    whereNotJsonSuperset(column, value) {
+        return this.#pushJson("and", true, "superset", column, value);
+    }
+    /** Lucid `orWhereNotJsonSuperset`. */
+    orWhereNotJsonSuperset(column, value) {
+        return this.#pushJson("or", true, "superset", column, value);
+    }
+    /** Lucid `whereJsonSubset` (alias of {@link whereJsonSubsetOf}). */
+    whereJsonSubset(column, value) {
+        return this.#pushJson("and", false, "subset", column, value);
+    }
+    /** Lucid `andWhereJsonSubset`. */
+    andWhereJsonSubset(column, value) {
+        return this.#pushJson("and", false, "subset", column, value);
+    }
+    /** Lucid `orWhereJsonSubset`. */
+    orWhereJsonSubset(column, value) {
+        return this.#pushJson("or", false, "subset", column, value);
+    }
+    /** Lucid `whereNotJsonSubset`. */
+    whereNotJsonSubset(column, value) {
+        return this.#pushJson("and", true, "subset", column, value);
+    }
+    /** Lucid `orWhereNotJsonSubset`. */
+    orWhereNotJsonSubset(column, value) {
+        return this.#pushJson("or", true, "subset", column, value);
+    }
     #pushJson(type, negated, jsonOp, column, value, path, operator) {
         // A JSONPath is bound, not interpolated, so injection is not the concern
         // here — a clear early error for a malformed path is. Lucid/Knex paths
@@ -1308,8 +1520,29 @@ export class ModelQuery {
         this.#selectSubqueries.push(this.#buildRelationSubquery(relationName, callback, "aggregate", relationName));
         return this;
     }
-    orderBy(column, direction = "asc") {
-        this.#orderBys.push({ column: this.#resolveColumn(column), direction });
+    orderBy(columnOrTerms, direction = "asc") {
+        // A raw fragment (e.g. `db.ref('posts.created_at')`) orders verbatim.
+        if (columnOrTerms instanceof RawSql) {
+            const dir = direction === "desc" ? "DESC" : "ASC";
+            this.#orderBys.push({ raw: `${columnOrTerms.sql} ${dir}` });
+            return this;
+        }
+        if (Array.isArray(columnOrTerms)) {
+            for (const t of columnOrTerms) {
+                const [col, dir] = typeof t === "string"
+                    ? [t, "asc"]
+                    : [t.column, t.order ?? "asc"];
+                this.#orderBys.push({
+                    column: this.#resolveColumn(col),
+                    direction: dir,
+                });
+            }
+            return this;
+        }
+        this.#orderBys.push({
+            column: this.#resolveColumn(columnOrTerms),
+            direction,
+        });
         return this;
     }
     /**
@@ -1373,6 +1606,40 @@ export class ModelQuery {
         });
         return this;
     }
+    /** HAVING col IS NULL (Lucid/Knex `havingNull`). */
+    havingNull(column) {
+        return this.#pushHaving(column, "IS NULL", null);
+    }
+    /** HAVING col IS NOT NULL (Lucid/Knex `havingNotNull`). */
+    havingNotNull(column) {
+        return this.#pushHaving(column, "IS NOT NULL", null);
+    }
+    /** HAVING col IN (...) (Lucid/Knex `havingIn`). */
+    havingIn(column, values) {
+        return this.#pushHaving(column, "IN", [...values]);
+    }
+    /** HAVING col NOT IN (...) (Lucid/Knex `havingNotIn`). */
+    havingNotIn(column, values) {
+        return this.#pushHaving(column, "NOT IN", [...values]);
+    }
+    /** HAVING col BETWEEN ? AND ? (Lucid/Knex `havingBetween`). */
+    havingBetween(column, range) {
+        return this.#pushHaving(column, "BETWEEN", [...range]);
+    }
+    /** HAVING col NOT BETWEEN ? AND ? (Lucid/Knex `havingNotBetween`). */
+    havingNotBetween(column, range) {
+        return this.#pushHaving(column, "NOT BETWEEN", [...range]);
+    }
+    /** Push a HAVING entry with a raw (non-`#prep`'d) value — for IN/BETWEEN/NULL. */
+    #pushHaving(column, operator, value) {
+        this.#having.push({
+            column: this.#resolveHavingCol(column),
+            operator,
+            value,
+            type: "and",
+        });
+        return this;
+    }
     /**
      * Resolve a HAVING column: a bare model property maps to its DB column
      * (honouring `@Column({ columnName })`), but an aggregate expression
@@ -1428,17 +1695,21 @@ export class ModelQuery {
      * the outer parameter list.
      */
     union(query) {
-        this.#unions.push({ query, all: false });
+        this.#unions.push({ query: this.#resolveUnion(query), all: false });
         return this;
     }
     /** `UNION ALL (<query>)` — duplicate-preserving {@link union}. */
     unionAll(query) {
-        this.#unions.push({ query, all: true });
+        this.#unions.push({ query: this.#resolveUnion(query), all: true });
         return this;
     }
     /** `INTERSECT (<query>)` — rows present in both (Lucid/Knex `intersect`). */
     intersect(query) {
-        this.#unions.push({ query, all: false, op: "intersect" });
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: false,
+            op: "intersect",
+        });
         return this;
     }
     /**
@@ -1449,19 +1720,43 @@ export class ModelQuery {
      * `E_UNSUPPORTED` there rather than emitting a syntax error.
      */
     intersectAll(query) {
-        this.#unions.push({ query, all: true, op: "intersect" });
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: true,
+            op: "intersect",
+        });
         return this;
     }
     /** `EXCEPT (<query>)` — rows in this query but not the other (Lucid/Knex `except`). */
     except(query) {
-        this.#unions.push({ query, all: false, op: "except" });
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: false,
+            op: "except",
+        });
         return this;
     }
     /** `EXCEPT ALL (<query>)` — duplicate-preserving {@link except}. Not on SQLite; see {@link intersectAll}. */
     exceptAll(query) {
-        this.#unions.push({ query, all: true, op: "except" });
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: true,
+            op: "except",
+        });
         return this;
     }
+    /** A compound-query arg — an explicit ModelQuery OR a callback building one on this model. */
+    #resolveUnion(query) {
+        if (typeof query !== "function")
+            return query;
+        const sub = this.#freshQuery();
+        query(sub);
+        return sub;
+    }
+    /** A fresh, empty query on the SAME model + connection (for compound callbacks). */
+    #freshQuery() {
+        return new _a(this.#tableName, this.#db, this.#hydrateFn, this.#entityClass, this.#resolveColumn, this.#softDeletes, this.#dialect, this.#prepareValue, this.#onDomainEvents);
+    }
     /**
      * `WITH <name> AS (<query>)` — register a Common Table Expression
      * (AdonisJS/Lucid `with`). The CTE name is validated as an identifier; the
@@ -1481,8 +1776,11 @@ export class ModelQuery {
      * The recursive term itself is a `UNION`/`UNION ALL` inside `query`, e.g.
      * an anchor `SELECT` unioned with a select that references `<name>`.
      */
-    withRecursive(name, query) {
-        return this.#pushCte("withRecursive", name, query, { recursive: true });
+    withRecursive(name, query, columns) {
+        return this.#pushCte("withRecursive", name, query, {
+            recursive: true,
+            columns,
+        });
     }
     /**
      * `WITH <name> AS MATERIALIZED (<query>)` — force the CTE to be evaluated
@@ -1506,7 +1804,18 @@ export class ModelQuery {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
             throw new Error(`${method}(): CTE name '${name}' is not a valid identifier`);
         }
-        this.#ctes.push({ name, query, ...options });
+        this.#ctes.push({ name, query: this.#resolveUnion(query), ...options });
+        return this;
+    }
+    /**
+     * `@ManyToMany` only — project EXTRA pivot columns at query time (AdonisJS/Lucid
+     * `pivotColumns([...])`), on top of any declared in the relation decorator. Read
+     * off each loaded relation as `$extras.pivot_<col>`. Inert on non-m2m relations.
+     *
+     *     userRepo.query().preload('skills', q => q.pivotColumns(['notes']))
+     */
+    pivotColumns(columns) {
+        this.#extraPivotColumns.push(...columns);
         return this;
     }
     wherePivot(column, operatorOrValue, value) {
@@ -1534,17 +1843,21 @@ export class ModelQuery {
     wherePivotIn(column, values) {
         return this.whereInPivot(column, values);
     }
-    /** `@ManyToMany` only — `WHERE <pivotCol> != <value>` on the pivot table (AdonisJS Lucid `whereNotPivot`). */
-    whereNotPivot(column, value) {
-        return this.#pushPivotOp("and", column, "!=", value);
+    whereNotPivot(column, operatorOrValue, value) {
+        if (value === undefined) {
+            return this.#pushPivotOp("and", column, "!=", operatorOrValue);
+        }
+        return this.#pushPivotOp("and", column, negateOperator(String(operatorOrValue)), value);
     }
-    /** Alias of {@link whereNotPivot} (Lucid parity). */
-    andWhereNotPivot(column, value) {
-        return this.#pushPivotOp("and", column, "!=", value);
+    andWhereNotPivot(column, operatorOrValue, value) {
+        return value === undefined
+            ? this.#pushPivotOp("and", column, "!=", operatorOrValue)
+            : this.#pushPivotOp("and", column, negateOperator(String(operatorOrValue)), value);
     }
-    /** `@ManyToMany` only — OR form of {@link whereNotPivot} (Lucid parity). */
-    orWhereNotPivot(column, value) {
-        return this.#pushPivotOp("or", column, "!=", value);
+    orWhereNotPivot(column, operatorOrValue, value) {
+        return value === undefined
+            ? this.#pushPivotOp("or", column, "!=", operatorOrValue)
+            : this.#pushPivotOp("or", column, negateOperator(String(operatorOrValue)), value);
     }
     /** `@ManyToMany` only — `WHERE <pivotCol> NOT IN (...)` on the pivot table (AdonisJS Lucid `whereNotInPivot`). */
     whereNotInPivot(column, values) {
@@ -1596,6 +1909,10 @@ export class ModelQuery {
     get pivotConstraints() {
         return this.#pivotWheres;
     }
+    /** Read-only accessor for query-time pivot columns — consumed by the m2m preload resolver. */
+    get pivotColumnRequests() {
+        return this.#extraPivotColumns;
+    }
     limit(n) {
         // Guard here with a clear message — the Rust spec types limit as
         // u64, so a negative/non-integer otherwise surfaces as a cryptic
@@ -1607,6 +1924,24 @@ export class ModelQuery {
         this.#limit = n;
         return this;
     }
+    /**
+     * In a has-many preload callback, cap the related rows PER PARENT (Lucid
+     * `groupLimit`) — a plain `.limit()` caps the whole result set across parents.
+     * Compiled with a `ROW_NUMBER() OVER (PARTITION BY <fk> …)` window. Pair with
+     * {@link groupOrderBy} to pick which N per parent.
+     */
+    groupLimit(n) {
+        if (!Number.isInteger(n) || n < 0) {
+            throw new Error(`groupLimit must be a non-negative integer, got ${n}`);
+        }
+        this.#groupLimit = n;
+        return this;
+    }
+    /** ORDER BY for the {@link groupLimit} per-parent window (Lucid `groupOrderBy`). */
+    groupOrderBy(column, direction = "asc") {
+        this.#groupOrderBy = { column, direction };
+        return this;
+    }
     offset(n) {
         if (!Number.isInteger(n) || n < 0) {
             throw new Error(`offset must be a non-negative integer, got ${n}`);
@@ -1754,6 +2089,7 @@ export class ModelQuery {
             table: this.#tableName,
             select: selectCols,
             selectSubqueries: this.#selectSubqueries,
+            selectRaw: this.#selectRaw,
             wheres,
             orderBy: this.#orderBys,
             groupBy: this.#groupBy,
@@ -1762,18 +2098,9 @@ export class ModelQuery {
             offset: this.#offset ?? null,
             distinct: this.#distinct,
             distinctOn: this.#distinctOn,
-            ctes: this.#ctes.map((c) => {
-                const { sql, params } = c.query.toSQL();
-                return {
-                    name: c.name,
-                    sql,
-                    params,
-                    recursive: c.recursive ?? false,
-                    materialized: c.materialized ?? null,
-                };
-            }),
+            ctes: this.#compiledCtes(),
             unions: this.#unions.map((u) => {
-                const { sql, params } = u.query.toSQL();
+                const { sql, params } = u.query.#compiledNative();
                 return { sql, params, all: u.all, op: u.op ?? null };
             }),
             joins: this.#joins,
@@ -1784,10 +2111,106 @@ export class ModelQuery {
                 : null,
         };
     }
-    /** Build SQL + params via the Rust query compiler. */
-    toSQL() {
+    /**
+     * Native compiled `{ sql, params }` (Postgres `$N`) — the form atlas executes
+     * and embeds inside parent queries. Public `toSQL()` normalizes to Knex `?`.
+     */
+    #compiledNative() {
         const compiled = compileStatementNative(this.#buildSpec(), this.#dialect);
-        return { sql: compiled.statements[0], params: compiled.params };
+        const sql = this.#commentPrefix() + compiled.statements[0];
+        return { sql, params: compiled.params };
+    }
+    /**
+     * Build SQL via the Rust query compiler (Lucid `toSQL`). `.sql` uses `?`
+     * placeholders (Knex-normalized, like Lucid); `.toNative()` yields the native
+     * form. Returns `bindings` (Lucid's name) and `params` (atlas's) — same array.
+     */
+    toSQL() {
+        const { sql, params } = this.#compiledNative();
+        return compiledStatement(sql, params);
+    }
+    /** `{ sql, bindings }` — the compiled native query (Lucid/Knex `toNative`). */
+    toNative() {
+        const { sql, params } = this.#compiledNative();
+        return { sql, bindings: params };
+    }
+    /** The model class this query targets (Adonis Lucid `query.model`). */
+    get model() {
+        return this.#entityClass;
+    }
+    /** Apply `cb` only on the given dialect(s) (Lucid `ifDialect`; Lucid names accepted). */
+    ifDialect(dialect, cb) {
+        const set = (Array.isArray(dialect) ? dialect : [dialect]).map(normalizeDialect);
+        if (set.includes(this.#dialect))
+            cb(this);
+        return this;
+    }
+    /** Apply `cb` on every dialect EXCEPT the given one(s) (Lucid `unlessDialect`). */
+    unlessDialect(dialect, cb) {
+        const set = (Array.isArray(dialect) ? dialect : [dialect]).map(normalizeDialect);
+        if (!set.includes(this.#dialect))
+            cb(this);
+        return this;
+    }
+    /** Prepend a `/* … *​/` SQL comment to the compiled query (Lucid/Knex `comment`). */
+    comment(text) {
+        if (text.includes("*/")) {
+            throw new Error("comment() text may not contain '*/'");
+        }
+        this.#comments.push(text);
+        return this;
+    }
+    /**
+     * Set a caller-facing statement timeout in milliseconds (Lucid `timeout(ms)`).
+     * The awaiting promise rejects after `ms` on the primary result fetch. With
+     * `{ cancel: true }` a SERVER-side statement timeout is also applied — Postgres
+     * `statement_timeout`, MySQL `MAX_EXECUTION_TIME` (SELECT) — so the server
+     * aborts the query, not just the client. (SQLite has no server timeout; the
+     * client race applies.) Called with no argument it clears the timeout.
+     */
+    timeout(ms, options) {
+        // `{ cancel: true }` also applies a SERVER-side statement timeout (Postgres
+        // statement_timeout / MySQL MAX_EXECUTION_TIME for SELECT); SQLite has none,
+        // so the client race applies there.
+        this.#timeoutMs = ms;
+        this.#cancelTimeout = options?.cancel === true;
+        return this;
+    }
+    /**
+     * Race `work` against the configured `.timeout(ms)`. Rejects the awaiter after
+     * `ms`; the losing DB promise is swallowed so a post-timeout driver error never
+     * surfaces as an unhandled rejection. No timeout set → returns `work` as-is.
+     */
+    #raceTimeout(work) {
+        const ms = this.#timeoutMs;
+        if (!ms || ms <= 0)
+            return work;
+        let timer;
+        const guard = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Query timed out after ${ms}ms`)), ms);
+        });
+        work.catch(() => { });
+        return Promise.race([work, guard]).finally(() => clearTimeout(timer));
+    }
+    /** The `/* … *​/` prefix for the compiled SQL, or empty when no comments. */
+    /** Compile the registered CTEs to the wire shape — shared by SELECT and DML. */
+    #compiledCtes() {
+        return this.#ctes.map((c) => {
+            const { sql, params } = c.query.#compiledNative();
+            return {
+                name: c.name,
+                sql,
+                params,
+                recursive: c.recursive ?? false,
+                materialized: c.materialized ?? null,
+                columns: c.columns ?? [],
+            };
+        });
+    }
+    #commentPrefix() {
+        return this.#comments.length > 0
+            ? `${this.#comments.map((c) => `/* ${c} */`).join(" ")} `
+            : "";
     }
     /**
      * Cached exec result. Memoizing the promise makes the builder a one-shot
@@ -1811,8 +2234,8 @@ export class ModelQuery {
         return results;
     }
     async #doExec() {
-        const { sql, params } = this.toSQL();
-        const rawRows = await this.#db.query(sql, params, this.#meta("exec"));
+        const { sql, params } = this.#compiledNative();
+        const rawRows = await this.#raceTimeout(this.#db.query(sql, params, this.#meta("exec")));
         // Peel withCount / withAggregate alias columns off the raw row into $extras
         // BEFORE hydration, so the hydrator doesn't try to interpret them as columns.
         const extraKeys = this.#selectSubqueries.map((s) => s.alias);
@@ -1836,6 +2259,14 @@ export class ModelQuery {
         if (this.#preloads.size > 0 && this.#entityClass && entities.length > 0) {
             await this.#resolvePreloads(entities);
         }
+        // rowTransformer callbacks run per instance AFTER preloads, before resolve
+        // (Lucid), so a transformer can read the eager-loaded relations.
+        if (this.#rowTransformers.length > 0) {
+            for (const entity of entities) {
+                for (const transform of this.#rowTransformers)
+                    transform.run(entity);
+            }
+        }
         return entities;
     }
     /**
@@ -1845,16 +2276,20 @@ export class ModelQuery {
      * instances aren't needed.
      */
     async pojo() {
-        const { sql, params } = this.toSQL();
+        const { sql, params } = this.#compiledNative();
         return this.#db.query(sql, params);
     }
     /**
      * Thread arbitrary context onto every instance this query hydrates, exposed as
      * `entity.$sideloaded` (AdonisJS Lucid `sideload`) — e.g. the current tenant or
-     * user, so hooks/computed can read it. Merges across calls. Chainable.
+     * user, so hooks/computed can read it. REPLACES the current sideloaded data by
+     * default (Lucid); pass `merge = true` to merge instead. The data also
+     * propagates to preloaded relation queries. Chainable.
      */
-    sideload(values) {
-        this.#sideloaded = { ...this.#sideloaded, ...values };
+    sideload(values, merge = false) {
+        this.#sideloaded = merge
+            ? { ...this.#sideloaded, ...values }
+            : { ...values };
         return this;
     }
     /** Resolve preloaded relations via batched subqueries (no N+1). */
@@ -1870,6 +2305,14 @@ export class ModelQuery {
             if (!ctx)
                 continue;
             const allRelated = await this.#resolveOneRelation(entities, relationName, relation.type, ctx);
+            // Propagate the parent query's sideloaded context onto the preloaded
+            // relation instances (Adonis Lucid). The related row's own sideloaded
+            // data (if any) wins over the inherited context.
+            if (this.#sideloaded) {
+                for (const related of allRelated) {
+                    related.$sideloaded = { ...this.#sideloaded, ...related.$sideloaded };
+                }
+            }
             await this.#applyNestedPreloads(allRelated, ctx);
         }
     }
@@ -1885,7 +2328,13 @@ export class ModelQuery {
         // entities using Adonis' `declare field: T` pattern have no own-properties
         // on a freshly constructed instance, so `key in entity` is always false and
         // every column would be silently dropped. Mirrors `BaseRepository.#hydrate`.
-        const relatedPkName = getPrimaryKey(relatedClass) ?? "id";
+        // For m2m the pivot's otherKey references `relatedKey` (default the related
+        // PK); the load must filter/index rows by THAT column, not always the PK.
+        const relatedPkName = (relation.type === "manyToMany"
+            ? relation.pivot?.relatedKey
+            : undefined) ??
+            getPrimaryKey(relatedClass) ??
+            "id";
         const validColumns = new Set();
         // Reverse map (db column → property) so an explicit `@Column({ columnName })`
         // on the related entity hydrates correctly — mirrors `BaseRepository.#hydrate`.
@@ -2148,9 +2597,13 @@ export class ModelQuery {
         // also runs (again) inside runRelationQuery against the related table; both
         // runs are pure builder mutations, and pivot constraints are inert there.
         const pivotWheres = [];
+        // Query-time pivotColumns([...]) requested in the preload callback (replayed
+        // on the scratch builder below) OR directly on this query (related().query()).
+        const extraPivotCols = [...this.#extraPivotColumns];
         if (ctx.nestedCallback) {
             const scratch = new _a(ctx.relatedTable, this.#db, (r) => r, ctx.relatedClass, buildColumnResolver(ctx.relatedClass), false, this.#dialect, buildValuePreparer(ctx.relatedClass));
             ctx.nestedCallback(scratch);
+            extraPivotCols.push(...scratch.pivotColumnRequests);
             // Apply the pivot column adapters' `prepare` to wherePivot values, so a
             // filter like wherePivot('amount', new Money(1)) matches what attach()/
             // sync() stored (they prepare the same extras on write).
@@ -2193,7 +2646,11 @@ export class ModelQuery {
         ];
         // Step 2 — load all related entities in one query
         const relRows = await ctx.runRelationQuery(ctx.relatedPk, otherIds);
-        const pivotCols = pivot.pivotColumns ?? [];
+        // Declared pivot columns (decorator) + any requested at query time
+        // (`pivotColumns([...])`, from the callback or this query), de-duplicated.
+        const pivotCols = [
+            ...new Set([...(pivot.pivotColumns ?? []), ...extraPivotCols]),
+        ];
         const pivotAdapters = pivot.pivotColumnAdapters ?? {};
         // When pivot extras are projected, each (parent, related) edge gets its OWN
         // hydrated instance so per-edge `$extras.pivot_<col>` values never clobber
@@ -2328,9 +2785,52 @@ export class ModelQuery {
             relation.onQuery(sub);
         if (userCallback)
             userCallback(sub);
-        const { sql, params } = sub.toSQL();
+        // Top-N per parent (Lucid groupLimit) → a ROW_NUMBER() window over the fk.
+        if (sub.#groupLimit != null) {
+            return this.#runGroupLimited(sub, column, sub.#groupLimit);
+        }
+        const { sql, params } = sub.#compiledNative();
         return this.#db.query(sql, params);
     }
+    /**
+     * Run a has-many preload query capped to `n` rows PER PARENT (Lucid
+     * `groupLimit`). Wraps the inner query with a `ROW_NUMBER() OVER (PARTITION BY
+     * <fk> ORDER BY <groupOrderBy | pk>)` window, then keeps `rn <= n`. Supported on
+     * Postgres, MySQL 8+, and SQLite 3.25+ (all have window functions).
+     */
+    async #runGroupLimited(sub, fkColumn, n) {
+        const quoteSeg = (name) => {
+            const qc = this.#dialect === "mysql" ? "`" : '"';
+            return name
+                .split(".")
+                .map((s) => {
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(s)) {
+                    throw new Error(`groupLimit: unsafe identifier '${name}'`);
+                }
+                return `${qc}${s}${qc}`;
+            })
+                .join(".");
+        };
+        const orderCol = sub.#groupOrderBy
+            ? sub.#resolveColumn(sub.#groupOrderBy.column)
+            : (getPrimaryKey(sub.#entityClass) ?? "id");
+        const dir = sub.#groupOrderBy?.direction === "desc" ? "DESC" : "ASC";
+        sub.#selectRaw.push({
+            sql: `ROW_NUMBER() OVER (PARTITION BY ${quoteSeg(fkColumn)} ORDER BY ${quoteSeg(orderCol)} ${dir}) AS __atlas_rn`,
+            params: [],
+        });
+        const inner = sub.#compiledNative();
+        const ph = this.#dialect === "postgres" ? `$${inner.params.length + 1}` : "?";
+        const outerSql = `SELECT * FROM (${inner.sql}) AS __atlas_grp WHERE __atlas_rn <= ${ph}`;
+        const rows = await this.#db.query(outerSql, [
+            ...inner.params,
+            n,
+        ]);
+        // Strip the window helper column so it doesn't leak into hydration.
+        for (const row of rows)
+            delete row.__atlas_rn;
+        return rows;
+    }
     /**
      * Build a correlated subquery over a relation. Returns `SubqueryProjection`
      * used by withCount / withAggregate. Default select is `COUNT(*)` for `'count'`
@@ -2448,14 +2948,26 @@ export class ModelQuery {
         }
         return sub;
     }
-    innerJoin(table, leftOrBuild, right) {
-        return this.#pushJoin("INNER", table, leftOrBuild, right);
+    join(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
+    }
+    innerJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
+    }
+    leftJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
+    }
+    leftOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
     }
-    leftJoin(table, leftOrBuild, right) {
-        return this.#pushJoin("LEFT", table, leftOrBuild, right);
+    rightJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
     }
-    rightJoin(table, leftOrBuild, right) {
-        return this.#pushJoin("RIGHT", table, leftOrBuild, right);
+    rightOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
+    }
+    fullOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("FULL OUTER", table, leftOrBuild, operatorOrRight, right);
     }
     crossJoin(table) {
         const tq = this.#quoteCol(table);
@@ -2501,8 +3013,15 @@ export class ModelQuery {
         return this.innerJoin(table, left, right);
     }
     // === Story 29.5 — aggregates / exists / pluck =====================================================
-    distinct() {
+    /**
+     * SELECT DISTINCT (Lucid/Knex `distinct`). With columns, those replace the
+     * projection too — `distinct('a', 'b')` ≈ `SELECT DISTINCT a, b`.
+     */
+    distinct(...columns) {
         this.#distinct = true;
+        if (columns.length > 0) {
+            this.#select = columns.map((c) => this.#resolveSelect(c));
+        }
         return this;
     }
     /**
@@ -2542,7 +3061,7 @@ export class ModelQuery {
         const clone = this.clone();
         clone.#select = ["1"];
         clone.#limit = 1;
-        const { sql, params } = clone.toSQL();
+        const { sql, params } = clone.#compiledNative();
         const rows = await this.#db.query(sql, params, this.#meta("exists"));
         return rows.length > 0;
     }
@@ -2554,7 +3073,7 @@ export class ModelQuery {
         const col = this.#resolveColumn(column);
         const clone = this.clone();
         clone.#select = [col];
-        const { sql, params } = clone.toSQL();
+        const { sql, params } = clone.#compiledNative();
         const rows = await this.#db.query(sql, params);
         return rows.map((row) => {
             const v = row[col];
@@ -2599,9 +3118,11 @@ export class ModelQuery {
             elseFn(this);
         return this;
     }
-    unless(condition, fn) {
+    unless(condition, fn, elseFn) {
         if (!condition)
             fn(this);
+        else if (elseFn)
+            elseFn(this);
         return this;
     }
     // === Story 29.10 — pagination =====================================================================
@@ -2609,11 +3130,17 @@ export class ModelQuery {
     async paginate(page, perPage) {
         const p = Math.max(1, Math.floor(page));
         const pp = Math.max(1, Math.floor(perPage));
-        // beforePaginate runs BEFORE cloning so a hook mutating the query (e.g. a
-        // tenant scope) propagates into both the COUNT and the data fetch.
-        await fireHooks(this.#entityClass, "beforePaginate", this);
-        // COUNT(*) + data fetch
+        // Adonis Lucid hook order:
+        //   beforePaginate([countQuery, query]) → beforeFetch(query)
+        //     → (count + data queries) → afterPaginate(paginator) → afterFetch(rows)
+        // The COUNT and data builders are separate clones so a beforePaginate hook
+        // can constrain BOTH (keeping totals in sync), exactly as documented.
         const countQ = this.clone();
+        const dataQ = this.clone();
+        await fireHooks(this.#entityClass, "beforePaginate", [countQ, dataQ]);
+        // beforeFetch fires on the main (data) query before either query runs.
+        await fireHooks(this.#entityClass, "beforeFetch", dataQ);
+        // COUNT(*) — strip pagination/order noise from the count clone.
         countQ.#limit = undefined;
         countQ.#offset = undefined;
         countQ.#orderBys = [];
@@ -2624,29 +3151,32 @@ export class ModelQuery {
             // group's own size), so `rows[0].count` would be the first group's size, not
             // the number of pages. Lucid counts via a subquery: wrap the grouped query
             // (select + groupBy + having preserved) and count its rows = group count.
-            const inner = countQ.toSQL();
+            const inner = countQ.#compiledNative();
             cSql = `SELECT COUNT(*) AS count FROM (${inner.sql}) AS __paginate_count`;
             cParams = inner.params;
         }
         else {
             countQ.#select = ["COUNT(*) AS count"];
-            const flat = countQ.toSQL();
+            const flat = countQ.#compiledNative();
             cSql = flat.sql;
             cParams = flat.params;
         }
         const cRows = await this.#db.query(cSql, cParams, this.#meta("paginate"));
         const total = Number(cRows[0]?.count ?? 0);
-        const dataQ = this.clone();
         dataQ.#limit = pp;
         dataQ.#offset = (p - 1) * pp;
-        // `#doExec` (not `exec`) so the generic beforeFetch/afterFetch don't fire on
-        // top of the paginate hooks — paginate is its own terminal.
+        // `#doExec` runs the raw fetch + preloads. beforeFetch already fired above;
+        // afterFetch fires AFTER afterPaginate (Lucid order), so #doExec must not
+        // fire either itself — hence #doExec, not exec().
         const items = await dataQ.#doExec();
-        await fireHooks(this.#entityClass, "afterPaginate", items);
         const metaKeys = this.#entityClass
             ? getNamingStrategy(this.#entityClass).paginationMetaKeys?.()
             : undefined;
-        return new Paginator(items, { total, perPage: pp, currentPage: p }, metaKeys);
+        const paginator = new Paginator(items, { total, perPage: pp, currentPage: p }, metaKeys);
+        // Lucid: afterPaginate(paginator) then afterFetch(rows).
+        await fireHooks(this.#entityClass, "afterPaginate", paginator);
+        await fireHooks(this.#entityClass, "afterFetch", items);
+        return paginator;
     }
     /**
      * Cursor-based pagination — base64 opaque keyset, multi-column aware.
@@ -2729,6 +3259,17 @@ export class ModelQuery {
         this.#debugFlag = flag;
         return this;
     }
+    /**
+     * Attach arbitrary metadata to the `db:query` event this query emits (Adonis
+     * Lucid `reporterData`) — request id, user id, feature flag, … A listener
+     * reads it off `event.reporterData`. Repeated calls merge. Setting it also
+     * forces emission (like {@link debug}), so the data actually reaches a listener.
+     */
+    reporterData(data) {
+        this.#reporterData = { ...this.#reporterData, ...data };
+        this.#debugFlag = true;
+        return this;
+    }
     /**
      * Context attached to each statement this query runs, so a `db:query`
      * listener can say which model and which call produced it — and so
@@ -2742,16 +3283,16 @@ export class ModelQuery {
             model: this.#entityClass.name,
             method,
             debug: this.#debugFlag,
+            reporterData: this.#reporterData,
+            serverTimeoutMs: this.#cancelTimeout && this.#timeoutMs != null
+                ? this.#timeoutMs
+                : undefined,
         };
     }
     /** Returns the compiled SQL with bindings interpolated as dialect-safe literals. */
     toQuery() {
-        const { sql, params } = this.toSQL();
-        let i = 0;
-        return sql.replace(/\?|\$\d+/g, () => {
-            const v = params[i++];
-            return this.#literalEscape(v);
-        });
+        const { sql, params } = this.#compiledNative();
+        return interpolateQuery(sql, params);
     }
     /** Deep clone of this query — mutations on the clone never affect the original. */
     clone() {
@@ -2761,9 +3302,20 @@ export class ModelQuery {
         c.#orderBys = [...this.#orderBys];
         c.#select = [...this.#select];
         c.#limit = this.#limit;
+        c.#groupLimit = this.#groupLimit;
+        c.#groupOrderBy = this.#groupOrderBy
+            ? { ...this.#groupOrderBy }
+            : undefined;
         c.#offset = this.#offset;
         c.#preloads = new Map(this.#preloads);
+        c.#rowTransformers = [...this.#rowTransformers];
         c.#selectSubqueries = structuredClone(this.#selectSubqueries);
+        c.#selectRaw = this.#selectRaw.map((s) => ({
+            ...s,
+            params: [...s.params],
+        }));
+        c.#timeoutMs = this.#timeoutMs;
+        c.#cancelTimeout = this.#cancelTimeout;
         c.#joins = this.#joins.map((j) => ({ sql: j.sql, params: [...j.params] }));
         c.#lockMode = this.#lockMode;
         c.#lockModifier = this.#lockModifier;
@@ -2777,6 +3329,7 @@ export class ModelQuery {
             query: e.query.clone(),
             recursive: e.recursive,
             materialized: e.materialized,
+            columns: e.columns ? [...e.columns] : undefined,
         }));
         c.#unions = this.#unions.map((u) => ({
             query: u.query.clone(),
@@ -2784,34 +3337,41 @@ export class ModelQuery {
             op: u.op,
         }));
         c.#pivotWheres = structuredCloneSafe(this.#pivotWheres);
+        c.#extraPivotColumns = [...this.#extraPivotColumns];
         // Pure closure over pivot metadata — safe to share by reference; it reads the
         // clone's own #pivotWheres at build time (passed in), holding no query state.
         c.#pivotExists = this.#pivotExists;
         c.#debugFlag = this.#debugFlag;
+        c.#reporterData = this.#reporterData
+            ? { ...this.#reporterData }
+            : undefined;
+        c.#comments = [...this.#comments];
         return c;
     }
-    // === Story 30.2 — update / delete fluent ===========================================================
-    /** Execute a fluent UPDATE. Returns affected rows (or rows when `returning` is set). */
-    async update(patch, returning) {
+    update(patchOrColumn, valueOrReturning) {
+        const patch = typeof patchOrColumn === "string"
+            ? { [patchOrColumn]: valueOrReturning }
+            : patchOrColumn;
+        const returning = typeof patchOrColumn === "string"
+            ? undefined
+            : valueOrReturning;
         if (!patch || Object.keys(patch).length === 0) {
             throw new Error("update() requires a non-empty payload");
         }
         // Lower each value through prepare (DateTime → ISO, @Column adapters) exactly
         // like BaseRepository's write paths — the fluent update() must not bypass it.
-        const setPairs = Object.entries(patch).map(([k, v]) => [this.#resolveColumn(k), this.#prepareValue(k, v)]);
-        const spec = {
+        // A `db.raw(...)` value is emitted as a raw SET expression instead.
+        const setPairs = Object.entries(patch).map(([k, v]) => v instanceof RawSql
+            ? [this.#resolveColumn(k), { raw: v.sql, rawParams: [...v.params] }]
+            : [this.#resolveColumn(k), this.#prepareValue(k, v)]);
+        return this.#makeDml((r) => ({
             kind: "update",
             table: this.#tableName,
             set: setPairs,
             wheres: this.#wheresForDml(),
-            returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
-        };
-        const compiled = compileStatementNative(spec, this.#dialect);
-        if (returning && returning.length > 0) {
-            return this.#db.query(compiled.statements[0], compiled.params);
-        }
-        const r = await this.#db.execute(compiled.statements[0], compiled.params);
-        return r.rowsAffected ?? 0;
+            returning: r,
+            ctes: this.#compiledCtes(),
+        }), returning);
     }
     /**
      * Execute a fluent DELETE. For a `@SoftDeletes` model this SOFT-deletes the
@@ -2820,28 +3380,29 @@ export class ModelQuery {
      * model it issues a hard `DELETE`. Returns affected rows (or rows when
      * `returning` is set).
      */
-    async delete(returning) {
+    delete(returning) {
         if (this.#softDeletes) {
-            const spec = {
+            const stampedAt = new Date().toISOString();
+            return this.#makeDml((r) => ({
                 kind: "update",
                 table: this.#tableName,
-                set: [[this.#deletedAtColumn(), new Date().toISOString()]],
+                set: [[this.#deletedAtColumn(), stampedAt]],
                 wheres: this.#wheresForDml(),
-                returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
-            };
-            return this.#runDml(spec, returning);
+                returning: r,
+                ctes: this.#compiledCtes(),
+            }), returning);
         }
         return this.forceDelete(returning);
     }
     /** Hard `DELETE` of the scoped rows, bypassing `@SoftDeletes` (AdonisJS/Lucid `forceDelete`). */
-    async forceDelete(returning) {
-        const spec = {
+    forceDelete(returning) {
+        return this.#makeDml((r) => ({
             kind: "delete",
             table: this.#tableName,
             wheres: this.#wheresForDml(),
-            returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
-        };
-        return this.#runDml(spec, returning);
+            returning: r,
+            ctes: this.#compiledCtes(),
+        }), returning);
     }
     /**
      * Bulk restore: clear `deleted_at` on the trashed rows matching the user's
@@ -2849,24 +3410,27 @@ export class ModelQuery {
      * on a non-soft-delete model. Independent of the current soft-scope — it always
      * targets trashed rows (`deleted_at IS NOT NULL`).
      */
-    async restore(returning) {
-        if (!this.#softDeletes)
-            return 0;
-        const wheres = this.#userWheresForDml();
-        wheres.push({
-            column: this.#deletedAtColumn(),
-            operator: "IS NOT NULL",
-            value: null,
-            type: "and",
-        });
-        const spec = {
-            kind: "update",
-            table: this.#tableName,
-            set: [[this.#deletedAtColumn(), null]],
-            wheres,
-            returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
-        };
-        return this.#runDml(spec, returning);
+    restore(returning) {
+        if (!this.#softDeletes) {
+            return new DmlBuilder(() => Promise.resolve(0), () => ({ sql: "", bindings: [], params: [] }), this.#dmlHooks());
+        }
+        return this.#makeDml((r) => {
+            const wheres = this.#userWheresForDml();
+            wheres.push({
+                column: this.#deletedAtColumn(),
+                operator: "IS NOT NULL",
+                value: null,
+                type: "and",
+            });
+            return {
+                kind: "update",
+                table: this.#tableName,
+                set: [[this.#deletedAtColumn(), null]],
+                wheres,
+                returning: r,
+                ctes: this.#compiledCtes(),
+            };
+        }, returning);
     }
     increment(colOrPatch, amount = 1) {
         return this.#runIncDec("increment", colOrPatch, amount);
@@ -2958,77 +3522,172 @@ export class ModelQuery {
             .map((seg) => this.#quote(seg))
             .join(".");
     }
-    #pushJoin(kind, table, leftOrBuild, right) {
+    #pushJoin(kind, table, leftOrBuild, operatorOrRight, right) {
         const tq = this.#quoteCol(table);
         if (typeof leftOrBuild === "function") {
+            const parts = [];
             const jb = {
-                parts: [],
-                on(l, r) {
-                    this.parts.push({ kind: "and", left: l, right: r });
-                    return this;
+                parts,
+                on: (l, opOrR, r) => {
+                    parts.push(r === undefined
+                        ? { kind: "and", left: l, right: opOrR }
+                        : { kind: "and", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                andOn: (l, opOrR, r) => {
+                    parts.push(r === undefined
+                        ? { kind: "and", left: l, right: opOrR }
+                        : { kind: "and", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                orOn: (l, opOrR, r) => {
+                    parts.push(r === undefined
+                        ? { kind: "or", left: l, right: opOrR }
+                        : { kind: "or", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                onVal: (l, v) => {
+                    parts.push({ kind: "and", left: l, value: { v } });
+                    return jb;
+                },
+                andOnVal: (l, v) => {
+                    parts.push({ kind: "and", left: l, value: { v } });
+                    return jb;
                 },
-                andOn(l, r) {
-                    this.parts.push({ kind: "and", left: l, right: r });
-                    return this;
+                orOnVal: (l, v) => {
+                    parts.push({ kind: "or", left: l, value: { v } });
+                    return jb;
                 },
-                orOn(l, r) {
-                    this.parts.push({ kind: "or", left: l, right: r });
-                    return this;
+                onIn: (l, values) => {
+                    parts.push({ kind: "and", left: l, values: [...values] });
+                    return jb;
                 },
-                onVal(l, v) {
-                    this.parts.push({ kind: "and", left: l, value: { v } });
-                    return this;
+                onNotIn: (l, values) => {
+                    parts.push({
+                        kind: "and",
+                        left: l,
+                        values: [...values],
+                        notIn: true,
+                    });
+                    return jb;
+                },
+                onNull: (l) => {
+                    parts.push({ kind: "and", left: l, nullOp: "IS NULL" });
+                    return jb;
+                },
+                onNotNull: (l) => {
+                    parts.push({ kind: "and", left: l, nullOp: "IS NOT NULL" });
+                    return jb;
                 },
-                andOnVal(l, v) {
-                    this.parts.push({ kind: "and", left: l, value: { v } });
-                    return this;
+                onBetween: (l, range) => {
+                    parts.push({ kind: "and", left: l, between: [range[0], range[1]] });
+                    return jb;
+                },
+                onNotBetween: (l, range) => {
+                    parts.push({
+                        kind: "and",
+                        left: l,
+                        between: [range[0], range[1]],
+                        notBetween: true,
+                    });
+                    return jb;
                 },
-                orOnVal(l, v) {
-                    this.parts.push({ kind: "or", left: l, value: { v } });
-                    return this;
+                onExists: (sub) => {
+                    const { sql, params } = this.#resolveUnion(sub).#compiledNative();
+                    parts.push({ kind: "and", exists: { sql, params, not: false } });
+                    return jb;
+                },
+                onNotExists: (sub) => {
+                    const { sql, params } = this.#resolveUnion(sub).#compiledNative();
+                    parts.push({ kind: "and", exists: { sql, params, not: true } });
+                    return jb;
                 },
             };
             leftOrBuild(jb);
-            // Collect the bound values in placeholder order as the fragment is built.
+            // A BASE-table column runs the full model prepare (DateTime→ISO + @Column
+            // adapters/casts), keyed by its property. A FOREIGN join column must NOT
+            // borrow the root model's adapter for a same-named column on another
+            // table — apply only universal type-lowering, matching Knex's
+            // model-agnostic join binding.
+            const prep = (col, v) => {
+                const dot = col.lastIndexOf(".");
+                const tablePrefix = dot >= 0 ? col.slice(0, dot) : "";
+                const leaf = dot >= 0 ? col.slice(dot + 1) : col;
+                const isBaseColumn = tablePrefix === "" || sameTableRef(tablePrefix, this.#tableName);
+                return isBaseColumn ? this.#prepareValue(leaf, v) : lowerJoinValue(v);
+            };
             const params = [];
-            const on = jb.parts
+            const on = parts
                 .map((p, i) => {
                 const prefix = i === 0 ? "ON" : p.kind === "or" ? "OR" : "AND";
+                if (p.exists) {
+                    params.push(...p.exists.params);
+                    return `${prefix} ${p.exists.not ? "NOT EXISTS" : "EXISTS"} (${p.exists.sql})`;
+                }
+                const col = this.#quoteCol(p.left ?? "");
+                if (p.nullOp) {
+                    return `${prefix} ${col} ${p.nullOp}`;
+                }
+                if (p.between) {
+                    params.push(prep(p.left ?? "", p.between[0]), prep(p.left ?? "", p.between[1]));
+                    return `${prefix} ${col} ${p.notBetween ? "NOT BETWEEN" : "BETWEEN"} ? AND ?`;
+                }
+                if (p.values) {
+                    const placeholders = p.values.map(() => "?").join(", ");
+                    for (const v of p.values)
+                        params.push(prep(p.left ?? "", v));
+                    return `${prefix} ${col} ${p.notIn ? "NOT IN" : "IN"} (${placeholders})`;
+                }
                 if (p.value) {
-                    // A BASE-table column runs the full model prepare (DateTime→ISO +
-                    // @Column adapters/casts), keyed by its property. A FOREIGN join
-                    // column must NOT borrow the root model's adapter for a same-named
-                    // column on another table — apply only universal type-lowering
-                    // (Date/DateTime→ISO), matching Knex's model-agnostic join binding.
-                    const dot = p.left.lastIndexOf(".");
-                    const tablePrefix = dot >= 0 ? p.left.slice(0, dot) : "";
-                    const leaf = dot >= 0 ? p.left.slice(dot + 1) : p.left;
-                    const isBaseColumn = tablePrefix === "" || sameTableRef(tablePrefix, this.#tableName);
-                    params.push(isBaseColumn
-                        ? this.#prepareValue(leaf, p.value.v)
-                        : lowerJoinValue(p.value.v));
-                    return `${prefix} ${this.#quoteCol(p.left)} = ?`;
+                    params.push(prep(p.left ?? "", p.value.v));
+                    return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ?`;
                 }
-                return `${prefix} ${this.#quoteCol(p.left)} = ${this.#quoteCol(p.right ?? "")}`;
+                return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ${this.#quoteCol(p.right ?? "")}`;
             })
                 .join(" ");
             this.#joins.push({ sql: `${kind} JOIN ${tq} ${on}`, params });
             return this;
         }
-        if (right === undefined)
+        // String form: 3-arg `(left, right)` or 4-arg `(left, operator, right)`.
+        const left = leftOrBuild;
+        const operator = right === undefined ? "=" : (operatorOrRight ?? "=");
+        const rightCol = right === undefined ? operatorOrRight : right;
+        if (rightCol === undefined)
             throw new Error("join() with string form requires both left and right operands");
         this.#joins.push({
-            sql: `${kind} JOIN ${tq} ON ${this.#quoteCol(leftOrBuild)} = ${this.#quoteCol(right)}`,
+            sql: `${kind} JOIN ${tq} ON ${this.#quoteCol(left)} ${this.#validateJoinOp(operator)} ${this.#quoteCol(rightCol)}`,
             params: [],
         });
         return this;
     }
+    /** Allowlist the comparison operator embedded verbatim into a JOIN's ON SQL. */
+    #validateJoinOp(op) {
+        const t = op.trim();
+        const up = t.toUpperCase();
+        const allowed = new Set([
+            "=",
+            "<>",
+            "!=",
+            "<",
+            "<=",
+            ">",
+            ">=",
+            "LIKE",
+            "NOT LIKE",
+            "ILIKE",
+        ]);
+        if (allowed.has(t))
+            return t;
+        if (allowed.has(up))
+            return up;
+        throw new Error(`Unsupported join operator '${op}'.`);
+    }
     async #runScalar(expr) {
         const clone = this.clone();
         clone.#select = [`${expr} AS __scalar__`];
         clone.#orderBys = [];
-        const { sql, params } = clone.toSQL();
-        const rows = await this.#db.query(sql, params);
+        const { sql, params } = clone.#compiledNative();
+        const rows = await this.#raceTimeout(this.#db.query(sql, params));
         const row = rows[0];
         return row ? row.__scalar__ : null;
     }
@@ -3041,42 +3700,21 @@ export class ModelQuery {
             set: setPairs,
             wheres: this.#wheresForDml(),
             returning: [],
+            ctes: this.#compiledCtes(),
         };
         const compiled = compileStatementNative(spec, this.#dialect);
-        const r = await this.#db.execute(compiled.statements[0], compiled.params);
+        const r = await this.#raceTimeout(this.#db.execute(this.#commentPrefix() + compiled.statements[0], compiled.params, this.#meta("dml")));
         return r.rowsAffected ?? 0;
     }
     /**
-     * Flatten the SELECT wheres to DML-compatible wheres. Standard predicates
-     * and `whereRaw` fragments pass through; `group` / `exists` / `inSub` are
-     * still rejected because the DML compiler's WHERE lowering does not yet
-     * handle nested sub-queries or correlated EXISTS.
+     * The user's own WHERE predicates for DML (no soft-delete scope). The DML
+     * compiler now REUSES the SELECT compiler's WHERE lowering, so every predicate
+     * the read builder accepts — standard, `whereRaw`, `whereExists`, sub-queries,
+     * and nested groups — is valid for update/delete too. Passed through unchanged
+     * (same as `#buildSpec` does for reads).
      */
-    /** The user's own WHERE predicates mapped for DML (no soft-delete scope). */
     #userWheresForDml() {
-        const out = [];
-        for (const w of this.#wheres) {
-            if ("kind" in w) {
-                if (w.kind === "raw") {
-                    out.push({
-                        kind: "raw",
-                        sql: w.sql,
-                        bindings: w.bindings,
-                        type: w.type,
-                    });
-                    continue;
-                }
-                throw new Error(`update/delete do not support '${w.kind}' WHERE clauses. ` +
-                    `Supported: plain predicates and whereRaw. Use a raw UPDATE/DELETE for complex criteria.`);
-            }
-            out.push({
-                column: w.column,
-                operator: w.operator,
-                value: w.value,
-                type: w.type,
-            });
-        }
-        return out;
+        return [...this.#wheres];
     }
     #wheresForDml() {
         const out = this.#userWheresForDml();
@@ -3106,13 +3744,55 @@ export class ModelQuery {
         }
         return out;
     }
+    /** Compile a DML spec with the comment prefix — for a lazy builder's `.toSQL()`. */
+    #compileDmlSpec(spec) {
+        const compiled = compileStatementNative(spec, this.#dialect);
+        const sql = this.#commentPrefix() + compiled.statements[0];
+        return { sql, bindings: compiled.params, params: compiled.params };
+    }
+    /** Hooks a lazy DML builder delegates back to (upsert clauses are N/A on a model query). */
+    #dmlHooks() {
+        return {
+            onConflict: () => { },
+            merge: () => { },
+            ignore: () => { },
+            returning: (...cols) => {
+                for (const c of cols) {
+                    if (Array.isArray(c))
+                        this.#dmlReturning.push(...c);
+                    else
+                        this.#dmlReturning.push(c);
+                }
+            },
+            timeout: (ms) => {
+                this.#timeoutMs = ms;
+            },
+            comment: (t) => {
+                this.comment(t);
+            },
+            debug: (enabled) => {
+                this.debug(enabled);
+            },
+            reporterData: (data) => {
+                this.reporterData(data);
+            },
+        };
+    }
+    /** Wrap a DML spec-builder as a lazy, chainable, inspectable {@link DmlBuilder}. */
+    #makeDml(build, paramReturning) {
+        const resolved = () => [...(paramReturning ?? []), ...this.#dmlReturning].map((c) => this.#resolveSelect(c));
+        return new DmlBuilder(() => {
+            const r = resolved();
+            return this.#runDml(build(r), r);
+        }, () => this.#compileDmlSpec(build(resolved())), this.#dmlHooks());
+    }
     /** Compile + run a DML spec: returns affected-row count, or rows when `returning` is set. */
     async #runDml(spec, returning) {
         const compiled = compileStatementNative(spec, this.#dialect);
         if (returning && returning.length > 0) {
-            return this.#db.query(compiled.statements[0], compiled.params);
+            return this.#raceTimeout(this.#db.query(this.#commentPrefix() + compiled.statements[0], compiled.params, this.#meta("dml")));
         }
-        const r = await this.#db.execute(compiled.statements[0], compiled.params);
+        const r = await this.#raceTimeout(this.#db.execute(this.#commentPrefix() + compiled.statements[0], compiled.params, this.#meta("dml")));
         return r.rowsAffected ?? 0;
     }
     /**
@@ -3128,18 +3808,6 @@ export class ModelQuery {
      * parameters via the Rust compiler — this escaper is never on the hot path.
      * If you are tempted to feed `.toQuery()` output into `db.prepare()`, STOP.
      */
-    #literalEscape(v) {
-        if (v === null || v === undefined)
-            return "NULL";
-        if (typeof v === "number")
-            return String(v);
-        if (typeof v === "boolean")
-            return v ? "1" : "0";
-        if (v instanceof Date)
-            return `'${v.toISOString()}'`;
-        // Strings — escape single quotes per SQL. NOT injection-safe against `\'`.
-        return `'${String(v).replace(/'/g, "''")}'`;
-    }
     /**
      * Build a parenthesised WHERE group from a callback. A throwaway ModelQuery
      * on the SAME table is used as the scratch builder so the callback can call