@c9up/atlas 0.1.18 → 0.2.0

package/dist/ModelQuery.js

@@ -7,8 +7,14 @@
  * 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 { getNamingStrategy } from "./naming/NamingStrategy.js";
 import { compileStatementNative, getAtlasDialect, } from "./query/native.js";
 import { camelToSnake, snakeToCamel } from "./utils/casing.js";
 /**
@@ -28,6 +34,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 +91,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 +208,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 +224,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 +262,46 @@ 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;
+    }
+    /** True when there is at least one more page after the current one (AdonisJS `hasMorePages`). */
+    get hasMorePages() {
+        return this.meta.currentPage < this.meta.lastPage;
+    }
     serialize(opts) {
         const data = this.items.map((item) => {
             if (!opts?.fields)
@@ -137,7 +311,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;
@@ -147,26 +323,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);
+            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;
         }
-        return { data: this.items, meta };
+        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,15 +413,38 @@ export class ModelQuery {
     #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;
     /** Distinct flag — Story 29.5. */
     #distinct = false;
+    #distinctOn = [];
+    /** GROUP BY columns (Lucid parity). */
+    #groupBy = [];
+    /** HAVING clauses — structured + raw (Lucid parity). */
+    #having = [];
+    /** CTEs registered via `.with()` (Lucid parity). */
+    #ctes = [];
+    /** UNION / UNION ALL branches (Lucid parity). */
+    #unions = [];
+    /** m2m pivot-table WHERE constraints — applied to the pivot lookup, not the related query. */
+    #pivotWheres = [];
+    /**
+     * 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;
@@ -209,7 +452,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";
@@ -234,11 +483,29 @@ export class ModelQuery {
     }
     /** Select specific columns (default: `*`). Accepts a comma-separated string or an array. */
     select(columns) {
-        this.#select = Array.isArray(columns)
+        const list = Array.isArray(columns)
             ? columns
             : columns.split(",").map((c) => c.trim());
+        this.#select = list.map((c) => this.#resolveSelect(c));
         return this;
     }
+    /**
+     * Resolve a bare model-property select/returning target to its DB column
+     * (honouring `@Column({ columnName })`), leaving expressions / aliases /
+     * qualified names / `*` untouched. A bare identifier IS validated through the
+     * column resolver — so a typo like `select('lable')` raises the same Atlas
+     * error as `where`/`orderBy`, rather than reaching the DB.
+     */
+    #resolveSelect(col) {
+        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));
@@ -271,13 +538,63 @@ export class ModelQuery {
         });
         return this;
     }
+    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);
+    }
     /** `WHERE col != ?` — negation of `where`. */
     whereNot(column, value) {
         this.#wheres.push({
             type: "and",
             column: this.#resolveColumn(column),
             operator: "!=",
-            value,
+            value: this.#prep(column, value),
         });
         return this;
     }
@@ -297,7 +614,7 @@ export class ModelQuery {
             type: "and",
             column: this.#resolveColumn(column),
             operator: "IN",
-            value: [...source],
+            value: this.#prep(column, [...source]),
         });
         return this;
     }
@@ -317,7 +634,7 @@ export class ModelQuery {
             type: "and",
             column: this.#resolveColumn(column),
             operator: "NOT IN",
-            value: [...source],
+            value: this.#prep(column, [...source]),
         });
         return this;
     }
@@ -327,7 +644,7 @@ export class ModelQuery {
             type: "and",
             column: this.#resolveColumn(column),
             operator: "BETWEEN",
-            value: [...range],
+            value: this.#prep(column, [...range]),
         });
         return this;
     }
@@ -337,7 +654,7 @@ export class ModelQuery {
             type: "and",
             column: this.#resolveColumn(column),
             operator: "NOT BETWEEN",
-            value: [...range],
+            value: this.#prep(column, [...range]),
         });
         return this;
     }
@@ -365,6 +682,119 @@ export class ModelQuery {
         });
         return this;
     }
