@c9up/atlas 0.1.19 → 0.2.1

package/src/ModelQuery.ts

@@ -7,22 +7,43 @@
  * Builds SQL fluently and executes against the database connection.
  */
 
-import type { BaseEntity } from "./BaseEntity.js";
-import type { DatabaseConnection } from "./BaseRepository.js";
+import { dateTimeAtlasAdapter } from "@c9up/chronos/atlas";
+import type { QueryMeta } from "./adapters/NapiDbAdapter.js";
+import { type BaseEntity, type DomainEvent, REPO_REF } from "./BaseEntity.js";
+// Value import used only inside method bodies (preload hydration) — the
+// BaseRepository ↔ ModelQuery cycle resolves at runtime, after both are defined.
 import {
+	assertNotPromise,
+	BaseRepository,
+	type DatabaseConnection,
+	wrapAdapterError,
+} from "./BaseRepository.js";
+import {
+	ensureEntityMetadata,
 	getColumnMetadata,
-	getEntityMetadata,
+	getDateColumnConfig,
 	getPrimaryKey,
 	getRelationMetadata,
 	hasSoftDeletes,
 	type RelationMetadata,
 } 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";
 
 /**
@@ -43,6 +64,50 @@ const WHEREEXPR_OPERATORS = new Set<string>([
 	"NOT LIKE",
 ]);
 
+/**
+ * SQL keyword tokens forbidden inside `whereExpr`'s arithmetic extra-expression.
+ * They are just letters (pass the charset guard) but would let the fragment alter
+ * the predicate's logical structure — whereExpr stays an arithmetic-only, SAFE
+ * alternative to whereRaw. A column genuinely named after a keyword must use whereRaw.
+ */
+const WHEREEXPR_FORBIDDEN_WORDS = new Set<string>([
+	"OR",
+	"AND",
+	"NOT",
+	"IS",
+	"NULL",
+	"IN",
+	"LIKE",
+	"ILIKE",
+	"BETWEEN",
+	"EXISTS",
+	"ANY",
+	"ALL",
+	"SOME",
+	"CASE",
+	"WHEN",
+	"THEN",
+	"ELSE",
+	"END",
+	"SELECT",
+	"FROM",
+	"WHERE",
+	"JOIN",
+	"UNION",
+	"INTERSECT",
+	"EXCEPT",
+	"HAVING",
+	"GROUP",
+	"ORDER",
+	"BY",
+	"LIMIT",
+	"OFFSET",
+	"AS",
+	"DISTINCT",
+	"TRUE",
+	"FALSE",
+]);
+
 /** True when every `(` in `s` has a matching `)` and none closes early. */
 function hasBalancedParens(s: string): boolean {
 	let depth = 0;
@@ -59,6 +124,112 @@ function hasBalancedParens(s: string): boolean {
 type PreloadCallback = (query: ModelQuery<BaseEntity>) => void;
 
 type ColumnResolver = (column: string) => string;
+/**
+ * Lower a value bound for a given property to its DB form — mirrors
+ * `BaseRepository.#applyPrepare` (a `@column.dateTime` DateTime → ISO string, a
+ * `@Column({ prepare })` adapter runs). Threaded into ModelQuery so the fluent
+ * `update()` / WHERE paths don't bypass prepare the way direct repo writes don't.
+ */
+type ValuePreparer = (column: string, value: unknown) => unknown;
+
+/**
+ * Column resolver for an ARBITRARY entity class, honouring `@Column({ columnName })`
+ * and the snake_case convention. Used to build correlated/preload subqueries on a
+ * RELATED model so their WHERE/join columns resolve like a direct query would.
+ */
+function buildColumnResolver(
+	entityClass: new () => BaseEntity,
+): ColumnResolver {
+	const map = new Map<string, string>();
+	for (const col of getColumnMetadata(entityClass)) {
+		const db = col.columnName ?? camelToSnake(col.propertyKey);
+		map.set(col.propertyKey, db);
+		map.set(db, db);
+	}
+	return (col) => map.get(col) ?? camelToSnake(col);
+}
+
+/**
+ * Value preparer for an ARBITRARY entity class — mirrors `BaseRepository.#applyPrepare`
+ * (a `@column.dateTime` DateTime → ISO, a `@Column({ prepare })` adapter runs). So a
+ * preload/whereHas constraint on a RELATED model prepares its values like a direct query.
+ */
+function buildValuePreparer(entityClass: new () => BaseEntity): ValuePreparer {
+	const prepares = new Map<
+		string,
+		(v: unknown, attribute?: string, model?: unknown) => unknown
+	>();
+	// Reverse map (db column → property) so a caller passing a DB name or an
+	// explicit `columnName` (e.g. preload/whereHas constraint on `published_at`)
+	// still routes through the property-keyed prepare/date maps — mirrors
+	// BaseRepository.#applyPrepare.
+	const byDbName = new Map<string, string>();
+	for (const col of getColumnMetadata(entityClass)) {
+		if (col.prepare) prepares.set(col.propertyKey, col.prepare);
+		byDbName.set(
+			col.columnName ?? camelToSnake(col.propertyKey),
+			col.propertyKey,
+		);
+	}
+	const dateCols = getDateColumnConfig(entityClass);
+	return (key, value) => {
+		const prop = byDbName.get(key) ?? key;
+		const p = prepares.get(prop);
+		// Query-builder value transform — no model instance, but the attribute is
+		// known (Adonis Lucid signature: value, attribute, model).
+		if (p) return p(value, prop, undefined);
+		if (dateCols[prop] && value != null) {
+			if (value instanceof Date) return value.toISOString();
+			return dateTimeAtlasAdapter.prepare(value);
+		}
+		return value;
+	};
+}
+
+/** Structural (cross-realm-safe) check for a value exposing `toISO()` — a Chronos/Luxon DateTime. */
+function joinValueHasToISO(v: unknown): v is { toISO(): string } {
+	return (
+		typeof v === "object" &&
+		v !== null &&
+		"toISO" in v &&
+		typeof v.toISO === "function"
+	);
+}
+
+/**
+ * Universal type-lowering for a JOIN `onVal`/`andOnVal`/`orOnVal` bound value:
+ * `Date`/`DateTime` → ISO string. Unlike the model value-preparer this applies NO
+ * column-specific `@Column({ prepare })` adapter, so a FOREIGN join column can't
+ * borrow the root model's adapter for a same-named column on a different table
+ * (Knex binds join values model-agnostically; we add only safe universal
+ * serialization so a DateTime still lowers to ISO like `where()`).
+ */
+function lowerJoinValue(value: unknown): unknown {
+	if (value instanceof Date) return value.toISOString();
+	if (joinValueHasToISO(value)) return value.toISO();
+	return value;
+}
+
+/**
+ * Does a join column's table reference (`ref`) denote the root model's own table
+ * (`modelTable`)? The match is ASYMMETRIC: a reference may OMIT the schema the
+ * model declares (default schema) — `orders` matches a `public.orders` model — but
+ * it may NOT ADD qualification the model doesn't claim. So a `public.orders` model
+ * accepts `orders.col`, while an unqualified `orders` model rejects
+ * `archive.orders.col` (a different schema the model never named) — keeping it
+ * foreign so the root model's `@Column` adapters aren't misapplied to it.
+ */
+function sameTableRef(ref: string, modelTable: string): boolean {
+	const rs = ref.split(".");
+	const ms = modelTable.split(".");
+	// The reference cannot be MORE qualified than the model (it can only drop the
+	// schema, never assert a new one) — otherwise treat it as a foreign table.
+	if (rs.length > ms.length) return false;
+	for (let i = 1; i <= rs.length; i++) {
+		if (rs[rs.length - i] !== ms[ms.length - i]) return false;
+	}
+	return true;
+}
 
 /** Per-preload-relation locals shared by the resolver helpers. Built once per relation, then passed by ref. */
 interface PreloadContext {
@@ -148,6 +319,22 @@ interface RawWhere {
 	bindings: unknown[];
 }
 
+/**
+ * A JSON predicate — path comparison or containment. The column is a quoted
+ * identifier; the path and value cross the boundary as bound params. Mirrors
+ * the Rust `json` WHERE kind.
+ */
+interface JsonWhere {
+	type: "and" | "or";
+	kind: "json";
+	jsonOp: "path" | "superset" | "subset" | "equals";
+	column: string;
+	negated: boolean;
+	path?: string;
+	operator?: string;
+	value: unknown;
+}
+
 /** An EXISTS / NOT EXISTS correlated subquery — used by whereHas / doesntHave. */
 interface ExistsWhere {
 	type: "and" | "or";
@@ -156,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)`. */
@@ -195,13 +384,27 @@ interface CteSpec {
 	name: string;
 	sql: string;
 	params: unknown[];
+	/** One recursive CTE makes the whole WITH clause recursive — see `withRecursive`. */
+	recursive?: boolean;
+	/**
+	 * `true` → AS MATERIALIZED, `false` → AS NOT MATERIALIZED, `null` →
+	 * planner's choice. Null rather than absent because this crosses the NAPI
+	 * boundary, where serde reads a missing key and an explicit null alike.
+	 */
+	materialized?: boolean | null;
 }
 
-/** A compiled UNION / UNION ALL branch — pre-compiled to SQL + params. */
+/**
+ * A compiled set-operation branch — pre-compiled to SQL + params. Still named
+ * `UnionSpec` (and sent under `unions`) because that wire field predates
+ * INTERSECT/EXCEPT; renaming it would break the contract for no gain.
+ */
 interface UnionSpec {
 	sql: string;
 	params: unknown[];
 	all: boolean;
+	/** Defaults to `union` when absent/null, keeping the pre-existing wire format. */
+	op?: "union" | "intersect" | "except" | null;
 }
 
 interface SubqueryProjection {
@@ -209,22 +412,52 @@ interface SubqueryProjection {
 	subquery: SelectSpec;
 }
 
+/**
+ * One ORDER BY term: a resolved column + direction, or a verbatim fragment
+ * (`orderByRaw`). Both share one list so a raw term keeps its position among
+ * the plain ones. Mirrors the Rust `OrderByClause`.
+ */
+type OrderByEntry =
+	| { column: string; direction: "asc" | "desc" }
+	| { raw: string };
+
+/**
+ * One GROUP BY term: a resolved column, or a verbatim fragment (`groupByRaw`).
+ * Mirrors the Rust `GroupByItem` — untagged, so a bare string stays a column
+ * and the pre-existing wire format is unchanged.
+ */
+type GroupByEntry = string | { raw: string };
+
 interface SelectSpec {
 	kind: "select";
 	table: string;
 	select: string[];
 	selectSubqueries: SubqueryProjection[];
 	wheres: WhereClause[];
-	orderBy: Array<{ column: string; direction: "asc" | "desc" }>;
-	groupBy: string[];
+	orderBy: OrderByEntry[];
+	groupBy: GroupByEntry[];
 	having: HavingEntry[];
 	limit: number | null;
 	offset: number | null;
 	distinct: boolean;
+	distinctOn: string[];
 	ctes: CteSpec[];
 	unions: UnionSpec[];
-	joins: string[];
-	lockMode: "FOR UPDATE" | "FOR SHARE" | null;
+	/** 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 =
@@ -232,15 +465,22 @@ type WhereClause =
 	| RawWhere
 	| ExistsWhere
 	| GroupWhere
-	| InSubWhere;
+	| 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()` and `joinRaw()`
- * throw unconditionally — forcing every call site to use the typed
- * `whereExpr()` / `joinOn()` / structured builder paths. Intended for prod
- * hardening on apps that can't audit every call site manually.
+ * Process-wide strict mode flag. When enabled, `whereRaw()`, `joinRaw()`,
+ * `havingRaw()` and the repository's `raw()` throw unconditionally — forcing every
+ * call site to use the typed `whereExpr()` / `joinOn()` / `having()` / structured
+ * builder paths. The connection-level `db.query()` / `db.execute()` stay available
+ * as the explicit, parameterised break-glass. Intended for prod hardening on apps
+ * that can't audit every call site manually.
  *
  * Enable via:
  *   - `setAtlasStrictMode(true)` at app bootstrap
@@ -252,7 +492,7 @@ type WhereCallback = (q: ModelQuery<BaseEntity>) => void;
  */
 let atlasStrictMode: boolean | undefined;
 
-/** Enable or disable Atlas strict mode. When enabled, whereRaw/joinRaw throw in user code. */
+/** Enable or disable Atlas strict mode. When enabled, whereRaw/joinRaw/havingRaw throw in user code. */
 export function setAtlasStrictMode(enabled: boolean): void {
 	atlasStrictMode = enabled;
 }
@@ -286,12 +526,54 @@ function isInternalBypass(): boolean {
 	return atlasInternalBypass;
 }
 
-/** Multi-condition join builder passed to innerJoin/leftJoin/rightJoin callbacks. */
+/**
+ * Multi-condition join builder passed to innerJoin/leftJoin/rightJoin callbacks.
+ * `on`/`andOn`/`orOn` join two COLUMNS; `onVal`/`andOnVal`/`orOnVal` join a column
+ * 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 {
-	parts: Array<{ kind: "and" | "or"; left: string; right: string }>;
+	/** 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). */
@@ -306,20 +588,46 @@ export class Paginator<T> {
 	};
 	#baseUrl?: string;
 	#queryString: Record<string, unknown> = {};
+	#metaKeys?: Record<string, string>;
 
 	constructor(
 		items: T[],
 		base: { total: number; perPage: number; currentPage: number },
+		metaKeys?: Record<string, string>,
 	) {
 		this.items = items;
 		const lastPage = Math.max(1, Math.ceil(base.total / base.perPage));
 		this.meta = { ...base, lastPage, firstPage: 1 };
+		this.#metaKeys = metaKeys;
 	}
 
 	all(): T[] {
 		return this.items;
 	}
 
+	// Top-level numeric accessors (AdonisJS Lucid paginator) — the same values
+	// carried in `.meta`, exposed directly on the instance for convenience.
+	/** Total row count across all pages. */
+	get total(): number {
+		return this.meta.total;
+	}
+	/** Rows per page. */
+	get perPage(): number {
+		return this.meta.perPage;
+	}
+	/** The current page number. */
+	get currentPage(): number {
+		return this.meta.currentPage;
+	}
+	/** The last page number. */
+	get lastPage(): number {
+		return this.meta.lastPage;
+	}
+	/** The first page number (always 1). */
+	get firstPage(): number {
+		return this.meta.firstPage;
+	}
+
 	/** True when there is more than one page of results (AdonisJS `hasPages`). */
 	get hasPages(): boolean {
 		return this.meta.lastPage > 1;
@@ -332,7 +640,7 @@ export class Paginator<T> {
 
 	serialize(opts?: { fields?: string[] }): {
 		data: unknown[];
-		meta: Paginator<T>["meta"];
+		meta: Record<string, unknown>;
 	} {
 		const data = this.items.map((item) => {
 			if (!opts?.fields) return item;
@@ -341,7 +649,9 @@ export class Paginator<T> {
 				picked[f] = (item as Record<string, unknown>)[f];
 			return picked;
 		});
-		return { data, meta: this.meta };
+		// Same meta shape as toJSON — snake_case keys via the naming strategy's
+		// paginationMetaKeys, plus page URLs when a baseUrl is set.
+		return { data, meta: this.#buildMeta() };
 	}
 
 	baseUrl(url: string): this {
@@ -353,29 +663,76 @@ export class Paginator<T> {
 		return this;
 	}
 
+	/**
+	 * Build the URL for a page number, honouring `baseUrl` + `queryString`.
+	 * Returns `''` when no `baseUrl` was set (AdonisJS `getUrl`).
+	 */
+	getUrl(page: number): string {
+		if (!this.#baseUrl) return "";
+		const params = new URLSearchParams();
+		for (const [k, v] of Object.entries(this.#queryString))
+			params.set(k, String(v));
+		params.set("page", String(page));
+		return `${this.#baseUrl}?${params.toString()}`;
+	}
+
+	/** URL of the next page, or `null` when on the last page (AdonisJS `getNextPageUrl`). */
+	getNextPageUrl(): string | null {
+		return this.hasMorePages ? this.getUrl(this.meta.currentPage + 1) : null;
+	}
+
+	/** URL of the previous page, or `null` when on the first page (AdonisJS `getPreviousPageUrl`). */
+	getPreviousPageUrl(): string | null {
+		return this.meta.currentPage > 1
+			? this.getUrl(this.meta.currentPage - 1)
+			: null;
+	}
+
+	/** URLs for an inclusive page range, clamped to `[1, lastPage]` (AdonisJS `getUrlsForRange`). */
+	getUrlsForRange(
+		start: number,
+		end: number,
+	): Array<{ page: number; url: string; isActive: boolean }> {
+		const lo = Math.max(1, start);
+		const hi = Math.min(this.meta.lastPage, end);
+		const range: Array<{ page: number; url: string; isActive: boolean }> = [];
+		for (let page = lo; page <= hi; page++)
+			range.push({
+				page,
+				url: this.getUrl(page),
+				isActive: page === this.meta.currentPage,
+			});
+		return range;
+	}
+
+	/**
+	 * Build the serialized `meta` object: the raw camelCase fields plus page URLs
+	 * (when a baseUrl is set), remapped through the naming strategy's
+	 * `paginationMetaKeys` — snake_case by default (AdonisJS Lucid parity).
+	 * Shared by {@link toJSON} and {@link serialize} so they never diverge.
+	 */
+	#buildMeta(): Record<string, unknown> {
+		const raw: Record<string, unknown> = { ...this.meta };
+		if (this.#baseUrl) {
+			raw.firstPageUrl = this.getUrl(1);
+			raw.lastPageUrl = this.getUrl(this.meta.lastPage);
+			const next = this.getNextPageUrl();
+			const prev = this.getPreviousPageUrl();
+			if (next) raw.nextPageUrl = next;
+			if (prev) raw.previousPageUrl = prev;
+		}
+		const keys = this.#metaKeys;
+		if (!keys) return raw;
+		const meta: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(raw)) meta[keys[k] ?? k] = v;
+		return meta;
+	}
+
 	toJSON(): {
 		data: unknown[];
-		meta: Paginator<T>["meta"] & Record<string, unknown>;
+		meta: Record<string, unknown>;
 	} {
-		const meta: Paginator<T>["meta"] & Record<string, unknown> = {
-			...this.meta,
-		};
-		if (this.#baseUrl) {
-			const build = (page: number) => {
-				const params = new URLSearchParams();
-				for (const [k, v] of Object.entries(this.#queryString))
-					params.set(k, String(v));
-				params.set("page", String(page));
-				return `${this.#baseUrl}?${params.toString()}`;
-			};
-			meta.firstPageUrl = build(1);
-			meta.lastPageUrl = build(this.meta.lastPage);
-			if (this.meta.currentPage < this.meta.lastPage)
-				meta.nextPageUrl = build(this.meta.currentPage + 1);
-			if (this.meta.currentPage > 1)
-				meta.previousPageUrl = build(this.meta.currentPage - 1);
-		}
-		return { data: this.items as unknown[], meta };
+		return { data: this.items as unknown[], meta: this.#buildMeta() };
 	}
 }
 
@@ -393,34 +750,96 @@ export class ModelQuery<T extends BaseEntity> {
 	#softDeletes: boolean;
 	#softScope: SoftDeleteScope = "default";
 	#wheres: WhereClause[] = [];
-	#orderBys: Array<{ column: string; direction: "asc" | "desc" }> = [];
+	#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. */
-	#joins: string[] = [];
-	/** Row lock mode — Story 30.8. */
-	#lockMode: "FOR UPDATE" | "FOR SHARE" | null = null;
+	#joins: Array<{ sql: string; params: unknown[] }> = [];
+	/** Row lock base mode — Story 30.8. */
+	#lockMode:
+		| "FOR UPDATE"
+		| "FOR SHARE"
+		| "FOR NO KEY UPDATE"
+		| "FOR KEY SHARE"
+		| null = null;
+	/** Optional lock modifier (SKIP LOCKED / NOWAIT), composed onto {@link #lockMode}. */
+	#lockModifier: "SKIP LOCKED" | "NOWAIT" | null = null;
+	/** Context threaded onto every hydrated instance's `$sideloaded` — AdonisJS `sideload`. */
+	#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[] = [];
 	/** GROUP BY columns (Lucid parity). */
-	#groupBy: string[] = [];
+	#groupBy: GroupByEntry[] = [];
 	/** HAVING clauses — structured + raw (Lucid parity). */
 	#having: HavingEntry[] = [];
 	/** CTEs registered via `.with()` (Lucid parity). */
-	#ctes: Array<{ name: string; query: ModelQuery<BaseEntity> }> = [];
+	#ctes: Array<{
+		name: string;
+		query: ModelQuery<BaseEntity>;
+		recursive?: boolean;
+		materialized?: boolean;
+		columns?: string[];
+	}> = [];
 	/** UNION / UNION ALL branches (Lucid parity). */
-	#unions: Array<{ query: ModelQuery<BaseEntity>; all: boolean }> = [];
+	#unions: Array<{
+		query: ModelQuery<BaseEntity>;
+		all: boolean;
+		op?: "union" | "intersect" | "except";
+	}> = [];
 	/** m2m pivot-table WHERE constraints — applied to the pivot lookup, not the related query. */
-	#pivotWheres: Array<{ column: string; operator: string; value: unknown }> =
-		[];
+	#pivotWheres: Array<{
+		column: string;
+		operator: string;
+		value: unknown;
+		/** 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
+	 * CURRENT `#pivotWheres` so `.wherePivot()` calls added AFTER the proxy handed
+	 * back the query still fold into the pivot EXISTS (a flat `whereRaw` at proxy
+	 * time would freeze the predicate before those calls and silently drop them).
+	 */
+	#pivotExists?: (
+		pivotWheres: ReadonlyArray<{
+			column: string;
+			operator: string;
+			value: unknown;
+		}>,
+	) => { sql: string; bindings: unknown[] };
 	/** SQL dialect for compilation — inherited from the owning BaseRepository. */
 	#dialect: AtlasDialect;
 
@@ -432,6 +851,8 @@ export class ModelQuery<T extends BaseEntity> {
 		resolveColumn: ColumnResolver = (c) => c,
 		softDeletes = false,
 		dialect: AtlasDialect = getAtlasDialect(),
+		prepareValue: ValuePreparer = (_c, v) => v,
+		onDomainEvents?: (events: DomainEvent[]) => Promise<void>,
 	) {
 		this.#tableName = tableName;
 		this.#db = db;
@@ -440,8 +861,15 @@ export class ModelQuery<T extends BaseEntity> {
 		this.#resolveColumn = resolveColumn;
 		this.#softDeletes = softDeletes;
 		this.#dialect = dialect;
+		this.#prepareValue = prepareValue;
+		this.#onDomainEvents = onDomainEvents;
 	}
 
+	/** @see ValuePreparer — identity unless the owning repository wires prepare in. */
+	#prepareValue: ValuePreparer;
+	/** Domain-event bus threaded from the owning repository — propagated to preload repos. */
+	#onDomainEvents?: (events: DomainEvent[]) => Promise<void>;
+
 	/** Include soft-deleted rows in the result (default behavior excludes them). */
 	withTrashed(): this {
 		this.#softScope = "with-trashed";
@@ -454,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.
@@ -467,14 +916,108 @@ 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 {
-		this.#select = Array.isArray(columns)
-			? columns
-			: columns.split(",").map((c) => c.trim());
+	/**
+	 * 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 /
+	 * qualified names / `*` untouched. A bare identifier IS validated through the
+	 * column resolver — so a typo like `select('lable')` raises the same Atlas
+	 * error as `where`/`orderBy`, rather than reaching the DB.
+	 */
+	#resolveSelect(col: string): string {
+		if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(col)) return this.#resolveColumn(col);
+		// `col as alias` — resolve the (bare) column part to its DB name, keep the
+		// alias verbatim, so `select('label as name')` honours a columnName override.
+		const aliased = col.match(
+			/^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/i,
+		);
+		if (aliased) return `${this.#resolveColumn(aliased[1])} AS ${aliased[2]}`;
+		return col;
+	}
+
 	where(callback: WhereCallback): this;
 	where(column: string, value: unknown): this;
 	where(column: string, operator: string, value: unknown): this;
@@ -525,37 +1068,175 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
-	/** `WHERE col != ?` — negation of `where`. */
-	whereNot(column: string, value: unknown): this {
+	// ─── AND aliases ──────────────────────────────────────────
+	//
+	// Lucid documents an `and*` spelling alongside every `where*`. They are
+	// exact synonyms — the base methods already default to AND — and exist so a
+	// chain can say so out loud: `.where(a).andWhere(b)`. Kept as thin
+	// delegations rather than duplicated bodies, so they cannot drift.
+
+	andWhere(callback: WhereCallback): this;
+	andWhere(column: string, value: unknown): this;
+	andWhere(column: string, operator: string, value: unknown): this;
+	andWhere(
+		columnOrCb: string | WhereCallback,
+		operatorOrValue?: unknown,
+		value?: unknown,
+	): this {
+		// The 2-arg overload must not forward a phantom third argument: `where`
+		// switches on `value === undefined` to tell `(col, value)` from
+		// `(col, operator, value)`.
+		return typeof columnOrCb === "function"
+			? this.where(columnOrCb)
+			: value === undefined
+				? this.where(columnOrCb, operatorOrValue)
+				: this.where(columnOrCb, operatorOrValue as string, value);
+	}
+
+	/** Alias of {@link whereNot} (Lucid parity). */
+	andWhereNot(column: string, value: unknown): this {
+		return this.whereNot(column, value);
+	}
+
+	/** Alias of {@link whereIn} (Lucid parity). */
+	andWhereIn(column: string, values: readonly unknown[]): this {
+		return this.whereIn(column, values);
+	}
+
+	/** Alias of {@link whereNotIn} (Lucid parity). */
+	andWhereNotIn(column: string, values: readonly unknown[]): this {
+		return this.whereNotIn(column, values);
+	}
+
+	/** Alias of {@link whereNull} (Lucid parity). */
+	andWhereNull(column: string): this {
+		return this.whereNull(column);
+	}
+
+	/** Alias of {@link whereNotNull} (Lucid parity). */
+	andWhereNotNull(column: string): this {
+		return this.whereNotNull(column);
+	}
+
+	/** Alias of {@link whereBetween} (Lucid parity). */
+	andWhereBetween(column: string, range: readonly [unknown, unknown]): this {
+		return this.whereBetween(column, range);
+	}
+
+	/** Alias of {@link whereNotBetween} (Lucid parity). */
+	andWhereNotBetween(column: string, range: readonly [unknown, unknown]): this {
+		return this.whereNotBetween(column, range);
+	}
+
+	/** Alias of {@link whereLike} (Lucid parity). */
+	andWhereLike(column: string, pattern: string): this {
+		return this.whereLike(column, pattern);
+	}
+
+	/** Alias of {@link whereILike} (Lucid parity). */
+	andWhereILike(column: string, pattern: string): this {
+		return this.whereILike(column, pattern);
+	}
+
+	/** Alias of {@link whereColumn} (Lucid parity). */
+	andWhereColumn(left: string, operator: string, right: string): this {
+		return this.whereColumn(left, operator, right);
+	}
+
+	/**
+	 * 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.#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: [...source],
+			value: this.#prep(columnOrColumns, [...source]),
 		});
 		return this;
 	}
@@ -579,7 +1260,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "and",
 			column: this.#resolveColumn(column),
 			operator: "NOT IN",
-			value: [...source],
+			value: this.#prep(column, [...source]),
 		});
 		return this;
 	}
@@ -590,7 +1271,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "and",
 			column: this.#resolveColumn(column),
 			operator: "BETWEEN",
-			value: [...range],
+			value: this.#prep(column, [...range]),
 		});
 		return this;
 	}
@@ -601,7 +1282,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "and",
 			column: this.#resolveColumn(column),
 			operator: "NOT BETWEEN",
-			value: [...range],
+			value: this.#prep(column, [...range]),
 		});
 		return this;
 	}
@@ -664,7 +1345,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "or",
 			column: this.#resolveColumn(column),
 			operator: "!=",
-			value,
+			value: this.#prep(column, value),
 		});
 		return this;
 	}
@@ -688,7 +1369,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "or",
 			column: this.#resolveColumn(column),
 			operator: "IN",
-			value: [...source],
+			value: this.#prep(column, [...source]),
 		});
 		return this;
 	}
@@ -712,7 +1393,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "or",
 			column: this.#resolveColumn(column),
 			operator: "NOT IN",
-			value: [...source],
+			value: this.#prep(column, [...source]),
 		});
 		return this;
 	}
@@ -723,7 +1404,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "or",
 			column: this.#resolveColumn(column),
 			operator: "BETWEEN",
-			value: [...range],
+			value: this.#prep(column, [...range]),
 		});
 		return this;
 	}
@@ -734,7 +1415,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "or",
 			column: this.#resolveColumn(column),
 			operator: "NOT BETWEEN",
-			value: [...range],
+			value: this.#prep(column, [...range]),
 		});
 		return this;
 	}
@@ -803,9 +1484,13 @@ export class ModelQuery<T extends BaseEntity> {
 	 * Not exported from the package barrel — only accessible inside the Atlas
 	 * codebase via direct ModelQuery instance access.
 	 */
-	#pushWhereRaw(sql: string, bindings: readonly unknown[] = []): this {
+	#pushWhereRaw(
+		sql: string,
+		bindings: readonly unknown[] = [],
+		type: "and" | "or" = "and",
+	): this {
 		this.#wheres.push({
-			type: "and",
+			type,
 			kind: "raw",
 			sql,
 			bindings: [...bindings],
@@ -813,6 +1498,52 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
+	/** Alias of {@link whereRaw} (Lucid parity). Subject to the same strict-mode gate. */
+	andWhereRaw(sql: string, bindings: readonly unknown[] = []): this {
+		return this.whereRaw(sql, bindings);
+	}
+
+	/**
+	 * `OR <raw fragment>` (Lucid parity).
+	 *
+	 * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+	 * Subject to the same strict-mode gate as {@link whereRaw}.
+	 */
+	orWhereRaw(sql: string, bindings: readonly unknown[] = []): this {
+		this.#assertRawAllowed("orWhereRaw");
+		return this.#pushWhereRaw(sql, bindings, "or");
+	}
+
+	/** Shared strict-mode gate for the raw WHERE entry points. */
+	#assertRawAllowed(method: string): void {
+		if (isAtlasStrictMode() && !isInternalBypass()) {
+			throw new Error(
+				`${method}() is disabled in Atlas strict mode. ` +
+					"Use whereExpr() or a structured builder method instead. " +
+					"Call setAtlasStrictMode(false) at bootstrap if you truly need raw SQL.",
+			);
+		}
+	}
+
+	/**
+	 * Framework-internal: register the deferred m2m EXISTS predicate for a lazy
+	 * `related().query()`. The builder is re-invoked on every `#buildSpec()` with
+	 * the pivot constraints known at that moment, so `.wherePivot()` added after
+	 * the proxy returned still applies. Not exported from the barrel.
+	 */
+	setPivotExistsBuilder(
+		builder: (
+			pivotWheres: ReadonlyArray<{
+				column: string;
+				operator: string;
+				value: unknown;
+			}>,
+		) => { sql: string; bindings: unknown[] },
+	): this {
+		this.#pivotExists = builder;
+		return this;
+	}
+
 	/**
 	 * **SAFE** alternative to `whereRaw` for the common case of a single
 	 * SQL expression built from a validated column + operator + bound value.
@@ -863,6 +1594,20 @@ export class ModelQuery<T extends BaseEntity> {
 					`whereExpr: extraExpression '${extra}' has unbalanced parentheses. Use whereRaw() if you need more.`,
 				);
 			}
+			// The charset blocks comparison/quote symbols, but bare SQL keywords
+			// (OR / AND / IS / NOT / SELECT …) are just letters and would slip
+			// through, letting `extra` alter the predicate's logical structure
+			// (e.g. `whereExpr('total', 'OR active', '>', 0)`). whereExpr is the
+			// SAFE arithmetic alternative to whereRaw, so reject any SQL keyword
+			// token — arithmetic on columns/numbers/functions only.
+			for (const word of extra.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? []) {
+				if (WHEREEXPR_FORBIDDEN_WORDS.has(word.toUpperCase())) {
+					throw new Error(
+						`whereExpr: extraExpression '${extra}' contains the SQL keyword '${word}'. ` +
+							"whereExpr allows arithmetic expressions only (columns, numbers, + - * / , functions). Use whereRaw() for logical/SQL constructs.",
+					);
+				}
+			}
 			// `op` is interpolated raw into the fragment below, so it MUST be
 			// allow-listed — the 3-arg path gets this from the Rust operator
 			// validation, but the raw 4-arg path bypasses Rust and would
@@ -881,9 +1626,16 @@ export class ModelQuery<T extends BaseEntity> {
 		// the operator against the allow-list above.
 		if (hasExtra) {
 			const q = this.#quote(resolved);
-			return this.#pushWhereRaw(`${q} ${extra} ${op} ?`, [value]);
+			return this.#pushWhereRaw(`${q} ${extra} ${op} ?`, [
+				this.#prep(column, value),
+			]);
 		}
-		this.#wheres.push({ type: "and", column: resolved, operator: op, value });
+		this.#wheres.push({
+			type: "and",
+			column: resolved,
+			operator: op,
+			value: this.#prep(column, value),
+		});
 		return this;
 	}
 
@@ -893,22 +1645,352 @@ export class ModelQuery<T extends BaseEntity> {
 	 * operator is allow-listed; nothing is bound (it's a column reference, not a
 	 * value), which the standard `where`/`whereExpr` value-binding path can't do.
 	 */
-	whereColumn(left: string, operator: string, right: string): this {
-		return this.#whereColumn("and", left, operator, right);
+	// ─── EXISTS ───────────────────────────────────────────────
+	//
+	// `whereExists` lived only on the low-level `query/QueryBuilder`, not on the
+	// builder `repo.query()` actually hands back, so it was unreachable from
+	// normal use. The subquery is another `ModelQuery`; correlate it to the
+	// outer table with `whereColumn`:
+	//
+	//     userRepo.query().whereExists(
+	//       postRepo.query().whereColumn('posts.user_id', '=', 'users.id')
+	//     )
+	//
+	// For relation-shaped EXISTS, prefer `whereHas`/`has`, which derive the
+	// join predicate from the relation metadata.
+
+	/** `WHERE EXISTS (subquery)` (Lucid parity). */
+	whereExists(subquery: ModelQuery<BaseEntity>): this {
+		return this.#pushExists("and", false, subquery);
 	}
 
-	/** `OR`-combined {@link whereColumn}. */
-	orWhereColumn(left: string, operator: string, right: string): this {
-		return this.#whereColumn("or", left, operator, right);
+	/** Alias of {@link whereExists} (Lucid parity). */
+	andWhereExists(subquery: ModelQuery<BaseEntity>): this {
+		return this.#pushExists("and", false, subquery);
 	}
 
-	#whereColumn(
-		type: "and" | "or",
-		left: string,
+	/** `OR EXISTS (subquery)` (Lucid parity). */
+	orWhereExists(subquery: ModelQuery<BaseEntity>): this {
+		return this.#pushExists("or", false, subquery);
+	}
+
+	/** `WHERE NOT EXISTS (subquery)` (Lucid parity). */
+	whereNotExists(subquery: ModelQuery<BaseEntity>): this {
+		return this.#pushExists("and", true, subquery);
+	}
+
+	/** Alias of {@link whereNotExists} (Lucid parity). */
+	andWhereNotExists(subquery: ModelQuery<BaseEntity>): this {
+		return this.#pushExists("and", true, subquery);
+	}
+
+	/** `OR NOT EXISTS (subquery)` (Lucid parity). */
+	orWhereNotExists(subquery: ModelQuery<BaseEntity>): this {
+		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.
+
+	/**
+	 * `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')
+	 */
+	whereJsonPath(column: string, path: string, value: unknown): this;
+	whereJsonPath(
+		column: string,
+		path: string,
 		operator: string,
-		right: string,
+		value: unknown,
+	): this;
+	whereJsonPath(
+		column: string,
+		path: string,
+		operatorOrValue: unknown,
+		value?: unknown,
 	): this {
-		if (!WHEREEXPR_OPERATORS.has(operator)) {
+		return this.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
+	}
+
+	/** 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.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
+	}
+
+	/** `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 {
+		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);
+	}
+
+	/**
+	 * `WHERE <col> @> ?` — the JSON column contains `value` (Lucid/Knex
+	 * `whereJsonSupersetOf`). `value` is any JSON-serialisable value.
+	 *
+	 * Postgres and MySQL only — SQLite has no JSON containment operator and the
+	 * compiler raises `E_UNSUPPORTED` there.
+	 */
+	whereJsonSupersetOf(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "superset", column, value);
+	}
+
+	/** Alias of {@link whereJsonSupersetOf} (Lucid parity). */
+	andWhereJsonSupersetOf(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "superset", column, value);
+	}
+
+	/** `OR <col> @> ?` (Lucid parity). See {@link whereJsonSupersetOf}. */
+	orWhereJsonSupersetOf(column: string, value: unknown): this {
+		return this.#pushJson("or", false, "superset", column, value);
+	}
+
+	/** `WHERE NOT (<col> @> ?)` (Lucid parity). */
+	whereNotJsonSupersetOf(column: string, value: unknown): this {
+		return this.#pushJson("and", true, "superset", column, value);
+	}
+
+	/** `OR NOT (<col> @> ?)` (Lucid parity). */
+	orWhereNotJsonSupersetOf(column: string, value: unknown): this {
+		return this.#pushJson("or", true, "superset", column, value);
+	}
+
+	/**
+	 * `WHERE <col> <@ ?` — the JSON column is contained in `value` (Lucid/Knex
+	 * `whereJsonSubsetOf`). Postgres/MySQL only; see {@link whereJsonSupersetOf}.
+	 */
+	whereJsonSubsetOf(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "subset", column, value);
+	}
+
+	/** Alias of {@link whereJsonSubsetOf} (Lucid parity). */
+	andWhereJsonSubsetOf(column: string, value: unknown): this {
+		return this.#pushJson("and", false, "subset", column, value);
+	}
+
+	/** `OR <col> <@ ?` (Lucid parity). See {@link whereJsonSubsetOf}. */
+	orWhereJsonSubsetOf(column: string, value: unknown): this {
+		return this.#pushJson("or", false, "subset", column, value);
+	}
+
+	/** `WHERE NOT (<col> <@ ?)` (Lucid parity). */
+	whereNotJsonSubsetOf(column: string, value: unknown): this {
+		return this.#pushJson("and", true, "subset", column, value);
+	}
+
+	/** `OR NOT (<col> <@ ?)` (Lucid parity). */
+	orWhereNotJsonSubsetOf(column: string, value: unknown): this {
+		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" | "equals",
+		column: string,
+		value: unknown,
+		path?: string,
+		operator?: string,
+	): this {
+		// 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
+		// start at the document root.
+		if (path !== undefined && !path.startsWith("$")) {
+			throw new Error(
+				`whereJsonPath: path '${path}' must start with '$' (e.g. '$.a.b' or '$.items[0]')`,
+			);
+		}
+		// Containment binds the value as JSON TEXT: `$1::jsonb` parses a string,
+		// and MySQL's JSON_CONTAINS takes a JSON document — a raw JS array bound
+		// as-is would not cast. A path comparison keeps its scalar value.
+		const bound =
+			jsonOp === "path"
+				? value
+				: typeof value === "string"
+					? value
+					: JSON.stringify(value);
+		this.#wheres.push({
+			type,
+			kind: "json",
+			jsonOp,
+			column: this.#resolveColumn(column),
+			negated,
+			path,
+			operator,
+			value: bound,
+		});
+		return this;
+	}
+
+	#pushExists(
+		type: "and" | "or",
+		negated: boolean,
+		subquery: ModelQuery<BaseEntity>,
+	): this {
+		// `#buildSpec` is private, but private access is per-class, not per
+		// instance: another ModelQuery's spec is reachable from here.
+		this.#wheres.push({
+			type,
+			kind: "exists",
+			negated,
+			subquery: subquery.#buildSpec(),
+		});
+		return this;
+	}
+
+	whereColumn(left: string, operator: string, right: string): this {
+		return this.#whereColumn("and", left, operator, right);
+	}
+
+	/** `OR`-combined {@link whereColumn}. */
+	orWhereColumn(left: string, operator: string, right: string): this {
+		return this.#whereColumn("or", left, operator, right);
+	}
+
+	/** `WHERE NOT (left <op> right)` — negation of {@link whereColumn} (Lucid parity). */
+	whereNotColumn(left: string, operator: string, right: string): this {
+		return this.#whereColumn("and", left, operator, right, true);
+	}
+
+	/** Alias of {@link whereNotColumn} (Lucid parity). */
+	andWhereNotColumn(left: string, operator: string, right: string): this {
+		return this.#whereColumn("and", left, operator, right, true);
+	}
+
+	/** `OR NOT (left <op> right)` (Lucid parity). */
+	orWhereNotColumn(left: string, operator: string, right: string): this {
+		return this.#whereColumn("or", left, operator, right, true);
+	}
+
+	#whereColumn(
+		type: "and" | "or",
+		left: string,
+		operator: string,
+		right: string,
+		negated = false,
+	): this {
+		if (!WHEREEXPR_OPERATORS.has(operator)) {
 			throw new Error(
 				`whereColumn: operator '${operator}' is not allowed. Use one of ${[...WHEREEXPR_OPERATORS].join(" ")}.`,
 			);
@@ -919,7 +2001,7 @@ export class ModelQuery<T extends BaseEntity> {
 		// `[table.]column` charset. This closes the injection surface regardless of
 		// what #resolveColumn returns (it can be an identity resolver on sub-queries).
 		const safe = (name: string): string => {
-			const resolved = this.#resolveColumn(name);
+			const resolved = this.#resolveColumnReference(name);
 			if (
 				!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(resolved)
 			) {
@@ -934,11 +2016,48 @@ export class ModelQuery<T extends BaseEntity> {
 				.map((part) => this.#quote(part))
 				.join(".");
 		};
-		const sql = `${safe(left)} ${operator} ${safe(right)}`;
+		const predicate = `${safe(left)} ${operator} ${safe(right)}`;
+		// Both operands are already validated identifiers and the operator is
+		// allow-listed, so wrapping in NOT(...) adds no new surface.
+		const sql = negated ? `NOT (${predicate})` : predicate;
 		this.#wheres.push({ type, kind: "raw", sql, bindings: [] });
 		return this;
 	}
 
+	/**
+	 * Resolve a column reference that may legitimately point at a table other
+	 * than this query's own.
+	 *
+	 * `#resolveColumn` only knows the entity's own columns, so it rejects
+	 * anything qualified. That is right for a value predicate, but wrong for a
+	 * column-to-column one: a correlated subquery
+	 * (`whereExists(post.query().whereColumn('posts.user_id', '=', 'users.id'))`)
+	 * and a joined query both have to name another table, and atlas cannot know
+	 * that table's columns. So: an unqualified name resolves as usual (typos
+	 * still get the helpful error), and a `table.column` naming a different
+	 * table passes through — validated against the identifier charset here and
+	 * quoted segment by segment by the caller, never interpolated loose. A typo
+	 * in that case surfaces as a database error rather than an atlas one, which
+	 * is the unavoidable cost of referencing a table we have no metadata for.
+	 */
+	#resolveColumnReference(name: string): string {
+		const qualified =
+			/^([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(name);
+		if (!qualified) return this.#resolveColumn(name);
+
+		const [, table, column] = qualified;
+		// Our own table: resolve the column half so `@Column({ columnName })` and
+		// the camel→snake convention still apply.
+		if (table === this.#tableName) {
+			return `${table}.${this.#resolveColumn(column as string)}`;
+		}
+		// Another table in scope (outer query or JOIN). Charset-checked by the
+		// regex above and quoted segment by segment by the caller — strict mode
+		// does not apply, since its concern is unvalidated SQL reaching the
+		// compiler and this identifier is validated.
+		return `${table}.${column}`;
+	}
+
 	/**
 	 * `WHERE EXISTS (SELECT * FROM related WHERE <join> AND <cb>)` — filter parent rows
 	 * by the existence of related rows, optionally constrained by a callback.
@@ -987,6 +2106,22 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
+	/** Alias of {@link whereHas} (Lucid parity) — `whereHas` is already AND. */
+	andWhereHas(
+		relationName: string,
+		callback?: (query: ModelQuery<BaseEntity>) => void,
+	): this {
+		return this.whereHas(relationName, callback);
+	}
+
+	/** Alias of {@link whereDoesntHave} (Lucid parity). */
+	andWhereDoesntHave(
+		relationName: string,
+		callback?: (query: ModelQuery<BaseEntity>) => void,
+	): this {
+		return this.whereDoesntHave(relationName, callback);
+	}
+
 	/**
 	 * Short form of `whereHas`. With an operator + count, emits a count threshold:
 	 *   has('comments')          → EXISTS (SELECT * FROM comments WHERE <join>)
@@ -1026,6 +2161,26 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
+	/** `OR NOT EXISTS (...)` — the OR form of {@link doesntHave} (Lucid parity). */
+	orDoesntHave(relationName: string): this {
+		this.#wheres.push(this.#buildExistsClause("or", true, relationName));
+		return this;
+	}
+
+	/** Alias of {@link has} (Lucid parity) — `has` is already AND. */
+	andHas(
+		relationName: string,
+		countOp?: string,
+		countThreshold?: number,
+	): this {
+		return this.has(relationName, countOp, countThreshold);
+	}
+
+	/** Alias of {@link doesntHave} (Lucid parity). */
+	andDoesntHave(relationName: string): this {
+		return this.doesntHave(relationName);
+	}
+
 	/**
 	 * Set this query's projection alias — only meaningful when this ModelQuery
 	 * is used as the sub-builder callback argument of `withCount` / `withAggregate`.
@@ -1070,27 +2225,37 @@ export class ModelQuery<T extends BaseEntity> {
 	/** `SELECT COUNT(col)` — executes and returns the scalar. `col` defaults to `*`. */
 	async count(column: string = "*"): Promise<number> {
 		const expr =
-			column === "*" ? "COUNT(*)" : `COUNT(${this.#quoteCol(column)})`;
+			column === "*"
+				? "COUNT(*)"
+				: `COUNT(${this.#quoteCol(this.#resolveColumn(column))})`;
 		return Number((await this.#runScalar(expr)) ?? 0);
 	}
 
 	async sum(column: string): Promise<number | null> {
-		const v = await this.#runScalar(`SUM(${this.#quoteCol(column)})`);
+		const v = await this.#runScalar(
+			`SUM(${this.#quoteCol(this.#resolveColumn(column))})`,
+		);
 		return v === null || v === undefined ? null : Number(v);
 	}
 
 	async avg(column: string): Promise<number | null> {
-		const v = await this.#runScalar(`AVG(${this.#quoteCol(column)})`);
+		const v = await this.#runScalar(
+			`AVG(${this.#quoteCol(this.#resolveColumn(column))})`,
+		);
 		return v === null || v === undefined ? null : Number(v);
 	}
 
 	async min(column: string): Promise<number | null> {
-		const v = await this.#runScalar(`MIN(${this.#quoteCol(column)})`);
+		const v = await this.#runScalar(
+			`MIN(${this.#quoteCol(this.#resolveColumn(column))})`,
+		);
 		return v === null || v === undefined ? null : Number(v);
 	}
 
 	async max(column: string): Promise<number | null> {
-		const v = await this.#runScalar(`MAX(${this.#quoteCol(column)})`);
+		const v = await this.#runScalar(
+			`MAX(${this.#quoteCol(this.#resolveColumn(column))})`,
+		);
 		return v === null || v === undefined ? null : Number(v);
 	}
 
@@ -1140,37 +2305,172 @@ 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;
+	}
+
+	/**
+	 * `ORDER BY <raw fragment>` (Lucid/Knex `orderByRaw`) — for orderings with
+	 * no typed form: `NULLS LAST`, `RANDOM()`, a CASE expression, a computed
+	 * alias.
+	 *
+	 *     query.orderBy('rank').orderByRaw('created_at DESC NULLS LAST')
+	 *
+	 * The fragment keeps its position among the plain `orderBy` terms.
+	 *
+	 * **Strict mode**: like {@link whereRaw}, this throws when
+	 * `setAtlasStrictMode(true)` (or `ATLAS_STRICT`) is on.
+	 *
+	 * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+	 */
+	orderByRaw(sql: string): this {
+		this.#assertRawAllowed("orderByRaw");
+		this.#orderBys.push({ raw: sql });
 		return this;
 	}
 
 	/**
 	 * `GROUP BY col1, col2, …` (AdonisJS/Lucid `groupBy`). Columns are resolved
 	 * through the entity's column map (camelCase → snake_case) like `orderBy`.
-	 * For a raw grouping expression, use a `whereRaw`-style construct via the
-	 * fluent {@link QueryBuilder}.
+	 * For a grouping expression with no typed form, see {@link groupByRaw}.
 	 */
 	groupBy(...columns: string[]): this {
 		for (const c of columns) this.#groupBy.push(this.#resolveColumn(c));
 		return this;
 	}
 
+	/**
+	 * `GROUP BY <raw fragment>` (Lucid/Knex `groupByRaw`) — for groupings with
+	 * no typed form, e.g. `DATE_TRUNC('day', created_at)`.
+	 *
+	 * The fragment keeps its position among the plain `groupBy` terms.
+	 *
+	 * **Strict mode**: like {@link whereRaw}, this throws when
+	 * `setAtlasStrictMode(true)` (or `ATLAS_STRICT`) is on.
+	 *
+	 * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+	 */
+	groupByRaw(sql: string): this {
+		this.#assertRawAllowed("groupByRaw");
+		this.#groupBy.push({ raw: sql });
+		return this;
+	}
+
 	/**
 	 * `HAVING <col> <op> ?` — applied after `groupBy` (AdonisJS/Lucid `having`).
-	 * The column is passed verbatim to the Rust HAVING compiler, which quotes a
-	 * plain identifier or accepts an allow-listed aggregate expression
-	 * (`COUNT(*)`, `SUM(col)`, …) — it is NOT run through the entity column map,
-	 * so aggregate expressions and result aliases both work.
+	 * A bare model property is resolved through the entity column map (honouring
+	 * `@Column({ columnName })`) via {@link #resolveHavingCol}; an aggregate
+	 * expression (`COUNT(*)`, `SUM(col)`, …) or a result alias is left verbatim so
+	 * `having` can still reference `withCount`/`withAggregate` aliases.
 	 */
 	having(column: string, operator: string, value: unknown): this {
-		this.#having.push({ column, operator, value, type: "and" });
+		this.#having.push({
+			column: this.#resolveHavingCol(column),
+			operator,
+			value: this.#prep(column, value),
+			type: "and",
+		});
 		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
+	 * (`COUNT(*)`), a result alias, or any unknown bare identifier is left verbatim
+	 * so `having` can still reference `withCount`/`withAggregate` aliases.
+	 */
+	#resolveHavingCol(column: string): string {
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(column)) return column;
+		try {
+			return this.#resolveColumn(column);
+		} catch {
+			return column;
+		}
+	}
+
 	/** `OR HAVING <col> <op> ?` — OR-combined {@link having}. */
 	orHaving(column: string, operator: string, value: unknown): this {
-		this.#having.push({ column, operator, value, type: "or" });
+		this.#having.push({
+			column: this.#resolveHavingCol(column),
+			operator,
+			value: this.#prep(column, value),
+			type: "or",
+		});
 		return this;
 	}
 
@@ -1183,6 +2483,14 @@ export class ModelQuery<T extends BaseEntity> {
 	 * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
 	 */
 	havingRaw(sql: string, bindings: readonly unknown[] = []): this {
+		// Same strict-mode gate as whereRaw()/joinRaw() — havingRaw is a raw-SQL
+		// surface, so prod hardening must be able to neutralise it too.
+		if (isAtlasStrictMode() && !isInternalBypass()) {
+			throw new Error(
+				"havingRaw() is disabled in Atlas strict mode. " +
+					"Use having(column, operator, value) instead.",
+			);
+		}
 		this.#having.push({
 			kind: "raw",
 			sql,
@@ -1197,27 +2505,161 @@ 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: UnionArg): this {
+		this.#unions.push({
+			query: this.#resolveUnion(query),
+			all: false,
+			op: "intersect",
+		});
+		return this;
+	}
+
+	/**
+	 * `INTERSECT ALL (<query>)` — duplicate-preserving {@link intersect}.
+	 *
+	 * Postgres and MySQL only: SQLite's compound operators are UNION, UNION ALL,
+	 * INTERSECT and EXCEPT — there is no INTERSECT ALL — so the compiler raises
+	 * `E_UNSUPPORTED` there rather than emitting a syntax error.
+	 */
+	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: 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: 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, {});
+	}
+
+	/**
+	 * `WITH RECURSIVE <name> AS (<query>)` — a self-referencing CTE
+	 * (Lucid/Knex `withRecursive`), for trees and graph walks.
+	 *
+	 * RECURSIVE is a property of the WITH clause rather than of one CTE, so a
+	 * single recursive entry makes the whole clause recursive — which is what
+	 * all three dialects require. Mixing `with()` and `withRecursive()` is fine.
+	 *
+	 * 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: UnionArg, columns?: string[]): this {
+		return this.#pushCte("withRecursive", name, query, {
+			recursive: true,
+			columns,
+		});
+	}
+
+	/**
+	 * `WITH <name> AS MATERIALIZED (<query>)` — force the CTE to be evaluated
+	 * once and stashed (Lucid/Knex `withMaterialized`).
+	 *
+	 * 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: 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: UnionArg): this {
+		return this.#pushCte("withNotMaterialized", name, query, {
+			materialized: false,
+		});
+	}
+
+	#pushCte(
+		method: string,
+		name: string,
+		query: UnionArg,
+		options: {
+			recursive?: boolean;
+			materialized?: boolean;
+			columns?: string[];
+		},
+	): this {
 		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
-			throw new Error(`with(): CTE name '${name}' is not a valid identifier`);
+			throw new Error(
+				`${method}(): CTE name '${name}' is not a valid identifier`,
+			);
 		}
-		this.#ctes.push({ name, query });
+		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;
 	}
 
@@ -1232,21 +2674,180 @@ export class ModelQuery<T extends BaseEntity> {
 	wherePivot(column: string, value: unknown): this;
 	wherePivot(column: string, operator: string, value: unknown): this;
 	wherePivot(column: string, operatorOrValue: unknown, value?: unknown): this {
+		return this.#pushPivot("and", column, operatorOrValue, value);
+	}
+
+	/** Alias of {@link wherePivot} (Lucid parity) — pivot filters already AND together. */
+	andWherePivot(column: string, value: unknown): this;
+	andWherePivot(column: string, operator: string, value: unknown): this;
+	andWherePivot(
+		column: string,
+		operatorOrValue: unknown,
+		value?: unknown,
+	): this {
+		return this.#pushPivot("and", column, operatorOrValue, value);
+	}
+
+	/**
+	 * `@ManyToMany` only — OR form of {@link wherePivot} (Lucid parity).
+	 *
+	 * The pivot filters are compiled as a parenthesised group, so an OR joins
+	 * the other pivot filters and cannot escape the `pivot_fk IN (parents)`
+	 * scoping that makes the preload correct.
+	 */
+	orWherePivot(column: string, value: unknown): this;
+	orWherePivot(column: string, operator: string, value: unknown): this;
+	orWherePivot(
+		column: string,
+		operatorOrValue: unknown,
+		value?: unknown,
+	): this {
+		return this.#pushPivot("or", column, operatorOrValue, value);
+	}
+
+	/** `@ManyToMany` only — `WHERE <pivotCol> IN (...)` on the pivot table (AdonisJS Lucid `whereInPivot`). */
+	whereInPivot(column: string, values: readonly unknown[]): this {
+		return this.#pushPivotOp("and", column, "IN", [...values]);
+	}
+
+	/** Alias of {@link whereInPivot} (Lucid parity). */
+	andWhereInPivot(column: string, values: readonly unknown[]): this {
+		return this.#pushPivotOp("and", column, "IN", [...values]);
+	}
+
+	/** `@ManyToMany` only — OR form of {@link whereInPivot} (Lucid parity). */
+	orWhereInPivot(column: string, values: readonly unknown[]): this {
+		return this.#pushPivotOp("or", column, "IN", [...values]);
+	}
+
+	/** Alias of {@link whereInPivot} kept for the earlier atlas name. */
+	wherePivotIn(column: string, values: readonly unknown[]): this {
+		return this.whereInPivot(column, values);
+	}
+
+	/**
+	 * `@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) {
-			this.#pivotWheres.push({ column, operator: "=", value: operatorOrValue });
-		} else {
-			this.#pivotWheres.push({
-				column,
-				operator: operatorOrValue as string,
-				value,
-			});
+			return this.#pushPivotOp("and", column, "!=", operatorOrValue);
 		}
-		return this;
+		return this.#pushPivotOp(
+			"and",
+			column,
+			negateOperator(String(operatorOrValue)),
+			value,
+		);
 	}
 
-	/** `@ManyToMany` only — `WHERE <pivotCol> IN (...)` on the pivot table (Lucid `wherePivotIn`). */
-	wherePivotIn(column: string, values: readonly unknown[]): this {
-		this.#pivotWheres.push({ column, operator: "IN", value: [...values] });
+	/** 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;
+	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`). */
+	whereNotInPivot(column: string, values: readonly unknown[]): this {
+		return this.#pushPivotOp("and", column, "NOT IN", [...values]);
+	}
+
+	/** Alias of {@link whereNotInPivot} (Lucid parity). */
+	andWhereNotInPivot(column: string, values: readonly unknown[]): this {
+		return this.#pushPivotOp("and", column, "NOT IN", [...values]);
+	}
+
+	/** `@ManyToMany` only — OR form of {@link whereNotInPivot} (Lucid parity). */
+	orWhereNotInPivot(column: string, values: readonly unknown[]): this {
+		return this.#pushPivotOp("or", column, "NOT IN", [...values]);
+	}
+
+	/** `@ManyToMany` only — `WHERE <pivotCol> IS NULL` on the pivot table (Lucid `whereNullPivot`). */
+	whereNullPivot(column: string): this {
+		return this.#pushPivotOp("and", column, "IS NULL", null);
+	}
+
+	/** Alias of {@link whereNullPivot} (Lucid parity). */
+	andWhereNullPivot(column: string): this {
+		return this.#pushPivotOp("and", column, "IS NULL", null);
+	}
+
+	/** `@ManyToMany` only — OR form of {@link whereNullPivot} (Lucid parity). */
+	orWhereNullPivot(column: string): this {
+		return this.#pushPivotOp("or", column, "IS NULL", null);
+	}
+
+	/** `@ManyToMany` only — `WHERE <pivotCol> IS NOT NULL` on the pivot table (Lucid `whereNotNullPivot`). */
+	whereNotNullPivot(column: string): this {
+		return this.#pushPivotOp("and", column, "IS NOT NULL", null);
+	}
+
+	/** Alias of {@link whereNotNullPivot} (Lucid parity). */
+	andWhereNotNullPivot(column: string): this {
+		return this.#pushPivotOp("and", column, "IS NOT NULL", null);
+	}
+
+	/** `@ManyToMany` only — OR form of {@link whereNotNullPivot} (Lucid parity). */
+	orWhereNotNullPivot(column: string): this {
+		return this.#pushPivotOp("or", column, "IS NOT NULL", null);
+	}
+
+	/** Shared `(column, value)` / `(column, operator, value)` overload split for the pivot filters. */
+	#pushPivot(
+		type: "and" | "or",
+		column: string,
+		operatorOrValue: unknown,
+		value?: unknown,
+	): this {
+		return value === undefined
+			? this.#pushPivotOp(type, column, "=", operatorOrValue)
+			: this.#pushPivotOp(type, column, operatorOrValue as string, value);
+	}
+
+	#pushPivotOp(
+		type: "and" | "or",
+		column: string,
+		operator: string,
+		value: unknown,
+	): this {
+		this.#pivotWheres.push({ column, operator, value, type });
 		return this;
 	}
 
