@c9up/atlas 0.1.19 → 0.2.1

package/dist/ModelQuery.js

@@ -7,9 +7,19 @@
  * Builds SQL fluently and executes against the database connection.
  */
 var _a;
-import { getColumnMetadata, getEntityMetadata, getPrimaryKey, getRelationMetadata, hasSoftDeletes, } from "./decorators/entity.js";
+import { dateTimeAtlasAdapter } from "@c9up/chronos/atlas";
+import { 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, wrapAdapterError, } from "./BaseRepository.js";
+import { ensureEntityMetadata, getColumnMetadata, getDateColumnConfig, getPrimaryKey, getRelationMetadata, hasSoftDeletes, } from "./decorators/entity.js";
 import { fireHooks } from "./decorators/hooks.js";
-import { compileStatementNative, getAtlasDialect, } from "./query/native.js";
+import { getNamingStrategy } from "./naming/NamingStrategy.js";
+import { DmlBuilder } from "./query/DmlBuilder.js";
+import { compiledStatement, interpolateQuery, } from "./query/interpolate.js";
+import { compileStatementNative, getAtlasDialect, normalizeDialect, } from "./query/native.js";
+import { negateOperator } from "./query/operators.js";
+import { RawSql } from "./query/QueryBuilder.js";
 import { camelToSnake, snakeToCamel } from "./utils/casing.js";
 /**
  * Comparison operators allowed in `whereExpr`'s raw 4-arg form (where
@@ -28,6 +38,49 @@ const WHEREEXPR_OPERATORS = new Set([
     "LIKE",
     "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([
+    "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) {
     let depth = 0;
@@ -42,6 +95,97 @@ function hasBalancedParens(s) {
     }
     return depth === 0;
 }
+/**
+ * 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) {
+    const map = new Map();
+    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) {
+    const prepares = new Map();
+    // 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();
+    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) {
+    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) {
+    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, modelTable) {
+    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;
+}
 /** Set an empty relation value on every parent and return no related rows. */
 function assignEmptyRelation(entities, relationName, single) {
     for (const e of entities)
@@ -68,10 +212,12 @@ function buildThroughToParent(throughRows, secondLocal, firstKey, err) {
     return throughToParent;
 }
 /**
- * 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
@@ -82,7 +228,7 @@ function buildThroughToParent(throughRows, secondLocal, firstKey, err) {
  * `__internal: true` flag on the call — not exposed in the public types.
  */
 let atlasStrictMode;
-/** 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) {
     atlasStrictMode = enabled;
 }
@@ -120,14 +266,38 @@ export class Paginator {
     meta;
     #baseUrl;
     #queryString = {};
-    constructor(items, base) {
+    #metaKeys;
+    constructor(items, base, metaKeys) {
         this.items = items;
         const lastPage = Math.max(1, Math.ceil(base.total / base.perPage));
         this.meta = { ...base, lastPage, firstPage: 1 };
+        this.#metaKeys = metaKeys;
     }
     all() {
         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() {
+        return this.meta.total;
+    }
+    /** Rows per page. */
+    get perPage() {
+        return this.meta.perPage;
+    }
+    /** The current page number. */
+    get currentPage() {
+        return this.meta.currentPage;
+    }
+    /** The last page number. */
+    get lastPage() {
+        return this.meta.lastPage;
+    }
+    /** The first page number (always 1). */
+    get firstPage() {
+        return this.meta.firstPage;
+    }
     /** True when there is more than one page of results (AdonisJS `hasPages`). */
     get hasPages() {
         return this.meta.lastPage > 1;
@@ -145,7 +315,9 @@ export class Paginator {
                 picked[f] = item[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) {
         this.#baseUrl = url;
@@ -155,26 +327,70 @@ export class Paginator {
         this.#queryString = qs;
         return this;
     }
-    toJSON() {
-        const meta = {
-            ...this.meta,
-        };
+    /**
+     * Build the URL for a page number, honouring `baseUrl` + `queryString`.
+     * Returns `''` when no `baseUrl` was set (AdonisJS `getUrl`).
+     */
+    getUrl(page) {
+        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() {
+        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() {
+        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, end) {
+        const lo = Math.max(1, start);
+        const hi = Math.min(this.meta.lastPage, end);
+        const range = [];
+        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() {
+        const raw = { ...this.meta };
         if (this.#baseUrl) {
-            const build = (page) => {
-                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, meta };
+            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 = {};
+        for (const [k, v] of Object.entries(raw))
+            meta[keys[k] ?? k] = v;
+        return meta;
+    }
+    toJSON() {
+        return { data: this.items, meta: this.#buildMeta() };
     }
 }
 /** Safe deep-clone for clause containers. `structuredClone` handles the shapes we use. */
@@ -193,20 +409,46 @@ export class ModelQuery {
     #orderBys = [];
     #select = ["*"];
     #limit;
+    /** Top-N-per-parent limit for a has-many preload (Lucid `groupLimit`). */
+    #groupLimit;
+    /** ORDER BY for the per-parent window (Lucid `groupOrderBy`). */
+    #groupOrderBy;
     #offset;
     #preloads = new Map();
+    // Per-query row transformers (Adonis Lucid `rowTransformer`). Stored via a
+    // method-signature wrapper (not a bare `(row: T) => void` property) so T stays
+    // in a bivariant position — a function-typed property would force ModelQuery<T>
+    // invariant and break the `this: ModelClass<T>` bound on every static finder.
+    #rowTransformers = [];
     /** Correlated subquery projections (withCount / withAggregate). */
     #selectSubqueries = [];
+    /** Raw / subquery SELECT fragments carrying their own params (Lucid `select(raw)`, `select(subquery.as())`). */
+    #selectRaw = [];
+    /** Caller-facing statement timeout in ms (Lucid `timeout(ms)`), applied via a race in exec. */
+    #timeoutMs;
+    /** `timeout(ms, { cancel: true })` — also apply a SERVER-side statement timeout. */
+    #cancelTimeout = false;
+    /** Columns from a chainable `.returning(...)` on a lazy DML builder. */
+    #dmlReturning = [];
     /** Alias stored by `.as()` — consumed when this query is used as a withCount/withAggregate sub-builder. */
     #subqueryAlias;
     /** Raw JOIN fragments — Story 29.4. */
     #joins = [];
-    /** Row lock mode — Story 30.8. */
+    /** Row lock base mode — Story 30.8. */
     #lockMode = null;
+    /** Optional lock modifier (SKIP LOCKED / NOWAIT), composed onto {@link #lockMode}. */
+    #lockModifier = null;
+    /** Context threaded onto every hydrated instance's `$sideloaded` — AdonisJS `sideload`. */
+    #sideloaded = null;
     /** Per-query debug flag — Story 29.11. */
     #debugFlag = false;
+    /** Metadata attached to the db:query event (Adonis Lucid `reporterData`). */
+    #reporterData;
+    /** SQL comments prepended to the compiled query (Lucid/Knex `comment`). */
+    #comments = [];
     /** Distinct flag — Story 29.5. */
     #distinct = false;
+    #distinctOn = [];
     /** GROUP BY columns (Lucid parity). */
     #groupBy = [];
     /** HAVING clauses — structured + raw (Lucid parity). */
@@ -217,9 +459,19 @@ export class ModelQuery {
     #unions = [];
     /** m2m pivot-table WHERE constraints — applied to the pivot lookup, not the related query. */
     #pivotWheres = [];
+    /** Extra pivot columns requested at query time (Lucid `pivotColumns([...])`). */
+    #extraPivotColumns = [];
+    /**
+     * Deferred builder for a lazy m2m `related().query()` EXISTS predicate. Set by
+     * the relation proxy's scoped query; invoked at `#buildSpec()` time with the
+     * 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;
     /** SQL dialect for compilation — inherited from the owning BaseRepository. */
     #dialect;
-    constructor(tableName, db, hydrateFn, entityClass, resolveColumn = (c) => c, softDeletes = false, dialect = getAtlasDialect()) {
+    constructor(tableName, db, hydrateFn, entityClass, resolveColumn = (c) => c, softDeletes = false, dialect = getAtlasDialect(), prepareValue = (_c, v) => v, onDomainEvents) {
         this.#tableName = tableName;
         this.#db = db;
         this.#hydrateFn = hydrateFn;
@@ -227,7 +479,13 @@ export class ModelQuery {
         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;
+    /** Domain-event bus threaded from the owning repository — propagated to preload repos. */
+    #onDomainEvents;
     /** Include soft-deleted rows in the result (default behavior excludes them). */
     withTrashed() {
         this.#softScope = "with-trashed";
@@ -238,6 +496,24 @@ export class ModelQuery {
         this.#softScope = "only-trashed";
         return this;
     }
+    /**
+     * Apply the first `[guard, callback]` whose guard is truthy (Adonis Lucid
+     * `match`); a trailing bare callback is the default, run when none matched.
+     */
+    match(...blocks) {
+        for (const block of blocks) {
+            if (typeof block === "function") {
+                block(this);
+                return this;
+            }
+            const [guard, callback] = block;
+            if (guard) {
+                callback(this);
+                return this;
+            }
+        }
+        return this;
+    }
     /**
      * Eager-load a relation (AdonisJS-style).
      * Relations are never loaded automatically — you must call .preload() explicitly.
@@ -250,13 +526,97 @@ export class ModelQuery {
         this.#preloads.set(relationName, callback);
         return this;
     }
-    /** Select specific columns (default: `*`). Accepts a comma-separated string or an array. */
-    select(columns) {
-        this.#select = Array.isArray(columns)
-            ? columns
-            : columns.split(",").map((c) => c.trim());
+    /**
+     * Eager-load a relation only if it hasn't been registered yet (Adonis Lucid
+     * `preloadOnce`) — a later `preload`/`preloadOnce` for the same relation is
+     * ignored, so a shared scope can safely add a preload without clobbering one
+     * the caller already set.
+     */
+    preloadOnce(relationName, callback) {
+        if (!this.#preloads.has(relationName)) {
+            this.#preloads.set(relationName, callback);
+        }
+        return this;
+    }
+    /**
+     * Register a callback run for every hydrated instance after loading (preloads
+     * included) but before the query resolves (Adonis Lucid `rowTransformer`). The
+     * callback mutates the instance in place — decorate rows with per-query
+     * computed values without a model hook/accessor. Multiple transformers run in
+     * registration order.
+     */
+    rowTransformer(callback) {
+        this.#rowTransformers.push({ run: callback });
         return this;
     }
+    /**
+     * Select columns (default: `*`). The model query builder extends the database
+     * query builder's `select` surface (Lucid parity): bare names, multiple args,
+     * a comma-separated string, an array, an `{ alias: 'column' }` object map, a
+     * `db.raw(...)` fragment, and a named subquery — `select(subquery.as('x'))`.
+     * Plain columns are resolved to their DB column (honouring `@Column`).
+     */
+    select(...columns) {
+        const plain = [];
+        for (const col of columns) {
+            if (typeof col === "string") {
+                plain.push(...col.split(",").map((c) => c.trim()));
+            }
+            else if (Array.isArray(col)) {
+                plain.push(...col);
+            }
+            else if (col instanceof RawSql) {
+                // Lucid `select(db.raw(sql, bindings))` — verbatim fragment + params.
+                this.#selectRaw.push({ sql: col.sql, params: [...col.params] });
+            }
+            else if (col instanceof _a) {
+                // Lucid `select(subquery.as('alias'))` — a correlated subquery column.
+                const alias = col.#subqueryAlias;
+                if (!alias) {
+                    throw new Error("select(subquery) requires the subquery to be named with .as('alias')");
+                }
+                const { sql, params } = col.#compiledNative();
+                this.#selectRaw.push({
+                    sql: `(${sql}) AS ${this.#quoteAliasName(alias)}`,
+                    params,
+                });
+            }
+            else {
+                for (const [alias, expr] of Object.entries(col)) {
+                    plain.push(`${expr} AS ${alias}`);
+                }
+            }
+        }
+        if (plain.length > 0) {
+            this.#select = plain.map((c) => this.#resolveSelect(c));
+        }
+        return this;
+    }
+    /** Validate + dialect-quote a bare alias identifier. */
+    #quoteAliasName(alias) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid alias '${alias}' — expected a bare identifier.`);
+        }
+        const q = this.#dialect === "mysql" ? "`" : '"';
+        return `${q}${alias}${q}`;
+    }
+    /**
+     * Resolve a bare model-property select/returning target to its DB column
+     * (honouring `@Column({ columnName })`), leaving expressions / aliases /
+     * 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) {
+        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(columnOrCb, operatorOrValue, value) {
         if (typeof columnOrCb === "function") {
             this.#wheres.push(this.#buildGroup("and", columnOrCb));
@@ -289,33 +649,123 @@ export class ModelQuery {
         });
         return this;
     }
-    /** `WHERE col != ?` — negation of `where`. */
-    whereNot(column, value) {
+    andWhere(columnOrCb, operatorOrValue, value) {
+        // 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, value);
+    }
+    /** Alias of {@link whereNot} (Lucid parity). */
+    andWhereNot(column, value) {
+        return this.whereNot(column, value);
+    }
+    /** Alias of {@link whereIn} (Lucid parity). */
+    andWhereIn(column, values) {
+        return this.whereIn(column, values);
+    }
+    /** Alias of {@link whereNotIn} (Lucid parity). */
+    andWhereNotIn(column, values) {
+        return this.whereNotIn(column, values);
+    }
+    /** Alias of {@link whereNull} (Lucid parity). */
+    andWhereNull(column) {
+        return this.whereNull(column);
+    }
+    /** Alias of {@link whereNotNull} (Lucid parity). */
+    andWhereNotNull(column) {
+        return this.whereNotNull(column);
+    }
+    /** Alias of {@link whereBetween} (Lucid parity). */
+    andWhereBetween(column, range) {
+        return this.whereBetween(column, range);
+    }
+    /** Alias of {@link whereNotBetween} (Lucid parity). */
+    andWhereNotBetween(column, range) {
+        return this.whereNotBetween(column, range);
+    }
+    /** Alias of {@link whereLike} (Lucid parity). */
+    andWhereLike(column, pattern) {
+        return this.whereLike(column, pattern);
+    }
+    /** Alias of {@link whereILike} (Lucid parity). */
+    andWhereILike(column, pattern) {
+        return this.whereILike(column, pattern);
+    }
+    /** Alias of {@link whereColumn} (Lucid parity). */
+    andWhereColumn(left, operator, right) {
+        return this.whereColumn(left, operator, right);
+    }
+    whereNot(columnOrCbOrObj, operatorOrValue, value) {
+        if (typeof columnOrCbOrObj === "function") {
+            this.#wheres.push({
+                ...this.#buildGroup("and", columnOrCbOrObj),
+                negated: true,
+            });
+            return this;
+        }
+        if (typeof columnOrCbOrObj === "object") {
+            for (const [col, val] of Object.entries(columnOrCbOrObj)) {
+                this.#wheres.push({
+                    type: "and",
+                    column: this.#resolveColumn(col),
+                    operator: "!=",
+                    value: this.#prep(col, val),
+                });
+            }
+            return this;
+        }
+        if (value === undefined) {
+            this.#wheres.push({
+                type: "and",
+                column: this.#resolveColumn(columnOrCbOrObj),
+                operator: "!=",
+                value: this.#prep(columnOrCbOrObj, operatorOrValue),
+            });
+            return this;
+        }
+        // (column, operator, value): NOT (col <op> value) via a negated group so any
+        // operator negates correctly without an operator-inversion table.
+        const col = columnOrCbOrObj;
+        const op = operatorOrValue;
         this.#wheres.push({
-            type: "and",
-            column: this.#resolveColumn(column),
-            operator: "!=",
-            value,
+            ...this.#buildGroup("and", (q) => q.where(col, op, value)),
+            negated: true,
         });
         return this;
     }
-    /** `WHERE col IN (...)` — accepts an array of values OR a `ModelQuery` subquery source. */
-    whereIn(column, source) {
+    whereIn(columnOrColumns, source) {
+        // Tuple form (Lucid `whereIn(['id','email'], [[1,'a@b.com']])`).
+        if (Array.isArray(columnOrColumns)) {
+            const cols = columnOrColumns.map((c) => this.#resolveColumn(c));
+            const rows = (Array.isArray(source) ? source : []).map((r) => (Array.isArray(r) ? r : [r]).map((v, j) => this.#prep(cols[j] ?? "", v)));
+            this.#wheres.push({
+                type: "and",
+                kind: "inTuple",
+                columns: cols,
+                rows,
+                negated: false,
+            });
+            return this;
+        }
         if (source instanceof _a) {
             this.#wheres.push({
                 type: "and",
                 kind: "inSub",
                 negated: false,
-                column: this.#resolveColumn(column),
+                column: this.#resolveColumn(columnOrColumns),
                 subquery: source.#buildSpec(),
             });
             return this;
         }
         this.#wheres.push({
             type: "and",
-            column: this.#resolveColumn(column),
+            column: this.#resolveColumn(columnOrColumns),
             operator: "IN",
-            value: [...source],
+            value: this.#prep(columnOrColumns, [...source]),
         });
         return this;
     }
@@ -335,7 +785,7 @@ export class ModelQuery {
             type: "and",
             column: this.#resolveColumn(column),
             operator: "NOT IN",
-            value: [...source],
+            value: this.#prep(column, [...source]),
         });
         return this;
     }
@@ -345,7 +795,7 @@ export class ModelQuery {
             type: "and",
             column: this.#resolveColumn(column),
             operator: "BETWEEN",
-            value: [...range],
+            value: this.#prep(column, [...range]),
         });
         return this;
     }
