@c9up/atlas 0.1.18 → 0.2.0

package/src/ModelQuery.ts

@@ -7,17 +7,28 @@
  * 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 {
 	type AtlasDialect,
 	compileStatementNative,
@@ -43,6 +54,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 +114,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 +309,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";
+	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";
@@ -180,27 +357,84 @@ interface HavingClause {
 	type: "and" | "or";
 }
 
+/** A raw SQL HAVING fragment with `?` bindings — kind-tagged for the Rust compiler. */
+interface HavingRawClause {
+	kind: "raw";
+	sql: string;
+	bindings: unknown[];
+	type: "and" | "or";
+}
+
+type HavingEntry = HavingClause | HavingRawClause;
+
+/** A compiled CTE (`WITH name AS (...)`) — the sub-select is pre-compiled to SQL + params. */
+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 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 {
 	alias: string;
 	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[];
-	having: HavingClause[];
+	orderBy: OrderByEntry[];
+	groupBy: GroupByEntry[];
+	having: HavingEntry[];
 	limit: number | null;
 	offset: number | null;
 	distinct: boolean;
-	ctes: unknown[];
-	unions: unknown[];
-	joins: string[];
-	lockMode: "FOR UPDATE" | "FOR SHARE" | null;
+	distinctOn: string[];
+	ctes: CteSpec[];
+	unions: UnionSpec[];
+	/** JOIN fragments; each carries its own `?`-style bound params (e.g. `onVal`). */
+	joins: Array<{ sql: string; params: unknown[] }>;
+	/** Composite lock clause, e.g. `FOR UPDATE`, `FOR NO KEY UPDATE SKIP LOCKED`. */
+	lockMode: string | null;
 }
 
 type WhereClause =
@@ -208,15 +442,18 @@ type WhereClause =
 	| RawWhere
 	| ExistsWhere
 	| GroupWhere
-	| InSubWhere;
+	| InSubWhere
+	| JsonWhere;
 
 type WhereCallback = (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
@@ -228,7 +465,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;
 }
@@ -262,12 +499,26 @@ 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 JoinBuilder {
-	parts: Array<{ kind: "and" | "or"; left: string; right: string }>;
+	/** A column-to-column part (`value` absent) or a column-to-value part (`value` set). */
+	parts: Array<{
+		kind: "and" | "or";
+		left: string;
+		right?: string;
+		value?: { v: unknown };
+	}>;
 	on(left: string, right: string): JoinBuilder;
 	andOn(left: string, right: string): JoinBuilder;
+	orOn(left: string, right: string): JoinBuilder;
+	onVal(left: string, value: unknown): JoinBuilder;
 	andOnVal(left: string, value: unknown): JoinBuilder;
+	orOnVal(left: string, value: unknown): JoinBuilder;
 }
 
 /** Offset-based paginator (Story 29.10). */
@@ -282,23 +533,59 @@ 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;
+	}
+
+	/** True when there is at least one more page after the current one (AdonisJS `hasMorePages`). */
+	get hasMorePages(): boolean {
+		return this.meta.currentPage < this.meta.lastPage;
+	}
+
 	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;
@@ -307,7 +594,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 {
@@ -319,29 +608,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() };
 	}
 }
 
@@ -359,7 +695,7 @@ 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;
 	#offset?: number;
@@ -369,13 +705,62 @@ export class ModelQuery<T extends BaseEntity> {
 	/** 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;
 	/** Distinct flag — Story 29.5. */
 	#distinct = false;
+	#distinctOn: string[] = [];
+	/** GROUP BY columns (Lucid parity). */
+	#groupBy: GroupByEntry[] = [];
+	/** HAVING clauses — structured + raw (Lucid parity). */
+	#having: HavingEntry[] = [];
+	/** CTEs registered via `.with()` (Lucid parity). */
+	#ctes: Array<{
+		name: string;
+		query: ModelQuery<BaseEntity>;
+		recursive?: boolean;
+		materialized?: boolean;
+	}> = [];
+	/** UNION / UNION ALL branches (Lucid parity). */
+	#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;
+		/** AND/OR within the parenthesised pivot-filter group — see `#runInQuery`. */
+		type: "and" | "or";
+	}> = [];
+	/**
+	 * 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;
 
@@ -387,6 +772,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;
@@ -395,8 +782,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";
@@ -424,12 +818,31 @@ export class ModelQuery<T extends BaseEntity> {
 
 	/** Select specific columns (default: `*`). Accepts a comma-separated string or an array. */
 	select(columns: string | string[]): this {
-		this.#select = Array.isArray(columns)
+		const list = Array.isArray(columns)
 			? columns
 			: columns.split(",").map((c) => c.trim());
+		this.#select = list.map((c) => this.#resolveSelect(c));
 		return this;
 	}
 
+	/**
+	 * 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;
@@ -480,13 +893,88 @@ export class ModelQuery<T extends BaseEntity> {
 		return 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);
+	}
+
 	/** `WHERE col != ?` — negation of `where`. */
 	whereNot(column: string, value: unknown): this {
 		this.#wheres.push({
 			type: "and",
 			column: this.#resolveColumn(column),
 			operator: "!=",
-			value,
+			value: this.#prep(column, value),
 		});
 		return this;
 	}