@@ -1255,10 +2856,16 @@ export class ModelQuery<T extends BaseEntity> {
 		column: string;
 		operator: string;
 		value: unknown;
+		type: "and" | "or";
 	}> {
 		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
@@ -1271,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}`);
@@ -1341,21 +2968,99 @@ export class ModelQuery<T extends BaseEntity> {
 	}
 
 	/** Build the spec object that gets sent to the Rust compiler. Extracted so whereHas can reuse it for sub-queries. */
+	/**
+	 * DB column backing the soft-delete `deletedAt` property — honours a
+	 * `@Column({ columnName })` override, read straight from the entity metadata
+	 * (not the resolver callback, which is identity for subqueries/preloads).
+	 */
+	#deletedAtColumn(): string {
+		const col = this.#entityClass
+			? getColumnMetadata(this.#entityClass).find(
+					(c) => c.propertyKey === "deletedAt",
+				)
+			: undefined;
+		return col?.columnName ?? "deleted_at";
+	}
+
 	#buildSpec(): SelectSpec {
+		// `SKIP LOCKED` / `NOWAIT` are meaningless without a base row lock — and the
+		// compiler emits the lock clause only when a base mode is set, so a lone
+		// modifier would be a SILENT no-op (dangerous for job-queue polling that
+		// believes it skips locked rows). Fail loud instead. Order-independent: this
+		// fires whether the modifier was chained before or after the base lock.
+		if (this.#lockModifier && !this.#lockMode) {
+			throw new Error(
+				`${this.#lockModifier} requires a base row lock — call forUpdate()/forShare()/forNoKeyUpdate()/forKeyShare() as well (a modifier alone emits no lock at all).`,
+			);
+		}
+		// With a JOIN and the default `SELECT *`, scope the projection to the base
+		// table's declared columns so joined columns can't clobber the model's fields
+		// (e.g. `users.id` overwriting `orders.id`) and corrupt the hydrated entity —
+		// AdonisJS/Lucid selects the model's own columns. Explicit `select()` wins.
+		let selectCols = this.#select;
+		if (
+			this.#joins.length > 0 &&
+			this.#select.length === 1 &&
+			this.#select[0] === "*"
+		) {
+			const cols = getColumnMetadata(this.#entityClass).map(
+				(c) =>
+					`${this.#tableName}.${c.columnName ?? camelToSnake(c.propertyKey)}`,
+			);
+			if (cols.length > 0) selectCols = cols;
+		} else if (
+			!(selectCols.length === 1 && selectCols[0] === "*") &&
+			selectCols.every((c) => /^[A-Za-z_][A-Za-z0-9_.]*$/.test(c))
+		) {
+			// A partial `select()` of PLAIN columns that omits the primary key would
+			// hydrate a persisted entity with no PK — a later save() would then INSERT
+			// instead of UPDATE (double-write / unique violation / spurious
+			// beforeCreate). Auto-include the (base-table-qualified) PK so model
+			// entities stay saveable. Aggregate/alias/expression selects are left
+			// untouched — use `.pojo()` for those.
+			const pkProp = getPrimaryKey(this.#entityClass);
+			if (pkProp) {
+				const pkCol =
+					getColumnMetadata(this.#entityClass).find(
+						(c) => c.propertyKey === pkProp,
+					)?.columnName ?? camelToSnake(pkProp);
+				// The PK counts as present ONLY as the bare column or the BASE-table-
+				// qualified column. A joined `other.id` must NOT satisfy it (its leaf
+				// collides with the PK name but it's a different table's row) — otherwise
+				// we'd skip adding `base.id` and hydrate the wrong PK, corrupting a later
+				// save(). Appended last, `base.id` also wins the duplicate result key
+				// (rows collect in column order, last-wins) so the base row's PK hydrates.
+				const baseQualifiedPk = `${this.#tableName}.${pkCol}`;
+				if (!selectCols.some((c) => c === pkCol || c === baseQualifiedPk)) {
+					selectCols = [...selectCols, baseQualifiedPk];
+				}
+			}
+		}
 		const wheres: WhereClause[] = [...this.#wheres];
-		// Auto-apply soft-delete scope when the entity opts in via @SoftDeletes
+		// Lazy m2m `related().query()`: emit the pivot EXISTS now, folding in any
+		// `.wherePivot()` recorded since the proxy handed back this query (pushed to
+		// the LOCAL copy so repeated #buildSpec calls — count, subquery — don't stack).
+		if (this.#pivotExists) {
+			const { sql, bindings } = this.#pivotExists(this.#pivotWheres);
+			wheres.push({ type: "and", kind: "raw", sql, bindings: [...bindings] });
+		}
+		// Auto-apply soft-delete scope when the entity opts in via @SoftDeletes.
+		// Resolve `deletedAt` through the column resolver so a `@Column({ columnName })`
+		// override on the soft-delete column is honoured on the read side too — matching
+		// the write side (delete/restore go through #dbColumn).
 		if (this.#softDeletes) {
+			const deletedAtCol = this.#deletedAtColumn();
 			if (this.#softScope === "default") {
 				wheres.push({
 					type: "and",
-					column: "deleted_at",
+					column: deletedAtCol,
 					operator: "IS NULL",
 					value: null,
 				});
 			} else if (this.#softScope === "only-trashed") {
 				wheres.push({
 					type: "and",
-					column: "deleted_at",
+					column: deletedAtCol,
 					operator: "IS NOT NULL",
 					value: null,
 				});
@@ -1366,8 +3071,9 @@ export class ModelQuery<T extends BaseEntity> {
 		return {
 			kind: "select",
 			table: this.#tableName,
-			select: this.#select,
+			select: selectCols,
 			selectSubqueries: this.#selectSubqueries,
+			selectRaw: this.#selectRaw,
 			wheres,
 			orderBy: this.#orderBys,
 			groupBy: this.#groupBy,
@@ -1375,23 +3081,148 @@ export class ModelQuery<T extends BaseEntity> {
 			limit: this.#limit ?? null,
 			offset: this.#offset ?? null,
 			distinct: this.#distinct,
-			ctes: this.#ctes.map((c) => {
-				const { sql, params } = c.query.toSQL();
-				return { name: c.name, sql, params };
-			}),
+			distinctOn: this.#distinctOn,
+			ctes: this.#compiledCtes(),
 			unions: this.#unions.map((u) => {
-				const { sql, params } = u.query.toSQL();
-				return { sql, params, all: u.all };
+				const { sql, params } = u.query.#compiledNative();
+				return { sql, params, all: u.all, op: u.op ?? null };
 			}),
 			joins: this.#joins,
-			lockMode: this.#lockMode,
+			lockMode: this.#lockMode
+				? this.#lockModifier
+					? `${this.#lockMode} ${this.#lockModifier}`
+					: this.#lockMode
+				: null,
 		};
 	}
 
-	/** 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(" ")} `
+			: "";
 	}
 
 	/**
@@ -1419,8 +3250,10 @@ 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);
+		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.
 		const extraKeys = this.#selectSubqueries.map((s) => s.alias);
@@ -1434,6 +3267,8 @@ export class ModelQuery<T extends BaseEntity> {
 			}
 			const entity = this.#hydrateFn(row);
 			for (const [k, v] of Object.entries(picked)) entity.setExtra(k, v);
+			// Thread query-level sideloaded context onto each hydrated instance.
+			if (this.#sideloaded) entity.$sideloaded = { ...this.#sideloaded };
 			return entity;
 		});
 
@@ -1442,9 +3277,42 @@ 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;
 	}
 
+	/**
+	 * Execute and return PLAIN row objects (raw snake_case DB columns), skipping
+	 * model hydration, `@column({ consume })`, dirty-tracking and preloads —
+	 * AdonisJS Lucid `pojo()`. Fast read path for reports/exports where model
+	 * instances aren't needed.
+	 */
+	async pojo<R = Record<string, unknown>>(): Promise<R[]> {
+		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. 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>, merge = false): this {
+		this.#sideloaded = merge
+			? { ...this.#sideloaded, ...values }
+			: { ...values };
+		return this;
+	}
+
 	/** Resolve preloaded relations via batched subqueries (no N+1). */
 	async #resolvePreloads(entities: T[]): Promise<void> {
 		if (!this.#entityClass) return;
@@ -1463,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);
 		}
 	}