@@ -355,7 +805,7 @@ export class ModelQuery {
             type: "and",
             column: this.#resolveColumn(column),
             operator: "NOT BETWEEN",
-            value: [...range],
+            value: this.#prep(column, [...range]),
         });
         return this;
     }
@@ -412,7 +862,7 @@ export class ModelQuery {
             type: "or",
             column: this.#resolveColumn(column),
             operator: "!=",
-            value,
+            value: this.#prep(column, value),
         });
         return this;
     }
@@ -432,7 +882,7 @@ export class ModelQuery {
             type: "or",
             column: this.#resolveColumn(column),
             operator: "IN",
-            value: [...source],
+            value: this.#prep(column, [...source]),
         });
         return this;
     }
@@ -452,7 +902,7 @@ export class ModelQuery {
             type: "or",
             column: this.#resolveColumn(column),
             operator: "NOT IN",
-            value: [...source],
+            value: this.#prep(column, [...source]),
         });
         return this;
     }
@@ -462,7 +912,7 @@ export class ModelQuery {
             type: "or",
             column: this.#resolveColumn(column),
             operator: "BETWEEN",
-            value: [...range],
+            value: this.#prep(column, [...range]),
         });
         return this;
     }
@@ -472,7 +922,7 @@ export class ModelQuery {
             type: "or",
             column: this.#resolveColumn(column),
             operator: "NOT BETWEEN",
-            value: [...range],
+            value: this.#prep(column, [...range]),
         });
         return this;
     }
@@ -535,15 +985,47 @@ export class ModelQuery {
      * Not exported from the package barrel — only accessible inside the Atlas
      * codebase via direct ModelQuery instance access.
      */
-    #pushWhereRaw(sql, bindings = []) {
+    #pushWhereRaw(sql, bindings = [], type = "and") {
         this.#wheres.push({
-            type: "and",
+            type,
             kind: "raw",
             sql,
             bindings: [...bindings],
         });
         return this;
     }
