@c9up/atlas 0.2.0 → 0.2.1

package/src/ModelQuery.ts

@@ -29,11 +29,21 @@ import {
 } from "./decorators/entity.js";
 import { fireHooks } from "./decorators/hooks.js";
 import { getNamingStrategy } from "./naming/NamingStrategy.js";
+import { DmlBuilder, type DmlChainHooks } from "./query/DmlBuilder.js";
+import {
+	type CompiledStatement,
+	compiledStatement,
+	interpolateQuery,
+} from "./query/interpolate.js";
 import {
 	type AtlasDialect,
 	compileStatementNative,
+	type DialectName,
 	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";
 
 /**
@@ -317,7 +327,7 @@ interface RawWhere {
 interface JsonWhere {
 	type: "and" | "or";
 	kind: "json";
-	jsonOp: "path" | "superset" | "subset";
+	jsonOp: "path" | "superset" | "subset" | "equals";
 	column: string;
 	negated: boolean;
 	path?: string;
@@ -333,11 +343,13 @@ interface ExistsWhere {
 	subquery: SelectSpec;
 }
 
-/** Parenthesised group of WHERE conditions — built via `where(cb)`. */
+/** Parenthesised group of WHERE conditions — built via `where(cb)` / `whereNot(cb)`. */
 interface GroupWhere {
 	type: "and" | "or";
 	kind: "group";
 	conditions: WhereClause[];
+	/** `whereNot(cb)` wraps the group in `NOT (…)` (honoured by the Rust compiler). */
+	negated?: boolean;
 }
 
 /** `col IN (SELECT ...)` / `col NOT IN (SELECT ...)` — built via `whereIn(col, subQ)`. */
@@ -433,20 +445,35 @@ interface SelectSpec {
 	unions: UnionSpec[];
 	/** JOIN fragments; each carries its own `?`-style bound params (e.g. `onVal`). */
 	joins: Array<{ sql: string; params: unknown[] }>;
+	/** Verbatim SELECT fragments with their own params — `select(raw)` / `select(subquery.as())`. */
+	selectRaw?: Array<{ sql: string; params: unknown[] }>;
 	/** Composite lock clause, e.g. `FOR UPDATE`, `FOR NO KEY UPDATE SKIP LOCKED`. */
 	lockMode: string | null;
 }
 
+/** `(col1, col2) IN ((v11, v12), …)` / NOT IN — built via `whereIn([cols], [rows])`. */
+interface InTupleWhere {
+	type: "and" | "or";
+	kind: "inTuple";
+	columns: string[];
+	rows: unknown[][];
+	negated: boolean;
+}
+
 type WhereClause =
 	| StandardWhere
 	| RawWhere
 	| ExistsWhere
 	| GroupWhere
 	| InSubWhere
+	| InTupleWhere
 	| JsonWhere;
 
 type WhereCallback = (q: ModelQuery<BaseEntity>) => void;
 
+/** A compound-query (union/intersect/except) arg — a query OR a callback building one. */
+type UnionArg = ModelQuery<BaseEntity> | ((q: ModelQuery<BaseEntity>) => void);
+
 /**
  * Process-wide strict mode flag. When enabled, `whereRaw()`, `joinRaw()`,
  * `havingRaw()` and the repository's `raw()` throw unconditionally — forcing every
@@ -505,20 +532,48 @@ function isInternalBypass(): boolean {
  * to a bound VALUE (AdonisJS/Knex parity) — the value flows through the join-params
  * channel into the compiled parameter list.
  */
+interface JoinPartMQ {
+	kind: "and" | "or";
+	left?: string;
+	operator?: string;
+	right?: string;
+	value?: { v: unknown };
+	values?: unknown[];
+	notIn?: boolean;
+	between?: [unknown, unknown];
+	notBetween?: boolean;
+	nullOp?: "IS NULL" | "IS NOT NULL";
+	exists?: { sql: string; params: unknown[]; not: boolean };
+}
+
 interface JoinBuilder {
-	/** A column-to-column part (`value` absent) or a column-to-value part (`value` set). */
-	parts: Array<{
-		kind: "and" | "or";
-		left: string;
-		right?: string;
-		value?: { v: unknown };
-	}>;
+	/** Accumulated `ON` parts — column-to-column, column-to-value, IN, BETWEEN, NULL, EXISTS. */
+	parts: JoinPartMQ[];
 	on(left: string, right: string): JoinBuilder;
+	on(left: string, operator: string, right: string): JoinBuilder;
 	andOn(left: string, right: string): JoinBuilder;
+	andOn(left: string, operator: string, right: string): JoinBuilder;
 	orOn(left: string, right: string): JoinBuilder;
+	orOn(left: string, operator: string, right: string): JoinBuilder;
 	onVal(left: string, value: unknown): JoinBuilder;
 	andOnVal(left: string, value: unknown): JoinBuilder;
 	orOnVal(left: string, value: unknown): JoinBuilder;
+	/** `ON col IN (?, ?)` (Lucid/Knex `onIn`). */
+	onIn(left: string, values: unknown[]): JoinBuilder;
+	/** `ON col NOT IN (?, ?)` (Lucid/Knex `onNotIn`). */
+	onNotIn(left: string, values: unknown[]): JoinBuilder;
+	/** `ON col IS NULL` (Lucid/Knex `onNull`). */
+	onNull(left: string): JoinBuilder;
+	/** `ON col IS NOT NULL` (Lucid/Knex `onNotNull`). */
+	onNotNull(left: string): JoinBuilder;
+	/** `ON col BETWEEN ? AND ?` — inclusive (Lucid/Knex `onBetween`). */
+	onBetween(left: string, range: readonly [unknown, unknown]): JoinBuilder;
+	/** `ON col NOT BETWEEN ? AND ?` (Lucid/Knex `onNotBetween`). */
+	onNotBetween(left: string, range: readonly [unknown, unknown]): JoinBuilder;
+	/** `ON EXISTS (subquery)` — a builder or a callback (Lucid/Knex `onExists`). */
+	onExists(subquery: UnionArg): JoinBuilder;
+	/** `ON NOT EXISTS (subquery)` (Lucid/Knex `onNotExists`). */
+	onNotExists(subquery: UnionArg): JoinBuilder;
 }
 
 /** Offset-based paginator (Story 29.10). */
@@ -698,10 +753,27 @@ export class ModelQuery<T extends BaseEntity> {
 	#orderBys: OrderByEntry[] = [];
 	#select: string[] = ["*"];
 	#limit?: number;
+	/** Top-N-per-parent limit for a has-many preload (Lucid `groupLimit`). */
+	#groupLimit?: number;
+	/** ORDER BY for the per-parent window (Lucid `groupOrderBy`). */
+	#groupOrderBy?: { column: string; direction: "asc" | "desc" };
 	#offset?: number;
 	#preloads = new Map<string, PreloadCallback | undefined>();
+	// 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: Array<{ run(row: T): void }> = [];
 	/** Correlated subquery projections (withCount / withAggregate). */
 	#selectSubqueries: SubqueryProjection[] = [];
+	/** Raw / subquery SELECT fragments carrying their own params (Lucid `select(raw)`, `select(subquery.as())`). */
+	#selectRaw: Array<{ sql: string; params: unknown[] }> = [];
+	/** Caller-facing statement timeout in ms (Lucid `timeout(ms)`), applied via a race in exec. */
+	#timeoutMs?: number;
+	/** `timeout(ms, { cancel: true })` — also apply a SERVER-side statement timeout. */
+	#cancelTimeout = false;
+	/** Columns from a chainable `.returning(...)` on a lazy DML builder. */
+	#dmlReturning: string[] = [];
 	/** Alias stored by `.as()` — consumed when this query is used as a withCount/withAggregate sub-builder. */
 	#subqueryAlias?: string;
 	/** Raw JOIN fragments — Story 29.4. */
@@ -719,6 +791,10 @@ export class ModelQuery<T extends BaseEntity> {
 	#sideloaded: Record<string, unknown> | null = null;
 	/** Per-query debug flag — Story 29.11. */
 	#debugFlag = false;
+	/** Metadata attached to the db:query event (Adonis Lucid `reporterData`). */
+	#reporterData?: Record<string, unknown>;
+	/** SQL comments prepended to the compiled query (Lucid/Knex `comment`). */
+	#comments: string[] = [];
 	/** Distinct flag — Story 29.5. */
 	#distinct = false;
 	#distinctOn: string[] = [];
@@ -732,6 +808,7 @@ export class ModelQuery<T extends BaseEntity> {
 		query: ModelQuery<BaseEntity>;
 		recursive?: boolean;
 		materialized?: boolean;
+		columns?: string[];
 	}> = [];
 	/** UNION / UNION ALL branches (Lucid parity). */
 	#unions: Array<{
@@ -747,6 +824,8 @@ export class ModelQuery<T extends BaseEntity> {
 		/** AND/OR within the parenthesised pivot-filter group — see `#runInQuery`. */
 		type: "and" | "or";
 	}> = [];
+	/** Extra pivot columns requested at query time (Lucid `pivotColumns([...])`). */
+	#extraPivotColumns: string[] = [];
 	/**
 	 * Deferred builder for a lazy m2m `related().query()` EXISTS predicate. Set by
 	 * the relation proxy's scoped query; invoked at `#buildSpec()` time with the
@@ -803,6 +882,27 @@ export class ModelQuery<T extends BaseEntity> {
 		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: Array<[unknown, (query: this) => void] | ((query: this) => void)>
+	): this {
+		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.
@@ -816,15 +916,90 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
-	/** Select specific columns (default: `*`). Accepts a comma-separated string or an array. */
-	select(columns: string | string[]): this {
-		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: string, callback?: PreloadCallback): this {
+		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: (row: T) => void): this {
+		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: Array<
+			| string
+			| string[]
+			| Record<string, string>
+			| RawSql
+			| ModelQuery<BaseEntity>
+		>
+	): this {
+		const plain: string[] = [];
+		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 ModelQuery) {
+				// 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: string): string {
+		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 /
@@ -968,37 +1143,100 @@ export class ModelQuery<T extends BaseEntity> {
 		return this.whereColumn(left, operator, right);
 	}
 
-	/** `WHERE col != ?` — negation of `where`. */
-	whereNot(column: string, value: unknown): this {
+	/**
+	 * Negated WHERE (Lucid/Knex `whereNot`) — the same forms as {@link where}: a
+	 * `(column, [operator,] value)` comparison, an object (`whereNot({ a: 1 })` →
+	 * `a != 1`), or a callback group (`whereNot((q) => …)` → `NOT (…)`).
+	 */
+	whereNot(callback: WhereCallback): this;
+	whereNot(conditions: Record<string, unknown>): this;
+	whereNot(column: string, value: unknown): this;
+	whereNot(column: string, operator: string, value: unknown): this;
+	whereNot(
+		columnOrCbOrObj: string | WhereCallback | Record<string, unknown>,
+		operatorOrValue?: unknown,
+		value?: unknown,
+	): this {
+		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 as string, value)),
+			negated: true,
 		});
 		return this;
 	}
 
 	/** `WHERE col IN (...)` — accepts an array of values OR a `ModelQuery` subquery source. */
+	whereIn(columns: string[], rows: unknown[][]): this;
 	whereIn(
 		column: string,
 		source: readonly unknown[] | ModelQuery<BaseEntity>,
+	): this;
+	whereIn(
+		columnOrColumns: string | string[],
+		source: readonly unknown[] | unknown[][] | ModelQuery<BaseEntity>,
 	): this {
+		// 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 ModelQuery) {
 			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;
 	}
@@ -1464,33 +1702,105 @@ export class ModelQuery<T extends BaseEntity> {
 	 *
 	 *     query.whereJsonPath('data', '$.address.city', '=', 'Paris')
 	 */
+	whereJsonPath(column: string, path: string, value: unknown): this;
 	whereJsonPath(
 		column: string,
 		path: string,
 		operator: string,
 		value: unknown,
+	): this;
+	whereJsonPath(
+		column: string,
+		path: string,
+		operatorOrValue: unknown,
+		value?: unknown,
 	): this {
-		return this.#pushJson("and", false, "path", column, value, path, operator);
+		return this.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
 	}
 
-	/** Alias of {@link whereJsonPath} (Lucid parity). */
+	/** Alias of {@link whereJsonPath} (Lucid parity). Operator defaults to `=`. */
+	andWhereJsonPath(column: string, path: string, value: unknown): this;
 	andWhereJsonPath(
 		column: string,
 		path: string,
 		operator: string,
 		value: unknown,
+	): this;
+	andWhereJsonPath(
+		column: string,
+		path: string,
+		operatorOrValue: unknown,
+		value?: unknown,
 	): this {
-		return this.#pushJson("and", false, "path", column, value, path, operator);
+		return this.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
 	}
 
-	/** `OR <col at path> <op> ?` (Lucid parity). */
+	/** `OR <col at path> <op> ?` (Lucid parity). Operator defaults to `=`. */
+	orWhereJsonPath(column: string, path: string, value: unknown): this;
 	orWhereJsonPath(
 		column: string,
 		path: string,
 		operator: string,
 		value: unknown,
+	): this;
+	orWhereJsonPath(
+		column: string,
+		path: string,
+		operatorOrValue: unknown,
+		value?: unknown,
+	): this {
+		return this.#pushJsonPathArgs("or", column, path, operatorOrValue, value);
+	}
+
+	/** Resolve the optional-operator JSONPath form, then push (default op `=`). */
+	#pushJsonPathArgs(
+		type: "and" | "or",
+		column: string,
+		path: string,
+		operatorOrValue: unknown,
+		value?: unknown,
 	): this {
-		return this.#pushJson("or", false, "path", column, value, path, operator);
+		const [operator, val] =
+			value === undefined
+				? ["=", operatorOrValue]
+				: [String(operatorOrValue), value];
+		return this.#pushJson(
+			type,
+			false,
+			"path",
+			column,
+			val,
+			path,
+			String(operator),
+		);
+	}
+
+	/**
+	 * Structural JSON match (Lucid `whereJson`) — the column's JSON must equal
+	 * `value` (canonical comparison on Postgres/MySQL). AND is the default.
+	 */
+	whereJson(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "equals", column, value);
+	}
+	/** Alias of {@link whereJson} (Lucid `andWhereJson`). */
+	andWhereJson(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "equals", column, value);
+	}
+	/** OR form of {@link whereJson} (Lucid `orWhereJson`). */
+	orWhereJson(column: string, value: unknown): this {
+		return this.#pushJson("or", false, "equals", column, value);
+	}
+	/** WHERE NOT structural JSON match (Lucid `whereNotJson`). */
+	whereNotJson(column: string, value: unknown): this {
+		return this.#pushJson("and", true, "equals", column, value);
+	}
+	/** Alias of {@link whereNotJson} (Lucid `andWhereNotJson`). */
+	andWhereNotJson(column: string, value: unknown): this {
+		return this.#pushJson("and", true, "equals", column, value);
+	}
+	/** OR NOT structural JSON match (Lucid `orWhereNotJson`). */
+	orWhereNotJson(column: string, value: unknown): this {
+		return this.#pushJson("or", true, "equals", column, value);
 	}
 
 	/**
@@ -1552,10 +1862,52 @@ export class ModelQuery<T extends BaseEntity> {
 		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: string, value: unknown): this {
+		return this.#pushJson("and", false, "superset", column, value);
+	}
+	/** Lucid `andWhereJsonSuperset`. */
+	andWhereJsonSuperset(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "superset", column, value);
+	}
+	/** Lucid `orWhereJsonSuperset`. */
+	orWhereJsonSuperset(column: string, value: unknown): this {
+		return this.#pushJson("or", false, "superset", column, value);
+	}
+	/** Lucid `whereNotJsonSuperset`. */
+	whereNotJsonSuperset(column: string, value: unknown): this {
+		return this.#pushJson("and", true, "superset", column, value);
+	}
+	/** Lucid `orWhereNotJsonSuperset`. */
+	orWhereNotJsonSuperset(column: string, value: unknown): this {
+		return this.#pushJson("or", true, "superset", column, value);
+	}
+	/** Lucid `whereJsonSubset` (alias of {@link whereJsonSubsetOf}). */
+	whereJsonSubset(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "subset", column, value);
+	}
+	/** Lucid `andWhereJsonSubset`. */
+	andWhereJsonSubset(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "subset", column, value);
+	}
+	/** Lucid `orWhereJsonSubset`. */
+	orWhereJsonSubset(column: string, value: unknown): this {
+		return this.#pushJson("or", false, "subset", column, value);
+	}
+	/** Lucid `whereNotJsonSubset`. */
+	whereNotJsonSubset(column: string, value: unknown): this {
+		return this.#pushJson("and", true, "subset", column, value);
+	}
+	/** Lucid `orWhereNotJsonSubset`. */
+	orWhereNotJsonSubset(column: string, value: unknown): this {
+		return this.#pushJson("or", true, "subset", column, value);
+	}
+
 	#pushJson(
 		type: "and" | "or",
 		negated: boolean,