@@ -1473,33 +3349,98 @@ export class ModelQuery<T extends BaseEntity> {
 		relationName: string,
 	): PreloadContext | null {
 		const relatedClass = relation.target() as new () => BaseEntity;
-		const relatedMeta = getEntityMetadata(relatedClass);
-		if (!relatedMeta) return null;
+		// Boot the related model's metadata on demand (Lucid parity): a preload
+		// must not silently no-op just because the related class hasn't been
+		// touched yet elsewhere. ensureEntityMetadata synthesizes @Entity from the
+		// static table / naming strategy when the decorator hasn't run.
+		const relatedMeta = ensureEntityMetadata(relatedClass);
 
 		// Resolve row keys against declared column metadata, NOT `in entity` —
 		// 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`.
+		const byDbName = new Map<string, string>();
+		// Capture the related model's `@Column({ consume })` adapters + its date
+		// columns so preloaded rows hydrate identically to a direct query — dates
+		// become Chronos DateTime, decimal/etc adapters run. Without this, a
+		// preloaded relation left column values raw (Lucid parity bug + a runtime
+		// footgun for getters/serializers/hooks). Mirrors BaseRepository.#applyConsume.
+		const consumes = new Map<
+			string,
+			(v: unknown, attribute?: string, model?: unknown) => unknown
+		>();
+		let relatedPkDb = camelToSnake(relatedPkName);
 		for (const col of getColumnMetadata(relatedClass)) {
+			const db = col.columnName ?? camelToSnake(col.propertyKey);
 			validColumns.add(col.propertyKey);
-			validColumns.add(camelToSnake(col.propertyKey));
+			validColumns.add(db);
+			byDbName.set(db, col.propertyKey);
+			if (col.consume) consumes.set(col.propertyKey, col.consume);
+			// The related PK may be multi-word (postId→post_id) or columnName-mapped;
+			// its DB column name is what the WHERE + row indexing must use.
+			if (col.propertyKey === relatedPkName) relatedPkDb = db;
 		}
 		validColumns.add(relatedPkName);
 		validColumns.add(camelToSnake(relatedPkName));
+		const dateCols = getDateColumnConfig(relatedClass);
+		const consumeValue = (
+			prop: string,
+			value: unknown,
+			model?: unknown,
+		): unknown => {
+			const c = consumes.get(prop);
+			// Adonis Lucid signature: (value, attribute, model).
+			if (c) return c(value, prop, model);
+			if (dateCols[prop] && value != null)
+				return dateTimeAtlasAdapter.consume(value);
+			return value;
+		};
 
+		// A repository for the related model so preloaded instances are hydrated with
+		// the SAME lifecycle state as a direct query: `$isPersisted`/not-`$isNew`,
+		// not-`$isLocal`, a clean dirty snapshot, and a REPO_REF backing
+		// refresh()/fresh()/load()/related(). Without this a preloaded relation
+		// looked $isNew/$isLocal/$dirty and a later save() over-updated it.
+		const relatedRepo = new BaseRepository(relatedClass, this.#db, {
+			dialect: this.#dialect,
+		});
+		// Propagate the domain-event bus so save()/create() from a preloaded relation
+		// still dispatch events (a fresh repo has none by default).
+		relatedRepo.onDomainEvents = this.#onDomainEvents;
 		const hydrate = (row: Record<string, unknown>): BaseEntity => {
 			const entity = new relatedClass();
 			for (const [key, value] of Object.entries(row)) {
 				const camelKey = snakeToCamel(key);
-				const targetKey = validColumns.has(camelKey)
-					? camelKey
-					: validColumns.has(key)
-						? key
-						: null;
-				if (targetKey !== null) entity.setProp(targetKey, value);
+				const targetKey =
+					byDbName.get(key) ??
+					(validColumns.has(camelKey)
+						? camelKey
+						: validColumns.has(key)
+							? key
+							: null);
+				if (targetKey !== null)
+					entity.setProp(targetKey, consumeValue(targetKey, value, entity));
 			}
+			// Freeze the clean snapshot + mark persisted/from-DB, and back-reference
+			// the related repo (mirrors BaseRepository.#hydrate).
+			entity.markAsPersisted();
+			entity.markAsFromDatabase();
+			Object.defineProperty(entity, REPO_REF, {
+				value: relatedRepo,
+				enumerable: false,
+				configurable: true,
+			});
 			return entity;
 		};
 