@@ -510,7 +998,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "and",
 			column: this.#resolveColumn(column),
 			operator: "IN",
-			value: [...source],
+			value: this.#prep(column, [...source]),
 		});
 		return this;
 	}
@@ -534,7 +1022,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;
 	}
@@ -545,7 +1033,7 @@ export class ModelQuery<T extends BaseEntity> {
 			type: "and",
 			column: this.#resolveColumn(column),
 			operator: "BETWEEN",
-			value: [...range],
+			value: this.#prep(column, [...range]),
 		});
 		return this;
 	}
@@ -556,7 +1044,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;
 	}
@@ -587,6 +1075,135 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
+	// ─── OR-combined variants (AdonisJS orWhere* family) ─────────
+	// Same predicates as the whereX methods above, combined with OR instead of
+	// AND — the named ergonomics Lucid exposes (vs emulating with `orWhere(cb)`).
+
+	/** `OR col IS NULL`. */
+	orWhereNull(column: string): this {
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "IS NULL",
+			value: null,
+		});
+		return this;
+	}
+
+	/** `OR col IS NOT NULL`. */
+	orWhereNotNull(column: string): this {
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "IS NOT NULL",
+			value: null,
+		});
+		return this;
+	}
+
+	/** `OR col != ?`. */
+	orWhereNot(column: string, value: unknown): this {
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "!=",
+			value: this.#prep(column, value),
+		});
+		return this;
+	}
+
+	/** `OR col IN (...)` — array or `ModelQuery` subquery source. */
+	orWhereIn(
+		column: string,
+		source: readonly unknown[] | ModelQuery<BaseEntity>,
+	): this {
+		if (source instanceof ModelQuery) {
+			this.#wheres.push({
+				type: "or",
+				kind: "inSub",
+				negated: false,
+				column: this.#resolveColumn(column),
+				subquery: source.#buildSpec(),
+			});
+			return this;
+		}
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "IN",
+			value: this.#prep(column, [...source]),
+		});
+		return this;
+	}
+
+	/** `OR col NOT IN (...)` — array or `ModelQuery` subquery source. */
+	orWhereNotIn(
+		column: string,
+		source: readonly unknown[] | ModelQuery<BaseEntity>,
+	): this {
+		if (source instanceof ModelQuery) {
+			this.#wheres.push({
+				type: "or",
+				kind: "inSub",
+				negated: true,
+				column: this.#resolveColumn(column),
+				subquery: source.#buildSpec(),
+			});
+			return this;
+		}
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "NOT IN",
+			value: this.#prep(column, [...source]),
+		});
+		return this;
+	}
+
+	/** `OR col BETWEEN ? AND ?`. */
+	orWhereBetween(column: string, range: readonly [unknown, unknown]): this {
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "BETWEEN",
+			value: this.#prep(column, [...range]),
+		});
+		return this;
+	}
+
+	/** `OR col NOT BETWEEN ? AND ?`. */
+	orWhereNotBetween(column: string, range: readonly [unknown, unknown]): this {
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "NOT BETWEEN",
+			value: this.#prep(column, [...range]),
+		});
+		return this;
+	}
+
+	/** `OR col LIKE ?`. */
+	orWhereLike(column: string, pattern: string): this {
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "LIKE",
+			value: pattern,
+		});
+		return this;
+	}
+
+	/** `OR col ILIKE ?` (rewritten to LOWER() LIKE LOWER() on sqlite/mysql). */
+	orWhereILike(column: string, pattern: string): this {
+		this.#wheres.push({
+			type: "or",
+			column: this.#resolveColumn(column),
+			operator: "ILIKE",
+			value: pattern,
+		});
+		return this;
+	}
+
 	/**
 	 * **⚠ UNSAFE** — append a raw SQL fragment to the WHERE clause with
 	 * `?`-style bindings. The Rust compiler re-indexes the placeholders so they
@@ -629,9 +1246,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],
@@ -639,6 +1260,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.
@@ -689,6 +1356,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
@@ -707,16 +1388,328 @@ 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;
 	}
 
 	/**
-	 * `WHERE EXISTS (SELECT * FROM related WHERE <join> AND <cb>)` — filter parent rows
-	 * by the existence of related rows, optionally constrained by a callback.
-	 *
+	 * Compare two COLUMNS (AdonisJS/Knex `whereColumn`) — `WHERE "a" op "b"`.
+	 * Both sides go through the identifier quoter (injection-safe) and the
+	 * 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.
+	 */
+	// ─── 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);
+	}
+
+	/** Alias of {@link whereExists} (Lucid parity). */
+	andWhereExists(subquery: ModelQuery<BaseEntity>): this {
+		return this.#pushExists("and", false, subquery);
+	}
+
+	/** `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,
+		operator: string,
+		value: unknown,
+	): this {
+		return this.#pushJson("and", false, "path", column, value, path, operator);
+	}
+
+	/** Alias of {@link whereJsonPath} (Lucid parity). */
+	andWhereJsonPath(
+		column: string,
+		path: string,
+		operator: string,
+		value: unknown,
+	): this {
+		return this.#pushJson("and", false, "path", column, value, path, operator);
+	}
+
+	/** `OR <col at path> <op> ?` (Lucid parity). */
+	orWhereJsonPath(
+		column: string,
+		path: string,
+		operator: string,
+		value: unknown,
+	): this {
+		return this.#pushJson("or", false, "path", column, value, path, operator);
+	}
+
+	/**
+	 * `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);
+	}
+
+	#pushJson(
+		type: "and" | "or",
+		negated: boolean,
+		jsonOp: "path" | "superset" | "subset",
+		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(" ")}.`,
+			);
+		}
+		// Both operands are interpolated as raw identifiers (no value binding for a
+		// column reference), and #quote is a plain wrapper that does NOT escape an
+		// embedded quote — so validate each RESOLVED identifier against a strict
+		// `[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.#resolveColumnReference(name);
+			if (
+				!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(resolved)
+			) {
+				throw new Error(
+					`whereColumn: '${name}' is not a valid column identifier ([table.]column, alphanumeric + underscore).`,
+				);
+			}
+			// Quote each dotted segment separately → `"table"."column"`, never a
+			// single mis-quoted `"table.column"`.
+			return resolved
+				.split(".")
+				.map((part) => this.#quote(part))
+				.join(".");
+		};
+		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.
+	 *
 	 *     userRepo.query().whereHas('comments', q => q.where('approved', true))
 	 */
 	whereHas(
@@ -761,6 +1754,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>)
@@ -800,6 +1809,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`.
@@ -844,27 +1873,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);
 	}
 
@@ -881,42 +1920,417 @@ export class ModelQuery<T extends BaseEntity> {
 		relationName: string,
 		callback?: (query: ModelQuery<BaseEntity>) => void,
 	): this {
-		this.#selectSubqueries.push(
-			this.#buildRelationSubquery(
-				relationName,
-				callback,
-				"count",
-				`${relationName}_count`,
-			),
-		);
-		return this;
+		this.#selectSubqueries.push(
+			this.#buildRelationSubquery(
+				relationName,
+				callback,
+				"count",
+				`${relationName}_count`,
+			),
+		);
+		return this;
+	}
+
+	/**
+	 * Project any aggregate (sum/avg/min/max/count) of a relation as an extra column.
+	 * The callback MUST set the aggregate via `.sum('col')` / `.avg(...)` etc. and
+	 * typically also set an alias via `.as('name')`.
+	 *
+	 *     userRepo.query().withAggregate('posts', q => q.sum('views').as('total_views'))
+	 */
+	withAggregate(
+		relationName: string,
+		callback: (query: ModelQuery<BaseEntity>) => void,
+	): this {
+		this.#selectSubqueries.push(
+			this.#buildRelationSubquery(
+				relationName,
+				callback,
+				"aggregate",
+				relationName,
+			),
+		);
+		return this;
+	}
+
+	orderBy(column: string, direction: "asc" | "desc" = "asc"): this {
+		this.#orderBys.push({ column: this.#resolveColumn(column), 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 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`).
+	 * 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: this.#resolveHavingCol(column),
+			operator,
+			value: this.#prep(column, 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: this.#resolveHavingCol(column),
+			operator,
+			value: this.#prep(column, value),
+			type: "or",
+		});
+		return this;
+	}
+
+	/**
+	 * **⚠ UNSAFE** — append a raw SQL `HAVING` fragment with `?` bindings
+	 * (AdonisJS/Lucid `havingRaw`). The Rust compiler re-indexes the placeholders;
+	 * everything else in `sql` is trusted verbatim. All values must go through
+	 * `bindings`.
+	 *
+	 * @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,
+			bindings: [...bindings],
+			type: "and",
+		});
+		return this;
+	}
+
+	/**
+	 * `UNION (<query>)` (AdonisJS/Lucid `union`). The other query is compiled and
+	 * 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 });
+		return this;
+	}
+
+	/** `UNION ALL (<query>)` — duplicate-preserving {@link union}. */
+	unionAll(query: ModelQuery<BaseEntity>): this {
+		this.#unions.push({ query, all: true });
+		return this;
+	}
+
+	/** `INTERSECT (<query>)` — rows present in both (Lucid/Knex `intersect`). */
+	intersect(query: ModelQuery<BaseEntity>): this {
+		this.#unions.push({ query, all: false, op: "intersect" });
+		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: ModelQuery<BaseEntity>): this {
+		this.#unions.push({ query, all: true, op: "intersect" });
+		return this;
+	}
+
+	/** `EXCEPT (<query>)` — rows in this query but not the other (Lucid/Knex `except`). */
+	except(query: ModelQuery<BaseEntity>): this {
+		this.#unions.push({ query, all: false, op: "except" });
+		return this;
+	}
+
+	/** `EXCEPT ALL (<query>)` — duplicate-preserving {@link except}. Not on SQLite; see {@link intersectAll}. */
+	exceptAll(query: ModelQuery<BaseEntity>): this {
+		this.#unions.push({ query, all: true, op: "except" });
+		return this;
+	}
+
+	/**
+	 * `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 {
+		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: ModelQuery<BaseEntity>): this {
+		return this.#pushCte("withRecursive", name, query, { recursive: true });
+	}
+
+	/**
+	 * `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: ModelQuery<BaseEntity>): this {
+		return this.#pushCte("withMaterialized", name, query, {
+			materialized: true,
+		});
+	}
+
+	/** `WITH <name> AS NOT MATERIALIZED (<query>)` — let it be inlined (Lucid/Knex `withNotMaterialized`). See {@link withMaterialized}. */
+	withNotMaterialized(name: string, query: ModelQuery<BaseEntity>): this {
+		return this.#pushCte("withNotMaterialized", name, query, {
+			materialized: false,
+		});
+	}
+
+	#pushCte(
+		method: string,
+		name: string,
+		query: ModelQuery<BaseEntity>,
+		options: { recursive?: boolean; materialized?: boolean },
+	): this {
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+			throw new Error(
+				`${method}(): CTE name '${name}' is not a valid identifier`,
+			);
+		}
+		this.#ctes.push({ name, query, ...options });
+		return this;
+	}
+
+	/**
+	 * `@ManyToMany` only — filter loaded relations by a PIVOT-table column
+	 * (AdonisJS/Lucid `wherePivot`). Recorded separately from the related-table
+	 * WHEREs and applied to the pivot lookup query by the m2m preload resolver;
+	 * inert on non-m2m relations.
+	 *
+	 *     userRepo.query().preload('roles', q => q.wherePivot('active', true))
+	 */
+	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 — `WHERE <pivotCol> != <value>` on the pivot table (AdonisJS Lucid `whereNotPivot`). */
+	whereNotPivot(column: string, value: unknown): this {
+		return this.#pushPivotOp("and", column, "!=", value);
+	}
+
+	/** Alias of {@link whereNotPivot} (Lucid parity). */
+	andWhereNotPivot(column: string, value: unknown): this {
+		return this.#pushPivotOp("and", column, "!=", value);
+	}
+
+	/** `@ManyToMany` only — OR form of {@link whereNotPivot} (Lucid parity). */
+	orWhereNotPivot(column: string, value: unknown): this {
+		return this.#pushPivotOp("or", column, "!=", 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);
 	}
 