+    /** Alias of {@link whereRaw} (Lucid parity). Subject to the same strict-mode gate. */
+    andWhereRaw(sql, bindings = []) {
+        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, bindings = []) {
+        this.#assertRawAllowed("orWhereRaw");
+        return this.#pushWhereRaw(sql, bindings, "or");
+    }
+    /** Shared strict-mode gate for the raw WHERE entry points. */
+    #assertRawAllowed(method) {
+        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) {
+        this.#pivotExists = builder;
+        return this;
+    }
     whereExpr(column, operatorOrExtra, operatorOrValue, maybeValue) {
         // 3-arg form: whereExpr(col, op, value)
         // 4-arg form: whereExpr(col, extraExpr, op, value)
@@ -562,6 +1044,18 @@ export class ModelQuery {
             if (!hasBalancedParens(extra)) {
                 throw new Error(`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
@@ -578,9 +1072,16 @@ export class ModelQuery {
         // 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;
     }
     /**
@@ -589,6 +1090,214 @@ export class ModelQuery {
      * 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) {
+        return this.#pushExists("and", false, subquery);
+    }
+    /** Alias of {@link whereExists} (Lucid parity). */
+    andWhereExists(subquery) {
+        return this.#pushExists("and", false, subquery);
+    }
+    /** `OR EXISTS (subquery)` (Lucid parity). */
+    orWhereExists(subquery) {
+        return this.#pushExists("or", false, subquery);
+    }
+    /** `WHERE NOT EXISTS (subquery)` (Lucid parity). */
+    whereNotExists(subquery) {
+        return this.#pushExists("and", true, subquery);
+    }
+    /** Alias of {@link whereNotExists} (Lucid parity). */
+    andWhereNotExists(subquery) {
+        return this.#pushExists("and", true, subquery);
+    }
+    /** `OR NOT EXISTS (subquery)` (Lucid parity). */
+    orWhereNotExists(subquery) {
+        return this.#pushExists("or", true, subquery);
+    }
+    whereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
+    }
+    andWhereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPathArgs("and", column, path, operatorOrValue, value);
+    }
+    orWhereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPathArgs("or", column, path, operatorOrValue, value);
+    }
+    /** Resolve the optional-operator JSONPath form, then push (default op `=`). */
+    #pushJsonPathArgs(type, column, path, operatorOrValue, value) {
+        const [operator, val] = value === undefined
+            ? ["=", operatorOrValue]
+            : [String(operatorOrValue), value];
+        return this.#pushJson(type, false, "path", column, val, path, String(operator));
+    }
+    /**
+     * Structural JSON match (Lucid `whereJson`) — the column's JSON must equal
+     * `value` (canonical comparison on Postgres/MySQL). AND is the default.
+     */
+    whereJson(column, value) {
+        return this.#pushJson("and", false, "equals", column, value);
+    }
+    /** Alias of {@link whereJson} (Lucid `andWhereJson`). */
+    andWhereJson(column, value) {
+        return this.#pushJson("and", false, "equals", column, value);
+    }
+    /** OR form of {@link whereJson} (Lucid `orWhereJson`). */
+    orWhereJson(column, value) {
+        return this.#pushJson("or", false, "equals", column, value);
+    }
+    /** WHERE NOT structural JSON match (Lucid `whereNotJson`). */
+    whereNotJson(column, value) {
+        return this.#pushJson("and", true, "equals", column, value);
+    }
+    /** Alias of {@link whereNotJson} (Lucid `andWhereNotJson`). */
+    andWhereNotJson(column, value) {
+        return this.#pushJson("and", true, "equals", column, value);
+    }
+    /** OR NOT structural JSON match (Lucid `orWhereNotJson`). */
+    orWhereNotJson(column, value) {
+        return this.#pushJson("or", true, "equals", column, value);
+    }
+    /**
+     * `WHERE <col> @> ?` — the JSON column contains `value` (Lucid/Knex
+     * `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, value) {
+        return this.#pushJson("and", false, "superset", column, value);
+    }
+    /** Alias of {@link whereJsonSupersetOf} (Lucid parity). */
+    andWhereJsonSupersetOf(column, value) {
+        return this.#pushJson("and", false, "superset", column, value);
+    }
+    /** `OR <col> @> ?` (Lucid parity). See {@link whereJsonSupersetOf}. */
+    orWhereJsonSupersetOf(column, value) {
+        return this.#pushJson("or", false, "superset", column, value);
+    }
+    /** `WHERE NOT (<col> @> ?)` (Lucid parity). */
+    whereNotJsonSupersetOf(column, value) {
+        return this.#pushJson("and", true, "superset", column, value);
+    }
+    /** `OR NOT (<col> @> ?)` (Lucid parity). */
+    orWhereNotJsonSupersetOf(column, value) {
+        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, value) {
+        return this.#pushJson("and", false, "subset", column, value);
+    }
+    /** Alias of {@link whereJsonSubsetOf} (Lucid parity). */
+    andWhereJsonSubsetOf(column, value) {
+        return this.#pushJson("and", false, "subset", column, value);
+    }
+    /** `OR <col> <@ ?` (Lucid parity). See {@link whereJsonSubsetOf}. */
+    orWhereJsonSubsetOf(column, value) {
+        return this.#pushJson("or", false, "subset", column, value);
+    }
+    /** `WHERE NOT (<col> <@ ?)` (Lucid parity). */
+    whereNotJsonSubsetOf(column, value) {
+        return this.#pushJson("and", true, "subset", column, value);
+    }
+    /** `OR NOT (<col> <@ ?)` (Lucid parity). */
+    orWhereNotJsonSubsetOf(column, value) {
+        return this.#pushJson("or", true, "subset", column, value);
+    }
+    // Lucid's canonical containment names drop the `Of` suffix — kept as aliases.
+    /** Lucid `whereJsonSuperset` (alias of {@link whereJsonSupersetOf}). */
+    whereJsonSuperset(column, value) {
+        return this.#pushJson("and", false, "superset", column, value);
+    }
+    /** Lucid `andWhereJsonSuperset`. */
+    andWhereJsonSuperset(column, value) {
+        return this.#pushJson("and", false, "superset", column, value);
+    }
+    /** Lucid `orWhereJsonSuperset`. */
+    orWhereJsonSuperset(column, value) {
+        return this.#pushJson("or", false, "superset", column, value);
+    }
+    /** Lucid `whereNotJsonSuperset`. */
+    whereNotJsonSuperset(column, value) {
+        return this.#pushJson("and", true, "superset", column, value);
+    }
+    /** Lucid `orWhereNotJsonSuperset`. */
+    orWhereNotJsonSuperset(column, value) {
+        return this.#pushJson("or", true, "superset", column, value);
+    }
+    /** Lucid `whereJsonSubset` (alias of {@link whereJsonSubsetOf}). */
+    whereJsonSubset(column, value) {
+        return this.#pushJson("and", false, "subset", column, value);
+    }
+    /** Lucid `andWhereJsonSubset`. */
+    andWhereJsonSubset(column, value) {
+        return this.#pushJson("and", false, "subset", column, value);
+    }
+    /** Lucid `orWhereJsonSubset`. */
+    orWhereJsonSubset(column, value) {
+        return this.#pushJson("or", false, "subset", column, value);
+    }
+    /** Lucid `whereNotJsonSubset`. */
+    whereNotJsonSubset(column, value) {
+        return this.#pushJson("and", true, "subset", column, value);
+    }
+    /** Lucid `orWhereNotJsonSubset`. */
+    orWhereNotJsonSubset(column, value) {
+        return this.#pushJson("or", true, "subset", column, value);
+    }
+    #pushJson(type, negated, jsonOp, column, value, path, operator) {
+        // A JSONPath is bound, not interpolated, so injection is not the concern
+        // here — a clear early error for a malformed path is. Lucid/Knex paths
+        // 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, negated, subquery) {
+        // `#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, operator, right) {
         return this.#whereColumn("and", left, operator, right);
     }
@@ -596,7 +1305,19 @@ export class ModelQuery {
     orWhereColumn(left, operator, right) {
         return this.#whereColumn("or", left, operator, right);
     }
-    #whereColumn(type, left, operator, right) {
+    /** `WHERE NOT (left <op> right)` — negation of {@link whereColumn} (Lucid parity). */
+    whereNotColumn(left, operator, right) {
+        return this.#whereColumn("and", left, operator, right, true);
+    }
+    /** Alias of {@link whereNotColumn} (Lucid parity). */
+    andWhereNotColumn(left, operator, right) {
+        return this.#whereColumn("and", left, operator, right, true);
+    }
+    /** `OR NOT (left <op> right)` (Lucid parity). */
+    orWhereNotColumn(left, operator, right) {
+        return this.#whereColumn("or", left, operator, right, true);
+    }
+    #whereColumn(type, left, operator, right, negated = false) {
         if (!WHEREEXPR_OPERATORS.has(operator)) {
             throw new Error(`whereColumn: operator '${operator}' is not allowed. Use one of ${[...WHEREEXPR_OPERATORS].join(" ")}.`);
         }
@@ -606,7 +1327,7 @@ export class ModelQuery {
         // `[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) => {
-            const resolved = this.#resolveColumn(name);
+            const resolved = this.#resolveColumnReference(name);
             if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(resolved)) {
                 throw new Error(`whereColumn: '${name}' is not a valid column identifier ([table.]column, alphanumeric + underscore).`);
             }
@@ -617,10 +1338,45 @@ export class ModelQuery {
                 .map((part) => this.#quote(part))
                 .join(".");
         };
-        const sql = `${safe(left)} ${operator} ${safe(right)}`;
+        const predicate = `${safe(left)} ${operator} ${safe(right)}`;
+        // Both operands are already validated identifiers and the operator is
+        // allow-listed, so wrapping in NOT(...) adds no new surface.
+        const sql = negated ? `NOT (${predicate})` : predicate;
         this.#wheres.push({ type, kind: "raw", sql, bindings: [] });
         return this;
     }
+    /**
+     * Resolve a column reference that may legitimately point at a table other
+     * than this query's own.
+     *
+     * `#resolveColumn` only knows the entity's own columns, so it rejects
+     * anything qualified. That is right for a value predicate, but wrong for a
+     * column-to-column one: a correlated subquery
+     * (`whereExists(post.query().whereColumn('posts.user_id', '=', 'users.id'))`)
+     * and a joined query both have to name another table, and atlas cannot know
+     * that table's columns. So: an unqualified name resolves as usual (typos
+     * still get the helpful error), and a `table.column` naming a different
+     * table passes through — validated against the identifier charset here and
+     * quoted segment by segment by the caller, never interpolated loose. A typo
+     * in that case surfaces as a database error rather than an atlas one, which
+     * is the unavoidable cost of referencing a table we have no metadata for.
+     */
+    #resolveColumnReference(name) {
+        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)}`;
+        }
+        // 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.
@@ -645,6 +1401,14 @@ export class ModelQuery {
         this.#wheres.push(this.#buildExistsClause("or", true, relationName, callback));
         return this;
     }
+    /** Alias of {@link whereHas} (Lucid parity) — `whereHas` is already AND. */
+    andWhereHas(relationName, callback) {
+        return this.whereHas(relationName, callback);
+    }
+    /** Alias of {@link whereDoesntHave} (Lucid parity). */
+    andWhereDoesntHave(relationName, callback) {
+        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>)
@@ -663,6 +1427,19 @@ export class ModelQuery {
         this.#wheres.push(this.#buildExistsClause("and", true, relationName));
         return this;
     }
+    /** `OR NOT EXISTS (...)` — the OR form of {@link doesntHave} (Lucid parity). */
+    orDoesntHave(relationName) {
+        this.#wheres.push(this.#buildExistsClause("or", true, relationName));
+        return this;
+    }
+    /** Alias of {@link has} (Lucid parity) — `has` is already AND. */
+    andHas(relationName, countOp, countThreshold) {
+        return this.has(relationName, countOp, countThreshold);
+    }
+    /** Alias of {@link doesntHave} (Lucid parity). */
+    andDoesntHave(relationName) {
+        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`.
@@ -698,23 +1475,25 @@ export class ModelQuery {
     // --- Top-level scalar executors (Story 29.5) ---
     /** `SELECT COUNT(col)` — executes and returns the scalar. `col` defaults to `*`. */
     async count(column = "*") {
-        const expr = column === "*" ? "COUNT(*)" : `COUNT(${this.#quoteCol(column)})`;
+        const expr = column === "*"
+            ? "COUNT(*)"
+            : `COUNT(${this.#quoteCol(this.#resolveColumn(column))})`;
         return Number((await this.#runScalar(expr)) ?? 0);
     }
     async sum(column) {
-        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) {
-        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) {
-        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) {
-        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);
     }
     /**
@@ -741,35 +1520,150 @@ export class ModelQuery {
         this.#selectSubqueries.push(this.#buildRelationSubquery(relationName, callback, "aggregate", relationName));
         return this;
     }
-    orderBy(column, direction = "asc") {
-        this.#orderBys.push({ column: this.#resolveColumn(column), direction });
+    orderBy(columnOrTerms, direction = "asc") {
+        // A raw fragment (e.g. `db.ref('posts.created_at')`) orders verbatim.
+        if (columnOrTerms instanceof RawSql) {
+            const dir = direction === "desc" ? "DESC" : "ASC";
+            this.#orderBys.push({ raw: `${columnOrTerms.sql} ${dir}` });
+            return this;
+        }
+        if (Array.isArray(columnOrTerms)) {
+            for (const t of columnOrTerms) {
+                const [col, dir] = typeof t === "string"
+                    ? [t, "asc"]
+                    : [t.column, t.order ?? "asc"];
+                this.#orderBys.push({
+                    column: this.#resolveColumn(col),
+                    direction: dir,
+                });
+            }
+            return this;
+        }
+        this.#orderBys.push({
+            column: this.#resolveColumn(columnOrTerms),
+            direction,
+        });
+        return this;
+    }
+    /**
+     * `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) {
+        this.#assertRawAllowed("orderByRaw");
+        this.#orderBys.push({ raw: sql });
         return this;
     }
     /**
      * `GROUP BY col1, col2, …` (AdonisJS/Lucid `groupBy`). Columns are resolved
      * through the entity's column map (camelCase → snake_case) like `orderBy`.
-     * For a raw grouping expression, use a `whereRaw`-style construct via the
-     * fluent {@link QueryBuilder}.
+     * For a grouping expression with no typed form, see {@link groupByRaw}.
      */
     groupBy(...columns) {
         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) {
+        this.#assertRawAllowed("groupByRaw");
+        this.#groupBy.push({ raw: sql });
+        return this;
+    }
     /**
      * `HAVING <col> <op> ?` — applied after `groupBy` (AdonisJS/Lucid `having`).
-     * The column is passed verbatim to the Rust HAVING compiler, which quotes a
-     * plain identifier or accepts an allow-listed aggregate expression
-     * (`COUNT(*)`, `SUM(col)`, …) — it is NOT run through the entity column map,
-     * so aggregate expressions and result aliases both work.
+     * A bare model property is resolved through the entity column map (honouring
+     * `@Column({ columnName })`) via {@link #resolveHavingCol}; an aggregate
+     * expression (`COUNT(*)`, `SUM(col)`, …) or a result alias is left verbatim so
+     * `having` can still reference `withCount`/`withAggregate` aliases.
      */
     having(column, operator, value) {
-        this.#having.push({ column, operator, value, type: "and" });
+        this.#having.push({
+            column: this.#resolveHavingCol(column),
+            operator,
+            value: this.#prep(column, value),
+            type: "and",
+        });
         return this;
     }
+    /** HAVING col IS NULL (Lucid/Knex `havingNull`). */
+    havingNull(column) {
+        return this.#pushHaving(column, "IS NULL", null);
+    }
+    /** HAVING col IS NOT NULL (Lucid/Knex `havingNotNull`). */
+    havingNotNull(column) {
+        return this.#pushHaving(column, "IS NOT NULL", null);
+    }
+    /** HAVING col IN (...) (Lucid/Knex `havingIn`). */
+    havingIn(column, values) {
+        return this.#pushHaving(column, "IN", [...values]);
+    }
+    /** HAVING col NOT IN (...) (Lucid/Knex `havingNotIn`). */
+    havingNotIn(column, values) {
+        return this.#pushHaving(column, "NOT IN", [...values]);
+    }
+    /** HAVING col BETWEEN ? AND ? (Lucid/Knex `havingBetween`). */
+    havingBetween(column, range) {
+        return this.#pushHaving(column, "BETWEEN", [...range]);
+    }
+    /** HAVING col NOT BETWEEN ? AND ? (Lucid/Knex `havingNotBetween`). */
+    havingNotBetween(column, range) {
+        return this.#pushHaving(column, "NOT BETWEEN", [...range]);
+    }
+    /** Push a HAVING entry with a raw (non-`#prep`'d) value — for IN/BETWEEN/NULL. */
+    #pushHaving(column, operator, value) {
+        this.#having.push({
+            column: this.#resolveHavingCol(column),
+            operator,
+            value,
+            type: "and",
+        });
+        return this;
+    }
+    /**
+     * Resolve a HAVING column: a bare model property maps to its DB column
+     * (honouring `@Column({ columnName })`), but an aggregate expression
+     * (`COUNT(*)`), a result alias, or any unknown bare identifier is left verbatim
+     * so `having` can still reference `withCount`/`withAggregate` aliases.
+     */
+    #resolveHavingCol(column) {
+        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, operator, value) {
-        this.#having.push({ column, operator, value, type: "or" });
+        this.#having.push({
+            column: this.#resolveHavingCol(column),
+            operator,
+            value: this.#prep(column, value),
+            type: "or",
+        });
         return this;
     }
     /**
@@ -781,6 +1675,12 @@ export class ModelQuery {
      * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
      */
     havingRaw(sql, bindings = []) {
+        // 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,
@@ -795,48 +1695,224 @@ export class ModelQuery {
      * the outer parameter list.
      */
     union(query) {
-        this.#unions.push({ query, all: false });
+        this.#unions.push({ query: this.#resolveUnion(query), all: false });
         return this;
     }
     /** `UNION ALL (<query>)` — duplicate-preserving {@link union}. */
     unionAll(query) {
-        this.#unions.push({ query, all: true });
+        this.#unions.push({ query: this.#resolveUnion(query), all: true });
+        return this;
+    }
+    /** `INTERSECT (<query>)` — rows present in both (Lucid/Knex `intersect`). */
+    intersect(query) {
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: false,
+            op: "intersect",
+        });
         return this;
     }