@@ -1508,7 +3449,9 @@ export class ModelQuery<T extends BaseEntity> {
 			relationName,
 			relatedClass,
 			relatedTable: relatedMeta.tableName,
-			relatedPk: getPrimaryKey(relatedClass) ?? "id",
+			// DB column name (not property) — used as the WHERE column in the related
+			// query AND to index the returned DB rows by their PK value.
+			relatedPk: relatedPkDb,
 			hydrate,
 			runInQuery: (table, column, values) =>
 				this.#runInQuery(table, column, values),
@@ -1570,11 +3513,7 @@ export class ModelQuery<T extends BaseEntity> {
 			);
 		}
 		const throughClass = relation.through() as new () => BaseEntity;
-		const throughMeta = getEntityMetadata(throughClass);
-		if (!throughMeta)
-			throw new Error(
-				`Entity metadata missing on through class ${throughClass.name}`,
-			);
+		const throughMeta = ensureEntityMetadata(throughClass);
 		const throughTable = throughMeta.tableName;
 		const throughPk = getPrimaryKey(throughClass) ?? "id";
 		const parentLocal =
@@ -1583,7 +3522,13 @@ export class ModelQuery<T extends BaseEntity> {
 			relation.firstKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 		const secondKey =
 			relation.secondKey ?? `${camelToSnake(throughClass.name)}_id`;
-		const secondLocal = relation.secondLocalKey ?? throughPk;
+		// secondLocal indexes the THROUGH row (`row[secondLocal]`), so it must be a
+		// DB column — resolve the through model's key (default: its PK), honouring a
+		// multi-word / columnName PK. (parentLocal stays a property: it's read off
+		// the parent ENTITY, not a row.)
+		const secondLocal = buildColumnResolver(throughClass)(
+			relation.secondLocalKey ?? throughPk,
+		);
 
 		const parentIds = entities
 			.map((e) => e[parentLocal])
@@ -1752,7 +3697,11 @@ export class ModelQuery<T extends BaseEntity> {
 			pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 		const otherKey =
 			pivot.otherKey ?? `${camelToSnake(ctx.relatedClass.name)}_id`;
-		const pk = getPrimaryKey(this.#entityClass) ?? "id";
+		// The pivot FK stores `parent[localKey]` (default PK) — attach() writes it,
+		// so preload MUST read back with the SAME key, else a custom-localKey m2m
+		// writes `user_code = code` but reads `user_code IN (id)` and never matches.
+		const pk =
+			ctx.relation.localKey ?? getPrimaryKey(this.#entityClass) ?? "id";
 
 		const ids = entities.map((e) => e[pk]).filter((v) => v != null);
 		if (ids.length === 0) return [];
@@ -1766,18 +3715,49 @@ 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,
 				this.#db,
 				(r) => r as BaseEntity,
 				ctx.relatedClass,
-				(c) => c,
+				buildColumnResolver(ctx.relatedClass),
 				false,
 				this.#dialect,
+				buildValuePreparer(ctx.relatedClass),
 			);
 			ctx.nestedCallback(scratch);
-			for (const c of scratch.pivotConstraints) pivotWheres.push({ ...c });
+			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).
+			const pivotAdapters = pivot.pivotColumnAdapters ?? {};
+			for (const c of scratch.pivotConstraints) {
+				const prep = pivotAdapters[c.column]?.prepare;
+				// Same guards as the attach()/sync() write path: wrap a throwing
+				// adapter with a column-annotated error and reject async adapters,
+				// so filter and write agree on the adapter contract.
+				const apply = (v: unknown): unknown => {
+					if (!prep) return v;
+					let out: unknown;
+					try {
+						// Adonis Lucid signature: (value, attribute, model). wherePivot is
+						// a query filter — attribute known, no model instance.
+						out = prep(v, c.column, undefined);
+					} catch (err) {
+						throw wrapAdapterError("prepare", c.column, err);
+					}
+					assertNotPromise("prepare", c.column, out);
+					return out;
+				};
+				const value = Array.isArray(c.value)
+					? c.value.map(apply)
+					: apply(c.value);
+				pivotWheres.push({ ...c, value });
+			}
 		}
 
 		// Step 1 — pivot table: find (foreignKey → otherKey) pairs (+ wherePivot)
@@ -1797,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
@@ -1830,7 +3814,8 @@ export class ModelQuery<T extends BaseEntity> {
 					const adapter = pivotAdapters[col];
 					related.setExtra(
 						`pivot_${col}`,
-						adapter?.consume ? adapter.consume(rawVal) : rawVal,
+						// Adonis Lucid signature: (value, attribute, model).
+						adapter?.consume ? adapter.consume(rawVal, col, related) : rawVal,
 					);
 				}
 				allRelated.push(related);
@@ -1860,6 +3845,10 @@ export class ModelQuery<T extends BaseEntity> {
 			this.#db,
 			(r) => ctx.hydrate(r),
 			ctx.relatedClass,
+			buildColumnResolver(ctx.relatedClass),
+			hasSoftDeletes(ctx.relatedClass),
+			this.#dialect,
+			buildValuePreparer(ctx.relatedClass),
 		);
 		ctx.nestedCallback(sub);
 		if (sub.#preloads.size > 0) {
@@ -1876,17 +3865,28 @@ export class ModelQuery<T extends BaseEntity> {
 			column: string;
 			operator: string;
 			value: unknown;
+			type?: "and" | "or";
 		}> = [],
 	): Promise<Record<string, unknown>[]> {
 		const wheres: Array<Record<string, unknown>> = [
 			{ column, operator: "IN", value: values, type: "and" },
 		];
-		for (const w of extraWheres) {
+		// The caller's filters go in a parenthesised group, never flat beside the
+		// `IN`. Flat, an `orWherePivot` would read as
+		// `WHERE fk IN (parents) OR active = 1` and hand back rows belonging to
+		// other parents; grouped, it is `WHERE fk IN (parents) AND (… OR …)`.
+		// With every filter ANDed the two forms are equivalent, so this changes
+		// no existing query.
+		if (extraWheres.length > 0) {
 			wheres.push({
-				column: w.column,
-				operator: w.operator,
-				value: w.value,
+				kind: "group",
 				type: "and",
+				conditions: extraWheres.map((w) => ({
+					column: w.column,
+					operator: w.operator,
+					value: w.value,
+					type: w.type ?? "and",
+				})),
 			});
 		}
 		const spec = {
@@ -1937,7 +3937,10 @@ export class ModelQuery<T extends BaseEntity> {
 			this.#db,
 			(row) => row as BaseEntity,
 			relatedClass,
-			(c) => c,
+			// Resolve columns + prepare values against the RELATED model so a preload
+			// constraint (onQuery / callback) targeting a columnName-mapped or date
+			// column compiles/binds like a direct query on that model.
+			buildColumnResolver(relatedClass),
 			// Propagate the RELATED entity's soft-delete flag — hardcoding
 			// false here meant `preload('posts')` returned soft-deleted
 			// posts even when Post is @SoftDeletes (a data leak). The
@@ -1947,14 +3950,63 @@ export class ModelQuery<T extends BaseEntity> {
 			// preload callback.)
 			hasSoftDeletes(relatedClass),
 			this.#dialect,
+			buildValuePreparer(relatedClass),
 		);
 		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'`
@@ -1995,30 +4047,46 @@ export class ModelQuery<T extends BaseEntity> {
 			);
 		}
 		const relatedClass = relation.target() as new () => BaseEntity;
-		const relatedMeta = getEntityMetadata(relatedClass);
-		if (!relatedMeta) {
-			throw new Error(
-				`Entity metadata missing on related class ${relatedClass.name}`,
-			);
-		}
+		const relatedMeta = ensureEntityMetadata(relatedClass);
 		const relatedTable = relatedMeta.tableName;
 		const parentPk = getPrimaryKey(this.#entityClass) ?? "id";
 		const parentTable = this.#tableName;
-		const q =
-			this.#dialect === "mysql"
-				? (name: string) => `\`${name}\``
-				: (name: string) => `"${name}"`;
+		// Strict single-segment identifier quote. This builds a RAW correlated
+		// subquery fragment (no bind params for identifiers), so every segment must
+		// be validated — a table/key from relation metadata carrying a quote/backtick
+		// would otherwise emit invalid or injectable SQL. Same policy as
+		// BaseRepository's lazy m2m path.
+		const q = (name: string): string => {
+			if (!/^[A-Za-z0-9_]+$/.test(name)) {
+				throw new Error(`Unsafe identifier in relation metadata: '${name}'`);
+			}
+			return this.#dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
+		};
+		// Table identifiers may be schema-qualified (`schema.table`) — quote each
+		// dotted segment on its own (`"schema"."table"`), else a Postgres pivot like
+		// `public.users_roles` gets wrapped as ONE identifier and silently targets a
+		// table literally named with a dot. Each segment still passes the strict
+		// guard above. Columns stay single-segment via `q`.
+		const qTable = (name: string): string => name.split(".").map(q).join(".");
 
 		const sub = new ModelQuery<BaseEntity>(
 			relatedTable,
 			this.#db,
 			(row) => row as BaseEntity,
 			relatedClass,
-			(c) => c,
+			// whereHas/withCount constraints run against the RELATED model — resolve
+			// its columns (columnName/multi-word) and prepare its values like a direct query.
+			buildColumnResolver(relatedClass),
 			false,
 			this.#dialect,
+			buildValuePreparer(relatedClass),
 		);
 
+		// `localKey`/`ownerKey`/`secondLocalKey` are MODEL properties (default to a
+		// PK); resolve each to its DB column via the owning model so a multi-word or
+		// `@Column({ columnName })` key produces valid SQL. `foreignKey`/`otherKey`/
+		// `firstKey`/`secondKey` are DB column names already — left as-is.
+		const resolveParent = buildColumnResolver(this.#entityClass);
 		switch (relation.type) {
 			case "hasOne":
 			case "hasMany": {
@@ -2026,19 +4094,20 @@ export class ModelQuery<T extends BaseEntity> {
 				// hard-coding them here produced silently-wrong whereHas/withCount SQL.
 				const fk =
 					relation.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
-				const localKey = relation.localKey ?? parentPk;
+				const localKey = resolveParent(relation.localKey ?? parentPk);
 				sub.#pushWhereRaw(
-					`${q(relatedTable)}.${q(fk)} = ${q(parentTable)}.${q(localKey)}`,
+					`${qTable(relatedTable)}.${q(fk)} = ${qTable(parentTable)}.${q(localKey)}`,
 				);
 				break;
 			}
 			case "belongsTo": {
 				const fk =
 					relation.foreignKey ?? `${camelToSnake(relatedClass.name)}_id`;
-				const ownerKey =
-					relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id";
+				const ownerKey = buildColumnResolver(relatedClass)(
+					relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id",
+				);
 				sub.#pushWhereRaw(
-					`${q(relatedTable)}.${q(ownerKey)} = ${q(parentTable)}.${q(fk)}`,
+					`${qTable(relatedTable)}.${q(ownerKey)} = ${qTable(parentTable)}.${q(fk)}`,
 				);
 				break;
 			}
@@ -2055,12 +4124,16 @@ export class ModelQuery<T extends BaseEntity> {
 					pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 				const otherKey =
 					pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
-				const relatedPk = getPrimaryKey(relatedClass) ?? "id";
-				const localKey = relation.localKey ?? parentPk;
+				const relatedPkProp = getPrimaryKey(relatedClass) ?? "id";
+				const relatedPk =
+					getColumnMetadata(relatedClass).find(
+						(c) => c.propertyKey === relatedPkProp,
+					)?.columnName ?? camelToSnake(relatedPkProp);
+				const localKey = resolveParent(relation.localKey ?? parentPk);
 				sub.#pushWhereRaw(
-					`${q(relatedTable)}.${q(relatedPk)} IN ` +
-						`(SELECT ${q(otherKey)} FROM ${q(pivot.pivotTable)} ` +
-						`WHERE ${q(pivot.pivotTable)}.${q(foreignKey)} = ${q(parentTable)}.${q(localKey)})`,
+					`${qTable(relatedTable)}.${q(relatedPk)} IN ` +
+						`(SELECT ${q(otherKey)} FROM ${qTable(pivot.pivotTable)} ` +
+						`WHERE ${qTable(pivot.pivotTable)}.${q(foreignKey)} = ${qTable(parentTable)}.${q(localKey)})`,
 				);
 				break;
 			}
@@ -2075,24 +4148,21 @@ export class ModelQuery<T extends BaseEntity> {
 					);
 				}
 				const throughClass = relation.through() as new () => BaseEntity;
-				const throughMeta = getEntityMetadata(throughClass);
-				if (!throughMeta) {
-					throw new Error(
-						`Entity metadata missing on through class ${throughClass.name}`,
-					);
-				}
+				const throughMeta = ensureEntityMetadata(throughClass);
 				const throughTable = throughMeta.tableName;
 				const throughPk = getPrimaryKey(throughClass) ?? "id";
-				const parentLocal = relation.localKey ?? parentPk;
+				const parentLocal = resolveParent(relation.localKey ?? parentPk);
 				const firstKey =
 					relation.firstKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 				const secondKey =
 					relation.secondKey ?? `${camelToSnake(throughClass.name)}_id`;
-				const secondLocal = relation.secondLocalKey ?? throughPk;
+				const secondLocal = buildColumnResolver(throughClass)(
+					relation.secondLocalKey ?? throughPk,
+				);
 				sub.#pushWhereRaw(
-					`${q(relatedTable)}.${q(secondKey)} IN ` +
-						`(SELECT ${q(secondLocal)} FROM ${q(throughTable)} ` +
-						`WHERE ${q(throughTable)}.${q(firstKey)} = ${q(parentTable)}.${q(parentLocal)})`,
+					`${qTable(relatedTable)}.${q(secondKey)} IN ` +
+						`(SELECT ${q(secondLocal)} FROM ${qTable(throughTable)} ` +
+						`WHERE ${qTable(throughTable)}.${q(firstKey)} = ${qTable(parentTable)}.${q(parentLocal)})`,
 				);
 				break;
 			}
@@ -2114,40 +4184,119 @@ 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, 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("RIGHT", table, leftOrBuild, right);
+		return this.#pushJoin(
+			"FULL OUTER",
+			table,
+			leftOrBuild,
+			operatorOrRight,
+			right,
+		);
 	}
 
 	crossJoin(table: string): this {
-		const tq = this.#quote(table);
-		this.#joins.push(`CROSS JOIN ${tq}`);
+		const tq = this.#quoteCol(table);
+		this.#joins.push({ sql: `CROSS JOIN ${tq}`, params: [] });
 		return this;
 	}
 