+    // ─── OR-combined variants (AdonisJS orWhere* family) ─────────
+    // Same predicates as the whereX methods above, combined with OR instead of
+    // AND — the named ergonomics Lucid exposes (vs emulating with `orWhere(cb)`).
+    /** `OR col IS NULL`. */
+    orWhereNull(column) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "IS NULL",
+            value: null,
+        });
+        return this;
+    }
+    /** `OR col IS NOT NULL`. */
+    orWhereNotNull(column) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "IS NOT NULL",
+            value: null,
+        });
+        return this;
+    }
+    /** `OR col != ?`. */
+    orWhereNot(column, value) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "!=",
+            value: this.#prep(column, value),
+        });
+        return this;
+    }
+    /** `OR col IN (...)` — array or `ModelQuery` subquery source. */
+    orWhereIn(column, source) {
+        if (source instanceof _a) {
+            this.#wheres.push({
+                type: "or",
+                kind: "inSub",
+                negated: false,
+                column: this.#resolveColumn(column),
+                subquery: source.#buildSpec(),
+            });
+            return this;
+        }
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "IN",
+            value: this.#prep(column, [...source]),
+        });
+        return this;
+    }
+    /** `OR col NOT IN (...)` — array or `ModelQuery` subquery source. */
+    orWhereNotIn(column, source) {
+        if (source instanceof _a) {
+            this.#wheres.push({
+                type: "or",
+                kind: "inSub",
+                negated: true,
+                column: this.#resolveColumn(column),
+                subquery: source.#buildSpec(),
+            });
+            return this;
+        }
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "NOT IN",
+            value: this.#prep(column, [...source]),
+        });
+        return this;
+    }
+    /** `OR col BETWEEN ? AND ?`. */
+    orWhereBetween(column, range) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "BETWEEN",
+            value: this.#prep(column, [...range]),
+        });
+        return this;
+    }
+    /** `OR col NOT BETWEEN ? AND ?`. */
+    orWhereNotBetween(column, range) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "NOT BETWEEN",
+            value: this.#prep(column, [...range]),
+        });
+        return this;
+    }
+    /** `OR col LIKE ?`. */
+    orWhereLike(column, pattern) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "LIKE",
+            value: pattern,
+        });
+        return this;
+    }
+    /** `OR col ILIKE ?` (rewritten to LOWER() LIKE LOWER() on sqlite/mysql). */
+    orWhereILike(column, pattern) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "ILIKE",
+            value: pattern,
+        });
+        return this;
+    }
     /**
      * **⚠ UNSAFE** — append a raw SQL fragment to the WHERE clause with
      * `?`-style bindings. The Rust compiler re-indexes the placeholders so they
@@ -404,15 +834,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)
@@ -431,6 +893,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
@@ -447,11 +921,250 @@ 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;
     }
+    /**
+     * Compare two COLUMNS (AdonisJS/Knex `whereColumn`) — `WHERE "a" op "b"`.
+     * Both sides go through the identifier quoter (injection-safe) and the
+     * operator is allow-listed; nothing is bound (it's a column reference, not a
+     * value), which the standard `where`/`whereExpr` value-binding path can't do.
+     */
+    // ─── EXISTS ───────────────────────────────────────────────
+    //
+    // `whereExists` lived only on the low-level `query/QueryBuilder`, not on the
+    // builder `repo.query()` actually hands back, so it was unreachable from
+    // normal use. The subquery is another `ModelQuery`; correlate it to the
+    // outer table with `whereColumn`:
+    //
+    //     userRepo.query().whereExists(
+    //       postRepo.query().whereColumn('posts.user_id', '=', 'users.id')
+    //     )
+    //
+    // For relation-shaped EXISTS, prefer `whereHas`/`has`, which derive the
+    // join predicate from the relation metadata.
+    /** `WHERE EXISTS (subquery)` (Lucid parity). */
+    whereExists(subquery) {
+        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);
+    }
+    // ─── JSON ─────────────────────────────────────────────────
+    //
+    // Every value crosses the boundary as a bound param — the path and the
+    // compared value both. Only the column is a quoted identifier. Path access
+    // and containment are each spelled per dialect, and SQLite has no
+    // containment operator, so `*JsonSupersetOf`/`*JsonSubsetOf` refuse there.
+    /**
+     * `WHERE <col at path> <op> ?` — compare a value inside a JSON column
+     * (Lucid/Knex `whereJsonPath`). `path` is a JSONPath (`$.a.b`, `$.items[0]`).
+     *
+     *     query.whereJsonPath('data', '$.address.city', '=', 'Paris')
+     */
+    whereJsonPath(column, path, operator, value) {
+        return this.#pushJson("and", false, "path", column, value, path, operator);
+    }
+    /** Alias of {@link whereJsonPath} (Lucid parity). */
+    andWhereJsonPath(column, path, operator, value) {
+        return this.#pushJson("and", false, "path", column, value, path, operator);
+    }
+    /** `OR <col at path> <op> ?` (Lucid parity). */
+    orWhereJsonPath(column, path, operator, value) {
+        return this.#pushJson("or", false, "path", column, value, path, operator);
+    }
+    /**
+     * `WHERE <col> @> ?` — the JSON column contains `value` (Lucid/Knex
+     * `whereJsonSupersetOf`). `value` is any JSON-serialisable value.
+     *
+     * Postgres and MySQL only — SQLite has no JSON containment operator and the
+     * compiler raises `E_UNSUPPORTED` there.
+     */
+    whereJsonSupersetOf(column, 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);
+    }
+    #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);
+    }
+    /** `OR`-combined {@link whereColumn}. */
+    orWhereColumn(left, operator, right) {
+        return this.#whereColumn("or", 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(" ")}.`);
+        }
+        // Both operands are interpolated as raw identifiers (no value binding for a
+        // column reference), and #quote is a plain wrapper that does NOT escape an
+        // embedded quote — so validate each RESOLVED identifier against a strict
+        // `[table.]column` charset. This closes the injection surface regardless of
+        // what #resolveColumn returns (it can be an identity resolver on sub-queries).
+        const safe = (name) => {
+            const resolved = this.#resolveColumnReference(name);
+            if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(resolved)) {
+                throw new Error(`whereColumn: '${name}' is not a valid column identifier ([table.]column, alphanumeric + underscore).`);
+            }
+            // Quote each dotted segment separately → `"table"."column"`, never a
+            // single mis-quoted `"table.column"`.
+            return resolved
+                .split(".")
+                .map((part) => this.#quote(part))
+                .join(".");
+        };
+        const predicate = `${safe(left)} ${operator} ${safe(right)}`;
+        // Both operands are already validated identifiers and the operator is
+        // allow-listed, so wrapping in NOT(...) adds no new surface.
+        const sql = negated ? `NOT (${predicate})` : predicate;
+        this.#wheres.push({ type, kind: "raw", sql, bindings: [] });
+        return this;
+    }
+    /**
+     * Resolve a column reference that may legitimately point at a table other
+     * than this query's own.
+     *
+     * `#resolveColumn` only knows the entity's own columns, so it rejects
+     * anything qualified. That is right for a value predicate, but wrong for a
+     * column-to-column one: a correlated subquery
+     * (`whereExists(post.query().whereColumn('posts.user_id', '=', 'users.id'))`)
+     * and a joined query both have to name another table, and atlas cannot know
+     * that table's columns. So: an unqualified name resolves as usual (typos
+     * still get the helpful error), and a `table.column` naming a different
+     * table passes through — validated against the identifier charset here and
+     * quoted segment by segment by the caller, never interpolated loose. A typo
+     * in that case surfaces as a database error rather than an atlas one, which
+     * is the unavoidable cost of referencing a table we have no metadata for.
+     */
+    #resolveColumnReference(name) {
+        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.
@@ -476,6 +1189,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>)
@@ -494,6 +1215,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`.
@@ -529,23 +1263,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);
     }
     /**
@@ -576,6 +1312,290 @@ export class ModelQuery {
         this.#orderBys.push({ column: this.#resolveColumn(column), direction });
         return this;
     }
+    /**
+     * `ORDER BY <raw fragment>` (Lucid/Knex `orderByRaw`) — for orderings with
+     * no typed form: `NULLS LAST`, `RANDOM()`, a CASE expression, a computed
+     * alias.
+     *
+     *     query.orderBy('rank').orderByRaw('created_at DESC NULLS LAST')
+     *
+     * The fragment keeps its position among the plain `orderBy` terms.
+     *
+     * **Strict mode**: like {@link whereRaw}, this throws when
+     * `setAtlasStrictMode(true)` (or `ATLAS_STRICT`) is on.
+     *
+     * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+     */
+    orderByRaw(sql) {
+        this.#assertRawAllowed("orderByRaw");
+        this.#orderBys.push({ raw: sql });
+        return this;
+    }
+    /**
+     * `GROUP BY col1, col2, …` (AdonisJS/Lucid `groupBy`). Columns are resolved
+     * through the entity's column map (camelCase → snake_case) like `orderBy`.
+     * For a grouping expression with no typed form, see {@link groupByRaw}.
+     */
+    groupBy(...columns) {
+        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`).
+     * 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: this.#resolveHavingCol(column),
+            operator,
+            value: this.#prep(column, value),
+            type: "and",
+        });
+        return this;
+    }
+    /**
+     * Resolve a HAVING column: a bare model property maps to its DB column
+     * (honouring `@Column({ columnName })`), but an aggregate expression
+     * (`COUNT(*)`), a result alias, or any unknown bare identifier is left verbatim
+     * so `having` can still reference `withCount`/`withAggregate` aliases.
+     */
+    #resolveHavingCol(column) {
+        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: this.#resolveHavingCol(column),
+            operator,
+            value: this.#prep(column, value),
+            type: "or",
+        });
+        return this;
+    }
+    /**
+     * **⚠ UNSAFE** — append a raw SQL `HAVING` fragment with `?` bindings
+     * (AdonisJS/Lucid `havingRaw`). The Rust compiler re-indexes the placeholders;
+     * everything else in `sql` is trusted verbatim. All values must go through
+     * `bindings`.
+     *
+     * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+     */
+    havingRaw(sql, 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,
+            bindings: [...bindings],
+            type: "and",
+        });
+        return this;
+    }
+    /**
+     * `UNION (<query>)` (AdonisJS/Lucid `union`). The other query is compiled and
+     * appended as a parenthesised UNION branch; its bindings are re-indexed into
+     * the outer parameter list.
+     */
+    union(query) {
+        this.#unions.push({ query, all: false });
+        return this;
+    }
+    /** `UNION ALL (<query>)` — duplicate-preserving {@link union}. */
+    unionAll(query) {
+        this.#unions.push({ query, all: true });
+        return this;
+    }
+    /** `INTERSECT (<query>)` — rows present in both (Lucid/Knex `intersect`). */
+    intersect(query) {
+        this.#unions.push({ query, all: false, op: "intersect" });
+        return this;
+    }
+    /**
+     * `INTERSECT ALL (<query>)` — duplicate-preserving {@link intersect}.
+     *
+     * Postgres and MySQL only: SQLite's compound operators are UNION, UNION ALL,
+     * INTERSECT and EXCEPT — there is no INTERSECT ALL — so the compiler raises
+     * `E_UNSUPPORTED` there rather than emitting a syntax error.
+     */
+    intersectAll(query) {
+        this.#unions.push({ query, all: true, op: "intersect" });
+        return this;
+    }
+    /** `EXCEPT (<query>)` — rows in this query but not the other (Lucid/Knex `except`). */
+    except(query) {
+        this.#unions.push({ query, all: false, op: "except" });
+        return this;
+    }
+    /** `EXCEPT ALL (<query>)` — duplicate-preserving {@link except}. Not on SQLite; see {@link intersectAll}. */
+    exceptAll(query) {
+        this.#unions.push({ query, all: true, op: "except" });
+        return this;
+    }
+    /**
+     * `WITH <name> AS (<query>)` — register a Common Table Expression
+     * (AdonisJS/Lucid `with`). The CTE name is validated as an identifier; the
+     * sub-query is compiled and its bindings are re-indexed into the outer list.
+     */
+    with(name, 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) {
+        return this.#pushCte("withRecursive", name, query, { recursive: true });
+    }
+    /**
+     * `WITH <name> AS MATERIALIZED (<query>)` — force the CTE to be evaluated
+     * once and stashed (Lucid/Knex `withMaterialized`).
+     *
+     * Postgres 12+ and SQLite 3.35+ only; MySQL has no such hint and the
+     * compiler raises `E_UNSUPPORTED` rather than emitting a syntax error.
+     */
+    withMaterialized(name, 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(`${method}(): CTE name '${name}' is not a valid identifier`);
+        }
+        this.#ctes.push({ name, query, ...options });
+        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);
+    }
+    /** `@ManyToMany` only — `WHERE <pivotCol> != <value>` on the pivot table (AdonisJS Lucid `whereNotPivot`). */
+    whereNotPivot(column, value) {
+        return this.#pushPivotOp("and", column, "!=", value);
+    }
+    /** Alias of {@link whereNotPivot} (Lucid parity). */
+    andWhereNotPivot(column, value) {
+        return this.#pushPivotOp("and", column, "!=", value);
+    }
+    /** `@ManyToMany` only — OR form of {@link whereNotPivot} (Lucid parity). */
+    orWhereNotPivot(column, value) {
+        return this.#pushPivotOp("or", column, "!=", 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;
+    }
     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
