@c9up/atlas 0.1.3 → 0.1.5

package/dist/BaseRepository.js

@@ -0,0 +1,1451 @@
+/**
+ * BaseRepository — Data Mapper ORM with typed CRUD, soft deletes, and domain events.
+ *
+ * @implements FR29, FR31, FR35
+ */
+import { randomUUID } from "node:crypto";
+import { REPO_REF } from "./BaseEntity.js";
+import { getColumnMetadata, getDateColumnConfig, getEntityMetadata, getPrimaryKey, getPrimaryKeyGenerator, getRelationMetadata, hasSoftDeletes, } from "./decorators/entity.js";
+import { fireHooks } from "./decorators/hooks.js";
+import { AtlasError, EntityNotFoundError } from "./errors.js";
+import { ModelQuery, runWithAtlasInternalBypass } from "./ModelQuery.js";
+import { compileStatementNative, getAtlasDialect, } from "./query/native.js";
+import { camelToSnake, snakeToCamel } from "./utils/casing.js";
+/**
+ * Coerce a `lastInsertRowid` to a JS number when it fits, leaving large
+ * mysql/sqlite values as bigint so callers don't silently lose precision.
+ */
+function normalizeRowid(rowid) {
+    if (typeof rowid === "number")
+        return rowid;
+    return rowid <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(rowid) : rowid;
+}
+/**
+ * Whether a primary-key value should be treated as supplied. Distinguishes
+ * "explicit zero / empty-string id" from "unset" — only `null`/`undefined`
+ * route through the INSERT path; every other value is a candidate UPDATE.
+ */
+function isProvidedPk(pk) {
+    return pk !== undefined && pk !== null;
+}
+/**
+ * Detect a unique-key / primary-key violation from the underlying driver
+ * error. Used by `save()` to recover from a TOCTOU race between the
+ * `find(pk)` check and the `INSERT`: a concurrent insert that wins the PK
+ * race surfaces as one of these codes, and we fall back to UPDATE rather
+ * than propagate a DB constraint error.
+ *
+ *   - PostgreSQL: SQLSTATE `23505` (`unique_violation`)
+ *   - SQLite:     `SQLITE_CONSTRAINT_PRIMARYKEY` / `SQLITE_CONSTRAINT_UNIQUE`
+ *   - MySQL:      `ER_DUP_ENTRY` (named) / errno `1062` (numeric)
+ */
+function isUniqueKeyViolation(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const e = err;
+    const code = e.code;
+    const errno = e.errno;
+    return (code === "23505" ||
+        code === "SQLITE_CONSTRAINT_PRIMARYKEY" ||
+        code === "SQLITE_CONSTRAINT_UNIQUE" ||
+        code === "ER_DUP_ENTRY" ||
+        errno === 1062);
+}
+// ─── Repository ─────────────────────────────────────────────
+/** Logical column types Postgres won't coerce from a text-bound param. */
+const POSTGRES_CAST_TYPES = new Set([
+    "timestamp",
+    "datetime",
+    "date",
+    "time",
+    "uuid",
+    "json",
+    "jsonb",
+]);
+/**
+ * Snake column → logical type for params needing a Postgres `$N::<type>` cast.
+ * sqlx binds JS strings as `text`; Postgres won't implicitly coerce that to
+ * timestamp/uuid/date. The Rust compiler applies these on Postgres only.
+ */
+function computeCastTypes(entityClass) {
+    const out = {};
+    for (const col of getColumnMetadata(entityClass)) {
+        const t = col.type?.toLowerCase();
+        if (t && POSTGRES_CAST_TYPES.has(t)) {
+            out[camelToSnake(col.propertyKey)] = t;
+        }
+    }
+    // A uuid-strategy primary key is generated app-side as a string.
+    if (getPrimaryKeyGenerator(entityClass) === "uuid") {
+        out[camelToSnake(getPrimaryKey(entityClass) ?? "id")] ??= "uuid";
+    }
+    return out;
+}
+export class BaseRepository {
+    #entityClass;
+    #tableName;
+    #primaryKey;
+    #columns;
+    #db;
+    #softDeletes;
+    #validColumns;
+    #columnMap; // camelCase → snake_case (cached)
+    #dateColumns;
+    /** Snake column → logical type for params needing a Postgres `::cast`. */
+    #castTypes;
+    /**
+     * Per-property `prepare` (model → DB) callbacks lifted directly from
+     * `@Column({ prepare })` metadata. Keyed by camelCase `propertyKey`.
+     * Mirror of Adonis Lucid's `@column.prepare`. Story 35.10.
+     */
+    #columnPrepares;
+    /**
+     * Per-property `consume` (DB → model) callbacks lifted directly from
+     * `@Column({ consume })` metadata. Keyed by camelCase `propertyKey`.
+     * Mirror of Adonis Lucid's `@column.consume`. Story 35.10.
+     */
+    #columnConsumes;
+    /**
+     * SQL dialect used by this repository. Resolved at construction time from
+     * the connection (if it exposes a `dialect` property) or from the explicit
+     * `options.dialect` override, falling back to the process-wide default as
+     * the last resort. Passed to every `compileStatementNative` call so that
+     * multi-connection apps with heterogeneous dialects (postgres + mysql, …)
+     * compile each query with the correct target.
+     */
+    #dialect;
+    /** Callback to dispatch domain events (set by framework integration). */
+    onDomainEvents;
+    constructor(entityClass, db, options) {
+        this.#entityClass = entityClass;
+        this.#db = db;
+        // Dialect resolution order: explicit option > connection.dialect > process default.
+        const connDialect = db.dialect;
+        this.#dialect = options?.dialect ?? connDialect ?? getAtlasDialect();
+        const meta = getEntityMetadata(entityClass);
+        if (!meta) {
+            throw new AtlasError("NOT_ENTITY", `Class '${entityClass.name}' is not decorated with @Entity()`, {
+                hint: "Add @Entity('table_name') decorator to the class.",
+            });
+        }
+        this.#tableName = meta.tableName;
+        this.#primaryKey = getPrimaryKey(entityClass) ?? "id";
+        const columnsMeta = getColumnMetadata(entityClass);
+        this.#columns = columnsMeta.map((c) => c.propertyKey);
+        this.#softDeletes = hasSoftDeletes(entityClass);
+        this.#dateColumns = getDateColumnConfig(entityClass);
+        // Lift per-column `prepare` / `consume` callbacks directly from metadata.
+        // No global registry, no late-registration concern: callbacks are baked
+        // into the entity definition. Mirrors Adonis Lucid's `@column.prepare` /
+        // `@column.consume` pattern.
+        this.#columnPrepares = new Map();
+        this.#columnConsumes = new Map();
+        for (const col of columnsMeta) {
+            if (col.prepare)
+                this.#columnPrepares.set(col.propertyKey, col.prepare);
+            if (col.consume)
+                this.#columnConsumes.set(col.propertyKey, col.consume);
+        }
+        // Pre-compute column mappings for validation + hydration.
+        // Snapshot is frozen at construction — `@Column` decorators that run
+        // AFTER the repository instance is created (e.g. lazy/dynamic
+        // definitions) are invisible to the validator and will be rejected
+        // by `#resolveColumn`. Decorators must run at class-body evaluation
+        // time, before any repository for that entity is instantiated.
+        this.#validColumns = new Set();
+        this.#columnMap = new Map();
+        for (const col of this.#columns) {
+            const snake = camelToSnake(col);
+            this.#validColumns.add(col);
+            this.#validColumns.add(snake);
+            this.#columnMap.set(col, snake);
+            this.#columnMap.set(snake, snake);
+        }
+        this.#validColumns.add(this.#primaryKey);
+        this.#validColumns.add(camelToSnake(this.#primaryKey));
+        this.#columnMap.set(this.#primaryKey, camelToSnake(this.#primaryKey));
+        // Postgres cast hints: sqlx binds JS strings as `text`, which Postgres
+        // won't coerce to timestamp/uuid/date. See `computeCastTypes`.
+        this.#castTypes = computeCastTypes(entityClass);
+    }
+    // ─── Column validation ────────────────────────────────────
+    /** Resolve a column name to snake_case. Throws on invalid column. */
+    #resolveColumn(column) {
+        const mapped = this.#columnMap.get(column);
+        if (mapped)
+            return mapped;
+        const snake = camelToSnake(column);
+        if (this.#validColumns.has(snake))
+            return snake;
+        throw new AtlasError("E_INVALID_COLUMN", `Column '${column}' does not exist on ${this.#entityClass.name}`, {
+            hint: `Valid columns: ${this.#columns.join(", ")}`,
+        });
+    }
+    // ─── Query builder ────────────────────────────────────────
+    query() {
+        return new ModelQuery(this.#tableName, this.#db, (row) => this.#hydrate(row), this.#entityClass, (col) => this.#resolveColumn(col), this.#softDeletes, this.#dialect);
+    }
+    // ─── Transaction ──────────────────────────────────────────
+    useTransaction(trx) {
+        // Propagate the owning repo's dialect so the transactional copy stays on
+        // the correct SQL flavour — critical for multi-connection apps where the
+        // primary is postgres but a tenant runs on sqlite (or vice versa).
+        // Without this the transactional repo silently fell back to the global
+        // default and compiled mis-quoted SQL.
+        const repo = new BaseRepository(this.#entityClass, trx, {
+            dialect: this.#dialect,
+        });
+        repo.onDomainEvents = this.onDomainEvents;
+        return repo;
+    }
+    // ─── Finders ──────────────────────────────────────────────
+    async find(id) {
+        const wheres = [
+            { column: this.#primaryKey, operator: "=", value: id, type: "and" },
+        ];
+        this.#appendSoftScope(wheres);
+        const { sql, params } = this.#compileSelect({ wheres, limit: 1 });
+        const rows = await this.#db.query(sql, params);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return this.#hydrate(row);
+    }
+    async findOrFail(id) {
+        const entity = await this.find(id);
+        if (!entity) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: id,
+            });
+        }
+        return entity;
+    }
+    async findBy(column, value) {
+        const col = this.#resolveColumn(column);
+        const wheres = [
+            { column: col, operator: "=", value, type: "and" },
+        ];
+        this.#appendSoftScope(wheres);
+        const { sql, params } = this.#compileSelect({ wheres, limit: 1 });
+        const rows = await this.#db.query(sql, params);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return this.#hydrate(row);
+    }
+    async all() {
+        const wheres = [];
+        this.#appendSoftScope(wheres);
+        return this.#runSelect({ wheres });
+    }
+    async allWithTrashed() {
+        return this.#runSelect({});
+    }
+    async onlyTrashed() {
+        if (!this.#softDeletes)
+            return [];
+        return this.#runSelect({
+            wheres: [
+                {
+                    column: "deleted_at",
+                    operator: "IS NOT NULL",
+                    value: null,
+                    type: "and",
+                },
+            ],
+        });
+    }
+    async where(column, value) {
+        const col = this.#resolveColumn(column);
+        const wheres = [
+            { column: col, operator: "=", value, type: "and" },
+        ];
+        this.#appendSoftScope(wheres);
+        // Order by the resolved primary key (DESC = most recent insert first when
+        // the PK is an auto-increment integer or a monotonic UUID). Previously
+        // this hard-coded `rowid DESC`, which is a SQLite-only pseudo-column and
+        // blew up on Postgres/MySQL the moment the app ran against a real driver.
+        // Using the PK works on every dialect and matches the user's actual
+        // schema — the ordering contract is "most recent first by PK" for
+        // `repo.where(col, val)` as a convenience finder.
+        const pkCol = camelToSnake(this.#primaryKey);
+        return this.#runSelect({
+            wheres,
+            orderBy: [{ column: pkCol, direction: "desc" }],
+        });
+    }
+    // ─── Create / Save / Delete ───────────────────────────────
+    /**
+     * Build an entity from a plain object and persist it. Fires `beforeSave` →
+     * `beforeCreate` → INSERT → `afterCreate` → `afterSave`.
+     */
+    async create(data) {
+        const entity = new this.#entityClass();
+        for (const [key, value] of Object.entries(data)) {
+            if (this.#validColumns.has(key) ||
+                this.#validColumns.has(camelToSnake(key))) {
+                entity.setProp(key, value);
+            }
+        }
+        await fireHooks(this.#entityClass, "beforeSave", entity);
+        await fireHooks(this.#entityClass, "beforeCreate", entity);
+        await this.#insert(entity);
+        await fireHooks(this.#entityClass, "afterCreate", entity);
+        await fireHooks(this.#entityClass, "afterSave", entity);
+        return entity;
+    }
+    /**
+     * Persist an entity. Insert if PK is missing or row doesn't exist, update
+     * otherwise. Fires `beforeSave` → (`beforeCreate` | `beforeUpdate`) → DB →
+     * (`afterCreate` | `afterUpdate`) → `afterSave`, then dispatches
+     * accumulated domain events through `onDomainEvents`.
+     *
+     * Race-safety: the `find(pk)` → branch decision has a TOCTOU window. If a
+     * concurrent save inserts the same PK between our `find` and our `#insert`,
+     * the INSERT hits a unique-key violation; we catch it and fall back to the
+     * UPDATE path. The race-loser still fires `beforeCreate` before the
+     * recovery (its hook ran once before the conflict surfaced) — design
+     * `beforeCreate` hooks to be idempotent or move side-effects into
+     * `afterCreate` / `afterSave` where they only fire on commit.
+     */
+    async save(entity) {
+        const pk = entity[this.#primaryKey];
+        // Treat a present PK (including `0` and `''`) as a candidate update —
+        // `pk && ...` would route legitimate zero / empty-string keys through
+        // INSERT and double-write the row.
+        const isUpdate = isProvidedPk(pk) && (await this.find(pk)) !== null;
+        await fireHooks(this.#entityClass, "beforeSave", entity);
+        if (isUpdate) {
+            await this.#runUpdateBranch(entity);
+        }
+        else {
+            try {
+                await this.#runInsertBranch(entity);
+            }
+            catch (err) {
+                // Race recovery: the row didn't exist when we checked, but a
+                // concurrent insert beat us to it. Only fall back when the PK
+                // was explicitly provided (auto-generated PK can't collide on
+                // a fresh insert — DB generates a unique one per call).
+                if (isProvidedPk(pk) && isUniqueKeyViolation(err)) {
+                    await this.#runUpdateBranch(entity);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        await fireHooks(this.#entityClass, "afterSave", entity);
+        const events = entity.flushDomainEvents();
+        if (events.length > 0 && this.onDomainEvents) {
+            try {
+                await this.onDomainEvents([...events]);
+            }
+            catch (err) {
+                for (const e of events)
+                    entity.addDomainEvent(e.name, e.data);
+                throw err;
+            }
+        }
+    }
+    async #runInsertBranch(entity) {
+        await fireHooks(this.#entityClass, "beforeCreate", entity);
+        await this.#insert(entity);
+        await fireHooks(this.#entityClass, "afterCreate", entity);
+    }
+    async #runUpdateBranch(entity) {
+        await fireHooks(this.#entityClass, "beforeUpdate", entity);
+        await this.#update(entity);
+        await fireHooks(this.#entityClass, "afterUpdate", entity);
+    }
+    /**
+     * Insert many rows in a single multi-row INSERT. Fires beforeSave/beforeCreate
+     * on each hydrated entity, then hydrates from the RETURNING clause (postgres +
+     * sqlite) before firing afterCreate/afterSave. On mysql, falls back to N single
+     * INSERTs (documented limitation).
+     *
+     * @implements Story 30.1 + 30.5
+     */
+    async createMany(rows) {
+        if (rows.length === 0)
+            return [];
+        const entities = rows.map((r) => {
+            const e = new this.#entityClass();
+            for (const [k, v] of Object.entries(r)) {
+                if (this.#validColumns.has(k) ||
+                    this.#validColumns.has(camelToSnake(k)))
+                    e.setProp(k, v);
+            }
+            return e;
+        });
+        for (const e of entities) {
+            await fireHooks(this.#entityClass, "beforeSave", e);
+            await fireHooks(this.#entityClass, "beforeCreate", e);
+        }
+        if (this.#dialect === "mysql") {
+            // mysql: loop single inserts (no RETURNING).
+            for (const e of entities)
+                await this.#insert(e);
+        }
+        else {
+            const specRows = entities.map((e) => this.#entityToRowPairs(e));
+            const spec = {
+                kind: "insert",
+                table: this.#tableName,
+                rows: specRows,
+                casts: this.#castTypes,
+                returning: [
+                    camelToSnake(this.#primaryKey),
+                    ...this.#columns.map((c) => camelToSnake(c)),
+                ],
+            };
+            const compiled = compileStatementNative(spec, this.#dialect);
+            const returned = await this.#db.query(compiled.statements[0], compiled.params);
+            returned.forEach((row, i) => {
+                for (const [k, v] of Object.entries(row))
+                    entities[i].setProp(snakeToCamel(k), v);
+                entities[i].markAsPersisted();
+            });
+        }
+        for (const e of entities) {
+            await fireHooks(this.#entityClass, "afterCreate", e);
+            await fireHooks(this.#entityClass, "afterSave", e);
+        }
+        return entities;
+    }
+    /**
+     * Persist many already-constructed entity instances. Same hooks + batching
+     * as `createMany`, but accepts prebuilt entities so dirty tracking works.
+     *
+     * @implements Story 30.5
+     */
+    async saveMany(entities) {
+        if (entities.length === 0)
+            return [];
+        // Split new vs already-persisted; for simplicity, persist new ones as a
+        // batch and fall back to per-entity save for dirty ones.
+        const fresh = [];
+        const dirty = [];
+        for (const e of entities) {
+            if (Object.keys(e.$original ?? {}).length === 0)
+                fresh.push(e);
+            else
+                dirty.push(e);
+        }
+        if (fresh.length > 0) {
+            const rows = fresh.map((e) => {
+                const r = {};
+                for (const c of this.#columns) {
+                    const v = e[c];
+                    if (v !== undefined)
+                        r[c] = v;
+                }
+                return r;
+            });
+            const created = await this.createMany(rows);
+            // Copy generated PKs back to the original instances.
+            created.forEach((c, i) => {
+                fresh[i].setProp(this.#primaryKey, c[this.#primaryKey]);
+                fresh[i].markAsPersisted();
+            });
+        }
+        for (const d of dirty)
+            await this.save(d);
+        return entities;
+    }
+    /**
+     * Dialect-aware upsert. postgres + sqlite emit `ON CONFLICT DO UPDATE`; mysql
+     * emits `ON DUPLICATE KEY UPDATE`. Empty `updateColumns` = DO NOTHING.
+     *
+     * @implements Story 30.4
+     */
+    async upsert(data, conflictColumns, updateColumns = []) {
+        const rowsArr = Array.isArray(data) ? data : [data];
+        const rows = rowsArr.map((r) => this.#plainToRowPairs(r));
+        const spec = {
+            kind: "upsert",
+            table: this.#tableName,
+            rows,
+            conflictColumns: conflictColumns.map((c) => this.#resolveColumn(c)),
+            updateColumns: updateColumns.map((c) => this.#resolveColumn(c)),
+            casts: this.#castTypes,
+        };
+        const compiled = compileStatementNative(spec, this.#dialect);
+        const result = await this.#db.execute(compiled.statements[0], compiled.params);
+        return result.rowsAffected;
+    }
+    /**
+     * Find a row matching `search` or create one merged with `defaults`.
+     *
+     * @implements Story 30.6
+     */
+    async firstOrCreate(search, defaults = {}) {
+        const existing = await this.#findBySearch(search);
+        if (existing)
+            return existing;
+        return this.create({ ...search, ...defaults });
+    }
+    /** Find a row or build an in-memory instance without persisting. */
+    async firstOrNew(search, defaults = {}) {
+        const existing = await this.#findBySearch(search);
+        if (existing)
+            return existing;
+        const e = new this.#entityClass();
+        for (const [k, v] of Object.entries({ ...search, ...defaults })) {
+            if (this.#validColumns.has(k) || this.#validColumns.has(camelToSnake(k)))
+                e.setProp(k, v);
+        }
+        return e;
+    }
+    /** Atomic find-or-update-or-insert. */
+    async updateOrCreate(search, values) {
+        const existing = await this.#findBySearch(search);
+        if (existing) {
+            for (const [k, v] of Object.entries(values))
+                existing.setProp(k, v);
+            await this.save(existing);
+            return existing;
+        }
+        return this.create({ ...search, ...values });
+    }
+    async #findBySearch(search) {
+        let q = this.query();
+        for (const [k, v] of Object.entries(search))
+            q = q.where(k, v);
+        return q.first();
+    }
+    /**
+     * Apply `@Column({ prepare })` (model → DB) when declared. Adonis Lucid's
+     * contract — callback receives the raw value (including null/undefined) and
+     * decides what to do with it.
+     */
+    #applyPrepare(propertyKey, value) {
+        const prepare = this.#columnPrepares.get(propertyKey);
+        if (!prepare)
+            return value;
+        let result;
+        try {
+            result = prepare(value);
+        }
+        catch (err) {
+            throw wrapAdapterError("prepare", propertyKey, err);
+        }
+        assertNotPromise("prepare", propertyKey, result);
+        return result;
+    }
+    #applyConsume(propertyKey, value) {
+        const consume = this.#columnConsumes.get(propertyKey);
+        if (!consume)
+            return value;
+        let result;
+        try {
+            result = consume(value);
+        }
+        catch (err) {
+            throw wrapAdapterError("consume", propertyKey, err);
+        }
+        assertNotPromise("consume", propertyKey, result);
+        return result;
+    }
+    #plainToRowPairs(obj) {
+        const pairs = [];
+        for (const [k, v] of Object.entries(obj)) {
+            // Skip explicit `undefined` so we don't emit `undefined` as a SQL bind —
+            // the Rust DML compiler / NAPI layer rejects it. `null` is allowed
+            // through because that's a meaningful SQL value.
+            if (v === undefined)
+                continue;
+            // Prepare map is keyed by camelCase property name. The input bag may use
+            // either camel or snake — try the raw key first, else convert.
+            const propKey = this.#columnPrepares.has(k) ? k : snakeToCamel(k);
+            pairs.push([this.#resolveColumn(k), this.#applyPrepare(propKey, v)]);
+        }
+        return pairs;
+    }
+    #entityToRowPairs(entity) {
+        const pairs = [];
+        for (const col of this.#columns) {
+            const v = entity[col];
+            if (v !== undefined)
+                pairs.push([camelToSnake(col), this.#applyPrepare(col, v)]);
+        }
+        return pairs;
+    }
+    /** Delete the entity. Fires `beforeDelete` → DB → `afterDelete`. Soft-delete aware. */
+    async delete(entity) {
+        await fireHooks(this.#entityClass, "beforeDelete", entity);
+        const pk = entity[this.#primaryKey];
+        if (this.#softDeletes) {
+            const now = new Date().toISOString();
+            await this.#runUpdate([["deleted_at", now]], [{ column: this.#primaryKey, operator: "=", value: pk, type: "and" }]);
+            entity.setProp("deletedAt", now);
+        }
+        else {
+            await this.#runDelete([
+                { column: this.#primaryKey, operator: "=", value: pk, type: "and" },
+            ]);
+        }
+        await fireHooks(this.#entityClass, "afterDelete", entity);
+    }
+    /** Permanently delete (bypasses soft delete). Fires `beforeDelete` / `afterDelete` hooks. */
+    async forceDelete(entity) {
+        await fireHooks(this.#entityClass, "beforeDelete", entity);
+        await this.#runDelete([
+            {
+                column: this.#primaryKey,
+                operator: "=",
+                value: entity[this.#primaryKey],
+                type: "and",
+            },
+        ]);
+        await fireHooks(this.#entityClass, "afterDelete", entity);
+    }
+    async restore(entity) {
+        if (!this.#softDeletes)
+            return;
+        await this.#runUpdate([["deleted_at", null]], [
+            {
+                column: this.#primaryKey,
+                operator: "=",
+                value: entity[this.#primaryKey],
+                type: "and",
+            },
+        ]);
+        entity.setProp("deletedAt", null);
+    }
+    // ─── Bulk updates ─────────────────────────────────────────
+    async updateById(id, data) {
+        const set = this.#buildSetPairs(data);
+        await this.#runUpdate(set, [
+            { column: this.#primaryKey, operator: "=", value: id, type: "and" },
+        ]);
+    }
+    async updateWhere(column, columnValue, data) {
+        const whereCol = this.#resolveColumn(column);
+        const set = this.#buildSetPairs(data);
+        await this.#runUpdate(set, [
+            { column: whereCol, operator: "=", value: columnValue, type: "and" },
+        ]);
+    }
+    async increment(id, columnOrMap, amount = 1) {
+        const set = this.#buildIncrementPairs(columnOrMap, amount, "increment");
+        await this.#runUpdate(set, [
+            { column: this.#primaryKey, operator: "=", value: id, type: "and" },
+        ]);
+    }
+    async decrement(id, columnOrMap, amount = 1) {
+        const set = this.#buildIncrementPairs(columnOrMap, amount, "decrement");
+        await this.#runUpdate(set, [
+            { column: this.#primaryKey, operator: "=", value: id, type: "and" },
+        ]);
+    }
+    // ─── Raw ──────────────────────────────────────────────────
+    async raw(sql, ...params) {
+        const rows = await this.#db.query(sql, params);
+        return rows.map((r) => this.#hydrate(r));
+    }
+    // ─── Accessors ────────────────────────────────────────────
+    getTableName() {
+        return this.#tableName;
+    }
+    getPrimaryKeyColumn() {
+        return this.#primaryKey;
+    }
+    // ─── Private helpers ──────────────────────────────────────
+    #compileSelect(opts) {
+        const spec = {
+            kind: "select",
+            table: this.#tableName,
+            select: ["*"],
+            wheres: opts.wheres ?? [],
+            orderBy: opts.orderBy ?? [],
+            groupBy: [],
+            having: [],
+            limit: opts.limit ?? null,
+            offset: null,
+            distinct: false,
+            ctes: [],
+            unions: [],
+        };
+        const compiled = compileStatementNative(spec, this.#dialect);
+        return { sql: compiled.statements[0], params: compiled.params };
+    }
+    async #runSelect(opts) {
+        const { sql, params } = this.#compileSelect(opts);
+        const rows = await this.#db.query(sql, params);
+        return rows.map((r) => this.#hydrate(r));
+    }
+    async #runDelete(wheres) {
+        const compiled = compileStatementNative({ kind: "delete", table: this.#tableName, wheres }, this.#dialect);
+        await this.#db.execute(compiled.statements[0], compiled.params);
+    }
+    /**
+     * Emit an UPDATE. Each entry in `set` is either `[col, rawValue]` (plain
+     * binding — `SET col = ?`) or `[col, { op: 'increment' | 'decrement', value }]`
+     * (atomic expression — `SET col = col ± ?`). The Rust compiler picks the
+     * right SQL via `SetValue::Value` / `SetValue::Expression`.
+     */
+    async #runUpdate(set, wheres) {
+        if (set.length === 0)
+            return;
+        const compiled = compileStatementNative({
+            kind: "update",
+            table: this.#tableName,
+            set,
+            wheres,
+            casts: this.#castTypes,
+        }, this.#dialect);
+        await this.#db.execute(compiled.statements[0], compiled.params);
+    }
+    /**
+     * Execute the INSERT and return whatever the engine surfaces about the
+     * fresh row: the RETURNING projection (postgres / sqlite) when available,
+     * otherwise just the rowsAffected count (mysql doesn't support RETURNING).
+     * Caller decides how much to rehydrate.
+     */
+    async #runInsert(values) {
+        if (values.length === 0)
+            return {};
+        const supportsReturning = this.#dialect !== "mysql";
+        const spec = supportsReturning
+            ? {
+                kind: "insert",
+                table: this.#tableName,
+                values,
+                casts: this.#castTypes,
+                returning: [
+                    camelToSnake(this.#primaryKey),
+                    ...this.#columns.map((c) => camelToSnake(c)),
+                ],
+            }
+            : {
+                kind: "insert",
+                table: this.#tableName,
+                values,
+                casts: this.#castTypes,
+            };
+        const compiled = compileStatementNative(spec, this.#dialect);
+        if (supportsReturning) {
+            const rows = await this.#db.query(compiled.statements[0], compiled.params);
+            const first = rows[0];
+            return first ? { row: first } : {};
+        }
+        await this.#db.execute(compiled.statements[0], compiled.params);
+        // MySQL path: napi adapter doesn't surface lastInsertRowid through
+        // `execute()`. Callers that need it must use an explicit dialect-
+        // specific query (e.g. `SELECT LAST_INSERT_ID()`). For Atlas's
+        // public surface, the entity carries the PK already (either set
+        // by the caller or generated client-side as a UUID).
+        return {};
+    }
+    #appendSoftScope(wheres) {
+        if (this.#softDeletes) {
+            wheres.push({
+                column: "deleted_at",
+                operator: "IS NULL",
+                value: null,
+                type: "and",
+            });
+        }
+    }
+    async #insert(entity) {
+        // Auto-generate the PK when declared via `@PrimaryKey({ generated })`.
+        this.#applyPrimaryKeyGenerator(entity);
+        // Auto-populate @column.dateTime({ autoCreate: true }) fields before building the row.
+        this.#applyAutoTimestamps(entity, "insert");
+        const data = this.#entityToRow(entity);
+        const result = await this.#runInsert(Object.entries(data));
+        // Hydrate DB-generated values (auto-increment ids, default columns) so
+        // callers see them on the entity without an extra `find()`. Mirrors
+        // `createMany`, where the multi-row path already does this.
+        if (result.row) {
+            for (const [k, v] of Object.entries(result.row))
+                entity.setProp(snakeToCamel(k), v);
+        }
+        else if (result.lastInsertRowid !== undefined &&
+            !isProvidedPk(entity[this.#primaryKey])) {
+            entity.setProp(this.#primaryKey, normalizeRowid(result.lastInsertRowid));
+        }
+        // After a successful INSERT, the entity is now persisted — snapshot
+        // its columns so subsequent dirty checks compare against the DB state.
+        entity.markAsPersisted();
+    }
+    /**
+     * UPDATE the entity — emits only the dirty columns (story 32.2).
+     *
+     * If no column is dirty, skips the query entirely (common case when a
+     * `save()` is called defensively without any real mutation).
+     */
+    async #update(entity) {
+        // Auto-bump @column.dateTime({ autoUpdate: true }) BEFORE computing $dirty
+        // so the bumped column lands in the SET if anything else is dirty.
+        this.#applyAutoTimestamps(entity, "update");
+        const dirty = entity.$dirty;
+        const pk = entity[this.#primaryKey];
+        // Primary key is never part of the SET — it's the WHERE.
+        delete dirty[this.#primaryKey];
+        if (Object.keys(dirty).length === 0)
+            return; // nothing changed
+        // Map dirty camelCase keys to snake_case DB columns. `$dirty` keys are
+        // already camelCase (they come from `entity.setProp` / direct assignment),
+        // so the prepare lookup uses `k` as-is. Skip explicit `undefined`
+        // assignments to mirror `#buildSetPairs` / `#plainToRowPairs` — the
+        // Rust DML compiler / NAPI layer rejects `undefined` binds.
+        const setPairs = [];
+        for (const [k, v] of Object.entries(dirty)) {
+            if (v === undefined)
+                continue;
+            setPairs.push([camelToSnake(k), this.#applyPrepare(k, v)]);
+        }
+        if (setPairs.length === 0) {
+            // All dirty entries were `undefined` (skipped above). Re-snapshot
+            // anyway: without this, `$dirty` keeps reporting the same
+            // undefined keys forever and a caller checking `entity.isDirty()`
+            // loops on a no-op save.
+            entity.markAsPersisted();
+            return;
+        }
+        await this.#runUpdate(setPairs, [
+            { column: this.#primaryKey, operator: "=", value: pk, type: "and" },
+        ]);
+        // Re-snapshot after a successful UPDATE.
+        entity.markAsPersisted();
+    }
+    /**
+     * Generate the primary key on INSERT when the entity declares
+     * `@PrimaryKey({ generated: 'uuid' })` and no value is set. Caller-supplied
+     * PKs win — we only fill in when the field is `undefined`.
+     */
+    #applyPrimaryKeyGenerator(entity) {
+        const strategy = getPrimaryKeyGenerator(this.#entityClass);
+        if (!strategy)
+            return;
+        if (entity[this.#primaryKey] !== undefined)
+            return;
+        if (strategy === "uuid") {
+            entity.setProp(this.#primaryKey, randomUUID());
+        }
+    }
+    /**
+     * Apply auto-timestamp columns (`@column.dateTime({ autoCreate, autoUpdate })`)
+     * on the entity before persistence. Called from `#insert` and `#update`.
+     */
+    #applyAutoTimestamps(entity, phase) {
+        const now = new Date();
+        for (const [prop, cfg] of Object.entries(this.#dateColumns)) {
+            if (phase === "insert") {
+                if (cfg.autoCreate && entity[prop] === undefined) {
+                    entity.setProp(prop, now);
+                }
+                if (cfg.autoUpdate && entity[prop] === undefined) {
+                    entity.setProp(prop, now);
+                }
+            }
+            else if (phase === "update" && cfg.autoUpdate) {
+                entity.setProp(prop, now);
+            }
+        }
+    }
+    #hydrate(row) {
+        const entity = new this.#entityClass();
+        for (const [key, value] of Object.entries(row)) {
+            const camelKey = snakeToCamel(key);
+            // Resolve against declared column metadata, not `in entity` — fields
+            // using Adonis' `declare field: T` pattern are not own-properties of
+            // a freshly constructed instance.
+            const targetKey = this.#validColumns.has(camelKey)
+                ? camelKey
+                : this.#validColumns.has(key)
+                    ? key
+                    : null;
+            if (!targetKey)
+                continue;
+            // Apply `@Column({ consume })` if declared on this property. Unlike the
+            // previous registry-based design, the callback receives every value
+            // including `null` / `undefined` — the user's `consume` is responsible
+            // for its own null-handling, matching Adonis Lucid's contract.
+            entity.setProp(targetKey, this.#applyConsume(targetKey, value));
+        }
+        // Freeze the original snapshot — from now on, only columns changed AFTER
+        // hydration are considered dirty by `entity.$dirty`.
+        entity.markAsPersisted();
+        // Back-pointer so `entity.refresh()` / `entity.fresh()` can re-query.
+        Object.defineProperty(entity, REPO_REF, {
+            value: this,
+            enumerable: false,
+            configurable: true,
+        });
+        return entity;
+    }
+    /**
+     * Re-read the entity's row from the database and mutate the instance in place.
+     * Used by `entity.refresh()` — not normally called directly.
+     *
+     * @implements Story 32.6
+     */
+    async refresh(entity) {
+        const pk = entity[this.#primaryKey];
+        if (pk === undefined || pk === null) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: pk,
+            });
+        }
+        const fresh = await this.find(pk);
+        if (!fresh) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: pk,
+            });
+        }
+        // Copy all column values from the fresh row onto the existing instance.
+        for (const col of this.#columns) {
+            entity.setProp(col, fresh[col]);
+        }
+        entity.setProp(this.#primaryKey, fresh[this.#primaryKey]);
+        entity.markAsPersisted();
+    }
+    /**
+     * Re-read the entity's row and return a NEW instance (the input is untouched).
+     *
+     * @implements Story 32.6
+     */
+    /**
+     * Lazy-load a relation count into `entity.$extras[alias ?? `${relationName}_count`]`.
+     * Uses `ModelQuery.withCount` with a restrictive `WHERE pk = ?` so it reads
+     * one entity's row back with the aggregate column attached.
+     *
+     * @implements Story 29.2
+     */
+    async loadCount(entity, relationName, alias) {
+        const pk = entity[this.#primaryKey];
+        if (pk === undefined || pk === null) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: pk,
+            });
+        }
+        const finalAlias = alias ?? `${relationName}_count`;
+        const q = this.query()
+            .where(this.#primaryKey, pk)
+            .withCount(relationName, (sub) => {
+            sub.as(finalAlias);
+        });
+        const [refreshed] = await q.exec();
+        if (refreshed)
+            entity.setExtra(finalAlias, refreshed.getExtra(finalAlias));
+    }
+    /**
+     * Lazy-load a relation aggregate. The builder callback sets the aggregate via
+     * `.sum/.avg/.min/.max/.count` and the alias via `.as('name')`.
+     *
+     * @implements Story 29.2
+     */
+    async loadAggregate(entity, relationName, build) {
+        const pk = entity[this.#primaryKey];
+        if (pk === undefined || pk === null) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: pk,
+            });
+        }
+        let capturedAlias;
+        const q = this.query()
+            .where(this.#primaryKey, pk)
+            .withAggregate(relationName, (sub) => {
+            build(sub);
+            capturedAlias = sub.subqueryAlias;
+        });
+        const [refreshed] = await q.exec();
+        const alias = capturedAlias ?? relationName;
+        if (refreshed)
+            entity.setExtra(alias, refreshed.getExtra(alias));
+    }
+    /**
+     * Lazy-load a relation onto an already-fetched entity. Re-uses the preload
+     * resolver by running a fresh query with `.where(pk = entity.pk).preload(...)`.
+     *
+     * @implements Story 31.10
+     */
+    async loadRelation(entity, relationName, callback) {
+        const pk = entity[this.#primaryKey];
+        if (pk === undefined || pk === null) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: pk,
+            });
+        }
+        const q = this.query().where(this.#primaryKey, pk);
+        if (callback)
+            q.preload(relationName, callback);
+        else
+            q.preload(relationName);
+        const [hydrated] = await q.exec();
+        if (hydrated) {
+            // Copy the loaded relation onto the caller's instance.
+            const value = hydrated[relationName];
+            entity.setProp(relationName, value);
+        }
+    }
+    /**
+     * Return a thin relation proxy bound to the given parent instance. Only
+     * `hasOne` / `hasMany` (and trivially `manyToMany` insert paths) are wired
+     * here; richer operations (attach/detach/sync) live in Story 31.7's proxy.
+     *
+     * @implements Story 31.5
+     */
+    relatedProxy(entity, relationName) {
+        const relations = getRelationMetadata(this.#entityClass);
+        const relation = relations.find((r) => r.propertyKey === relationName);
+        if (!relation)
+            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 relatedTable = relatedMeta.tableName;
+        const parentPk = relation.localKey ?? getPrimaryKey(this.#entityClass) ?? "id";
+        const parentIdValue = entity[parentPk];
+        const relatedRepo = new BaseRepository(relatedClass, this.#db, {
+            dialect: this.#dialect,
+        });
+        const db = this.#db;
+        // FK column naming: belongsTo stores the FK on THIS side; has* / m2m on the OTHER side.
+        const fkCol = relation.foreignKey ??
+            (relation.type === "belongsTo"
+                ? `${camelToSnake(relatedClass.name)}_id`
+                : `${camelToSnake(this.#entityClass.name)}_id`);
+        const fkProp = snakeToCamel(fkCol);
+        const injectFk = (data) => ({
+            ...data,
+            [fkCol]: parentIdValue,
+            [fkProp]: parentIdValue,
+        });
+        // Shared "has" proxy methods (create/createMany/save/saveMany).
+        const hasOps = {
+            async create(data) {
+                return relatedRepo.create(injectFk(data));
+            },
+            async createMany(rows) {
+                return relatedRepo.createMany(rows.map(injectFk));
+            },
+            async save(related) {
+                related.setProp(fkCol, parentIdValue);
+                related.setProp(fkProp, parentIdValue);
+                await relatedRepo.save(related);
+            },
+            async saveMany(related) {
+                for (const r of related) {
+                    r.setProp(fkCol, parentIdValue);
+                    r.setProp(fkProp, parentIdValue);
+                }
+                return relatedRepo.saveMany(related);
+            },
+        };
+        // Scoped query builder (Story 31.9) — pre-applies the FK predicate
+        // (or pivot JOIN for m2m) so downstream filters/updates/deletes stay
+        // inside the relation boundary.
+        const scopedQuery = () => {
+            const q = relatedRepo.query();
+            if (relation.type === "manyToMany") {
+                if (!relation.pivot)
+                    throw new Error(`@ManyToMany ${relationName} requires pivot options`);
+                const pivot = relation.pivot;
+                const pivotFk = pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+                const pivotOther = pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
+                const relatedPk = getPrimaryKey(relatedClass) ?? "id";
+                // Inline validated quote (same policy as the m2m branch below).
+                const dialect = this.#dialect;
+                const quote = (name) => {
+                    if (!/^[A-Za-z0-9_]+$/.test(name)) {
+                        throw new Error(`Unsafe identifier in pivot metadata: '${name}'`);
+                    }
+                    return dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
+                };
+                // EXISTS (SELECT 1 FROM pivot WHERE pivot.pivotFk = ? AND pivot.pivotOther = related.pk)
+                // Framework-internal raw fragment (identifiers already validated by
+                // the `quote` helper above) — bypass strict mode so this path still
+                // works when the user enables `setAtlasStrictMode(true)` on their app.
+                runWithAtlasInternalBypass(() => {
+                    q.whereRaw(`EXISTS (SELECT 1 FROM ${quote(pivot.pivotTable)} ` +
+                        `WHERE ${quote(pivot.pivotTable)}.${quote(pivotFk)} = ? ` +
+                        `AND ${quote(pivot.pivotTable)}.${quote(pivotOther)} = ${quote(relatedTable)}.${quote(relatedPk)})`, [parentIdValue]);
+                });
+            }
+            else if (relation.type === "belongsTo") {
+                const ownerKey = relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id";
+                q.where(ownerKey, entity[fkProp] ?? entity[fkCol]);
+            }
+            else {
+                // hasOne / hasMany
+                q.where(fkCol, parentIdValue);
+            }
+            return q;
+        };
+        if (relation.type === "belongsTo") {
+            // Story 31.6 — associate / dissociate set the FK on THIS entity and save
+            // it through the outer repository. Both methods close over `parentRepo`,
+            // which is the repo that owns `entity` (i.e. `this`). The double cast is
+            // the standard TS idiom for widening a generic `this` — safe because
+            // `T extends BaseEntity`.
+            const parentRepo = this;
+            const proxy = {
+                type: "belongsTo",
+                ...hasOps,
+                query: scopedQuery,
+                async associate(model) {
+                    if (model === null || model === undefined) {
+                        throw new Error(`related('${relationName}').associate() rejects null/undefined — use dissociate() instead`);
+                    }
+                    const ownerKey = relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id";
+                    const fkValue = model[ownerKey];
+                    entity.setProp(fkCol, fkValue);
+                    entity.setProp(fkProp, fkValue);
+                    await parentRepo.save(entity);
+                },
+                async dissociate() {
+                    entity.setProp(fkCol, null);
+                    entity.setProp(fkProp, null);
+                    await parentRepo.save(entity);
+                },
+            };
+            return proxy;
+        }
+        if (relation.type === "manyToMany") {
+            if (!relation.pivot)
+                throw new Error(`@ManyToMany ${relationName} requires pivot options`);
+            const pivot = relation.pivot;
+            const pivotTable = pivot.pivotTable;
+            const pivotFk = pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+            const pivotOther = pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
+            const tsConfig = pivot.pivotTimestamps;
+            const pivotAdapters = pivot.pivotColumnAdapters;
+            const dialect = this.#dialect;
+            /**
+             * Resolve pivot timestamp column names from the decorator config.
+             *
+             * Three forms supported:
+             *   - `pivotTimestamps: true`           → { created_at, updated_at } default names
+             *   - `pivotTimestamps: { createdAt: false, updatedAt: 'updated_on' }` → opt-out / rename
+             *   - `pivotTimestamps: undefined`      → no timestamps written
+             *
+             * `false` opts a timestamp out; a string overrides the column name;
+             * `undefined` falls back to the default name.
+             */
+            const resolveTimestamps = () => {
+                if (!tsConfig)
+                    return {};
+                const now = new Date().toISOString();
+                let createdCol;
+                let updatedCol;
+                if (tsConfig === true) {
+                    createdCol = "created_at";
+                    updatedCol = "updated_at";
+                }
+                else {
+                    createdCol =
+                        tsConfig.createdAt === false
+                            ? null
+                            : (tsConfig.createdAt ?? "created_at");
+                    updatedCol =
+                        tsConfig.updatedAt === false
+                            ? null
+                            : (tsConfig.updatedAt ?? "updated_at");
+                }
+                const out = {};
+                if (createdCol)
+                    out[createdCol] = now;
+                if (updatedCol)
+                    out[updatedCol] = now;
+                return out;
+            };
+            const normalizeAttach = (arg) => {
+                if (Array.isArray(arg))
+                    return arg.map((id) => ({ id, extras: {} }));
+                return Object.entries(arg).map(([id, extras]) => ({ id, extras }));
+            };
+            // Current pivot rows — compiled through the Rust SELECT path so the
+            // pivot identifiers go through `quote_identifier` (rejects anything
+            // outside `[A-Za-z0-9_]`), rather than through the ad-hoc `quote`
+            // helper that would blindly wrap a malicious metadata string.
+            //
+            // Now async — every site in `sync()` is in an async closure.
+            const currentIds = async () => {
+                const selectSpec = {
+                    kind: "select",
+                    table: pivotTable,
+                    select: [pivotOther],
+                    wheres: [
+                        {
+                            column: pivotFk,
+                            operator: "=",
+                            value: parentIdValue,
+                            type: "and",
+                        },
+                    ],
+                    selectSubqueries: [],
+                    orderBy: [],
+                    groupBy: [],
+                    having: [],
+                    limit: null,
+                    offset: null,
+                    distinct: false,
+                    ctes: [],
+                    unions: [],
+                    joins: [],
+                    lockMode: null,
+                };
+                const compiled = compileStatementNative(selectSpec, dialect);
+                const rows = await db.query(compiled.statements[0], compiled.params);
+                return rows.map((r) => r[pivotOther]);
+            };
+            // Delete via the Rust DELETE compiler so the pivot table + columns get
+            // `quote_identifier` validation (rejects `"`, `;`, etc.) — safer than
+            // the previous hand-built SQL with a dumb `"` wrapper.
+            const detach = async (ids) => {
+                const wheres = [
+                    { column: pivotFk, operator: "=", value: parentIdValue, type: "and" },
+                ];
+                if (ids && ids.length > 0) {
+                    wheres.push({
+                        column: pivotOther,
+                        operator: "IN",
+                        value: ids,
+                        type: "and",
+                    });
+                }
+                const spec = {
+                    kind: "delete",
+                    table: pivotTable,
+                    wheres,
+                    returning: [],
+                };
+                const compiled = compileStatementNative(spec, dialect);
+                await db.execute(compiled.statements[0], compiled.params);
+            };
+            const attach = async (ids) => {
+                const entries = normalizeAttach(ids);
+                if (entries.length === 0)
+                    return;
+                const ts = resolveTimestamps();
+                // Normalize heterogeneous extras: compute the union of extra keys
+                // across all entries and back-fill missing keys with `null`, so every
+                // row in the multi-insert shares the same column set (required by the
+                // Rust compiler's homogeneity check).
+                const extraKeys = new Set();
+                for (const e of entries) {
+                    for (const k of Object.keys(e.extras))
+                        extraKeys.add(k);
+                }
+                // Reject extras keys that collide with reserved pivot columns. Without
+                // this guard, an extras entry named after the FK or a timestamp column
+                // would emit a duplicate column in the INSERT row pair: the FK case
+                // silently overrides `parentIdValue` (corrupting the join); the
+                // timestamp case duplicates the column entirely (driver-dependent
+                // failure or last-wins overwrite).
+                for (const k of extraKeys) {
+                    if (k === pivotFk || k === pivotOther) {
+                        throw new Error(`Pivot extras key '${k}' collides with the ${k === pivotFk ? "foreignKey" : "otherKey"} column on '${pivotTable}'. Reserved keys MUST NOT appear in attach()/sync() extras.`);
+                    }
+                    if (Object.hasOwn(ts, k)) {
+                        throw new Error(`Pivot extras key '${k}' collides with a pivotTimestamps column on '${pivotTable}'. Disable the timestamp in the relation options or rename your extra.`);
+                    }
+                }
+                const rowPairs = entries.map((e) => {
+                    const pairs = [
+                        [pivotFk, parentIdValue],
+                        [pivotOther, e.id],
+                    ];
+                    for (const k of extraKeys) {
+                        const raw = e.extras[k] ?? null;
+                        const prepare = pivotAdapters?.[k]?.prepare;
+                        if (!prepare) {
+                            pairs.push([k, raw]);
+                            continue;
+                        }
+                        let encoded;
+                        try {
+                            encoded = prepare(raw);
+                        }
+                        catch (err) {
+                            throw wrapAdapterError("prepare", k, err);
+                        }
+                        assertNotPromise("prepare", k, encoded);
+                        pairs.push([k, encoded]);
+                    }
+                    for (const [k, v] of Object.entries(ts))
+                        pairs.push([k, v]);
+                    return pairs;
+                });
+                // Postgres casts for the pivot row: the two FK columns reference the
+                // parent / related PK types (often uuid), and pivot timestamps are
+                // bound strings — all need `$N::<type>` on Postgres.
+                const pivotCasts = {};
+                const parentPkCast = this.#castTypes[camelToSnake(this.#primaryKey)];
+                if (parentPkCast)
+                    pivotCasts[pivotFk] = parentPkCast;
+                const relatedPkCast = computeCastTypes(relatedClass)[camelToSnake(getPrimaryKey(relatedClass) ?? "id")];
+                if (relatedPkCast)
+                    pivotCasts[pivotOther] = relatedPkCast;
+                for (const k of Object.keys(ts))
+                    pivotCasts[k] = "timestamp";
+                const spec = {
+                    kind: "insert",
+                    table: pivotTable,
+                    rows: rowPairs,
+                    casts: pivotCasts,
+                };
+                const compiled = compileStatementNative(spec, dialect);
+                await db.execute(compiled.statements[0], compiled.params);
+            };
+            /**
+             * Diff the current pivot state against a target set and apply the
+             * minimum attach/detach to converge.
+             *
+             * **NOT ATOMIC.** `sync` reads the pivot, computes the diff, then
+             * writes — another process mutating the pivot between the read and
+             * the writes will cause divergence. Wrap the call in a transaction
+             * if you need strong consistency under concurrent writers.
+             *
+             * On SQLite this is typically fine because better-sqlite3 serializes
+             * writes per connection; on Postgres/MySQL use `useTransaction` first.
+             */
+            const sync = async (target, additive = false) => {
+                const current = new Set(await currentIds());
+                const entries = normalizeAttach(target);
+                const desired = new Set(entries.map((e) => e.id));
+                const toAttach = entries.filter((e) => !current.has(e.id));
+                const toDetach = additive
+                    ? []
+                    : [...current].filter((id) => !desired.has(id));
+                if (toDetach.length > 0)
+                    await detach(toDetach);
+                if (toAttach.length > 0) {
+                    const attachArg = {};
+                    for (const e of toAttach)
+                        attachArg[String(e.id)] = e.extras;
+                    await attach(attachArg);
+                }
+            };
+            const proxy = {
+                type: "manyToMany",
+                ...hasOps,
+                query: scopedQuery,
+                attach,
+                detach,
+                sync,
+            };
+            return proxy;
+        }
+        // Default: hasOne / hasMany
+        if (relation.type === "hasOne") {
+            // @HasOne is a one-to-one relation — createMany/saveMany would violate
+            // the invariant at the ORM level (and silently shadow a missing UNIQUE
+            // constraint at the DB level). The typed proxy declares them as
+            // `Promise<never>` so callers get a compile-time signal; at runtime
+            // both throw a clear error.
+            const reject = async (op) => {
+                throw new Error(`related('${relationName}').${op}() is not supported on @HasOne — ` +
+                    `use .create() / .save() for a single related row.`);
+            };
+            const proxy = {
+                type: "hasOne",
+                create: hasOps.create,
+                save: hasOps.save,
+                createMany: () => reject("createMany"),
+                saveMany: () => reject("saveMany"),
+                query: scopedQuery,
+            };
+            return proxy;
+        }
+        const proxy = {
+            type: "hasMany",
+            ...hasOps,
+            query: scopedQuery,
+        };
+        return proxy;
+    }
+    async fresh(entity) {
+        const pk = entity[this.#primaryKey];
+        if (pk === undefined || pk === null) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: pk,
+            });
+        }
+        const found = await this.find(pk);
+        if (!found) {
+            throw new EntityNotFoundError(this.#entityClass.name, {
+                [this.#primaryKey]: pk,
+            });
+        }
+        return found;
+    }
+    #entityToRow(entity) {
+        // `#columns` already includes the primary-key property: `@PrimaryKey()`
+        // internally calls `@Column()` to register the PK as a regular column
+        // (see decorators/entity.ts). The earlier trailing block re-emitted
+        // the PK as a raw camelCase key, producing a double-write for non-`id`
+        // PK names (`{ user_id: ..., userId: ... }` would land in the row dict).
+        const row = {};
+        for (const col of this.#columns) {
+            const value = entity[col];
+            if (value !== undefined) {
+                row[camelToSnake(col)] = this.#applyPrepare(col, value);
+            }
+        }
+        return row;
+    }
+    #buildSetPairs(data) {
+        const pairs = [];
+        for (const [key, value] of Object.entries(data)) {
+            // Mirror `#plainToRowPairs` — skip undefined so updates can't bind it.
+            if (value === undefined)
+                continue;
+            const propKey = this.#columnPrepares.has(key) ? key : snakeToCamel(key);
+            pairs.push([
+                this.#resolveColumn(key),
+                this.#applyPrepare(propKey, value),
+            ]);
+        }
+        return pairs;
+    }
+    /**
+     * Build SET pairs for `increment`/`decrement` — each entry carries a
+     * `{ op, value }` payload that the Rust compiler turns into
+     * `SET col = col ± ?` instead of the standard `SET col = ?`.
+     */
+    #buildIncrementPairs(columnOrMap, amount, op) {
+        if (typeof columnOrMap === "string") {
+            return [[this.#resolveColumn(columnOrMap), { op, value: amount }]];
+        }
+        return Object.entries(columnOrMap).map(([col, delta]) => [this.#resolveColumn(col), { op, value: delta }]);
+    }
+}
+/**
+ * Annotate an adapter callback failure with the property key that triggered
+ * it. Without this, a `prepare`/`consume` throwing on row N silently surfaces
+ * as "Invalid bind value" or similar, with no hint at WHICH column the
+ * adapter rejected — the dev has to bisect across every adapter-tagged
+ * property to find the culprit.
+ */
+function wrapAdapterError(phase, propertyKey, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // `cause: err` preserves the original error (and its stack) per ES2022
+    // Error Cause. The wrapped Error keeps its own `stack` pointing at the
+    // wrap site so `console.error(wrapped)` shows the column-annotated
+    // header; Node ≥16.9 walks the cause chain to print the underlying
+    // throw's stack underneath.
+    return new Error(`@Column.${phase} threw on '${propertyKey}': ${message}`, {
+        cause: err,
+    });
+}
+/**
+ * Adapter callbacks must be synchronous — the bind layer cannot await before
+ * handing values to the Rust DML compiler. Catching an `async` adapter here
+ * gives the user a column-annotated error instead of an opaque "Invalid bind
+ * value" downstream when the unawaited Promise hits the NAPI boundary.
+ */
+function assertNotPromise(phase, propertyKey, value) {
+    if (value !== null &&
+        typeof value === "object" &&
+        "then" in value &&
+        typeof Reflect.get(value, "then") === "function") {
+        throw new Error(`@Column.${phase} on '${propertyKey}' returned a Promise — adapters must be synchronous (the bind layer cannot await).`);
+    }
+}
+//# sourceMappingURL=BaseRepository.js.map