@@ -2167,14 +4316,14 @@ export class ModelQuery<T extends BaseEntity> {
 	 *
 	 * @unsafe Raw SQL fragment — never concatenate user input into `fragment`.
 	 */
-	joinRaw(fragment: string): this {
+	joinRaw(fragment: string, bindings: readonly unknown[] = []): this {
 		if (isAtlasStrictMode() && !isInternalBypass()) {
 			throw new Error(
 				"joinRaw() is disabled in Atlas strict mode. " +
 					"Use joinOn() or the callback form of innerJoin/leftJoin/rightJoin instead.",
 			);
 		}
-		this.#joins.push(fragment);
+		this.#joins.push({ sql: fragment, params: [...bindings] });
 		return this;
 	}
 
@@ -2195,25 +4344,72 @@ 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;
+	}
+
+	/**
+	 * `SELECT DISTINCT ON (cols) …` — keep the first row per distinct set of
+	 * `columns` (Lucid/Knex `distinctOn`). Takes precedence over
+	 * {@link distinct}.
+	 *
+	 * Postgres-only, and the compiler refuses it elsewhere: MySQL and SQLite
+	 * would parse `DISTINCT (a, b)` as a plain DISTINCT over a row value and
+	 * return a *different* result set rather than fail — a silent wrong answer
+	 * is worse than an error.
+	 *
+	 * Postgres also requires the leading `ORDER BY` terms to match `columns`;
+	 * that is left to the database to enforce.
+	 */
+	distinctOn(...columns: string[]): this {
+		for (const c of columns) this.#distinctOn.push(this.#resolveColumn(c));
 		return this;
 	}
 
 	/** `SELECT COUNT(DISTINCT col)`. */
 	async countDistinct(column: string): Promise<number> {
 		return Number(
-			(await this.#runScalar(`COUNT(DISTINCT ${this.#quoteCol(column)})`)) ?? 0,
+			(await this.#runScalar(
+				`COUNT(DISTINCT ${this.#quoteCol(this.#resolveColumn(column))})`,
+			)) ?? 0,
 		);
 	}
 
+	/** `SUM(DISTINCT col)` (Lucid parity). */
+	async sumDistinct(column: string): Promise<number | null> {
+		const v = await this.#runScalar(
+			`SUM(DISTINCT ${this.#quoteCol(this.#resolveColumn(column))})`,
+		);
+		return v === null || v === undefined ? null : Number(v);
+	}
+
+	/** `AVG(DISTINCT col)` (Lucid parity). */
+	async avgDistinct(column: string): Promise<number | null> {
+		const v = await this.#runScalar(
+			`AVG(DISTINCT ${this.#quoteCol(this.#resolveColumn(column))})`,
+		);
+		return v === null || v === undefined ? null : Number(v);
+	}
+
 	/** `SELECT 1 FROM ... LIMIT 1` — returns boolean. */
 	async exists(): Promise<boolean> {
 		const clone = this.clone();
 		clone.#select = ["1"];
 		clone.#limit = 1;
-		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.#db.query<Record<string, unknown>>(
+			sql,
+			params,
+			this.#meta("exists"),
+		);
 		return rows.length > 0;
 	}
 