@@ -611,6 +1631,21 @@ export class ModelQuery {
             throw new Error(`No ${this.#tableName} found matching query`);
         return result;
     }
+    /**
+     * Return the single matching row, or throw if there are zero OR more than one
+     * (AdonisJS/Laravel `sole`). Use when exactly one row is a correctness
+     * invariant — a second match signals a bug the silent `first()` would hide.
+     */
+    async sole() {
+        const rows = await this.limit(2).exec();
+        if (rows.length === 0) {
+            throw new Error(`No ${this.#tableName} found matching query (sole()).`);
+        }
+        if (rows.length > 1) {
+            throw new Error(`Expected exactly one ${this.#tableName} but the query matched multiple rows (sole()).`);
+        }
+        return rows[0];
+    }
     /**
      * Thenable — `await someQuery` is equivalent to `await someQuery.exec()`.
      * A chain like `await repo.query().where('active', true).orderBy('id')`
@@ -627,14 +1662,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,
                 });
@@ -642,7 +1742,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,
                 });
@@ -652,19 +1752,36 @@ export class ModelQuery {
         return {
             kind: "select",
             table: this.#tableName,
-            select: this.#select,
+            select: selectCols,
             selectSubqueries: this.#selectSubqueries,
             wheres,
             orderBy: this.#orderBys,
-            groupBy: [],
-            having: [],
+            groupBy: this.#groupBy,
+            having: this.#having,
             limit: this.#limit ?? null,
             offset: this.#offset ?? null,
             distinct: this.#distinct,
-            ctes: [],
-            unions: [],
+            distinctOn: this.#distinctOn,
+            ctes: this.#ctes.map((c) => {
+                const { sql, params } = c.query.toSQL();
+                return {
+                    name: c.name,
+                    sql,
+                    params,
+                    recursive: c.recursive ?? false,
+                    materialized: c.materialized ?? null,
+                };
+            }),
+            unions: this.#unions.map((u) => {
+                const { sql, params } = u.query.toSQL();
+                return { sql, params, all: u.all, op: u.op ?? null };
+            }),
             joins: this.#joins,
-            lockMode: this.#lockMode,
+            lockMode: this.#lockMode
+                ? this.#lockModifier
+                    ? `${this.#lockMode} ${this.#lockModifier}`
+                    : this.#lockMode
+                : null,
         };
     }
     /** Build SQL + params via the Rust query compiler. */