-		jsonOp: "path" | "superset" | "subset",
+		jsonOp: "path" | "superset" | "subset" | "equals",
 		column: string,
 		value: unknown,
 		path?: string,
@@ -1953,8 +2305,41 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
-	orderBy(column: string, direction: "asc" | "desc" = "asc"): this {
-		this.#orderBys.push({ column: this.#resolveColumn(column), direction });
+	/** ORDER BY a column, a `db.ref()` fragment, or an array of terms (Lucid/Knex `orderBy`). */
+	orderBy(column: string | RawSql, direction?: "asc" | "desc"): this;
+	orderBy(
+		terms: Array<string | { column: string; order?: "asc" | "desc" }>,
+	): this;
+	orderBy(
+		columnOrTerms:
+			| string
+			| RawSql
+			| Array<string | { column: string; order?: "asc" | "desc" }>,
+		direction: "asc" | "desc" = "asc",
+	): this {
+		// 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" as const]
+						: [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;
 	}
 
@@ -2022,6 +2407,47 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
+	/** HAVING col IS NULL (Lucid/Knex `havingNull`). */
+	havingNull(column: string): this {
+		return this.#pushHaving(column, "IS NULL", null);
+	}
+
+	/** HAVING col IS NOT NULL (Lucid/Knex `havingNotNull`). */
+	havingNotNull(column: string): this {
+		return this.#pushHaving(column, "IS NOT NULL", null);
+	}
+
+	/** HAVING col IN (...) (Lucid/Knex `havingIn`). */
+	havingIn(column: string, values: unknown[]): this {
+		return this.#pushHaving(column, "IN", [...values]);
+	}
+
+	/** HAVING col NOT IN (...) (Lucid/Knex `havingNotIn`). */
+	havingNotIn(column: string, values: unknown[]): this {
+		return this.#pushHaving(column, "NOT IN", [...values]);
+	}
+
+	/** HAVING col BETWEEN ? AND ? (Lucid/Knex `havingBetween`). */
+	havingBetween(column: string, range: readonly [unknown, unknown]): this {
+		return this.#pushHaving(column, "BETWEEN", [...range]);
+	}
+
+	/** HAVING col NOT BETWEEN ? AND ? (Lucid/Knex `havingNotBetween`). */
+	havingNotBetween(column: string, range: readonly [unknown, unknown]): this {
+		return this.#pushHaving(column, "NOT BETWEEN", [...range]);
+	}
+
+	/** Push a HAVING entry with a raw (non-`#prep`'d) value — for IN/BETWEEN/NULL. */
+	#pushHaving(column: string, operator: string, value: unknown): this {
+		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
@@ -2079,20 +2505,24 @@ export class ModelQuery<T extends BaseEntity> {
 	 * appended as a parenthesised UNION branch; its bindings are re-indexed into
 	 * the outer parameter list.
 	 */
-	union(query: ModelQuery<BaseEntity>): this {
-		this.#unions.push({ query, all: false });
+	union(query: UnionArg): this {
+		this.#unions.push({ query: this.#resolveUnion(query), all: false });
 		return this;
 	}
 
 	/** `UNION ALL (<query>)` — duplicate-preserving {@link union}. */
-	unionAll(query: ModelQuery<BaseEntity>): this {
-		this.#unions.push({ query, all: true });
+	unionAll(query: UnionArg): this {
+		this.#unions.push({ query: this.#resolveUnion(query), all: true });
 		return this;
 	}
 
 	/** `INTERSECT (<query>)` — rows present in both (Lucid/Knex `intersect`). */
-	intersect(query: ModelQuery<BaseEntity>): this {
-		this.#unions.push({ query, all: false, op: "intersect" });
+	intersect(query: UnionArg): this {
+		this.#unions.push({
+			query: this.#resolveUnion(query),
+			all: false,
+			op: "intersect",
+		});
 		return this;
 	}
 
@@ -2103,29 +2533,64 @@ export class ModelQuery<T extends BaseEntity> {
 	 * INTERSECT and EXCEPT — there is no INTERSECT ALL — so the compiler raises
 	 * `E_UNSUPPORTED` there rather than emitting a syntax error.
 	 */
-	intersectAll(query: ModelQuery<BaseEntity>): this {
-		this.#unions.push({ query, all: true, op: "intersect" });
+	intersectAll(query: UnionArg): this {
+		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: ModelQuery<BaseEntity>): this {
-		this.#unions.push({ query, all: false, op: "except" });
+	except(query: UnionArg): this {
+		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: ModelQuery<BaseEntity>): this {
-		this.#unions.push({ query, all: true, op: "except" });
+	exceptAll(query: UnionArg): this {
+		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: UnionArg): ModelQuery<BaseEntity> {
+		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(): ModelQuery<BaseEntity> {
+		return new ModelQuery<BaseEntity>(
+			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
 	 * sub-query is compiled and its bindings are re-indexed into the outer list.
 	 */
-	with(name: string, query: ModelQuery<BaseEntity>): this {
+	with(name: string, query: UnionArg): this {
 		return this.#pushCte("with", name, query, {});
 	}
 
@@ -2140,8 +2605,11 @@ export class ModelQuery<T extends BaseEntity> {
 	 * 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: string, query: ModelQuery<BaseEntity>): this {
-		return this.#pushCte("withRecursive", name, query, { recursive: true });
+	withRecursive(name: string, query: UnionArg, columns?: string[]): this {
+		return this.#pushCte("withRecursive", name, query, {
+			recursive: true,
+			columns,
+		});
 	}
 
 	/**
@@ -2151,14 +2619,14 @@ export class ModelQuery<T extends BaseEntity> {
 	 * Postgres 12+ and SQLite 3.35+ only; MySQL has no such hint and the
 	 * compiler raises `E_UNSUPPORTED` rather than emitting a syntax error.
 	 */
-	withMaterialized(name: string, query: ModelQuery<BaseEntity>): this {
+	withMaterialized(name: string, query: UnionArg): this {
 		return this.#pushCte("withMaterialized", name, query, {
 			materialized: true,
 		});
 	}
 
 	/** `WITH <name> AS NOT MATERIALIZED (<query>)` — let it be inlined (Lucid/Knex `withNotMaterialized`). See {@link withMaterialized}. */
-	withNotMaterialized(name: string, query: ModelQuery<BaseEntity>): this {
+	withNotMaterialized(name: string, query: UnionArg): this {
 		return this.#pushCte("withNotMaterialized", name, query, {
 			materialized: false,
 		});
@@ -2167,15 +2635,31 @@ export class ModelQuery<T extends BaseEntity> {
 	#pushCte(
 		method: string,
 		name: string,
-		query: ModelQuery<BaseEntity>,
-		options: { recursive?: boolean; materialized?: boolean },
+		query: UnionArg,
+		options: {
+			recursive?: boolean;
+			materialized?: boolean;
+			columns?: string[];
+		},
 	): this {
 		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: string[]): this {
+		this.#extraPivotColumns.push(...columns);
 		return this;
 	}
 
@@ -2241,19 +2725,63 @@ export class ModelQuery<T extends BaseEntity> {
 		return this.whereInPivot(column, values);
 	}
 
-	/** `@ManyToMany` only — `WHERE <pivotCol> != <value>` on the pivot table (AdonisJS Lucid `whereNotPivot`). */
-	whereNotPivot(column: string, value: unknown): this {
-		return this.#pushPivotOp("and", column, "!=", value);
+	/**
+	 * `@ManyToMany` only — negated pivot filter (AdonisJS Lucid `whereNotPivot`).
+	 * `whereNotPivot(col, value)` → `col != value`; `whereNotPivot(col, op, value)`
+	 * → the negated comparison (`whereNotPivot('proficiency', '>=', 4)` → `< 4`).
+	 */
+	whereNotPivot(column: string, value: unknown): this;
+	whereNotPivot(column: string, operator: string, value: unknown): this;
+	whereNotPivot(
+		column: string,
+		operatorOrValue: unknown,
+		value?: unknown,
+	): this {
+		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: string, value: unknown): this {
-		return this.#pushPivotOp("and", column, "!=", value);
+	/** Alias of {@link whereNotPivot} (Lucid parity). Operator form supported too. */
+	andWhereNotPivot(column: string, value: unknown): this;
+	andWhereNotPivot(column: string, operator: string, value: unknown): this;
+	andWhereNotPivot(
+		column: string,
+		operatorOrValue: unknown,
+		value?: unknown,
+	): this {
+		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: string, value: unknown): this {
-		return this.#pushPivotOp("or", column, "!=", value);
+	orWhereNotPivot(column: string, value: unknown): this;
+	orWhereNotPivot(column: string, operator: string, value: unknown): this;
+	orWhereNotPivot(
+		column: string,
+		operatorOrValue: unknown,
+		value?: unknown,
+	): this {
+		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`). */
@@ -2333,6 +2861,11 @@ export class ModelQuery<T extends BaseEntity> {
 		return this.#pivotWheres;
 	}
 
+	/** Read-only accessor for query-time pivot columns — consumed by the m2m preload resolver. */
+	get pivotColumnRequests(): readonly string[] {
+		return this.#extraPivotColumns;
+	}
+
 	limit(n: number): this {
 		// Guard here with a clear message — the Rust spec types limit as
 		// u64, so a negative/non-integer otherwise surfaces as a cryptic
@@ -2345,6 +2878,26 @@ export class ModelQuery<T extends BaseEntity> {
 		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: number): this {
+		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: string, direction: "asc" | "desc" = "asc"): this {
+		this.#groupOrderBy = { column, direction };
+		return this;
+	}
+
 	offset(n: number): this {
 		if (!Number.isInteger(n) || n < 0) {
 			throw new Error(`offset must be a non-negative integer, got ${n}`);
@@ -2520,6 +3073,7 @@ export class ModelQuery<T extends BaseEntity> {
 			table: this.#tableName,
 			select: selectCols,
 			selectSubqueries: this.#selectSubqueries,
+			selectRaw: this.#selectRaw,
 			wheres,
 			orderBy: this.#orderBys,
 			groupBy: this.#groupBy,
@@ -2528,18 +3082,9 @@ export class ModelQuery<T extends BaseEntity> {
 			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,
@@ -2551,10 +3096,133 @@ export class ModelQuery<T extends BaseEntity> {
 		};
 	}
 
-	/** Build SQL + params via the Rust query compiler. */
-	toSQL(): { sql: string; params: unknown[] } {
+	/**
+	 * Native compiled `{ sql, params }` (Postgres `$N`) — the form atlas executes
+	 * and embeds inside parent queries. Public `toSQL()` normalizes to Knex `?`.
+	 */
+	#compiledNative(): { sql: string; params: unknown[] } {
 		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(): CompiledStatement {
+		const { sql, params } = this.#compiledNative();
+		return compiledStatement(sql, params);
+	}
+
+	/** `{ sql, bindings }` — the compiled native query (Lucid/Knex `toNative`). */
+	toNative(): { sql: string; bindings: unknown[] } {
+		const { sql, params } = this.#compiledNative();
+		return { sql, bindings: params };
+	}
+
+	/** The model class this query targets (Adonis Lucid `query.model`). */
+	get model(): new () => T {
+		return this.#entityClass;
+	}
+
+	/** Apply `cb` only on the given dialect(s) (Lucid `ifDialect`; Lucid names accepted). */
+	ifDialect(
+		dialect: DialectName | DialectName[],
+		cb: (query: this) => void,
+	): this {
+		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: DialectName | DialectName[],
+		cb: (query: this) => void,
+	): this {
+		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: string): this {
+		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?: number, options?: { cancel?: boolean }): this {
+		// `{ 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<R>(work: Promise<R>): Promise<R> {
+		const ms = this.#timeoutMs;
+		if (!ms || ms <= 0) return work;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const guard = new Promise<never>((_, 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(): Array<{
+		name: string;
+		sql: string;
+		params: unknown[];
+		recursive: boolean;
+		materialized: boolean | null;
+		columns: string[];
+	}> {
+		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(): string {
+		return this.#comments.length > 0
+			? `${this.#comments.map((c) => `/* ${c} */`).join(" ")} `
+			: "";
 	}
 
 	/**
@@ -2582,11 +3250,9 @@ export class ModelQuery<T extends BaseEntity> {
 	}
 
 	async #doExec(): Promise<T[]> {
-		const { sql, params } = this.toSQL();
-		const rawRows = await this.#db.query<Record<string, unknown>>(
-			sql,
-			params,
-			this.#meta("exec"),
+		const { sql, params } = this.#compiledNative();
+		const rawRows = await this.#raceTimeout(
+			this.#db.query<Record<string, unknown>>(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.
@@ -2611,6 +3277,14 @@ export class ModelQuery<T extends BaseEntity> {
 			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;
 	}
 
@@ -2621,17 +3295,21 @@ export class ModelQuery<T extends BaseEntity> {
 	 * instances aren't needed.
 	 */
 	async pojo<R = Record<string, unknown>>(): Promise<R[]> {
-		const { sql, params } = this.toSQL();
+		const { sql, params } = this.#compiledNative();
 		return this.#db.query<R>(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: Record<string, unknown>): this {
-		this.#sideloaded = { ...this.#sideloaded, ...values };
+	sideload(values: Record<string, unknown>, merge = false): this {
+		this.#sideloaded = merge
+			? { ...this.#sideloaded, ...values }
+			: { ...values };
 		return this;
 	}
 
@@ -2653,6 +3331,14 @@ export class ModelQuery<T extends BaseEntity> {
 				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);
 		}
 	}
@@ -2673,7 +3359,14 @@ export class ModelQuery<T extends BaseEntity> {
 		// 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<string>();
 		// Reverse map (db column → property) so an explicit `@Column({ columnName })`
 		// on the related entity hydrates correctly — mirrors `BaseRepository.#hydrate`.
@@ -3022,6 +3715,9 @@ export class ModelQuery<T extends BaseEntity> {
 			operator: string;
 			value: unknown;
 		}> = [];
+		// Query-time pivotColumns([...]) requested in the preload callback (replayed
+		// on the scratch builder below) OR directly on this query (related().query()).
+		const extraPivotCols: string[] = [...this.#extraPivotColumns];
 		if (ctx.nestedCallback) {
 			const scratch = new ModelQuery<BaseEntity>(
 				ctx.relatedTable,
@@ -3034,6 +3730,7 @@ export class ModelQuery<T extends BaseEntity> {
 				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).
@@ -3080,7 +3777,11 @@ export class ModelQuery<T extends BaseEntity> {
 
 		// 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
@@ -3254,10 +3955,58 @@ export class ModelQuery<T extends BaseEntity> {
 		sub.whereIn(column, values);
 		if (relation.onQuery) relation.onQuery(sub as unknown);
 		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<Record<string, unknown>>(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: ModelQuery<BaseEntity>,
+		fkColumn: string,
+		n: number,
+	): Promise<Record<string, unknown>[]> {
+		const quoteSeg = (name: string): string => {
+			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<Record<string, unknown>>(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'`
@@ -3435,35 +4184,114 @@ export class ModelQuery<T extends BaseEntity> {
 	 */
 	// === Story 29.4 — joins ===========================================================================
 
-	/** `INNER JOIN <table> ON <left> = <right>`. */
+	/** `INNER JOIN` — alias of {@link innerJoin} (Lucid/Knex `join`). */
+	join(table: string, left: string, right: string): this;
+	join(table: string, left: string, operator: string, right: string): this;
+	join(table: string, build: (j: JoinBuilder) => void): this;
+	join(
+		table: string,
+		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
+		right?: string,
+	): this {
+		return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
+	}
+
+	/** `INNER JOIN <table> ON <left> [op] <right>` or a callback `ON` builder. */
 	innerJoin(table: string, left: string, right: string): this;
+	innerJoin(table: string, left: string, operator: string, right: string): this;
 	innerJoin(table: string, build: (j: JoinBuilder) => void): this;
 	innerJoin(
 		table: string,
 		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
 		right?: string,
 	): this {
-		return this.#pushJoin("INNER", table, leftOrBuild, right);
+		return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
 	}
 
 	leftJoin(table: string, left: string, right: string): this;
+	leftJoin(table: string, left: string, operator: string, right: string): this;
 	leftJoin(table: string, build: (j: JoinBuilder) => void): this;
 	leftJoin(
 		table: string,
 		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
+		right?: string,
+	): this {
+		return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
+	}
+
+	/** `LEFT OUTER JOIN` — alias of {@link leftJoin} (Lucid/Knex `leftOuterJoin`). */
+	leftOuterJoin(table: string, left: string, right: string): this;
+	leftOuterJoin(
+		table: string,
+		left: string,
+		operator: string,
+		right: string,
+	): this;
+	leftOuterJoin(table: string, build: (j: JoinBuilder) => void): this;
+	leftOuterJoin(
+		table: string,
+		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
 		right?: string,
 	): this {
-		return this.#pushJoin("LEFT", table, leftOrBuild, right);
+		return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
 	}
 
 	rightJoin(table: string, left: string, right: string): this;
+	rightJoin(table: string, left: string, operator: string, right: string): this;
 	rightJoin(table: string, build: (j: JoinBuilder) => void): this;
 	rightJoin(
 		table: string,
 		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
+		right?: string,
+	): this {
+		return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
+	}
+
+	/** `RIGHT OUTER JOIN` — alias of {@link rightJoin} (Lucid/Knex `rightOuterJoin`). */
+	rightOuterJoin(table: string, left: string, right: string): this;
+	rightOuterJoin(
+		table: string,
+		left: string,
+		operator: string,
+		right: string,
+	): this;
+	rightOuterJoin(table: string, build: (j: JoinBuilder) => void): this;
+	rightOuterJoin(
+		table: string,
+		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
 		right?: string,
 	): this {
-		return this.#pushJoin("RIGHT", table, leftOrBuild, right);
+		return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
+	}
+
+	/** `FULL OUTER JOIN` (Lucid/Knex `fullOuterJoin`; Postgres — MySQL/SQLite lack it). */
+	fullOuterJoin(table: string, left: string, right: string): this;
+	fullOuterJoin(
+		table: string,
+		left: string,
+		operator: string,
+		right: string,
+	): this;
+	fullOuterJoin(table: string, build: (j: JoinBuilder) => void): this;
+	fullOuterJoin(
+		table: string,
+		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
+		right?: string,
+	): this {
+		return this.#pushJoin(
+			"FULL OUTER",
+			table,
+			leftOrBuild,
+			operatorOrRight,
+			right,
+		);
 	}
 
 	crossJoin(table: string): this {
@@ -3516,8 +4344,15 @@ export class ModelQuery<T extends BaseEntity> {
 
 	// === Story 29.5 — aggregates / exists / pluck =====================================================
 
-	distinct(): this {
+	/**
+	 * SELECT DISTINCT (Lucid/Knex `distinct`). With columns, those replace the
+	 * projection too — `distinct('a', 'b')` ≈ `SELECT DISTINCT a, b`.
+	 */
+	distinct(...columns: string[]): this {
 		this.#distinct = true;
+		if (columns.length > 0) {
+			this.#select = columns.map((c) => this.#resolveSelect(c));
+		}
 		return this;
 	}
 
@@ -3569,7 +4404,7 @@ export class ModelQuery<T extends BaseEntity> {
 		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<Record<string, unknown>>(
 			sql,
 			params,
@@ -3587,7 +4422,7 @@ export class ModelQuery<T extends BaseEntity> {
 		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<Record<string, unknown>>(sql, params);
 		return rows.map((row) => {
 			const v = row[col];
@@ -3658,8 +4493,10 @@ export class ModelQuery<T extends BaseEntity> {
 	unless<V>(
 		condition: V | undefined | null | false,
 		fn: (q: this) => void,
+		elseFn?: (q: this) => void,
 	): this {
 		if (!condition) fn(this);
+		else if (elseFn) elseFn(this);
 		return this;
 	}
 
@@ -3669,11 +4506,17 @@ export class ModelQuery<T extends BaseEntity> {
 	async paginate(page: number, perPage: number): Promise<Paginator<T>> {
 		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 = [];
@@ -3684,12 +4527,12 @@ export class ModelQuery<T extends BaseEntity> {
 			// 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;
 		}
@@ -3700,21 +4543,24 @@ export class ModelQuery<T extends BaseEntity> {
 		);
 		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<T>(
+		const paginator = new Paginator<T>(
 			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;
 	}
 
 	/**
@@ -3813,6 +4659,18 @@ export class ModelQuery<T extends BaseEntity> {
 		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: Record<string, unknown>): this {
+		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
@@ -3826,17 +4684,18 @@ export class ModelQuery<T extends BaseEntity> {
 			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(): string {
-		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. */
@@ -3857,9 +4716,20 @@ export class ModelQuery<T extends BaseEntity> {
 		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;
@@ -3873,6 +4743,7 @@ export class ModelQuery<T extends BaseEntity> {
 			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(),
@@ -3880,45 +4751,67 @@ export class ModelQuery<T extends BaseEntity> {
 			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(
+	/**
+	 * Execute a fluent UPDATE (Lucid/Knex `update`). Accepts a `{ col: value }` map
+	 * OR a single `(column, value)` pair; a value may be a `db.raw(...)` expression.
+	 * Returns affected rows (or the RETURNING rows when `returning` is set).
+	 */
+	update(
+		column: string,
+		value: unknown,
+	): DmlBuilder<number | Record<string, unknown>[]>;
+	update(
 		patch: Record<string, unknown>,
 		returning?: string[],
-	): Promise<number | Record<string, unknown>[]> {
+	): DmlBuilder<number | Record<string, unknown>[]>;
+	update(
+		patchOrColumn: Record<string, unknown> | string,
+		valueOrReturning?: unknown,
+	): DmlBuilder<number | Record<string, unknown>[]> {
+		const patch =
+			typeof patchOrColumn === "string"
+				? { [patchOrColumn]: valueOrReturning }
+				: patchOrColumn;
+		const returning =
+			typeof patchOrColumn === "string"
+				? undefined
+				: (valueOrReturning as string[] | undefined);
 		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)] as [string, unknown],
+		// A `db.raw(...)` value is emitted as a raw SET expression instead.
+		const setPairs = Object.entries(patch).map(([k, v]): [string, unknown] =>
+			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: r,
+				ctes: this.#compiledCtes(),
+			}),
+			returning,
 		);
-		const spec = {
-			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<Record<string, unknown>>(
-				compiled.statements[0],
-				compiled.params,
-			);
-		}
-		const r = await this.#db.execute(compiled.statements[0], compiled.params);
-		return r.rowsAffected ?? 0;
 	}
 
 	/**
@@ -3928,33 +4821,38 @@ export class ModelQuery<T extends BaseEntity> {
 	 * model it issues a hard `DELETE`. Returns affected rows (or rows when
 	 * `returning` is set).
 	 */
-	async delete(
-		returning?: string[],
-	): Promise<number | Record<string, unknown>[]> {
+	delete(returning?: string[]): DmlBuilder<number | Record<string, unknown>[]> {
 		if (this.#softDeletes) {
-			const spec = {
-				kind: "update",
-				table: this.#tableName,
-				set: [[this.#deletedAtColumn(), new Date().toISOString()]],
-				wheres: this.#wheresForDml(),
-				returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
-			};
-			return this.#runDml(spec, returning);
+			const stampedAt = new Date().toISOString();
+			return this.#makeDml(
+				(r) => ({
+					kind: "update",
+					table: this.#tableName,
+					set: [[this.#deletedAtColumn(), stampedAt]],
+					wheres: this.#wheresForDml(),
+					returning: r,
+					ctes: this.#compiledCtes(),
+				}),
+				returning,
+			);
 		}
 		return this.forceDelete(returning);
 	}
 
 	/** Hard `DELETE` of the scoped rows, bypassing `@SoftDeletes` (AdonisJS/Lucid `forceDelete`). */
-	async forceDelete(
+	forceDelete(
 		returning?: string[],
-	): Promise<number | Record<string, unknown>[]> {
-		const spec = {
-			kind: "delete",
-			table: this.#tableName,
-			wheres: this.#wheresForDml(),
-			returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
-		};
-		return this.#runDml(spec, returning);
+	): DmlBuilder<number | Record<string, unknown>[]> {
+		return this.#makeDml(
+			(r) => ({
+				kind: "delete",
+				table: this.#tableName,
+				wheres: this.#wheresForDml(),
+				returning: r,
+				ctes: this.#compiledCtes(),
+			}),
+			returning,
+		);
 	}
 
 	/**
@@ -3963,30 +4861,38 @@ export class ModelQuery<T extends BaseEntity> {
 	 * on a non-soft-delete model. Independent of the current soft-scope — it always
 	 * targets trashed rows (`deleted_at IS NOT NULL`).
 	 */
-	async restore(
+	restore(
 		returning?: string[],
-	): Promise<number | Record<string, unknown>[]> {
-		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);
+	): DmlBuilder<number | Record<string, unknown>[]> {
+		if (!this.#softDeletes) {
+			return new DmlBuilder(
+				() => Promise.resolve<number | Record<string, unknown>[]>(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);
 	}
 
 	// === Story 30.3 — increment / decrement already implemented? check ================================
 
-	increment(column: string, amount: number): Promise<number>;
+	increment(column: string, amount?: number): Promise<number>;
 	increment(patch: Record<string, number>): Promise<number>;
 	increment(
 		colOrPatch: string | Record<string, number>,
@@ -3995,7 +4901,7 @@ export class ModelQuery<T extends BaseEntity> {
 		return this.#runIncDec("increment", colOrPatch, amount);
 	}
 
-	decrement(column: string, amount: number): Promise<number>;
+	decrement(column: string, amount?: number): Promise<number>;
 	decrement(patch: Record<string, number>): Promise<number>;
 	decrement(
 		colOrPatch: string | Record<string, number>,
@@ -4103,87 +5009,190 @@ export class ModelQuery<T extends BaseEntity> {
 	}
 
 	#pushJoin(
-		kind: "INNER" | "LEFT" | "RIGHT",
+		kind: "INNER" | "LEFT" | "RIGHT" | "FULL OUTER",
 		table: string,
 		leftOrBuild: string | ((j: JoinBuilder) => void),
+		operatorOrRight?: string,
 		right?: string,
 	): this {
 		const tq = this.#quoteCol(table);
 		if (typeof leftOrBuild === "function") {
+			const parts: JoinPartMQ[] = [];
 			const jb: JoinBuilder = {
-				parts: [],
-				on(l: string, r: string) {
-					this.parts.push({ kind: "and", left: l, right: r });
-					return this;
+				parts,
+				on: (l: string, opOrR: string, r?: string) => {
+					parts.push(
+						r === undefined
+							? { kind: "and", left: l, right: opOrR }
+							: { kind: "and", left: l, operator: opOrR, right: r },
+					);
+					return jb;
 				},
-				andOn(l: string, r: string) {
-					this.parts.push({ kind: "and", left: l, right: r });
-					return this;
+				andOn: (l: string, opOrR: string, r?: string) => {
+					parts.push(
+						r === undefined
+							? { kind: "and", left: l, right: opOrR }
+							: { kind: "and", left: l, operator: opOrR, right: r },
+					);
+					return jb;
+				},
+				orOn: (l: string, opOrR: string, r?: string) => {
+					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;
 				},
-				orOn(l: string, r: string) {
-					this.parts.push({ kind: "or", left: l, right: r });
-					return this;
+				andOnVal: (l, v) => {
+					parts.push({ kind: "and", left: l, value: { v } });
+					return jb;
+				},
+				orOnVal: (l, v) => {
+					parts.push({ kind: "or", left: l, value: { v } });
+					return jb;
+				},
+				onIn: (l, values) => {
+					parts.push({ kind: "and", left: l, values: [...values] });
+					return jb;
+				},
+				onNotIn: (l, values) => {
+					parts.push({
+						kind: "and",
+						left: l,
+						values: [...values],
+						notIn: true,
+					});
+					return jb;
 				},
-				onVal(l: string, v: unknown) {
-					this.parts.push({ kind: "and", left: l, value: { v } });
-					return this;
+				onNull: (l) => {
+					parts.push({ kind: "and", left: l, nullOp: "IS NULL" });
+					return jb;
 				},
-				andOnVal(l: string, v: unknown) {
-					this.parts.push({ kind: "and", left: l, value: { v } });
-					return this;
+				onNotNull: (l) => {
+					parts.push({ kind: "and", left: l, nullOp: "IS NOT NULL" });
+					return jb;
 				},
-				orOnVal(l: string, v: unknown) {
-					this.parts.push({ kind: "or", 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;
+				},
+				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: string, v: unknown): unknown => {
+				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: unknown[] = [];
-			const on = jb.parts
+			const on = parts
 				.map((p, i) => {
 					const prefix = i === 0 ? "ON" : p.kind === "or" ? "OR" : "AND";
-					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);
+					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(
-							isBaseColumn
-								? this.#prepareValue(leaf, p.value.v)
-								: lowerJoinValue(p.value.v),
+							prep(p.left ?? "", p.between[0]),
+							prep(p.left ?? "", p.between[1]),
 						);
-						return `${prefix} ${this.#quoteCol(p.left)} = ?`;
+						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) {
+						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: string): string {
+		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: string): Promise<unknown> {
 		const clone = this.clone();
 		clone.#select = [`${expr} AS __scalar__`];
 		clone.#orderBys = [];
-		const { sql, params } = clone.toSQL();
-		const rows = await this.#db.query<Record<string, unknown>>(sql, params);
+		const { sql, params } = clone.#compiledNative();
+		const rows = await this.#raceTimeout(
+			this.#db.query<Record<string, unknown>>(sql, params),
+		);
 		const row = rows[0];
 		return row ? row.__scalar__ : null;
 	}
@@ -4208,48 +5217,31 @@ export class ModelQuery<T extends BaseEntity> {
 			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(): Array<Record<string, unknown>> {
-		const out: Array<Record<string, unknown>> = [];
-		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;
+	#userWheresForDml(): WhereClause[] {
+		return [...this.#wheres];
 	}
 
-	#wheresForDml(): Array<Record<string, unknown>> {
+	#wheresForDml(): WhereClause[] {
 		const out = this.#userWheresForDml();
 		// Mirror the read scope (`#buildSpec`): a `@SoftDeletes` model's bulk
 		// update/delete/increment/decrement must NOT touch trashed rows under the
@@ -4277,6 +5269,63 @@ export class ModelQuery<T extends BaseEntity> {
 		return out;
 	}
 
+	/** Compile a DML spec with the comment prefix — for a lazy builder's `.toSQL()`. */
+	#compileDmlSpec(spec: Record<string, unknown>): {
+		sql: string;
+		bindings: unknown[];
+		params: unknown[];
+	} {
+		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(): DmlChainHooks {
+		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: (returning: string[]) => Record<string, unknown>,
+		paramReturning?: string[],
+	): DmlBuilder<number | Record<string, unknown>[]> {
+		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: Record<string, unknown>,
@@ -4284,12 +5333,21 @@ export class ModelQuery<T extends BaseEntity> {
 	): Promise<number | Record<string, unknown>[]> {
 		const compiled = compileStatementNative(spec, this.#dialect);
 		if (returning && returning.length > 0) {
-			return this.#db.query<Record<string, unknown>>(
-				compiled.statements[0],
-				compiled.params,
+			return this.#raceTimeout(
+				this.#db.query<Record<string, unknown>>(
+					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;
 	}
 
@@ -4306,15 +5364,6 @@ export class ModelQuery<T extends BaseEntity> {
 	 * 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: unknown): string {
-		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