-	/**
-	 * Project any aggregate (sum/avg/min/max/count) of a relation as an extra column.
-	 * The callback MUST set the aggregate via `.sum('col')` / `.avg(...)` etc. and
-	 * typically also set an alias via `.as('name')`.
-	 *
-	 *     userRepo.query().withAggregate('posts', q => q.sum('views').as('total_views'))
-	 */
-	withAggregate(
-		relationName: string,
-		callback: (query: ModelQuery<BaseEntity>) => void,
+	#pushPivotOp(
+		type: "and" | "or",
+		column: string,
+		operator: string,
+		value: unknown,
 	): this {
-		this.#selectSubqueries.push(
-			this.#buildRelationSubquery(
-				relationName,
-				callback,
-				"aggregate",
-				relationName,
-			),
-		);
+		this.#pivotWheres.push({ column, operator, value, type });
 		return this;
 	}
 
-	orderBy(column: string, direction: "asc" | "desc" = "asc"): this {
-		this.#orderBys.push({ column: this.#resolveColumn(column), direction });
-		return this;
+	/** Read-only accessor for pivot constraints — consumed by the m2m preload resolver. */
+	get pivotConstraints(): ReadonlyArray<{
+		column: string;
+		operator: string;
+		value: unknown;
+		type: "and" | "or";
+	}> {
+		return this.#pivotWheres;
 	}
 
 	limit(n: number): this {
@@ -957,6 +2371,24 @@ export class ModelQuery<T extends BaseEntity> {
 		return result;
 	}
 
+	/**
+	 * Return the single matching row, or throw if there are zero OR more than one
+	 * (AdonisJS/Laravel `sole`). Use when exactly one row is a correctness
+	 * invariant — a second match signals a bug the silent `first()` would hide.
+	 */
+	async sole(): Promise<T> {
+		const rows = await this.limit(2).exec();
+		if (rows.length === 0) {
+			throw new Error(`No ${this.#tableName} found matching query (sole()).`);
+		}
+		if (rows.length > 1) {
+			throw new Error(
+				`Expected exactly one ${this.#tableName} but the query matched multiple rows (sole()).`,
+			);
+		}
+		return rows[0];
+	}
+
 	/**
 	 * Thenable — `await someQuery` is equivalent to `await someQuery.exec()`.
 	 * A chain like `await repo.query().where('active', true).orderBy('id')`
@@ -983,21 +2415,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,
 				});
@@ -1008,19 +2518,36 @@ export class ModelQuery<T extends BaseEntity> {
 		return {
 			kind: "select",
 			table: this.#tableName,
-			select: this.#select,
+			select: selectCols,
 			selectSubqueries: this.#selectSubqueries,
 			wheres,
 			orderBy: this.#orderBys,
-			groupBy: [],
-			having: [],
+			groupBy: this.#groupBy,
+			having: this.#having,
 			limit: this.#limit ?? null,
 			offset: this.#offset ?? null,
 			distinct: this.#distinct,
-			ctes: [],
-			unions: [],
+			distinctOn: this.#distinctOn,
+			ctes: this.#ctes.map((c) => {
+				const { sql, params } = c.query.toSQL();
+				return {
+					name: c.name,
+					sql,
+					params,
+					recursive: c.recursive ?? false,
+					materialized: c.materialized ?? null,
+				};
+			}),
+			unions: this.#unions.map((u) => {
+				const { sql, params } = u.query.toSQL();
+				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,
 		};
 	}
 
@@ -1056,7 +2583,11 @@ 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 rawRows = await 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);
@@ -1070,6 +2601,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;
 		});
 
@@ -1081,6 +2614,27 @@ export class ModelQuery<T extends BaseEntity> {
 		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.toSQL();
+		return this.#db.query<R>(sql, params);
+	}
+
+	/**
+	 * Thread arbitrary context onto every instance this query hydrates, exposed as
+	 * `entity.$sideloaded` (AdonisJS Lucid `sideload`) — e.g. the current tenant or
+	 * user, so hooks/computed can read it. Merges across calls. Chainable.
+	 */
+	sideload(values: Record<string, unknown>): this {
+		this.#sideloaded = { ...this.#sideloaded, ...values };
+		return this;
+	}
+
 	/** Resolve preloaded relations via batched subqueries (no N+1). */
 	async #resolvePreloads(entities: T[]): Promise<void> {
 		if (!this.#entityClass) return;
@@ -1109,8 +2663,11 @@ 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
@@ -1118,24 +2675,79 @@ export class ModelQuery<T extends BaseEntity> {
 		// every column would be silently dropped. Mirrors `BaseRepository.#hydrate`.
 		const relatedPkName = 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;
 		};
 
@@ -1144,7 +2756,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),
@@ -1206,11 +2820,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 =
@@ -1219,7 +2829,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])
@@ -1388,13 +3004,72 @@ 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 [];
 