@@ -695,7 +1812,7 @@ export class ModelQuery {
     }
     async #doExec() {
         const { sql, params } = this.toSQL();
-        const rawRows = await this.#db.query(sql, params);
+        const rawRows = await 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);
@@ -710,6 +1827,9 @@ 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)
@@ -718,6 +1838,25 @@ export class ModelQuery {
         }
         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.toSQL();
+        return this.#db.query(sql, params);
+    }
+    /**
+     * Thread arbitrary context onto every instance this query hydrates, exposed as
+     * `entity.$sideloaded` (AdonisJS Lucid `sideload`) — e.g. the current tenant or
+     * user, so hooks/computed can read it. Merges across calls. Chainable.
+     */
+    sideload(values) {
+        this.#sideloaded = { ...this.#sideloaded, ...values };
+        return this;
+    }
     /** Resolve preloaded relations via batched subqueries (no N+1). */
     async #resolvePreloads(entities) {
         if (!this.#entityClass)
@@ -737,33 +1876,84 @@ export class ModelQuery {
     /** 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";
         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 {
@@ -771,7 +1961,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)),
@@ -805,15 +1997,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);
@@ -942,12 +2136,53 @@ 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 [];
-        // Step 1 — pivot table: find (foreignKey → otherKey) pairs
-        const pivotRows = await ctx.runInQuery(pivot.pivotTable, foreignKey, ids);
+        // Extract PIVOT-table constraints (wherePivot / wherePivotIn) from the
+        // preload callback by replaying it on a throwaway builder. The callback
+        // also runs (again) inside runRelationQuery against the related table; both
+        // runs are pure builder mutations, and pivot constraints are inert there.
+        const pivotWheres = [];
+        if (ctx.nestedCallback) {
+            const scratch = new _a(ctx.relatedTable, this.#db, (r) => r, ctx.relatedClass, buildColumnResolver(ctx.relatedClass), false, this.#dialect, buildValuePreparer(ctx.relatedClass));
+            ctx.nestedCallback(scratch);
+            // 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);
         if (pivotRows.length === 0) {
             for (const entity of entities)
                 entity.setProp(relationName, []);
@@ -958,17 +2193,46 @@ export class ModelQuery {
         ];
         // Step 2 — load all related entities in one query
         const relRows = await ctx.runRelationQuery(ctx.relatedPk, otherIds);
+        const pivotCols = pivot.pivotColumns ?? [];
+        const pivotAdapters = pivot.pivotColumnAdapters ?? {};
+        // When pivot extras are projected, each (parent, related) edge gets its OWN
+        // hydrated instance so per-edge `$extras.pivot_<col>` values never clobber
+        // across parents (Lucid gives distinct pivot-bearing instances). Otherwise a
+        // single shared instance per related PK is reused (cheaper, current behaviour).
+        const projectPivot = pivotCols.length > 0;
+        const rawByRelatedPk = new Map();
         const byRelatedPk = new Map();
         const allRelated = [];
         for (const row of relRows) {
-            const hydrated = ctx.hydrate(row);
-            byRelatedPk.set(row[ctx.relatedPk], hydrated);
-            allRelated.push(hydrated);
+            rawByRelatedPk.set(row[ctx.relatedPk], row);
+            if (!projectPivot) {
+                const hydrated = ctx.hydrate(row);
+                byRelatedPk.set(row[ctx.relatedPk], hydrated);
+                allRelated.push(hydrated);
+            }
         }
-        // Step 3 — group via the pivot
+        // Step 3 — group via the pivot, projecting declared pivotColumns into
+        // `$extras.pivot_<col>` (running each column's `consume` adapter if any).
         const grouped = new Map();
         for (const pivotRow of pivotRows) {
-            const related = byRelatedPk.get(pivotRow[otherKey]);
+            let related;
+            if (projectPivot) {
+                const raw = rawByRelatedPk.get(pivotRow[otherKey]);
+                if (!raw)
+                    continue;
+                related = ctx.hydrate(raw);
+                for (const col of pivotCols) {
+                    const rawVal = pivotRow[col];
+                    const adapter = pivotAdapters[col];
+                    related.setExtra(`pivot_${col}`, 
+                    // Adonis Lucid signature: (value, attribute, model).
+                    adapter?.consume ? adapter.consume(rawVal, col, related) : rawVal);
+                }
+                allRelated.push(related);
+            }
+            else {
+                related = byRelatedPk.get(pivotRow[otherKey]);
+            }
             if (!related)
                 continue;
             const parentId = pivotRow[foreignKey];
@@ -985,20 +2249,41 @@ 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);
         }
     }
     /** Compile + execute a `SELECT * FROM <table> WHERE <column> IN (...)` via the Rust compiler. */
-    async #runInQuery(table, column, values) {
+    async #runInQuery(table, column, values, extraWheres = []) {
+        const wheres = [
+            { column, operator: "IN", value: values, type: "and" },
+        ];
+        // The caller's filters go in a parenthesised group, never flat beside the
+        // `IN`. Flat, an `orWherePivot` would read as
+        // `WHERE fk IN (parents) OR active = 1` and hand back rows belonging to
+        // other parents; grouped, it is `WHERE fk IN (parents) AND (… OR …)`.
+        // With every filter ANDed the two forms are equivalent, so this changes
+        // no existing query.
+        if (extraWheres.length > 0) {
+            wheres.push({
+                kind: "group",
+                type: "and",
+                conditions: extraWheres.map((w) => ({
+                    column: w.column,
+                    operator: w.operator,
+                    value: w.value,
+                    type: w.type ?? "and",
+                })),
+            });
+        }
         const spec = {
             kind: "select",
             table,
             select: ["*"],
             selectSubqueries: [],
-            wheres: [{ column, operator: "IN", value: values, type: "and" }],
+            wheres,
             orderBy: [],
             groupBy: [],
             having: [],
@@ -1025,7 +2310,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
@@ -1033,7 +2322,7 @@ 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);
@@ -1072,28 +2361,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": {
-                const fk = `${camelToSnake(this.#entityClass.name)}_id`;
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(fk)} = ${q(parentTable)}.${q(parentPk)}`);
+                // Honour custom foreignKey/localKey exactly like the eager loader —
+                // hard-coding them here produced silently-wrong whereHas/withCount SQL.
+                const fk = relation.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+                const localKey = resolveParent(relation.localKey ?? parentPk);
+                sub.#pushWhereRaw(`${qTable(relatedTable)}.${q(fk)} = ${qTable(parentTable)}.${q(localKey)}`);
                 break;
             }
             case "belongsTo": {
-                const fk = `${camelToSnake(relatedClass.name)}_id`;
-                const relatedPk = getPrimaryKey(relatedClass) ?? "id";
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(relatedPk)} = ${q(parentTable)}.${q(fk)}`);
+                const fk = relation.foreignKey ?? `${camelToSnake(relatedClass.name)}_id`;
+                const ownerKey = buildColumnResolver(relatedClass)(relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id");
+                sub.#pushWhereRaw(`${qTable(relatedTable)}.${q(ownerKey)} = ${qTable(parentTable)}.${q(fk)}`);
                 break;
             }
             case "manyToMany": {
@@ -1105,20 +2416,35 @@ 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";
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(relatedPk)} IN ` +
-                    `(SELECT ${q(otherKey)} FROM ${q(pivot.pivotTable)} ` +
-                    `WHERE ${q(pivot.pivotTable)}.${q(foreignKey)} = ${q(parentTable)}.${q(parentPk)})`);
+                const relatedPkProp = getPrimaryKey(relatedClass) ?? "id";
+                const relatedPk = getColumnMetadata(relatedClass).find((c) => c.propertyKey === relatedPkProp)?.columnName ?? camelToSnake(relatedPkProp);
+                const localKey = resolveParent(relation.localKey ?? parentPk);
+                sub.#pushWhereRaw(`${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":
+            case "hasManyThrough": {
+                // Two-hop correlated EXISTS: parent → through → related. Mirrors the
+                // eager loader's key resolution (`#resolveThrough`) exactly so
+                // whereHas/withCount agree with what preload() would return.
+                if (!relation.through) {
+                    throw new Error(`@HasOneThrough/@HasManyThrough '${relationName}' requires a through model`);
+                }
+                const throughClass = relation.through();
+                const throughMeta = ensureEntityMetadata(throughClass);
+                const throughTable = throughMeta.tableName;
+                const throughPk = getPrimaryKey(throughClass) ?? "id";
+                const parentLocal = resolveParent(relation.localKey ?? parentPk);
+                const firstKey = relation.firstKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+                const secondKey = relation.secondKey ?? `${camelToSnake(throughClass.name)}_id`;
+                const secondLocal = buildColumnResolver(throughClass)(relation.secondLocalKey ?? throughPk);
+                sub.#pushWhereRaw(`${qTable(relatedTable)}.${q(secondKey)} IN ` +
+                    `(SELECT ${q(secondLocal)} FROM ${qTable(throughTable)} ` +
+                    `WHERE ${qTable(throughTable)}.${q(firstKey)} = ${qTable(parentTable)}.${q(parentLocal)})`);
                 break;
             }