@@ -2226,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];
@@ -2297,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;
 	}
 
@@ -2308,27 +4506,61 @@ 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);
-		// Parallel 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();
-		countQ.#select = ["COUNT(*) AS count"];
+		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 = [];
-		const { sql: cSql, params: cParams } = countQ.toSQL();
-		const cRows = await this.#db.query<Record<string, unknown>>(cSql, cParams);
+		let cSql: string;
+		let cParams: unknown[];
+		if (countQ.#groupBy.length > 0) {
+			// A flat `SELECT COUNT(*) … GROUP BY x` returns one row PER GROUP (each the
+			// 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.#compiledNative();
+			cSql = `SELECT COUNT(*) AS count FROM (${inner.sql}) AS __paginate_count`;
+			cParams = inner.params;
+		} else {
+			countQ.#select = ["COUNT(*) AS count"];
+			const flat = countQ.#compiledNative();
+			cSql = flat.sql;
+			cParams = flat.params;
+		}
+		const cRows = await this.#db.query<Record<string, unknown>>(
+			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);
-		return new Paginator<T>(items, { total, perPage: pp, currentPage: p });
+		const metaKeys = this.#entityClass
+			? getNamingStrategy(this.#entityClass).paginationMetaKeys?.()
+			: undefined;
+		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;
 	}
 
 	/**
@@ -2349,9 +4581,13 @@ export class ModelQuery<T extends BaseEntity> {
 		limit: number;
 		orderBy: string | string[];
 	}): Promise<{ items: T[]; nextCursor: string | null; hasMore: boolean }> {
-		const cols = (
-			Array.isArray(opts.orderBy) ? opts.orderBy : [opts.orderBy]
-		).map((c) => this.#resolveColumn(c));
+		// Keep BOTH forms: `props` (model property names) to read the cursor value
+		// off the hydrated entity, and `cols` (resolved DB columns) for the SQL
+		// ORDER BY / WHERE. Mixing them up made a columnName/camelCase order key
+		// encode `undefined` into the cursor (entity exposes the property, not the
+		// DB column) — an unstable / stuck cursor.
+		const props = Array.isArray(opts.orderBy) ? opts.orderBy : [opts.orderBy];
+		const cols = props.map((c) => this.#resolveColumn(c));
 		if (cols.length === 0)
 			throw new Error("cursorPaginate requires at least one orderBy column");
 		const lim = Math.max(1, Math.floor(opts.limit));
@@ -2400,9 +4636,9 @@ export class ModelQuery<T extends BaseEntity> {
 		const last = items[items.length - 1] as Record<string, unknown> | undefined;
 		const nextCursor =
 			hasMore && last
-				? Buffer.from(JSON.stringify({ v: cols.map((c) => last[c]) })).toString(
-						"base64",
-					)
+				? Buffer.from(
+						JSON.stringify({ v: props.map((p) => last[p]) }),
+					).toString("base64")
 				: null;
 		return { items, nextCursor, hasMore };
 	}
@@ -2423,14 +4659,43 @@ 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
+	 * {@link debug} can force emission for this query alone.
+	 *
+	 * Note the connection's own `debug: true` emits every statement regardless;
+	 * `meta` only enriches the event and opens the per-query override.
+	 */
+	#meta(method: string): QueryMeta {
+		return {
+			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. */
@@ -2443,85 +4708,191 @@ export class ModelQuery<T extends BaseEntity> {
 			this.#resolveColumn,
 			this.#softDeletes,
 			this.#dialect,
+			this.#prepareValue,
+			this.#onDomainEvents,
 		);
 		c.#softScope = this.#softScope;
 		c.#wheres = structuredCloneSafe(this.#wheres);
 		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.#joins = [...this.#joins];
+		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;
+		c.#sideloaded = this.#sideloaded ? { ...this.#sideloaded } : null;
 		c.#distinct = this.#distinct;
+		c.#distinctOn = [...this.#distinctOn];
 		c.#groupBy = [...this.#groupBy];
 		c.#having = structuredCloneSafe(this.#having);
-		c.#ctes = this.#ctes.map((e) => ({ name: e.name, query: e.query.clone() }));
+		c.#ctes = this.#ctes.map((e) => ({
+			name: e.name,
+			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(),
 			all: u.all,
+			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");
 		}