+    /**
+     * `INTERSECT ALL (<query>)` — duplicate-preserving {@link intersect}.
+     *
+     * Postgres and MySQL only: SQLite's compound operators are UNION, UNION ALL,
+     * INTERSECT and EXCEPT — there is no INTERSECT ALL — so the compiler raises
+     * `E_UNSUPPORTED` there rather than emitting a syntax error.
+     */
+    intersectAll(query) {
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: true,
+            op: "intersect",
+        });
+        return this;
+    }
+    /** `EXCEPT (<query>)` — rows in this query but not the other (Lucid/Knex `except`). */
+    except(query) {
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: false,
+            op: "except",
+        });
+        return this;
+    }
+    /** `EXCEPT ALL (<query>)` — duplicate-preserving {@link except}. Not on SQLite; see {@link intersectAll}. */
+    exceptAll(query) {
+        this.#unions.push({
+            query: this.#resolveUnion(query),
+            all: true,
+            op: "except",
+        });
+        return this;
+    }
+    /** A compound-query arg — an explicit ModelQuery OR a callback building one on this model. */
+    #resolveUnion(query) {
+        if (typeof query !== "function")
+            return query;
+        const sub = this.#freshQuery();
+        query(sub);
+        return sub;
+    }
+    /** A fresh, empty query on the SAME model + connection (for compound callbacks). */
+    #freshQuery() {
+        return new _a(this.#tableName, this.#db, this.#hydrateFn, this.#entityClass, this.#resolveColumn, this.#softDeletes, this.#dialect, this.#prepareValue, this.#onDomainEvents);
+    }
     /**
      * `WITH <name> AS (<query>)` — register a Common Table Expression
      * (AdonisJS/Lucid `with`). The CTE name is validated as an identifier; the
      * sub-query is compiled and its bindings are re-indexed into the outer list.
      */
     with(name, query) {
+        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, query, columns) {
+        return this.#pushCte("withRecursive", name, query, {
+            recursive: true,
+            columns,
+        });
+    }
+    /**
+     * `WITH <name> AS MATERIALIZED (<query>)` — force the CTE to be evaluated
+     * once and stashed (Lucid/Knex `withMaterialized`).
+     *
+     * Postgres 12+ and SQLite 3.35+ only; MySQL has no such hint and the
+     * compiler raises `E_UNSUPPORTED` rather than emitting a syntax error.
+     */
+    withMaterialized(name, query) {
+        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, query) {
+        return this.#pushCte("withNotMaterialized", name, query, {
+            materialized: false,
+        });
+    }
+    #pushCte(method, name, query, options) {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
-            throw new Error(`with(): CTE name '${name}' is not a valid identifier`);
+            throw new Error(`${method}(): CTE name '${name}' is not a valid identifier`);
         }
-        this.#ctes.push({ name, query });
+        this.#ctes.push({ name, query: this.#resolveUnion(query), ...options });
+        return this;
+    }
+    /**
+     * `@ManyToMany` only — project EXTRA pivot columns at query time (AdonisJS/Lucid
+     * `pivotColumns([...])`), on top of any declared in the relation decorator. Read
+     * off each loaded relation as `$extras.pivot_<col>`. Inert on non-m2m relations.
+     *
+     *     userRepo.query().preload('skills', q => q.pivotColumns(['notes']))
+     */
+    pivotColumns(columns) {
+        this.#extraPivotColumns.push(...columns);
         return this;
     }
     wherePivot(column, operatorOrValue, value) {
+        return this.#pushPivot("and", column, operatorOrValue, value);
+    }
+    andWherePivot(column, operatorOrValue, value) {
+        return this.#pushPivot("and", column, operatorOrValue, value);
+    }
+    orWherePivot(column, operatorOrValue, value) {
+        return this.#pushPivot("or", column, operatorOrValue, value);
+    }
+    /** `@ManyToMany` only — `WHERE <pivotCol> IN (...)` on the pivot table (AdonisJS Lucid `whereInPivot`). */
+    whereInPivot(column, values) {
+        return this.#pushPivotOp("and", column, "IN", [...values]);
+    }
+    /** Alias of {@link whereInPivot} (Lucid parity). */
+    andWhereInPivot(column, values) {
+        return this.#pushPivotOp("and", column, "IN", [...values]);
+    }
+    /** `@ManyToMany` only — OR form of {@link whereInPivot} (Lucid parity). */
+    orWhereInPivot(column, values) {
+        return this.#pushPivotOp("or", column, "IN", [...values]);
+    }
+    /** Alias of {@link whereInPivot} kept for the earlier atlas name. */
+    wherePivotIn(column, values) {
+        return this.whereInPivot(column, values);
+    }
+    whereNotPivot(column, operatorOrValue, value) {
         if (value === undefined) {
-            this.#pivotWheres.push({ column, operator: "=", value: operatorOrValue });
-        }
-        else {
-            this.#pivotWheres.push({
-                column,
-                operator: operatorOrValue,
-                value,
-            });
+            return this.#pushPivotOp("and", column, "!=", operatorOrValue);
         }
-        return this;
+        return this.#pushPivotOp("and", column, negateOperator(String(operatorOrValue)), value);
     }
-    /** `@ManyToMany` only — `WHERE <pivotCol> IN (...)` on the pivot table (Lucid `wherePivotIn`). */
-    wherePivotIn(column, values) {
-        this.#pivotWheres.push({ column, operator: "IN", value: [...values] });
+    andWhereNotPivot(column, operatorOrValue, value) {
+        return value === undefined
+            ? this.#pushPivotOp("and", column, "!=", operatorOrValue)
+            : this.#pushPivotOp("and", column, negateOperator(String(operatorOrValue)), value);
+    }
+    orWhereNotPivot(column, operatorOrValue, value) {
+        return value === undefined
+            ? this.#pushPivotOp("or", column, "!=", operatorOrValue)
+            : this.#pushPivotOp("or", column, negateOperator(String(operatorOrValue)), value);
+    }
+    /** `@ManyToMany` only — `WHERE <pivotCol> NOT IN (...)` on the pivot table (AdonisJS Lucid `whereNotInPivot`). */
+    whereNotInPivot(column, values) {
+        return this.#pushPivotOp("and", column, "NOT IN", [...values]);
+    }
+    /** Alias of {@link whereNotInPivot} (Lucid parity). */
+    andWhereNotInPivot(column, values) {
+        return this.#pushPivotOp("and", column, "NOT IN", [...values]);
+    }
+    /** `@ManyToMany` only — OR form of {@link whereNotInPivot} (Lucid parity). */
+    orWhereNotInPivot(column, values) {
+        return this.#pushPivotOp("or", column, "NOT IN", [...values]);
+    }
+    /** `@ManyToMany` only — `WHERE <pivotCol> IS NULL` on the pivot table (Lucid `whereNullPivot`). */
+    whereNullPivot(column) {
+        return this.#pushPivotOp("and", column, "IS NULL", null);
+    }
+    /** Alias of {@link whereNullPivot} (Lucid parity). */
+    andWhereNullPivot(column) {
+        return this.#pushPivotOp("and", column, "IS NULL", null);
+    }
+    /** `@ManyToMany` only — OR form of {@link whereNullPivot} (Lucid parity). */
+    orWhereNullPivot(column) {
+        return this.#pushPivotOp("or", column, "IS NULL", null);
+    }
+    /** `@ManyToMany` only — `WHERE <pivotCol> IS NOT NULL` on the pivot table (Lucid `whereNotNullPivot`). */
+    whereNotNullPivot(column) {
+        return this.#pushPivotOp("and", column, "IS NOT NULL", null);
+    }
+    /** Alias of {@link whereNotNullPivot} (Lucid parity). */
+    andWhereNotNullPivot(column) {
+        return this.#pushPivotOp("and", column, "IS NOT NULL", null);
+    }
+    /** `@ManyToMany` only — OR form of {@link whereNotNullPivot} (Lucid parity). */
+    orWhereNotNullPivot(column) {
+        return this.#pushPivotOp("or", column, "IS NOT NULL", null);
+    }
+    /** Shared `(column, value)` / `(column, operator, value)` overload split for the pivot filters. */
+    #pushPivot(type, column, operatorOrValue, value) {
+        return value === undefined
+            ? this.#pushPivotOp(type, column, "=", operatorOrValue)
+            : this.#pushPivotOp(type, column, operatorOrValue, value);
+    }
+    #pushPivotOp(type, column, operator, value) {
+        this.#pivotWheres.push({ column, operator, value, type });
         return this;
     }
     /** Read-only accessor for pivot constraints — consumed by the m2m preload resolver. */
     get pivotConstraints() {
         return this.#pivotWheres;
     }