-		// Step 1 — pivot table: find (foreignKey → otherKey) pairs
-		const pivotRows = await ctx.runInQuery(pivot.pivotTable, foreignKey, ids);
+		// Extract PIVOT-table constraints (wherePivot / wherePivotIn) from the
+		// preload callback by replaying it on a throwaway builder. The callback
+		// also runs (again) inside runRelationQuery against the related table; both
+		// runs are pure builder mutations, and pivot constraints are inert there.
+		const pivotWheres: Array<{
+			column: string;
+			operator: string;
+			value: unknown;
+		}> = [];
+		if (ctx.nestedCallback) {
+			const scratch = new ModelQuery<BaseEntity>(
+				ctx.relatedTable,
+				this.#db,
+				(r) => r as BaseEntity,
+				ctx.relatedClass,
+				buildColumnResolver(ctx.relatedClass),
+				false,
+				this.#dialect,
+				buildValuePreparer(ctx.relatedClass),
+			);
+			ctx.nestedCallback(scratch);
+			// 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)
+		const pivotRows = await this.#runInQuery(
+			pivot.pivotTable,
+			foreignKey,
+			ids,
+			pivotWheres,
+		);
 		if (pivotRows.length === 0) {
 			for (const entity of entities) entity.setProp(relationName, []);
 			return [];
@@ -1405,18 +3080,47 @@ 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 ?? [];
+		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
+		// across parents (Lucid gives distinct pivot-bearing instances). Otherwise a
+		// single shared instance per related PK is reused (cheaper, current behaviour).
+		const projectPivot = pivotCols.length > 0;
+		const rawByRelatedPk = new Map<unknown, Record<string, unknown>>();
 		const byRelatedPk = new Map<unknown, BaseEntity>();
 		const allRelated: BaseEntity[] = [];
 		for (const row of relRows) {
-			const hydrated = ctx.hydrate(row);
-			byRelatedPk.set(row[ctx.relatedPk], hydrated);
-			allRelated.push(hydrated);
+			rawByRelatedPk.set(row[ctx.relatedPk], row);
+			if (!projectPivot) {
+				const hydrated = ctx.hydrate(row);
+				byRelatedPk.set(row[ctx.relatedPk], hydrated);
+				allRelated.push(hydrated);
+			}
 		}
 
-		// Step 3 — group via the pivot
+		// Step 3 — group via the pivot, projecting declared pivotColumns into
+		// `$extras.pivot_<col>` (running each column's `consume` adapter if any).
 		const grouped = new Map<unknown, BaseEntity[]>();
 		for (const pivotRow of pivotRows) {
-			const related = byRelatedPk.get(pivotRow[otherKey]);
+			let related: BaseEntity | undefined;
+			if (projectPivot) {
+				const raw = rawByRelatedPk.get(pivotRow[otherKey]);
+				if (!raw) continue;
+				related = ctx.hydrate(raw);
+				for (const col of pivotCols) {
+					const rawVal = pivotRow[col];
+					const adapter = pivotAdapters[col];
+					related.setExtra(
+						`pivot_${col}`,
+						// Adonis Lucid signature: (value, attribute, model).
+						adapter?.consume ? adapter.consume(rawVal, col, related) : rawVal,
+					);
+				}
+				allRelated.push(related);
+			} else {
+				related = byRelatedPk.get(pivotRow[otherKey]);
+			}
 			if (!related) continue;
 			const parentId = pivotRow[foreignKey];
 			if (!grouped.has(parentId)) grouped.set(parentId, []);
@@ -1440,6 +3144,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) {
@@ -1452,13 +3160,40 @@ export class ModelQuery<T extends BaseEntity> {
 		table: string,
 		column: string,
 		values: unknown[],
+		extraWheres: ReadonlyArray<{
+			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" },
+		];
+		// 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({
+				kind: "group",
+				type: "and",
+				conditions: extraWheres.map((w) => ({
+					column: w.column,
+					operator: w.operator,
+					value: w.value,
+					type: w.type ?? "and",
+				})),
+			});
+		}
 		const spec = {
 			kind: "select",
 			table,
 			select: ["*"],
 			selectSubqueries: [],
-			wheres: [{ column, operator: "IN", value: values, type: "and" }],
+			wheres,
 			orderBy: [],
 			groupBy: [],
 			having: [],
@@ -1501,7 +3236,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
@@ -1511,6 +3249,7 @@ 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);
@@ -1559,44 +3298,67 @@ 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": {
-				const fk = `${camelToSnake(this.#entityClass.name)}_id`;
+				// Honour custom foreignKey/localKey exactly like the eager loader —
+				// hard-coding them here produced silently-wrong whereHas/withCount SQL.
+				const fk =
+					relation.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+				const localKey = resolveParent(relation.localKey ?? parentPk);
 				sub.#pushWhereRaw(