-		const setPairs = Object.entries(patch).map(
-			([k, v]) => [this.#resolveColumn(k), v] as [string, unknown],
+		// Lower each value through prepare (DateTime → ISO, @Column adapters) exactly
+		// like BaseRepository's write paths — the fluent update() must not bypass it.
+		// 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)],
 		);
-		const spec = {
-			kind: "update",
-			table: this.#tableName,
-			set: setPairs,
-			wheres: this.#wheresForDml(),
-			returning: returning ?? [],
-		};
-		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.#makeDml(
+			(r) => ({
+				kind: "update",
+				table: this.#tableName,
+				set: setPairs,
+				wheres: this.#wheresForDml(),
+				returning: r,
+				ctes: this.#compiledCtes(),
+			}),
+			returning,
+		);
+	}
+
+	/**
+	 * Execute a fluent DELETE. For a `@SoftDeletes` model this SOFT-deletes the
+	 * scoped rows (stamps `deleted_at`) — consistent with the entity-level
+	 * `delete()`; use {@link forceDelete} for a hard `DELETE`. For a non-soft-delete
+	 * model it issues a hard `DELETE`. Returns affected rows (or rows when
+	 * `returning` is set).
+	 */
+	delete(returning?: string[]): DmlBuilder<number | Record<string, unknown>[]> {
+		if (this.#softDeletes) {
+			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,
 			);
 		}