+    /** Read-only accessor for query-time pivot columns — consumed by the m2m preload resolver. */
+    get pivotColumnRequests() {
+        return this.#extraPivotColumns;
+    }
     limit(n) {
         // Guard here with a clear message — the Rust spec types limit as
         // u64, so a negative/non-integer otherwise surfaces as a cryptic
@@ -848,6 +1924,24 @@ export class ModelQuery {
         this.#limit = n;
         return this;
     }
+    /**
+     * In a has-many preload callback, cap the related rows PER PARENT (Lucid
+     * `groupLimit`) — a plain `.limit()` caps the whole result set across parents.
+     * Compiled with a `ROW_NUMBER() OVER (PARTITION BY <fk> …)` window. Pair with
+     * {@link groupOrderBy} to pick which N per parent.
+     */
+    groupLimit(n) {
+        if (!Number.isInteger(n) || n < 0) {
+            throw new Error(`groupLimit must be a non-negative integer, got ${n}`);
+        }
+        this.#groupLimit = n;
+        return this;
+    }
+    /** ORDER BY for the {@link groupLimit} per-parent window (Lucid `groupOrderBy`). */
+    groupOrderBy(column, direction = "asc") {
+        this.#groupOrderBy = { column, direction };
+        return this;
+    }
     offset(n) {
         if (!Number.isInteger(n) || n < 0) {
             throw new Error(`offset must be a non-negative integer, got ${n}`);
@@ -903,14 +1997,79 @@ export class ModelQuery {
         return this.exec().then(onfulfilled, onrejected);
     }
     /** 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() {
+        const col = this.#entityClass
+            ? getColumnMetadata(this.#entityClass).find((c) => c.propertyKey === "deletedAt")
+            : undefined;
+        return col?.columnName ?? "deleted_at";
+    }
     #buildSpec() {
+        // `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 = [...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,
                 });
@@ -918,7 +2077,7 @@ export class ModelQuery {
             else if (this.#softScope === "only-trashed") {
                 wheres.push({
                     type: "and",
-                    column: "deleted_at",
+                    column: deletedAtCol,
                     operator: "IS NOT NULL",
                     value: null,
                 });
@@ -928,8 +2087,9 @@ export class ModelQuery {
         return {
             kind: "select",
             table: this.#tableName,
-            select: this.#select,
+            select: selectCols,
             selectSubqueries: this.#selectSubqueries,
+            selectRaw: this.#selectRaw,
             wheres,
             orderBy: this.#orderBys,
             groupBy: this.#groupBy,
@@ -937,22 +2097,120 @@ export class ModelQuery {
             limit: this.#limit ?? null,
             offset: this.#offset ?? null,
             distinct: this.#distinct,
-            ctes: this.#ctes.map((c) => {
-                const { sql, params } = c.query.toSQL();
-                return { name: c.name, sql, params };
-            }),
+            distinctOn: this.#distinctOn,
+            ctes: this.#compiledCtes(),
             unions: this.#unions.map((u) => {
-                const { sql, params } = u.query.toSQL();
-                return { sql, params, all: u.all };
+                const { sql, params } = u.query.#compiledNative();
+                return { sql, params, all: u.all, op: u.op ?? null };
             }),
             joins: this.#joins,
-            lockMode: this.#lockMode,
+            lockMode: this.#lockMode
+                ? this.#lockModifier
+                    ? `${this.#lockMode} ${this.#lockModifier}`
+                    : this.#lockMode
+                : null,
         };
     }
-    /** Build SQL + params via the Rust query compiler. */
-    toSQL() {
+    /**
+     * Native compiled `{ sql, params }` (Postgres `$N`) — the form atlas executes
+     * and embeds inside parent queries. Public `toSQL()` normalizes to Knex `?`.
+     */
+    #compiledNative() {
         const compiled = compileStatementNative(this.#buildSpec(), this.#dialect);
-        return { sql: compiled.statements[0], params: compiled.params };
+        const sql = this.#commentPrefix() + compiled.statements[0];
+        return { sql, params: compiled.params };
+    }
+    /**
+     * Build SQL via the Rust query compiler (Lucid `toSQL`). `.sql` uses `?`
+     * placeholders (Knex-normalized, like Lucid); `.toNative()` yields the native
+     * form. Returns `bindings` (Lucid's name) and `params` (atlas's) — same array.
+     */
+    toSQL() {
+        const { sql, params } = this.#compiledNative();
+        return compiledStatement(sql, params);
+    }
+    /** `{ sql, bindings }` — the compiled native query (Lucid/Knex `toNative`). */
+    toNative() {
+        const { sql, params } = this.#compiledNative();
+        return { sql, bindings: params };
+    }
+    /** The model class this query targets (Adonis Lucid `query.model`). */
+    get model() {
+        return this.#entityClass;
+    }
+    /** Apply `cb` only on the given dialect(s) (Lucid `ifDialect`; Lucid names accepted). */
+    ifDialect(dialect, cb) {
+        const set = (Array.isArray(dialect) ? dialect : [dialect]).map(normalizeDialect);
+        if (set.includes(this.#dialect))
+            cb(this);
+        return this;
+    }
+    /** Apply `cb` on every dialect EXCEPT the given one(s) (Lucid `unlessDialect`). */
+    unlessDialect(dialect, cb) {
+        const set = (Array.isArray(dialect) ? dialect : [dialect]).map(normalizeDialect);
+        if (!set.includes(this.#dialect))
+            cb(this);
+        return this;
+    }
+    /** Prepend a `/* … *​/` SQL comment to the compiled query (Lucid/Knex `comment`). */
+    comment(text) {
+        if (text.includes("*/")) {
+            throw new Error("comment() text may not contain '*/'");
+        }
+        this.#comments.push(text);
+        return this;
+    }
+    /**
+     * Set a caller-facing statement timeout in milliseconds (Lucid `timeout(ms)`).
+     * The awaiting promise rejects after `ms` on the primary result fetch. With
+     * `{ cancel: true }` a SERVER-side statement timeout is also applied — Postgres
+     * `statement_timeout`, MySQL `MAX_EXECUTION_TIME` (SELECT) — so the server
+     * aborts the query, not just the client. (SQLite has no server timeout; the
+     * client race applies.) Called with no argument it clears the timeout.
+     */
+    timeout(ms, options) {
+        // `{ cancel: true }` also applies a SERVER-side statement timeout (Postgres
+        // statement_timeout / MySQL MAX_EXECUTION_TIME for SELECT); SQLite has none,
+        // so the client race applies there.
+        this.#timeoutMs = ms;
+        this.#cancelTimeout = options?.cancel === true;
+        return this;
+    }
+    /**
+     * Race `work` against the configured `.timeout(ms)`. Rejects the awaiter after
+     * `ms`; the losing DB promise is swallowed so a post-timeout driver error never
+     * surfaces as an unhandled rejection. No timeout set → returns `work` as-is.
+     */
+    #raceTimeout(work) {
+        const ms = this.#timeoutMs;
+        if (!ms || ms <= 0)
+            return work;
+        let timer;
+        const guard = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Query timed out after ${ms}ms`)), ms);
+        });
+        work.catch(() => { });
+        return Promise.race([work, guard]).finally(() => clearTimeout(timer));
+    }
+    /** The `/* … *​/` prefix for the compiled SQL, or empty when no comments. */
+    /** Compile the registered CTEs to the wire shape — shared by SELECT and DML. */
+    #compiledCtes() {
+        return this.#ctes.map((c) => {
+            const { sql, params } = c.query.#compiledNative();
+            return {
+                name: c.name,
+                sql,
+                params,
+                recursive: c.recursive ?? false,
+                materialized: c.materialized ?? null,
+                columns: c.columns ?? [],
+            };
+        });
+    }
+    #commentPrefix() {
+        return this.#comments.length > 0
+            ? `${this.#comments.map((c) => `/* ${c} */`).join(" ")} `
+            : "";
     }
     /**
      * Cached exec result. Memoizing the promise makes the builder a one-shot
@@ -976,8 +2234,8 @@ export class ModelQuery {
         return results;
     }
     async #doExec() {
-        const { sql, params } = this.toSQL();
-        const rawRows = await this.#db.query(sql, params);
+        const { sql, params } = this.#compiledNative();
+        const rawRows = await this.#raceTimeout(this.#db.query(sql, params, this.#meta("exec")));
         // Peel withCount / withAggregate alias columns off the raw row into $extras
         // BEFORE hydration, so the hydrator doesn't try to interpret them as columns.
         const extraKeys = this.#selectSubqueries.map((s) => s.alias);
@@ -992,14 +2250,48 @@ export class ModelQuery {
             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;
         });
         // Resolve preloads (eager loading)
         if (this.#preloads.size > 0 && this.#entityClass && entities.length > 0) {
             await this.#resolvePreloads(entities);
         }
+        // rowTransformer callbacks run per instance AFTER preloads, before resolve
+        // (Lucid), so a transformer can read the eager-loaded relations.
+        if (this.#rowTransformers.length > 0) {
+            for (const entity of entities) {
+                for (const transform of this.#rowTransformers)
+                    transform.run(entity);
+            }
+        }
         return entities;
     }
+    /**
+     * 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() {
+        const { sql, params } = this.#compiledNative();
+        return this.#db.query(sql, params);
+    }
+    /**
+     * Thread arbitrary context onto every instance this query hydrates, exposed as
+     * `entity.$sideloaded` (AdonisJS Lucid `sideload`) — e.g. the current tenant or
+     * user, so hooks/computed can read it. REPLACES the current sideloaded data by
+     * default (Lucid); pass `merge = true` to merge instead. The data also
+     * propagates to preloaded relation queries. Chainable.
+     */
+    sideload(values, merge = false) {
+        this.#sideloaded = merge
+            ? { ...this.#sideloaded, ...values }
+            : { ...values };
+        return this;
+    }
     /** Resolve preloaded relations via batched subqueries (no N+1). */
     async #resolvePreloads(entities) {
         if (!this.#entityClass)
@@ -1013,39 +2305,104 @@ export class ModelQuery {
             if (!ctx)
                 continue;
             const allRelated = await this.#resolveOneRelation(entities, relationName, relation.type, ctx);
+            // Propagate the parent query's sideloaded context onto the preloaded
+            // relation instances (Adonis Lucid). The related row's own sideloaded
+            // data (if any) wins over the inherited context.
+            if (this.#sideloaded) {
+                for (const related of allRelated) {
+                    related.$sideloaded = { ...this.#sideloaded, ...related.$sideloaded };
+                }
+            }
             await this.#applyNestedPreloads(allRelated, ctx);
         }
     }
     /** Per-preload constants (related class, table, pk, hydrator, query helper, nested callback). */
     #buildPreloadContext(relation, relationName) {
         const relatedClass = relation.target();
-        const relatedMeta = getEntityMetadata(relatedClass);
-        if (!relatedMeta)
-            return null;
+        // Boot the related model's metadata on demand (Lucid parity): a preload
+        // must not silently no-op just because the related class hasn't been
+        // touched yet elsewhere. ensureEntityMetadata synthesizes @Entity from the
+        // static table / naming strategy when the decorator hasn't run.
+        const relatedMeta = ensureEntityMetadata(relatedClass);
         // Resolve row keys against declared column metadata, NOT `in entity` —
         // entities using Adonis' `declare field: T` pattern have no own-properties
         // on a freshly constructed instance, so `key in entity` is always false and
         // every column would be silently dropped. Mirrors `BaseRepository.#hydrate`.
-        const relatedPkName = getPrimaryKey(relatedClass) ?? "id";
+        // For m2m the pivot's otherKey references `relatedKey` (default the related
+        // PK); the load must filter/index rows by THAT column, not always the PK.
+        const relatedPkName = (relation.type === "manyToMany"
+            ? relation.pivot?.relatedKey
+            : undefined) ??
+            getPrimaryKey(relatedClass) ??
+            "id";
         const validColumns = new Set();
+        // Reverse map (db column → property) so an explicit `@Column({ columnName })`
+        // on the related entity hydrates correctly — mirrors `BaseRepository.#hydrate`.
+        const byDbName = new Map();
+        // 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();
+        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, value, model) => {
+            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) => {
             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;
+                const targetKey = byDbName.get(key) ??
+                    (validColumns.has(camelKey)
+                        ? camelKey
+                        : validColumns.has(key)
+                            ? key
+                            : null);
                 if (targetKey !== null)
-                    entity.setProp(targetKey, value);
+                    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;
         };
         return {
@@ -1053,7 +2410,9 @@ export class ModelQuery {
             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),
             runRelationQuery: (column, values) => this.#runRelationQuery(relatedMeta.tableName, relatedClass, column, values, relation, this.#preloads.get(relationName)),
@@ -1087,15 +2446,17 @@ export class ModelQuery {
             throw new Error(`@HasOneThrough/@HasManyThrough '${relationName}' requires a through model`);
         }
         const throughClass = relation.through();
-        const throughMeta = getEntityMetadata(throughClass);
-        if (!throughMeta)
-            throw new Error(`Entity metadata missing on through class ${throughClass.name}`);
+        const throughMeta = ensureEntityMetadata(throughClass);
         const throughTable = throughMeta.tableName;
         const throughPk = getPrimaryKey(throughClass) ?? "id";
         const parentLocal = relation.localKey ?? getPrimaryKey(this.#entityClass) ?? "id";
         const firstKey = 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])
             .filter((v) => v != null);
@@ -1224,7 +2585,10 @@ export class ModelQuery {
         // on `status`/`address`/`campus` (→ `statu_id`). Explicit pivot keys win.
         const foreignKey = 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 [];
@@ -1233,11 +2597,42 @@ export class ModelQuery {
         // also runs (again) inside runRelationQuery against the related table; both
         // runs are pure builder mutations, and pivot constraints are inert there.
         const pivotWheres = [];
+        // Query-time pivotColumns([...]) requested in the preload callback (replayed
+        // on the scratch builder below) OR directly on this query (related().query()).
+        const extraPivotCols = [...this.#extraPivotColumns];
         if (ctx.nestedCallback) {
-            const scratch = new _a(ctx.relatedTable, this.#db, (r) => r, ctx.relatedClass, (c) => c, false, this.#dialect);
+            const scratch = new _a(ctx.relatedTable, this.#db, (r) => r, ctx.relatedClass, buildColumnResolver(ctx.relatedClass), false, this.#dialect, buildValuePreparer(ctx.relatedClass));
             ctx.nestedCallback(scratch);
-            for (const c of scratch.pivotConstraints)
-                pivotWheres.push({ ...c });
+            extraPivotCols.push(...scratch.pivotColumnRequests);
+            // Apply the pivot column adapters' `prepare` to wherePivot values, so a
+            // filter like wherePivot('amount', new Money(1)) matches what attach()/
+            // sync() stored (they prepare the same extras on write).
+            const pivotAdapters = pivot.pivotColumnAdapters ?? {};
+            for (const c of scratch.pivotConstraints) {
+                const prep = pivotAdapters[c.column]?.prepare;
+                // Same guards as the attach()/sync() write path: wrap a throwing
+                // adapter with a column-annotated error and reject async adapters,
+                // so filter and write agree on the adapter contract.
+                const apply = (v) => {
+                    if (!prep)
+                        return v;
+                    let out;
+                    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);
@@ -1251,7 +2646,11 @@ export class ModelQuery {
         ];
         // Step 2 — load all related entities in one query
         const relRows = await ctx.runRelationQuery(ctx.relatedPk, otherIds);
-        const pivotCols = pivot.pivotColumns ?? [];
+        // Declared pivot columns (decorator) + any requested at query time
+        // (`pivotColumns([...])`, from the callback or this query), de-duplicated.
+        const pivotCols = [
+            ...new Set([...(pivot.pivotColumns ?? []), ...extraPivotCols]),
+        ];
         const pivotAdapters = pivot.pivotColumnAdapters ?? {};
         // When pivot extras are projected, each (parent, related) edge gets its OWN
         // hydrated instance so per-edge `$extras.pivot_<col>` values never clobber
@@ -1282,7 +2681,9 @@ export class ModelQuery {
                 for (const col of pivotCols) {
                     const rawVal = pivotRow[col];
                     const adapter = pivotAdapters[col];
-                    related.setExtra(`pivot_${col}`, adapter?.consume ? adapter.consume(rawVal) : rawVal);
+                    related.setExtra(`pivot_${col}`, 
+                    // Adonis Lucid signature: (value, attribute, model).
+                    adapter?.consume ? adapter.consume(rawVal, col, related) : rawVal);
                 }
                 allRelated.push(related);
             }
@@ -1305,7 +2706,7 @@ export class ModelQuery {
     async #applyNestedPreloads(relatedEntities, ctx) {
         if (!ctx.nestedCallback || relatedEntities.length === 0)
             return;
-        const sub = new _a(ctx.relatedTable, this.#db, (r) => ctx.hydrate(r), ctx.relatedClass);
+        const sub = new _a(ctx.relatedTable, 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) {
             await sub.#resolveAgainst(relatedEntities, ctx.relatedClass);
@@ -1316,12 +2717,22 @@ export class ModelQuery {
         const wheres = [
             { column, operator: "IN", value: values, type: "and" },
         ];
-        for (const w of extraWheres) {
+        // The caller's filters go in a parenthesised group, never flat beside the
+        // `IN`. Flat, an `orWherePivot` would read as
+        // `WHERE fk IN (parents) OR active = 1` and hand back rows belonging to
+        // other parents; grouped, it is `WHERE fk IN (parents) AND (… OR …)`.
+        // With every filter ANDed the two forms are equivalent, so this changes
+        // no existing query.
+        if (extraWheres.length > 0) {
             wheres.push({
-                column: w.column,
-                operator: w.operator,
-                value: w.value,
+                kind: "group",
                 type: "and",
+                conditions: extraWheres.map((w) => ({
+                    column: w.column,
+                    operator: w.operator,
+                    value: w.value,
+                    type: w.type ?? "and",
+                })),
             });
         }
         const spec = {
@@ -1356,7 +2767,11 @@ export class ModelQuery {
      * inside the callback are re-collected later by `#applyNestedPreloads`.
      */
     async #runRelationQuery(relatedTable, relatedClass, column, values, relation, userCallback) {
-        const sub = new _a(relatedTable, this.#db, (row) => row, relatedClass, (c) => c, 
+        const sub = new _a(relatedTable, this.#db, (row) => row, relatedClass, 
+        // 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
@@ -1364,15 +2779,58 @@ export class ModelQuery {
         // matching a direct query on that entity. (with-trashed on the
         // related set, if ever needed, would be opted-in via the
         // preload callback.)
-        hasSoftDeletes(relatedClass), this.#dialect);
+        hasSoftDeletes(relatedClass), this.#dialect, buildValuePreparer(relatedClass));
         sub.whereIn(column, values);
         if (relation.onQuery)
             relation.onQuery(sub);
         if (userCallback)
             userCallback(sub);
-        const { sql, params } = sub.toSQL();
+        // Top-N per parent (Lucid groupLimit) → a ROW_NUMBER() window over the fk.
+        if (sub.#groupLimit != null) {
+            return this.#runGroupLimited(sub, column, sub.#groupLimit);
+        }
+        const { sql, params } = sub.#compiledNative();
         return this.#db.query(sql, params);
     }
+    /**
+     * Run a has-many preload query capped to `n` rows PER PARENT (Lucid
+     * `groupLimit`). Wraps the inner query with a `ROW_NUMBER() OVER (PARTITION BY
+     * <fk> ORDER BY <groupOrderBy | pk>)` window, then keeps `rn <= n`. Supported on
+     * Postgres, MySQL 8+, and SQLite 3.25+ (all have window functions).
+     */
+    async #runGroupLimited(sub, fkColumn, n) {
+        const quoteSeg = (name) => {
+            const qc = this.#dialect === "mysql" ? "`" : '"';
+            return name
+                .split(".")
+                .map((s) => {
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(s)) {
+                    throw new Error(`groupLimit: unsafe identifier '${name}'`);
+                }
+                return `${qc}${s}${qc}`;
+            })
+                .join(".");
+        };
+        const orderCol = sub.#groupOrderBy
+            ? sub.#resolveColumn(sub.#groupOrderBy.column)
+            : (getPrimaryKey(sub.#entityClass) ?? "id");
+        const dir = sub.#groupOrderBy?.direction === "desc" ? "DESC" : "ASC";
+        sub.#selectRaw.push({
+            sql: `ROW_NUMBER() OVER (PARTITION BY ${quoteSeg(fkColumn)} ORDER BY ${quoteSeg(orderCol)} ${dir}) AS __atlas_rn`,
+            params: [],
+        });
+        const inner = sub.#compiledNative();
+        const ph = this.#dialect === "postgres" ? `$${inner.params.length + 1}` : "?";
+        const outerSql = `SELECT * FROM (${inner.sql}) AS __atlas_grp WHERE __atlas_rn <= ${ph}`;
+        const rows = await this.#db.query(outerSql, [
+            ...inner.params,
+            n,
+        ]);
+        // Strip the window helper column so it doesn't leak into hydration.
+        for (const row of rows)
+            delete row.__atlas_rn;
+        return rows;
+    }
     /**
      * Build a correlated subquery over a relation. Returns `SubqueryProjection`
      * used by withCount / withAggregate. Default select is `COUNT(*)` for `'count'`
@@ -1403,31 +2861,50 @@ export class ModelQuery {
             throw new Error(`Relation '${relationName}' not found on ${this.#entityClass.name}`);
         }
         const relatedClass = relation.target();
-        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) => `\`${name}\``
-            : (name) => `"${name}"`;
-        const sub = new _a(relatedTable, this.#db, (row) => row, relatedClass, (c) => c, false, this.#dialect);
+        // 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) => {
+            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) => name.split(".").map(q).join(".");
+        const sub = new _a(relatedTable, this.#db, (row) => row, relatedClass, 
+        // 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": {
                 // 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 = relation.localKey ?? parentPk;
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(fk)} = ${q(parentTable)}.${q(localKey)}`);
+                const localKey = resolveParent(relation.localKey ?? parentPk);
+                sub.#pushWhereRaw(`${qTable(relatedTable)}.${q(fk)} = ${qTable(parentTable)}.${q(localKey)}`);
                 break;
             }
             case "belongsTo": {
                 const fk = relation.foreignKey ?? `${camelToSnake(relatedClass.name)}_id`;
-                const ownerKey = relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id";
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(ownerKey)} = ${q(parentTable)}.${q(fk)}`);
+                const ownerKey = buildColumnResolver(relatedClass)(relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id");
+                sub.#pushWhereRaw(`${qTable(relatedTable)}.${q(ownerKey)} = ${qTable(parentTable)}.${q(fk)}`);
                 break;
             }
             case "manyToMany": {
@@ -1439,11 +2916,12 @@ export class ModelQuery {
                 // name stripped of a trailing `s` — see the eager loader above.
                 const foreignKey = pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
                 const otherKey = pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
-                const relatedPk = getPrimaryKey(relatedClass) ?? "id";
-                const localKey = relation.localKey ?? parentPk;
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(relatedPk)} IN ` +
-                    `(SELECT ${q(otherKey)} FROM ${q(pivot.pivotTable)} ` +
-                    `WHERE ${q(pivot.pivotTable)}.${q(foreignKey)} = ${q(parentTable)}.${q(localKey)})`);
+                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(`${qTable(relatedTable)}.${q(relatedPk)} IN ` +
+                    `(SELECT ${q(otherKey)} FROM ${qTable(pivot.pivotTable)} ` +
+                    `WHERE ${qTable(pivot.pivotTable)}.${q(foreignKey)} = ${qTable(parentTable)}.${q(localKey)})`);
                 break;
             }
             case "hasOneThrough":
@@ -1455,36 +2933,45 @@ export class ModelQuery {
                     throw new Error(`@HasOneThrough/@HasManyThrough '${relationName}' requires a through model`);
                 }
                 const throughClass = relation.through();
-                const throughMeta = getEntityMetadata(throughClass);
-                if (!throughMeta) {
-                    throw new Error(`Entity metadata missing on through class ${throughClass.name}`);
-                }
+                const throughMeta = ensureEntityMetadata(throughClass);
                 const throughTable = throughMeta.tableName;
                 const throughPk = getPrimaryKey(throughClass) ?? "id";
-                const parentLocal = relation.localKey ?? parentPk;
+                const parentLocal = resolveParent(relation.localKey ?? parentPk);
                 const firstKey = relation.firstKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
                 const secondKey = relation.secondKey ?? `${camelToSnake(throughClass.name)}_id`;
-                const secondLocal = relation.secondLocalKey ?? throughPk;
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(secondKey)} IN ` +
-                    `(SELECT ${q(secondLocal)} FROM ${q(throughTable)} ` +
-                    `WHERE ${q(throughTable)}.${q(firstKey)} = ${q(parentTable)}.${q(parentLocal)})`);
+                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;
     }
-    innerJoin(table, leftOrBuild, right) {
-        return this.#pushJoin("INNER", table, leftOrBuild, right);
+    join(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
+    }
+    innerJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
     }
-    leftJoin(table, leftOrBuild, right) {
-        return this.#pushJoin("LEFT", table, leftOrBuild, right);
+    leftJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
     }
-    rightJoin(table, leftOrBuild, right) {
-        return this.#pushJoin("RIGHT", table, leftOrBuild, right);
+    leftOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
+    }
+    rightJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
+    }
+    rightOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
+    }
+    fullOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("FULL OUTER", table, leftOrBuild, operatorOrRight, right);
     }
     crossJoin(table) {
-        const tq = this.#quote(table);
-        this.#joins.push(`CROSS JOIN ${tq}`);
+        const tq = this.#quoteCol(table);
+        this.#joins.push({ sql: `CROSS JOIN ${tq}`, params: [] });
         return this;
     }
     /**
@@ -1503,12 +2990,12 @@ export class ModelQuery {
      *
      * @unsafe Raw SQL fragment — never concatenate user input into `fragment`.
      */
-    joinRaw(fragment) {
+    joinRaw(fragment, bindings = []) {
         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;
     }
     /**
@@ -1526,21 +3013,56 @@ export class ModelQuery {
         return this.innerJoin(table, left, right);
     }
     // === Story 29.5 — aggregates / exists / pluck =====================================================
-    distinct() {
+    /**
+     * SELECT DISTINCT (Lucid/Knex `distinct`). With columns, those replace the
+     * projection too — `distinct('a', 'b')` ≈ `SELECT DISTINCT a, b`.
+     */
+    distinct(...columns) {
         this.#distinct = true;
+        if (columns.length > 0) {
+            this.#select = columns.map((c) => this.#resolveSelect(c));
+        }
+        return this;
+    }
+    /**
+     * `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) {
+        for (const c of columns)
+            this.#distinctOn.push(this.#resolveColumn(c));
         return this;
     }
     /** `SELECT COUNT(DISTINCT col)`. */
     async countDistinct(column) {
-        return Number((await this.#runScalar(`COUNT(DISTINCT ${this.#quoteCol(column)})`)) ?? 0);
+        return Number((await this.#runScalar(`COUNT(DISTINCT ${this.#quoteCol(this.#resolveColumn(column))})`)) ?? 0);
+    }
+    /** `SUM(DISTINCT col)` (Lucid parity). */
+    async sumDistinct(column) {
+        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) {
+        const v = await this.#runScalar(`AVG(DISTINCT ${this.#quoteCol(this.#resolveColumn(column))})`);
+        return v === null || v === undefined ? null : Number(v);
     }
     /** `SELECT 1 FROM ... LIMIT 1` — returns boolean. */
     async exists() {
         const clone = this.clone();
         clone.#select = ["1"];
         clone.#limit = 1;
-        const { sql, params } = clone.toSQL();
-        const rows = await this.#db.query(sql, params);
+        const { sql, params } = clone.#compiledNative();
+        const rows = await this.#db.query(sql, params, this.#meta("exists"));
         return rows.length > 0;
     }
     async doesntExist() {
@@ -1551,7 +3073,7 @@ export class ModelQuery {
         const col = this.#resolveColumn(column);
         const clone = this.clone();
         clone.#select = [col];
-        const { sql, params } = clone.toSQL();
+        const { sql, params } = clone.#compiledNative();
         const rows = await this.#db.query(sql, params);
         return rows.map((row) => {
             const v = row[col];
@@ -1596,9 +3118,11 @@ export class ModelQuery {
             elseFn(this);
         return this;
     }
-    unless(condition, fn) {
+    unless(condition, fn, elseFn) {
         if (!condition)
             fn(this);
+        else if (elseFn)
+            elseFn(this);
         return this;
     }
     // === Story 29.10 — pagination =====================================================================
@@ -1606,26 +3130,53 @@ export class ModelQuery {
     async paginate(page, perPage) {
         const p = Math.max(1, Math.floor(page));
         const pp = Math.max(1, Math.floor(perPage));
-        // beforePaginate runs BEFORE cloning so a hook mutating the query (e.g. a
-        // tenant scope) propagates into both the COUNT and the data fetch.
-        await fireHooks(this.#entityClass, "beforePaginate", this);
-        // Parallel COUNT(*) + data fetch
+        // Adonis Lucid hook order:
+        //   beforePaginate([countQuery, query]) → beforeFetch(query)
+        //     → (count + data queries) → afterPaginate(paginator) → afterFetch(rows)
+        // The COUNT and data builders are separate clones so a beforePaginate hook
+        // can constrain BOTH (keeping totals in sync), exactly as documented.
         const countQ = this.clone();
-        countQ.#select = ["COUNT(*) AS count"];
+        const dataQ = this.clone();
+        await fireHooks(this.#entityClass, "beforePaginate", [countQ, dataQ]);
+        // beforeFetch fires on the main (data) query before either query runs.
+        await fireHooks(this.#entityClass, "beforeFetch", dataQ);
+        // COUNT(*) — strip pagination/order noise from the count clone.
         countQ.#limit = undefined;
         countQ.#offset = undefined;
         countQ.#orderBys = [];
-        const { sql: cSql, params: cParams } = countQ.toSQL();
-        const cRows = await this.#db.query(cSql, cParams);
+        let cSql;
+        let cParams;
+        if (countQ.#groupBy.length > 0) {
+            // A flat `SELECT COUNT(*) … GROUP BY x` returns one row PER GROUP (each the
+            // group's own size), so `rows[0].count` would be the first group's size, not
+            // the number of pages. Lucid counts via a subquery: wrap the grouped query
+            // (select + groupBy + having preserved) and count its rows = group count.
+            const inner = countQ.#compiledNative();
+            cSql = `SELECT COUNT(*) AS count FROM (${inner.sql}) AS __paginate_count`;
+            cParams = inner.params;
+        }
+        else {
+            countQ.#select = ["COUNT(*) AS count"];
+            const flat = countQ.#compiledNative();
+            cSql = flat.sql;
+            cParams = flat.params;
+        }
+        const cRows = await this.#db.query(cSql, cParams, this.#meta("paginate"));
         const total = Number(cRows[0]?.count ?? 0);
-        const dataQ = this.clone();
         dataQ.#limit = pp;
         dataQ.#offset = (p - 1) * pp;
-        // `#doExec` (not `exec`) so the generic beforeFetch/afterFetch don't fire on
-        // top of the paginate hooks — paginate is its own terminal.
+        // `#doExec` runs the raw fetch + preloads. beforeFetch already fired above;
+        // afterFetch fires AFTER afterPaginate (Lucid order), so #doExec must not
+        // fire either itself — hence #doExec, not exec().
         const items = await dataQ.#doExec();
-        await fireHooks(this.#entityClass, "afterPaginate", items);
-        return new Paginator(items, { total, perPage: pp, currentPage: p });
+        const metaKeys = this.#entityClass
+            ? getNamingStrategy(this.#entityClass).paginationMetaKeys?.()
+            : undefined;
+        const paginator = new Paginator(items, { total, perPage: pp, currentPage: p }, metaKeys);
+        // Lucid: afterPaginate(paginator) then afterFetch(rows).
+        await fireHooks(this.#entityClass, "afterPaginate", paginator);
+        await fireHooks(this.#entityClass, "afterFetch", items);
+        return paginator;
     }
     /**
      * Cursor-based pagination — base64 opaque keyset, multi-column aware.
@@ -1641,7 +3192,13 @@ export class ModelQuery {
      * accepts row-value comparisons.
      */
     async cursorPaginate(opts) {
-        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));
@@ -1685,7 +3242,7 @@ export class ModelQuery {
         const items = hasMore ? rows.slice(0, lim) : rows;
         const last = items[items.length - 1];
         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 };
     }
@@ -1702,75 +3259,178 @@ export class ModelQuery {
         this.#debugFlag = flag;
         return this;
     }
+    /**
+     * Attach arbitrary metadata to the `db:query` event this query emits (Adonis
+     * Lucid `reporterData`) — request id, user id, feature flag, … A listener
+     * reads it off `event.reporterData`. Repeated calls merge. Setting it also
+     * forces emission (like {@link debug}), so the data actually reaches a listener.
+     */
+    reporterData(data) {
+        this.#reporterData = { ...this.#reporterData, ...data };
+        this.#debugFlag = true;
+        return this;
+    }
+    /**
+     * Context attached to each statement this query runs, so a `db:query`
+     * listener can say which model and which call produced it — and so
+     * {@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) {
+        return {
+            model: this.#entityClass.name,
+            method,
+            debug: this.#debugFlag,
+            reporterData: this.#reporterData,
+            serverTimeoutMs: this.#cancelTimeout && this.#timeoutMs != null
+                ? this.#timeoutMs
+                : undefined,
+        };
+    }
     /** Returns the compiled SQL with bindings interpolated as dialect-safe literals. */
     toQuery() {
-        const { sql, params } = this.toSQL();
-        let i = 0;
-        return sql.replace(/\?|\$\d+/g, () => {
-            const v = params[i++];
-            return this.#literalEscape(v);
-        });
+        const { sql, params } = this.#compiledNative();
+        return interpolateQuery(sql, params);
     }
     /** Deep clone of this query — mutations on the clone never affect the original. */
     clone() {
-        const c = new _a(this.#tableName, this.#db, this.#hydrateFn, this.#entityClass, this.#resolveColumn, this.#softDeletes, this.#dialect);
+        const c = new _a(this.#tableName, this.#db, this.#hydrateFn, this.#entityClass, this.#resolveColumn, this.#softDeletes, this.#dialect, this.#prepareValue, this.#onDomainEvents);
         c.#softScope = this.#softScope;
         c.#wheres = structuredCloneSafe(this.#wheres);
         c.#orderBys = [...this.#orderBys];
         c.#select = [...this.#select];
         c.#limit = this.#limit;
+        c.#groupLimit = this.#groupLimit;
+        c.#groupOrderBy = this.#groupOrderBy
+            ? { ...this.#groupOrderBy }
+            : undefined;
         c.#offset = this.#offset;
         c.#preloads = new Map(this.#preloads);
+        c.#rowTransformers = [...this.#rowTransformers];
         c.#selectSubqueries = structuredClone(this.#selectSubqueries);
-        c.#joins = [...this.#joins];
+        c.#selectRaw = this.#selectRaw.map((s) => ({
+            ...s,
+            params: [...s.params],
+        }));
+        c.#timeoutMs = this.#timeoutMs;
+        c.#cancelTimeout = this.#cancelTimeout;
+        c.#joins = this.#joins.map((j) => ({ sql: j.sql, params: [...j.params] }));
         c.#lockMode = this.#lockMode;
+        c.#lockModifier = this.#lockModifier;
+        c.#sideloaded = this.#sideloaded ? { ...this.#sideloaded } : null;
         c.#distinct = this.#distinct;
+        c.#distinctOn = [...this.#distinctOn];
         c.#groupBy = [...this.#groupBy];
         c.#having = structuredCloneSafe(this.#having);
-        c.#ctes = this.#ctes.map((e) => ({ name: e.name, query: e.query.clone() }));
+        c.#ctes = this.#ctes.map((e) => ({
+            name: e.name,
+            query: e.query.clone(),
+            recursive: e.recursive,
+            materialized: e.materialized,
+            columns: e.columns ? [...e.columns] : undefined,
+        }));
         c.#unions = this.#unions.map((u) => ({
             query: u.query.clone(),
             all: u.all,
+            op: u.op,
         }));
         c.#pivotWheres = structuredCloneSafe(this.#pivotWheres);
+        c.#extraPivotColumns = [...this.#extraPivotColumns];
+        // Pure closure over pivot metadata — safe to share by reference; it reads the
+        // clone's own #pivotWheres at build time (passed in), holding no query state.
+        c.#pivotExists = this.#pivotExists;
         c.#debugFlag = this.#debugFlag;
+        c.#reporterData = this.#reporterData
+            ? { ...this.#reporterData }
+            : undefined;
+        c.#comments = [...this.#comments];
         return c;
     }
-    // === Story 30.2 — update / delete fluent ===========================================================
-    /** Execute a fluent UPDATE. Returns affected rows (or rows when `returning` is set). */
-    async update(patch, returning) {
+    update(patchOrColumn, valueOrReturning) {
+        const patch = typeof patchOrColumn === "string"
+            ? { [patchOrColumn]: valueOrReturning }
+            : patchOrColumn;
+        const returning = typeof patchOrColumn === "string"
+            ? undefined
+            : valueOrReturning;
         if (!patch || Object.keys(patch).length === 0) {
             throw new Error("update() requires a non-empty payload");
         }
-        const setPairs = Object.entries(patch).map(([k, v]) => [this.#resolveColumn(k), v]);
-        const spec = {
+        // Lower each value through prepare (DateTime → ISO, @Column adapters) exactly
+        // like BaseRepository's write paths — the fluent update() must not bypass it.
+        // A `db.raw(...)` value is emitted as a raw SET expression instead.
+        const setPairs = Object.entries(patch).map(([k, v]) => v instanceof RawSql
+            ? [this.#resolveColumn(k), { raw: v.sql, rawParams: [...v.params] }]
+            : [this.#resolveColumn(k), this.#prepareValue(k, v)]);
+        return this.#makeDml((r) => ({
             kind: "update",
             table: this.#tableName,
             set: setPairs,
             wheres: this.#wheresForDml(),
-            returning: returning ?? [],
-        };
-        const compiled = compileStatementNative(spec, this.#dialect);
-        if (returning && returning.length > 0) {
-            return this.#db.query(compiled.statements[0], compiled.params);
-        }
-        const r = await this.#db.execute(compiled.statements[0], compiled.params);
-        return r.rowsAffected ?? 0;
+            returning: r,
+            ctes: this.#compiledCtes(),
+        }), returning);
     }
-    /** Execute a fluent DELETE. Returns affected rows (or rows when `returning` is set). */
-    async delete(returning) {
-        const spec = {
+    /**
+     * Execute a fluent DELETE. For a `@SoftDeletes` model this SOFT-deletes the
+     * scoped rows (stamps `deleted_at`) — consistent with the entity-level
+     * `delete()`; use {@link forceDelete} for a hard `DELETE`. For a non-soft-delete
+     * model it issues a hard `DELETE`. Returns affected rows (or rows when
+     * `returning` is set).
+     */
+    delete(returning) {
+        if (this.#softDeletes) {
+            const stampedAt = new Date().toISOString();
+            return this.#makeDml((r) => ({
+                kind: "update",
+                table: this.#tableName,
+                set: [[this.#deletedAtColumn(), stampedAt]],
+                wheres: this.#wheresForDml(),
+                returning: r,
+                ctes: this.#compiledCtes(),
+            }), returning);
+        }
+        return this.forceDelete(returning);
+    }
+    /** Hard `DELETE` of the scoped rows, bypassing `@SoftDeletes` (AdonisJS/Lucid `forceDelete`). */
+    forceDelete(returning) {
+        return this.#makeDml((r) => ({
             kind: "delete",
             table: this.#tableName,
             wheres: this.#wheresForDml(),
-            returning: returning ?? [],
-        };
-        const compiled = compileStatementNative(spec, this.#dialect);
-        if (returning && returning.length > 0) {
-            return this.#db.query(compiled.statements[0], compiled.params);
+            returning: r,
+            ctes: this.#compiledCtes(),
+        }), returning);
+    }
+    /**
+     * Bulk restore: clear `deleted_at` on the trashed rows matching the user's
+     * predicates (the soft-delete counterpart of {@link delete}). No-op count `0`
+     * on a non-soft-delete model. Independent of the current soft-scope — it always
+     * targets trashed rows (`deleted_at IS NOT NULL`).
+     */
+    restore(returning) {
+        if (!this.#softDeletes) {
+            return new DmlBuilder(() => Promise.resolve(0), () => ({ sql: "", bindings: [], params: [] }), this.#dmlHooks());
         }
-        const r = await this.#db.execute(compiled.statements[0], compiled.params);
-        return r.rowsAffected ?? 0;
+        return this.#makeDml((r) => {
+            const wheres = this.#userWheresForDml();
+            wheres.push({
+                column: this.#deletedAtColumn(),
+                operator: "IS NOT NULL",
+                value: null,
+                type: "and",
+            });
+            return {
+                kind: "update",
+                table: this.#tableName,
+                set: [[this.#deletedAtColumn(), null]],
+                wheres,
+                returning: r,
+                ctes: this.#compiledCtes(),
+            };
+        }, returning);
     }
     increment(colOrPatch, amount = 1) {
         return this.#runIncDec("increment", colOrPatch, amount);
@@ -1797,57 +3457,237 @@ export class ModelQuery {
         }
         return this;
     }
+    /** Postgres `FOR NO KEY UPDATE` — a weaker lock that doesn't block FK checks (AdonisJS/Knex). */
+    forNoKeyUpdate() {
+        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() {
+        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() {
+        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() {
+        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) {
         return this.#dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
     }
     /** Quote a `table.column` reference on both sides of the dot. */
     #quoteCol(ref) {
-        if (ref.includes(".")) {
-            const [t, c] = ref.split(".", 2);
-            return `${this.#quote(t)}.${this.#quote(c)}`;
-        }
-        return this.#quote(ref);
-    }
-    #pushJoin(kind, table, leftOrBuild, right) {
-        const tq = this.#quote(table);
+        // 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 ref
+            .split(".")
+            .map((seg) => this.#quote(seg))
+            .join(".");
+    }
+    #pushJoin(kind, table, leftOrBuild, operatorOrRight, right) {
+        const tq = this.#quoteCol(table);
         if (typeof leftOrBuild === "function") {
+            const parts = [];
             const jb = {
-                parts: [],
-                on(l, r) {
-                    this.parts.push({ kind: "and", left: l, right: r });
-                    return this;
+                parts,
+                on: (l, opOrR, r) => {
+                    parts.push(r === undefined
+                        ? { kind: "and", left: l, right: opOrR }
+                        : { kind: "and", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                andOn: (l, opOrR, r) => {
+                    parts.push(r === undefined
+                        ? { kind: "and", left: l, right: opOrR }
+                        : { kind: "and", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                orOn: (l, opOrR, r) => {
+                    parts.push(r === undefined
+                        ? { kind: "or", left: l, right: opOrR }
+                        : { kind: "or", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                onVal: (l, v) => {
+                    parts.push({ kind: "and", left: l, value: { v } });
+                    return jb;
+                },
+                andOnVal: (l, v) => {
+                    parts.push({ kind: "and", left: l, value: { v } });
+                    return jb;
+                },
+                orOnVal: (l, v) => {
+                    parts.push({ kind: "or", left: l, value: { v } });
+                    return jb;
+                },
+                onIn: (l, values) => {
+                    parts.push({ kind: "and", left: l, values: [...values] });
+                    return jb;
                 },
-                andOn(l, r) {
-                    this.parts.push({ kind: "and", left: l, right: r });
-                    return this;
+                onNotIn: (l, values) => {
+                    parts.push({
+                        kind: "and",
+                        left: l,
+                        values: [...values],
+                        notIn: true,
+                    });
+                    return jb;
+                },
+                onNull: (l) => {
+                    parts.push({ kind: "and", left: l, nullOp: "IS NULL" });
+                    return jb;
+                },
+                onNotNull: (l) => {
+                    parts.push({ kind: "and", left: l, nullOp: "IS NOT NULL" });
+                    return jb;
+                },
+                onBetween: (l, range) => {
+                    parts.push({ kind: "and", left: l, between: [range[0], range[1]] });
+                    return jb;
                 },
-                andOnVal(l, _v) {
-                    this.parts.push({ kind: "and", left: l, right: "?" });
-                    return this;
+                onNotBetween: (l, range) => {
+                    parts.push({
+                        kind: "and",
+                        left: l,
+                        between: [range[0], range[1]],
+                        notBetween: true,
+                    });
+                    return jb;
+                },
+                onExists: (sub) => {
+                    const { sql, params } = this.#resolveUnion(sub).#compiledNative();
+                    parts.push({ kind: "and", exists: { sql, params, not: false } });
+                    return jb;
+                },
+                onNotExists: (sub) => {
+                    const { sql, params } = this.#resolveUnion(sub).#compiledNative();
+                    parts.push({ kind: "and", exists: { sql, params, not: true } });
+                    return jb;
                 },
             };
             leftOrBuild(jb);
-            const on = jb.parts
+            // A BASE-table column runs the full model prepare (DateTime→ISO + @Column
+            // adapters/casts), keyed by its property. A FOREIGN join column must NOT
+            // borrow the root model's adapter for a same-named column on another
+            // table — apply only universal type-lowering, matching Knex's
+            // model-agnostic join binding.
+            const prep = (col, v) => {
+                const dot = col.lastIndexOf(".");
+                const tablePrefix = dot >= 0 ? col.slice(0, dot) : "";
+                const leaf = dot >= 0 ? col.slice(dot + 1) : col;
+                const isBaseColumn = tablePrefix === "" || sameTableRef(tablePrefix, this.#tableName);
+                return isBaseColumn ? this.#prepareValue(leaf, v) : lowerJoinValue(v);
+            };
+            const params = [];
+            const on = parts
                 .map((p, i) => {
                 const prefix = i === 0 ? "ON" : p.kind === "or" ? "OR" : "AND";
-                return `${prefix} ${this.#quoteCol(p.left)} = ${p.right === "?" ? "?" : this.#quoteCol(p.right)}`;
+                if (p.exists) {
+                    params.push(...p.exists.params);
+                    return `${prefix} ${p.exists.not ? "NOT EXISTS" : "EXISTS"} (${p.exists.sql})`;
+                }
+                const col = this.#quoteCol(p.left ?? "");
+                if (p.nullOp) {
+                    return `${prefix} ${col} ${p.nullOp}`;
+                }
+                if (p.between) {
+                    params.push(prep(p.left ?? "", p.between[0]), prep(p.left ?? "", p.between[1]));
+                    return `${prefix} ${col} ${p.notBetween ? "NOT BETWEEN" : "BETWEEN"} ? AND ?`;
+                }
+                if (p.values) {
+                    const placeholders = p.values.map(() => "?").join(", ");
+                    for (const v of p.values)
+                        params.push(prep(p.left ?? "", v));
+                    return `${prefix} ${col} ${p.notIn ? "NOT IN" : "IN"} (${placeholders})`;
+                }
+                if (p.value) {
+                    params.push(prep(p.left ?? "", p.value.v));
+                    return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ?`;
+                }
+                return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ${this.#quoteCol(p.right ?? "")}`;
             })
                 .join(" ");
-            this.#joins.push(`${kind} JOIN ${tq} ${on}`);
+            this.#joins.push({ sql: `${kind} JOIN ${tq} ${on}`, params });
             return this;
         }
-        if (right === undefined)
+        // String form: 3-arg `(left, right)` or 4-arg `(left, operator, right)`.
+        const left = leftOrBuild;
+        const operator = right === undefined ? "=" : (operatorOrRight ?? "=");
+        const rightCol = right === undefined ? operatorOrRight : right;
+        if (rightCol === undefined)
             throw new Error("join() with string form requires both left and right operands");
-        this.#joins.push(`${kind} JOIN ${tq} ON ${this.#quoteCol(leftOrBuild)} = ${this.#quoteCol(right)}`);
+        this.#joins.push({
+            sql: `${kind} JOIN ${tq} ON ${this.#quoteCol(left)} ${this.#validateJoinOp(operator)} ${this.#quoteCol(rightCol)}`,
+            params: [],
+        });
         return this;
     }
+    /** Allowlist the comparison operator embedded verbatim into a JOIN's ON SQL. */
+    #validateJoinOp(op) {
+        const t = op.trim();
+        const up = t.toUpperCase();
+        const allowed = new Set([
+            "=",
+            "<>",
+            "!=",
+            "<",
+            "<=",
+            ">",
+            ">=",
+            "LIKE",
+            "NOT LIKE",
+            "ILIKE",
+        ]);
+        if (allowed.has(t))
+            return t;
+        if (allowed.has(up))
+            return up;
+        throw new Error(`Unsupported join operator '${op}'.`);
+    }
     async #runScalar(expr) {
         const clone = this.clone();
         clone.#select = [`${expr} AS __scalar__`];
         clone.#orderBys = [];
-        const { sql, params } = clone.toSQL();
-        const rows = await this.#db.query(sql, params);
+        const { sql, params } = clone.#compiledNative();
+        const rows = await this.#raceTimeout(this.#db.query(sql, params));
         const row = rows[0];
         return row ? row.__scalar__ : null;
     }
@@ -1860,42 +3700,101 @@ export class ModelQuery {
             set: setPairs,
             wheres: this.#wheresForDml(),
             returning: [],
+            ctes: this.#compiledCtes(),
         };
         const compiled = compileStatementNative(spec, this.#dialect);
-        const r = await this.#db.execute(compiled.statements[0], compiled.params);
+        const r = await this.#raceTimeout(this.#db.execute(this.#commentPrefix() + compiled.statements[0], compiled.params, this.#meta("dml")));
         return r.rowsAffected ?? 0;
     }
     /**
-     * Flatten the SELECT wheres to DML-compatible wheres. Standard predicates
-     * and `whereRaw` fragments pass through; `group` / `exists` / `inSub` are
-     * still rejected because the DML compiler's WHERE lowering does not yet
-     * handle nested sub-queries or correlated EXISTS.
+     * The user's own WHERE predicates for DML (no soft-delete scope). The DML
+     * compiler now REUSES the SELECT compiler's WHERE lowering, so every predicate
+     * the read builder accepts — standard, `whereRaw`, `whereExists`, sub-queries,
+     * and nested groups — is valid for update/delete too. Passed through unchanged
+     * (same as `#buildSpec` does for reads).
      */
+    #userWheresForDml() {
+        return [...this.#wheres];
+    }
     #wheresForDml() {
-        const out = [];
-        for (const w of this.#wheres) {
-            if ("kind" in w) {
-                if (w.kind === "raw") {
-                    out.push({
-                        kind: "raw",
-                        sql: w.sql,
-                        bindings: w.bindings,
-                        type: w.type,
-                    });
-                    continue;
-                }
-                throw new Error(`update/delete do not support '${w.kind}' WHERE clauses. ` +
-                    `Supported: plain predicates and whereRaw. Use a raw UPDATE/DELETE for complex criteria.`);
+        const out = this.#userWheresForDml();
+        // Mirror the read scope (`#buildSpec`): a `@SoftDeletes` model's bulk
+        // update/delete/increment/decrement must NOT touch trashed rows under the
+        // default scope — otherwise `query().where(x)` would denote a different row
+        // set for `.exec()` than for `.update()`/`.delete()`. `.withTrashed()` widens,
+        // `.onlyTrashed()` restricts to trashed (mirrors reads).
+        if (this.#softDeletes) {
+            const deletedAtCol = this.#deletedAtColumn();
+            if (this.#softScope === "default") {
+                out.push({
+                    column: deletedAtCol,
+                    operator: "IS NULL",
+                    value: null,
+                    type: "and",
+                });
+            }
+            else if (this.#softScope === "only-trashed") {
+                out.push({
+                    column: deletedAtCol,
+                    operator: "IS NOT NULL",
+                    value: null,
+                    type: "and",
+                });
             }
-            out.push({
-                column: w.column,
-                operator: w.operator,
-                value: w.value,
-                type: w.type,
-            });
         }
         return out;
     }
+    /** Compile a DML spec with the comment prefix — for a lazy builder's `.toSQL()`. */
+    #compileDmlSpec(spec) {
+        const compiled = compileStatementNative(spec, this.#dialect);
+        const sql = this.#commentPrefix() + compiled.statements[0];
+        return { sql, bindings: compiled.params, params: compiled.params };
+    }
+    /** Hooks a lazy DML builder delegates back to (upsert clauses are N/A on a model query). */
+    #dmlHooks() {
+        return {
+            onConflict: () => { },
+            merge: () => { },
+            ignore: () => { },
+            returning: (...cols) => {
+                for (const c of cols) {
+                    if (Array.isArray(c))
+                        this.#dmlReturning.push(...c);
+                    else
+                        this.#dmlReturning.push(c);
+                }
+            },
+            timeout: (ms) => {
+                this.#timeoutMs = ms;
+            },
+            comment: (t) => {
+                this.comment(t);
+            },
+            debug: (enabled) => {
+                this.debug(enabled);
+            },
+            reporterData: (data) => {
+                this.reporterData(data);
+            },
+        };
+    }
+    /** Wrap a DML spec-builder as a lazy, chainable, inspectable {@link DmlBuilder}. */
+    #makeDml(build, paramReturning) {
+        const resolved = () => [...(paramReturning ?? []), ...this.#dmlReturning].map((c) => this.#resolveSelect(c));
+        return new DmlBuilder(() => {
+            const r = resolved();
+            return this.#runDml(build(r), r);
+        }, () => this.#compileDmlSpec(build(resolved())), this.#dmlHooks());
+    }
+    /** Compile + run a DML spec: returns affected-row count, or rows when `returning` is set. */
+    async #runDml(spec, returning) {
+        const compiled = compileStatementNative(spec, this.#dialect);
+        if (returning && returning.length > 0) {
+            return this.#raceTimeout(this.#db.query(this.#commentPrefix() + compiled.statements[0], compiled.params, this.#meta("dml")));
+        }
+        const r = await this.#raceTimeout(this.#db.execute(this.#commentPrefix() + compiled.statements[0], compiled.params, this.#meta("dml")));
+        return r.rowsAffected ?? 0;
+    }
     /**
      * !!! DEBUG ONLY — DO NOT USE FOR EXECUTION !!!
      *
@@ -1909,18 +3808,6 @@ export class ModelQuery {
      * parameters via the Rust compiler — this escaper is never on the hot path.
      * If you are tempted to feed `.toQuery()` output into `db.prepare()`, STOP.
      */
-    #literalEscape(v) {
-        if (v === null || v === undefined)
-            return "NULL";
-        if (typeof v === "number")
-            return String(v);
-        if (typeof v === "boolean")
-            return v ? "1" : "0";
-        if (v instanceof Date)
-            return `'${v.toISOString()}'`;
-        // Strings — escape single quotes per SQL. NOT injection-safe against `\'`.
-        return `'${String(v).replace(/'/g, "''")}'`;
-    }
     /**
      * Build a parenthesised WHERE group from a callback. A throwaway ModelQuery
      * on the SAME table is used as the scratch builder so the callback can call
@@ -1928,7 +3815,7 @@ export class ModelQuery {
      * groups. We then copy its accumulated `#wheres` into a `GroupWhere` clause.
      */
     #buildGroup(type, callback) {
-        const scratch = new _a(this.#tableName, this.#db, (row) => row, this.#entityClass, this.#resolveColumn, false, this.#dialect);
+        const scratch = new _a(this.#tableName, this.#db, (row) => row, this.#entityClass, this.#resolveColumn, false, this.#dialect, this.#prepareValue);
         callback(scratch);
         return { type, kind: "group", conditions: scratch.#wheres };
     }
@@ -1968,7 +3855,7 @@ export class ModelQuery {
                 type,
                 column: resolved,
                 operator: "=",
-                value: operatorOrValue,
+                value: this.#prep(column, operatorOrValue),
             });
         }
         else {
@@ -1976,11 +3863,21 @@ export class ModelQuery {
                 type,
                 column: resolved,
                 operator: operatorOrValue,
-                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, value) {
+        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.