-					`${q(relatedTable)}.${q(fk)} = ${q(parentTable)}.${q(parentPk)}`,
+					`${qTable(relatedTable)}.${q(fk)} = ${qTable(parentTable)}.${q(localKey)}`,
 				);
 				break;
 			}
 			case "belongsTo": {
-				const fk = `${camelToSnake(relatedClass.name)}_id`;
-				const relatedPk = getPrimaryKey(relatedClass) ?? "id";
+				const fk =
+					relation.foreignKey ?? `${camelToSnake(relatedClass.name)}_id`;
+				const ownerKey = buildColumnResolver(relatedClass)(
+					relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id",
+				);
 				sub.#pushWhereRaw(
-					`${q(relatedTable)}.${q(relatedPk)} = ${q(parentTable)}.${q(fk)}`,
+					`${qTable(relatedTable)}.${q(ownerKey)} = ${qTable(parentTable)}.${q(fk)}`,
 				);
 				break;
 			}
@@ -1613,24 +3375,48 @@ 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 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(parentPk)})`,
+					`${qTable(relatedTable)}.${q(relatedPk)} IN ` +
+						`(SELECT ${q(otherKey)} FROM ${qTable(pivot.pivotTable)} ` +
+						`WHERE ${qTable(pivot.pivotTable)}.${q(foreignKey)} = ${qTable(parentTable)}.${q(localKey)})`,
 				);
 				break;
 			}
-			default:
-				// hasOneThrough / hasManyThrough build a 2-hop correlated subquery,
-				// which isn't implemented here. Fail loud — falling through would
-				// leave `sub` WITHOUT a join predicate, so whereHas/withCount would
-				// silently match/count EVERY related row.
-				throw new Error(
-					`whereHas/withCount on a '${relation.type}' relation ` +
-						`(${this.#entityClass.name}.${relationName}) is not supported yet. ` +
-						`Use a direct hasMany/belongsTo/manyToMany relation, or filter via a sub-query.`,
+			case "hasOneThrough":
+			case "hasManyThrough": {
+				// Two-hop correlated EXISTS: parent → through → related. Mirrors the
+				// eager loader's key resolution (`#resolveThrough`) exactly so
+				// whereHas/withCount agree with what preload() would return.
+				if (!relation.through) {
+					throw new Error(
+						`@HasOneThrough/@HasManyThrough '${relationName}' requires a through model`,
+					);
+				}
+				const throughClass = relation.through() as new () => BaseEntity;
+				const throughMeta = ensureEntityMetadata(throughClass);
+				const throughTable = throughMeta.tableName;
+				const throughPk = getPrimaryKey(throughClass) ?? "id";
+				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 = buildColumnResolver(throughClass)(
+					relation.secondLocalKey ?? throughPk,
 				);
+				sub.#pushWhereRaw(
+					`${qTable(relatedTable)}.${q(secondKey)} IN ` +
+						`(SELECT ${q(secondLocal)} FROM ${qTable(throughTable)} ` +
+						`WHERE ${qTable(throughTable)}.${q(firstKey)} = ${qTable(parentTable)}.${q(parentLocal)})`,
+				);
+				break;
+			}
 		}
 		return sub;
 	}