-		const r = await this.#db.execute(compiled.statements[0], compiled.params);
-		return r.rowsAffected ?? 0;
+		return this.forceDelete(returning);
 	}
 
-	/** Execute a fluent DELETE. Returns affected rows (or rows when `returning` is set). */
-	async delete(
+	/** Hard `DELETE` of the scoped rows, bypassing `@SoftDeletes` (AdonisJS/Lucid `forceDelete`). */
+	forceDelete(
 		returning?: string[],
-	): Promise<number | Record<string, unknown>[]> {
-		const spec = {
-			kind: "delete",
-			table: this.#tableName,
-			wheres: this.#wheresForDml(),
-			returning: returning ?? [],
-		};
-		const compiled = compileStatementNative(spec, this.#dialect);
-		if (returning && returning.length > 0) {
-			return this.#db.query<Record<string, unknown>>(
-				compiled.statements[0],
-				compiled.params,
+	): DmlBuilder<number | Record<string, unknown>[]> {
+		return this.#makeDml(
+			(r) => ({
+				kind: "delete",
+				table: this.#tableName,
+				wheres: this.#wheresForDml(),
+				returning: r,
+				ctes: this.#compiledCtes(),
+			}),
+			returning,
+		);
+	}
+
+	/**
+	 * Bulk restore: clear `deleted_at` on the trashed rows matching the user's
+	 * predicates (the soft-delete counterpart of {@link delete}). No-op count `0`
+	 * on a non-soft-delete model. Independent of the current soft-scope — it always
+	 * targets trashed rows (`deleted_at IS NOT NULL`).
+	 */
+	restore(
+		returning?: string[],
+	): DmlBuilder<number | Record<string, unknown>[]> {
+		if (!this.#softDeletes) {
+			return new DmlBuilder(
+				() => Promise.resolve<number | Record<string, unknown>[]>(0),
+				() => ({ sql: "", bindings: [], params: [] }),
+				this.#dmlHooks(),
 			);
 		}
-		const r = await this.#db.execute(compiled.statements[0], compiled.params);
-		return r.rowsAffected ?? 0;
+		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>,
@@ -2530,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>,
@@ -2563,6 +4934,56 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
+	/** Postgres `FOR NO KEY UPDATE` — a weaker lock that doesn't block FK checks (AdonisJS/Knex). */
+	forNoKeyUpdate(): this {
+		if (this.#dialect === "postgres") {
+			this.#lockMode = "FOR NO KEY UPDATE";
+		} else {
+			console.warn(
+				`[atlas] forNoKeyUpdate ignored on ${this.#dialect} (Postgres-only lock)`,
+			);
+		}
+		return this;
+	}
+
+	/** Postgres `FOR KEY SHARE` — the weakest share lock (AdonisJS/Knex). */
+	forKeyShare(): this {
+		if (this.#dialect === "postgres") {
+			this.#lockMode = "FOR KEY SHARE";
+		} else {
+			console.warn(
+				`[atlas] forKeyShare ignored on ${this.#dialect} (Postgres-only lock)`,
+			);
+		}
+		return this;
+	}
+
+	/**
+	 * Append `SKIP LOCKED` to the lock clause — locked rows are skipped instead of
+	 * waited on (AdonisJS/Knex). Requires a base lock (`forUpdate`/`forShare`/…).
+	 */
+	skipLocked(): this {
+		if (this.#dialect === "sqlite") {
+			console.warn("[atlas] skipLocked ignored on sqlite (no row-level lock)");
+		} else {
+			this.#lockModifier = "SKIP LOCKED";
+		}
+		return this;
+	}
+
+	/**
+	 * Append `NOWAIT` to the lock clause — error immediately instead of waiting on
+	 * a locked row (AdonisJS/Knex). Requires a base lock (`forUpdate`/`forShare`/…).
+	 */
+	noWait(): this {
+		if (this.#dialect === "sqlite") {
+			console.warn("[atlas] noWait ignored on sqlite (no row-level lock)");
+		} else {
+			this.#lockModifier = "NOWAIT";
+		}
+		return this;
+	}
+
 	// === Private helpers ==============================================================================
 
 	#quote(name: string): string {
@@ -2571,62 +4992,207 @@ export class ModelQuery<T extends BaseEntity> {
 
 	/** Quote a `table.column` reference on both sides of the dot. */
 	#quoteCol(ref: string): string {
-		if (ref.includes(".")) {
-			const [t, c] = ref.split(".", 2);
-			return `${this.#quote(t)}.${this.#quote(c)}`;
+		// Validate BEFORE quoting — `#quote` only wraps in quotes/backticks, so an
+		// identifier smuggling a `"`/backtick would break out of the quoting on the
+		// join path (which the Rust screen doesn't re-validate). Strict
+		// `[[schema.]table.]column` grammar (up to 3 dot segments); keeps join
+		// helpers injection-safe. Use joinRaw() for anything more complex.
+		if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*){0,2}$/.test(ref)) {
+			throw new Error(
+				`Invalid join/column identifier '${ref}' — expected [[schema.]table.]column (letters, digits, underscore). Use joinRaw() for anything else.`,
+			);
 		}
-		return this.#quote(ref);
+		return ref
+			.split(".")
+			.map((seg) => this.#quote(seg))
+			.join(".");
 	}
 
 	#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.#quote(table);
+		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, 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;
+				},
+				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;
+				},
+				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;
+				},
+				onBetween: (l, range) => {
+					parts.push({ kind: "and", left: l, between: [range[0], range[1]] });
+					return jb;
 				},
-				andOn(l: string, r: string) {
-					this.parts.push({ kind: "and", left: l, right: r });
-					return this;
+				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;
 				},
-				andOnVal(l: string, _v: unknown) {
-					this.parts.push({ kind: "and", left: l, right: "?" });
-					return this;
+				onNotExists: (sub) => {
+					const { sql, params } = this.#resolveUnion(sub).#compiledNative();
+					parts.push({ kind: "and", exists: { sql, params, not: true } });
+					return jb;
 				},
 			};
 			leftOrBuild(jb);
-			const on = jb.parts
+			// 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 = parts
 				.map((p, i) => {
 					const prefix = i === 0 ? "ON" : p.kind === "or" ? "OR" : "AND";
-					return `${prefix} ${this.#quoteCol(p.left)} = ${p.right === "?" ? "?" : this.#quoteCol(p.right)}`;
+					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) {
+						params.push(prep(p.left ?? "", p.value.v));
+						return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ?`;
+					}
+					return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ${this.#quoteCol(p.right ?? "")}`;
 				})
 				.join(" ");
-			this.#joins.push(`${kind} JOIN ${tq} ${on}`);
+			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(
-			`${kind} JOIN ${tq} ON ${this.#quoteCol(leftOrBuild)} = ${this.#quoteCol(right)}`,
-		);
+		this.#joins.push({
+			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;
 	}
@@ -2651,46 +5217,140 @@ 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).
 	 */
-	#wheresForDml(): 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.`,
-				);
+	#userWheresForDml(): WhereClause[] {
+		return [...this.#wheres];
+	}
+
+	#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
+		// default scope — otherwise `query().where(x)` would denote a different row
+		// set for `.exec()` than for `.update()`/`.delete()`. `.withTrashed()` widens,
+		// `.onlyTrashed()` restricts to trashed (mirrors reads).
+		if (this.#softDeletes) {
+			const deletedAtCol = this.#deletedAtColumn();
+			if (this.#softScope === "default") {
+				out.push({
+					column: deletedAtCol,
+					operator: "IS NULL",
+					value: null,
+					type: "and",
+				});
+			} else if (this.#softScope === "only-trashed") {
+				out.push({
+					column: deletedAtCol,
+					operator: "IS NOT NULL",
+					value: null,
+					type: "and",
+				});
 			}
-			out.push({
-				column: w.column,
-				operator: w.operator,
-				value: w.value,
-				type: w.type,
-			});
 		}
 		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>,
+		returning?: string[],
+	): Promise<number | Record<string, unknown>[]> {
+		const compiled = compileStatementNative(spec, this.#dialect);
+		if (returning && returning.length > 0) {
+			return this.#raceTimeout(
+				this.#db.query<Record<string, unknown>>(
+					this.#commentPrefix() + compiled.statements[0],
+					compiled.params,
+					this.#meta("dml"),
+				),
+			);
+		}
+		const r = await this.#raceTimeout(
+			this.#db.execute(
+				this.#commentPrefix() + compiled.statements[0],
+				compiled.params,
+				this.#meta("dml"),
+			),
+		);
+		return r.rowsAffected ?? 0;
+	}
+
 	/**
 	 * !!! DEBUG ONLY — DO NOT USE FOR EXECUTION !!!
 	 *
@@ -2704,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
@@ -2728,6 +5379,7 @@ export class ModelQuery<T extends BaseEntity> {
 			this.#resolveColumn,
 			false,
 			this.#dialect,
+			this.#prepareValue,
 		);
 		callback(scratch);
 		return { type, kind: "group", conditions: scratch.#wheres };
@@ -2781,19 +5433,30 @@ export class ModelQuery<T extends BaseEntity> {
 				type,
 				column: resolved,
 				operator: "=",
-				value: operatorOrValue,
+				value: this.#prep(column, operatorOrValue),
 			});
 		} else {
 			this.#wheres.push({
 				type,
 				column: resolved,
 				operator: operatorOrValue as string,
-				value,
+				value: this.#prep(column, value),
 			});
 		}
 		return this;
 	}
 
+	/**
+	 * Lower a WHERE/search value (or each element of an array) to its DB form via
+	 * the prepare hook — so a `@column.dateTime` DateTime or a `@Column({ prepare })`
+	 * adapter column used as a predicate binds the same shape the write path stores.
+	 */
+	#prep(column: string, value: unknown): unknown {
+		return Array.isArray(value)
+			? value.map((v) => this.#prepareValue(column, v))
+			: this.#prepareValue(column, value);
+	}
+
 	/**
 	 * Resolve this ModelQuery's preloads against a pre-loaded set of entities.
 	 * Used by the nested-preload machinery to recurse without re-running the root select.