-            default:
-                // hasOneThrough / hasManyThrough build a 2-hop correlated subquery,
-                // which isn't implemented here. Fail loud — falling through would
-                // leave `sub` WITHOUT a join predicate, so whereHas/withCount would
-                // silently match/count EVERY related row.
-                throw new Error(`whereHas/withCount on a '${relation.type}' relation ` +
-                    `(${this.#entityClass.name}.${relationName}) is not supported yet. ` +
-                    `Use a direct hasMany/belongsTo/manyToMany relation, or filter via a sub-query.`);
         }
         return sub;
     }
@@ -1132,8 +2458,8 @@ export class ModelQuery {
         return this.#pushJoin("RIGHT", table, leftOrBuild, 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;
     }
     /**
@@ -1152,12 +2478,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;
     }
     /**
@@ -1179,9 +2505,37 @@ export class ModelQuery {
         this.#distinct = true;
         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() {
@@ -1189,7 +2543,7 @@ export class ModelQuery {
         clone.#select = ["1"];
         clone.#limit = 1;
         const { sql, params } = clone.toSQL();
-        const rows = await this.#db.query(sql, params);
+        const rows = await this.#db.query(sql, params, this.#meta("exists"));
         return rows.length > 0;
     }
     async doesntExist() {
@@ -1258,14 +2612,29 @@ export class ModelQuery {
         // beforePaginate runs BEFORE cloning so a hook mutating the query (e.g. a
         // tenant scope) propagates into both the COUNT and the data fetch.
         await fireHooks(this.#entityClass, "beforePaginate", this);
-        // Parallel COUNT(*) + data fetch
+        // COUNT(*) + data fetch
         const countQ = this.clone();
-        countQ.#select = ["COUNT(*) AS count"];
         countQ.#limit = undefined;
         countQ.#offset = undefined;
         countQ.#orderBys = [];
-        const { sql: cSql, params: cParams } = countQ.toSQL();
-        const cRows = await this.#db.query(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.toSQL();
+            cSql = `SELECT COUNT(*) AS count FROM (${inner.sql}) AS __paginate_count`;
+            cParams = inner.params;
+        }
+        else {
+            countQ.#select = ["COUNT(*) AS count"];
+            const flat = countQ.toSQL();
+            cSql = flat.sql;
+            cParams = flat.params;
+        }
+        const cRows = await this.#db.query(cSql, cParams, this.#meta("paginate"));
         const total = Number(cRows[0]?.count ?? 0);
         const dataQ = this.clone();
         dataQ.#limit = pp;
@@ -1274,7 +2643,10 @@ export class ModelQuery {
         // top of the paginate hooks — paginate is its own terminal.
         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;
+        return new Paginator(items, { total, perPage: pp, currentPage: p }, metaKeys);
     }
     /**
      * Cursor-based pagination — base64 opaque keyset, multi-column aware.
@@ -1290,7 +2662,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));
@@ -1334,7 +2712,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 };
     }
@@ -1351,6 +2729,21 @@ export class ModelQuery {
         this.#debugFlag = flag;
         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,
+        };
+    }
     /** Returns the compiled SQL with bindings interpolated as dialect-safe literals. */
     toQuery() {
         const { sql, params } = this.toSQL();
@@ -1362,7 +2755,7 @@ export class ModelQuery {
     }
     /** 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];
@@ -1371,9 +2764,29 @@ export class ModelQuery {
         c.#offset = this.#offset;
         c.#preloads = new Map(this.#preloads);
         c.#selectSubqueries = structuredClone(this.#selectSubqueries);
-        c.#joins = [...this.#joins];
+        c.#joins = this.#joins.map((j) => ({ sql: j.sql, params: [...j.params] }));
         c.#lockMode = this.#lockMode;
+        c.#lockModifier = this.#lockModifier;
+        c.#sideloaded = this.#sideloaded ? { ...this.#sideloaded } : null;
         c.#distinct = this.#distinct;
+        c.#distinctOn = [...this.#distinctOn];
+        c.#groupBy = [...this.#groupBy];
+        c.#having = structuredCloneSafe(this.#having);
+        c.#ctes = this.#ctes.map((e) => ({
+            name: e.name,
+            query: e.query.clone(),
+            recursive: e.recursive,
+            materialized: e.materialized,
+        }));
+        c.#unions = this.#unions.map((u) => ({
+            query: u.query.clone(),
+            all: u.all,
+            op: u.op,
+        }));
+        c.#pivotWheres = structuredCloneSafe(this.#pivotWheres);
+        // Pure closure over pivot metadata — safe to share by reference; it reads the
+        // clone's own #pivotWheres at build time (passed in), holding no query state.
+        c.#pivotExists = this.#pivotExists;
         c.#debugFlag = this.#debugFlag;
         return c;
     }
@@ -1383,13 +2796,15 @@ export class ModelQuery {
         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]);
+        // Lower each value through prepare (DateTime → ISO, @Column adapters) exactly
+        // like BaseRepository's write paths — the fluent update() must not bypass it.
+        const setPairs = Object.entries(patch).map(([k, v]) => [this.#resolveColumn(k), this.#prepareValue(k, v)]);
         const spec = {
             kind: "update",
             table: this.#tableName,
             set: setPairs,
             wheres: this.#wheresForDml(),
-            returning: returning ?? [],
+            returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
         };
         const compiled = compileStatementNative(spec, this.#dialect);
         if (returning && returning.length > 0) {
@@ -1398,20 +2813,60 @@ export class ModelQuery {
         const r = await this.#db.execute(compiled.statements[0], compiled.params);
         return r.rowsAffected ?? 0;
     }
-    /** Execute a fluent DELETE. Returns affected rows (or rows when `returning` is set). */
+    /**
+     * Execute a fluent DELETE. For a `@SoftDeletes` model this SOFT-deletes the
+     * scoped rows (stamps `deleted_at`) — consistent with the entity-level
+     * `delete()`; use {@link forceDelete} for a hard `DELETE`. For a non-soft-delete
+     * model it issues a hard `DELETE`. Returns affected rows (or rows when
+     * `returning` is set).
+     */
     async delete(returning) {
+        if (this.#softDeletes) {
+            const spec = {
+                kind: "update",
+                table: this.#tableName,
+                set: [[this.#deletedAtColumn(), new Date().toISOString()]],
+                wheres: this.#wheresForDml(),
+                returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
+            };
+            return this.#runDml(spec, returning);
+        }
+        return this.forceDelete(returning);
+    }
+    /** Hard `DELETE` of the scoped rows, bypassing `@SoftDeletes` (AdonisJS/Lucid `forceDelete`). */
+    async forceDelete(returning) {
         const spec = {
             kind: "delete",
             table: this.#tableName,
             wheres: this.#wheresForDml(),
-            returning: returning ?? [],
+            returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
         };
-        const compiled = compileStatementNative(spec, this.#dialect);
-        if (returning && returning.length > 0) {
-            return this.#db.query(compiled.statements[0], compiled.params);
-        }
-        const r = await this.#db.execute(compiled.statements[0], compiled.params);
-        return r.rowsAffected ?? 0;
+        return this.#runDml(spec, returning);
+    }
+    /**
+     * Bulk restore: clear `deleted_at` on the trashed rows matching the user's
+     * predicates (the soft-delete counterpart of {@link delete}). No-op count `0`
+     * on a non-soft-delete model. Independent of the current soft-scope — it always
+     * targets trashed rows (`deleted_at IS NOT NULL`).
+     */
+    async restore(returning) {
+        if (!this.#softDeletes)
+            return 0;
+        const wheres = this.#userWheresForDml();
+        wheres.push({
+            column: this.#deletedAtColumn(),
+            operator: "IS NOT NULL",
+            value: null,
+            type: "and",
+        });
+        const spec = {
+            kind: "update",
+            table: this.#tableName,
+            set: [[this.#deletedAtColumn(), null]],
+            wheres,
+            returning: (returning ?? []).map((c) => this.#resolveSelect(c)),
+        };
+        return this.#runDml(spec, returning);
     }
     increment(colOrPatch, amount = 1) {
         return this.#runIncDec("increment", colOrPatch, amount);
@@ -1438,20 +2893,73 @@ 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)}`;
+        // Validate BEFORE quoting — `#quote` only wraps in quotes/backticks, so an
+        // identifier smuggling a `"`/backtick would break out of the quoting on the
+        // join path (which the Rust screen doesn't re-validate). Strict
+        // `[[schema.]table.]column` grammar (up to 3 dot segments); keeps join
+        // helpers injection-safe. Use joinRaw() for anything more complex.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*){0,2}$/.test(ref)) {
+            throw new Error(`Invalid join/column identifier '${ref}' — expected [[schema.]table.]column (letters, digits, underscore). Use joinRaw() for anything else.`);
         }
-        return this.#quote(ref);
+        return ref
+            .split(".")
+            .map((seg) => this.#quote(seg))
+            .join(".");
     }
     #pushJoin(kind, table, leftOrBuild, right) {
-        const tq = this.#quote(table);
+        const tq = this.#quoteCol(table);
         if (typeof leftOrBuild === "function") {
             const jb = {
                 parts: [],
@@ -1463,24 +2971,56 @@ export class ModelQuery {
                     this.parts.push({ kind: "and", left: l, right: r });
                     return this;
                 },
-                andOnVal(l, _v) {
-                    this.parts.push({ kind: "and", left: l, right: "?" });
+                orOn(l, r) {
+                    this.parts.push({ kind: "or", left: l, right: r });
+                    return this;
+                },
+                onVal(l, v) {
+                    this.parts.push({ kind: "and", left: l, value: { v } });
+                    return this;
+                },
+                andOnVal(l, v) {
+                    this.parts.push({ kind: "and", left: l, value: { v } });
+                    return this;
+                },
+                orOnVal(l, v) {
+                    this.parts.push({ kind: "or", left: l, value: { v } });
                     return this;
                 },
             };
             leftOrBuild(jb);
+            // Collect the bound values in placeholder order as the fragment is built.
+            const params = [];
             const on = jb.parts
                 .map((p, i) => {
                 const prefix = i === 0 ? "ON" : p.kind === "or" ? "OR" : "AND";
-                return `${prefix} ${this.#quoteCol(p.left)} = ${p.right === "?" ? "?" : this.#quoteCol(p.right)}`;
+                if (p.value) {
+                    // A BASE-table column runs the full model prepare (DateTime→ISO +
+                    // @Column adapters/casts), keyed by its property. A FOREIGN join
+                    // column must NOT borrow the root model's adapter for a same-named
+                    // column on another table — apply only universal type-lowering
+                    // (Date/DateTime→ISO), matching Knex's model-agnostic join binding.
+                    const dot = p.left.lastIndexOf(".");
+                    const tablePrefix = dot >= 0 ? p.left.slice(0, dot) : "";
+                    const leaf = dot >= 0 ? p.left.slice(dot + 1) : p.left;
+                    const isBaseColumn = tablePrefix === "" || sameTableRef(tablePrefix, this.#tableName);
+                    params.push(isBaseColumn
+                        ? this.#prepareValue(leaf, p.value.v)
+                        : lowerJoinValue(p.value.v));
+                    return `${prefix} ${this.#quoteCol(p.left)} = ?`;
+                }
+                return `${prefix} ${this.#quoteCol(p.left)} = ${this.#quoteCol(p.right ?? "")}`;
             })
                 .join(" ");
-            this.#joins.push(`${kind} JOIN ${tq} ${on}`);
+            this.#joins.push({ sql: `${kind} JOIN ${tq} ${on}`, params });
             return this;
         }
         if (right === undefined)
             throw new Error("join() with string form requires both left and right operands");
-        this.#joins.push(`${kind} JOIN ${tq} ON ${this.#quoteCol(leftOrBuild)} = ${this.#quoteCol(right)}`);
+        this.#joins.push({
+            sql: `${kind} JOIN ${tq} ON ${this.#quoteCol(leftOrBuild)} = ${this.#quoteCol(right)}`,
+            params: [],
+        });
         return this;
     }
     async #runScalar(expr) {
@@ -1512,7 +3052,8 @@ export class ModelQuery {
      * still rejected because the DML compiler's WHERE lowering does not yet
      * handle nested sub-queries or correlated EXISTS.
      */
-    #wheresForDml() {
+    /** The user's own WHERE predicates mapped for DML (no soft-delete scope). */
+    #userWheresForDml() {
         const out = [];
         for (const w of this.#wheres) {
             if ("kind" in w) {
@@ -1537,6 +3078,43 @@ export class ModelQuery {
         }
         return out;
     }
+    #wheresForDml() {
+        const out = this.#userWheresForDml();
+        // Mirror the read scope (`#buildSpec`): a `@SoftDeletes` model's bulk
+        // update/delete/increment/decrement must NOT touch trashed rows under the
+        // default scope — otherwise `query().where(x)` would denote a different row
+        // set for `.exec()` than for `.update()`/`.delete()`. `.withTrashed()` widens,
+        // `.onlyTrashed()` restricts to trashed (mirrors reads).
+        if (this.#softDeletes) {
+            const deletedAtCol = this.#deletedAtColumn();
+            if (this.#softScope === "default") {
+                out.push({
+                    column: deletedAtCol,
+                    operator: "IS NULL",
+                    value: null,
+                    type: "and",
+                });
+            }
+            else if (this.#softScope === "only-trashed") {
+                out.push({
+                    column: deletedAtCol,
+                    operator: "IS NOT NULL",
+                    value: null,
+                    type: "and",
+                });
+            }
+        }
+        return out;
+    }
+    /** Compile + run a DML spec: returns affected-row count, or rows when `returning` is set. */
+    async #runDml(spec, 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;
+    }
     /**
      * !!! DEBUG ONLY — DO NOT USE FOR EXECUTION !!!
      *
@@ -1569,7 +3147,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 };
     }
@@ -1609,7 +3187,7 @@ export class ModelQuery {
                 type,
                 column: resolved,
                 operator: "=",
-                value: operatorOrValue,
+                value: this.#prep(column, operatorOrValue),
             });
         }
         else {
@@ -1617,11 +3195,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.