@@ -1681,8 +3467,8 @@ export class ModelQuery<T extends BaseEntity> {
 	}
 
 	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;
 	}
 
@@ -1702,14 +3488,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;
 	}
 
@@ -1735,11 +3521,47 @@ export class ModelQuery<T extends BaseEntity> {
 		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. */
@@ -1748,7 +3570,11 @@ export class ModelQuery<T extends BaseEntity> {
 		clone.#select = ["1"];
 		clone.#limit = 1;
 		const { sql, params } = clone.toSQL();
-		const rows = await this.#db.query<Record<string, unknown>>(sql, params);
+		const rows = await this.#db.query<Record<string, unknown>>(
+			sql,
+			params,
+			this.#meta("exists"),
+		);
 		return rows.length > 0;
 	}
 
@@ -1846,14 +3672,32 @@ export class ModelQuery<T extends BaseEntity> {
 		// 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
+		// COUNT(*) + data fetch
 		const countQ = this.clone();
-		countQ.#select = ["COUNT(*) AS count"];
 		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.toSQL();
+			cSql = `SELECT COUNT(*) AS count FROM (${inner.sql}) AS __paginate_count`;
+			cParams = inner.params;
+		} else {
+			countQ.#select = ["COUNT(*) AS count"];
+			const flat = countQ.toSQL();
+			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();
@@ -1863,7 +3707,14 @@ export class ModelQuery<T extends BaseEntity> {
 		// top of the paginate hooks — paginate is its own terminal.
 		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;
+		return new Paginator<T>(
+			items,
+			{ total, perPage: pp, currentPage: p },
+			metaKeys,
+		);
 	}
 
 	/**
@@ -1884,9 +3735,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));
@@ -1935,9 +3790,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 };
 	}
@@ -1958,6 +3813,22 @@ export class ModelQuery<T extends BaseEntity> {
 		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,
+		};
+	}
+
 	/** Returns the compiled SQL with bindings interpolated as dialect-safe literals. */
 	toQuery(): string {
 		const { sql, params } = this.toSQL();
@@ -1978,6 +3849,8 @@ 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);
@@ -1987,9 +3860,29 @@ export class ModelQuery<T extends BaseEntity> {
 		c.#offset = this.#offset;
 		c.#preloads = new Map(this.#preloads);
 		c.#selectSubqueries = structuredClone(this.#selectSubqueries);
-		c.#joins = [...this.#joins];
+		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(),
+			recursive: e.recursive,
+			materialized: e.materialized,
+		}));
+		c.#unions = this.#unions.map((u) => ({
+			query: u.query.clone(),
+			all: u.all,
+			op: u.op,
+		}));
+		c.#pivotWheres = structuredCloneSafe(this.#pivotWheres);
+		// 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;
 		return c;
 	}
@@ -2004,15 +3897,18 @@ export class ModelQuery<T extends BaseEntity> {
 		if (!patch || Object.keys(patch).length === 0) {
 			throw new Error("update() requires a non-empty payload");
 		}
+		// Lower each value through prepare (DateTime → ISO, @Column adapters) exactly
+		// like BaseRepository's write paths — the fluent update() must not bypass it.
 		const setPairs = Object.entries(patch).map(
-			([k, v]) => [this.#resolveColumn(k), v] as [string, unknown],
+			([k, v]) =>
+				[this.#resolveColumn(k), this.#prepareValue(k, v)] as [string, unknown],
 		);
 		const spec = {
 			kind: "update",
 			table: this.#tableName,
 			set: setPairs,
 			wheres: this.#wheresForDml(),
-			returning: returning ?? [],
+			returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
 		};
 		const compiled = compileStatementNative(spec, this.#dialect);
 		if (returning && returning.length > 0) {
@@ -2025,25 +3921,67 @@ export class ModelQuery<T extends BaseEntity> {
 		return r.rowsAffected ?? 0;
 	}
 
-	/** Execute a fluent DELETE. Returns affected rows (or rows when `returning` is set). */
+	/**
+	 * 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).
+	 */
 	async delete(
 		returning?: string[],
+	): Promise<number | Record<string, unknown>[]> {
+		if (this.#softDeletes) {
+			const spec = {
+				kind: "update",
+				table: this.#tableName,
+				set: [[this.#deletedAtColumn(), new Date().toISOString()]],
+				wheres: this.#wheresForDml(),
+				returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
+			};
+			return this.#runDml(spec, returning);
+		}
+		return this.forceDelete(returning);
+	}
+
+	/** Hard `DELETE` of the scoped rows, bypassing `@SoftDeletes` (AdonisJS/Lucid `forceDelete`). */
+	async forceDelete(
+		returning?: string[],
 	): Promise<number | Record<string, unknown>[]> {
 		const spec = {
 			kind: "delete",
 			table: this.#tableName,
 			wheres: this.#wheresForDml(),
-			returning: returning ?? [],
+			returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
 		};
-		const compiled = compileStatementNative(spec, this.#dialect);
-		if (returning && returning.length > 0) {
-			return this.#db.query<Record<string, unknown>>(
-				compiled.statements[0],
-				compiled.params,
-			);
-		}
-		const r = await this.#db.execute(compiled.statements[0], compiled.params);
-		return r.rowsAffected ?? 0;
+		return this.#runDml(spec, 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`).
+	 */
+	async restore(
+		returning?: string[],
+	): Promise<number | Record<string, unknown>[]> {
+		if (!this.#softDeletes) return 0;
+		const wheres = this.#userWheresForDml();
+		wheres.push({
+			column: this.#deletedAtColumn(),
+			operator: "IS NOT NULL",
+			value: null,
+			type: "and",
+		});
+		const spec = {
+			kind: "update",
+			table: this.#tableName,
+			set: [[this.#deletedAtColumn(), null]],
+			wheres,
+			returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
+		};
+		return this.#runDml(spec, returning);
 	}
 
 	// === Story 30.3 — increment / decrement already implemented? check ================================
@@ -2090,6 +4028,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 {
@@ -2098,11 +4086,20 @@ 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(
@@ -2111,7 +4108,7 @@ export class ModelQuery<T extends BaseEntity> {
 		leftOrBuild: string | ((j: JoinBuilder) => void),
 		right?: string,
 	): this {
-		const tq = this.#quote(table);
+		const tq = this.#quoteCol(table);
 		if (typeof leftOrBuild === "function") {
 			const jb: JoinBuilder = {
 				parts: [],
@@ -2123,28 +4120,61 @@ export class ModelQuery<T extends BaseEntity> {
 					this.parts.push({ kind: "and", left: l, right: r });
 					return this;
 				},
-				andOnVal(l: string, _v: unknown) {
-					this.parts.push({ kind: "and", left: l, right: "?" });
+				orOn(l: string, r: string) {
+					this.parts.push({ kind: "or", left: l, right: r });
+					return this;
+				},
+				onVal(l: string, v: unknown) {
+					this.parts.push({ kind: "and", left: l, value: { v } });
+					return this;
+				},
+				andOnVal(l: string, v: unknown) {
+					this.parts.push({ kind: "and", left: l, value: { v } });
+					return this;
+				},
+				orOnVal(l: string, v: unknown) {
+					this.parts.push({ kind: "or", left: l, value: { v } });
 					return this;
 				},
 			};
 			leftOrBuild(jb);
+			// Collect the bound values in placeholder order as the fragment is built.
+			const params: unknown[] = [];
 			const on = jb.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.value) {
+						// A BASE-table column runs the full model prepare (DateTime→ISO +
+						// @Column adapters/casts), keyed by its property. A FOREIGN join
+						// column must NOT borrow the root model's adapter for a same-named
+						// column on another table — apply only universal type-lowering
+						// (Date/DateTime→ISO), matching Knex's model-agnostic join binding.
+						const dot = p.left.lastIndexOf(".");
+						const tablePrefix = dot >= 0 ? p.left.slice(0, dot) : "";
+						const leaf = dot >= 0 ? p.left.slice(dot + 1) : p.left;
+						const isBaseColumn =
+							tablePrefix === "" || sameTableRef(tablePrefix, this.#tableName);
+						params.push(
+							isBaseColumn
+								? this.#prepareValue(leaf, p.value.v)
+								: lowerJoinValue(p.value.v),
+						);
+						return `${prefix} ${this.#quoteCol(p.left)} = ?`;
+					}
+					return `${prefix} ${this.#quoteCol(p.left)} = ${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)
 			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(leftOrBuild)} = ${this.#quoteCol(right)}`,
+			params: [],
+		});
 		return this;
 	}
 
@@ -2190,7 +4220,8 @@ export class ModelQuery<T extends BaseEntity> {
 	 * still rejected because the DML compiler's WHERE lowering does not yet
 	 * handle nested sub-queries or correlated EXISTS.
 	 */
-	#wheresForDml(): Array<Record<string, unknown>> {
+	/** The user's own WHERE predicates mapped for DML (no soft-delete scope). */
+	#userWheresForDml(): Array<Record<string, unknown>> {
 		const out: Array<Record<string, unknown>> = [];
 		for (const w of this.#wheres) {
 			if ("kind" in w) {
@@ -2218,6 +4249,50 @@ export class ModelQuery<T extends BaseEntity> {
 		return out;
 	}
 
+	#wheresForDml(): Array<Record<string, unknown>> {
+		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",
+				});
+			}
+		}
+		return out;
+	}
+
+	/** 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.#db.query<Record<string, unknown>>(
+				compiled.statements[0],
+				compiled.params,
+			);
+		}
+		const r = await this.#db.execute(compiled.statements[0], compiled.params);
+		return r.rowsAffected ?? 0;
+	}
+
 	/**
 	 * !!! DEBUG ONLY — DO NOT USE FOR EXECUTION !!!
 	 *
@@ -2255,6 +4330,7 @@ export class ModelQuery<T extends BaseEntity> {
 			this.#resolveColumn,
 			false,
 			this.#dialect,
+			this.#prepareValue,
 		);
 		callback(scratch);
 		return { type, kind: "group", conditions: scratch.#wheres };
@@ -2308,19 +4384,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.