@c9up/atlas 0.2.0 → 0.2.1

package/src/BaseModel.ts

@@ -1,11 +1,34 @@
-import type { AsyncDatabaseConnection } from "./adapters/NapiDbAdapter.js";
+import type {
+	AsyncDatabaseConnection,
+	TransactionOptions,
+} from "./adapters/NapiDbAdapter.js";
 import { BaseEntity } from "./BaseEntity.js";
 import { BaseRepository, type DatabaseConnection } from "./BaseRepository.js";
 import { ensureEntityMetadata } from "./decorators/entity.js";
 import { AtlasError } from "./errors.js";
 import { getConnection, getDb } from "./services/db.js";
+import type { TransactionClient } from "./Transaction.js";
 import { isTransactionClient } from "./utils/transactionBrand.js";
 
+/**
+ * Options accepted by the static finders/creators — Adonis Lucid's
+ * `{ client: trx }`. Routes the operation through a transaction client instead
+ * of the model's own connection.
+ */
+export interface ModelClientOptions {
+	client?: DatabaseConnection;
+}
+
+/**
+ * Narrow the optional trailing argument of an overloaded finder (which is a
+ * value in the `(column, value)` form, or the options in the `(clause)` form) to
+ * client options — without a cast. An options object without a `client` reads as
+ * "no options", which is the same as passing none.
+ */
+function isClientOptions(x: unknown): x is ModelClientOptions {
+	return typeof x === "object" && x !== null && "client" in x;
+}
+
 /** A concrete BaseModel subclass: a `new()` constructor plus the static façade. */
 type ModelClass<T extends BaseModel> = (new () => T) & typeof BaseModel;
 
@@ -61,10 +84,58 @@ export abstract class BaseModel extends BaseEntity {
 		return conn;
 	}
 
-	/** The {@link BaseRepository} backing this model on its resolved connection. */
-	static $repo<T extends BaseModel>(this: ModelClass<T>): BaseRepository<T> {
+	/**
+	 * The {@link BaseRepository} backing this model on its resolved connection.
+	 * Pass `{ client: trx }` (Adonis Lucid) to bind the repository to a
+	 * transaction, so every finder/creator routed through it runs on that trx.
+	 */
+	static $repo<T extends BaseModel>(
+		this: ModelClass<T>,
+		options?: ModelClientOptions,
+	): BaseRepository<T> {
 		this.$boot();
-		return new BaseRepository<T>(this, this.$connection());
+		const repo = new BaseRepository<T>(this, this.$connection());
+		return options?.client ? repo.useTransaction(options.client) : repo;
+	}
+
+	/**
+	 * Start a transaction on THIS model's connection (Adonis Lucid
+	 * `Model.transaction`) — handy when the model overrides `static connection`.
+	 * Managed when given a callback (auto commit on success, rollback on throw),
+	 * manual otherwise. On the default connection it is equivalent to
+	 * `db.transaction(...)`. Accepts an `isolationLevel` via the options.
+	 */
+	static transaction<T>(
+		this: ModelClass<BaseModel>,
+		callback: (trx: TransactionClient) => Promise<T> | T,
+		options?: TransactionOptions,
+	): Promise<T>;
+	static transaction(
+		this: ModelClass<BaseModel>,
+		options?: TransactionOptions,
+	): Promise<TransactionClient>;
+	static transaction(
+		this: ModelClass<BaseModel>,
+		callbackOrOptions?:
+			| ((trx: TransactionClient) => unknown)
+			| TransactionOptions,
+		options?: TransactionOptions,
+	): Promise<unknown> {
+		const conn = this.$connection();
+		if (typeof conn.transaction !== "function") {
+			throw new AtlasError(
+				"E_NO_INTERACTIVE_TRANSACTION",
+				`Model '${this.name}' connection has no interactive transaction().`,
+			);
+		}
+		if (typeof callbackOrOptions === "function") {
+			return conn.transaction(callbackOrOptions, options);
+		}
+		// Manual mode: forward the isolation options if any (the overload rejects an
+		// explicit `undefined`, so call with no args when none were passed).
+		return callbackOrOptions === undefined
+			? conn.transaction()
+			: conn.transaction(callbackOrOptions);
 	}
 
 	// — Static finders (AdonisJS Lucid) —
@@ -72,97 +143,126 @@ export abstract class BaseModel extends BaseEntity {
 	static find<T extends BaseModel>(
 		this: ModelClass<T>,
 		id: string | number,
+		options?: ModelClientOptions,
 	): Promise<T | null> {
-		return this.$repo().find(id);
+		return this.$repo(options).find(id);
 	}
 
 	static findOrFail<T extends BaseModel>(
 		this: ModelClass<T>,
 		id: string | number,
+		options?: ModelClientOptions,
 	): Promise<T> {
-		return this.$repo().findOrFail(id);
+		return this.$repo(options).findOrFail(id);
 	}
 
 	static findBy<T extends BaseModel>(
 		this: ModelClass<T>,
 		column: string,
 		value: unknown,
+		options?: ModelClientOptions,
 	): Promise<T | null>;
 	static findBy<T extends BaseModel>(
 		this: ModelClass<T>,
 		clause: Record<string, unknown>,
+		options?: ModelClientOptions,
 	): Promise<T | null>;
 	static findBy<T extends BaseModel>(
 		this: ModelClass<T>,
 		columnOrClause: string | Record<string, unknown>,
-		value?: unknown,
+		valueOrOptions?: unknown,
+		options?: ModelClientOptions,
 	): Promise<T | null> {
-		return typeof columnOrClause === "string"
-			? this.$repo().findBy(columnOrClause, value)
-			: this.$repo().findBy(columnOrClause);
+		if (typeof columnOrClause === "string") {
+			return this.$repo(options).findBy(columnOrClause, valueOrOptions);
+		}
+		const opts = isClientOptions(valueOrOptions) ? valueOrOptions : undefined;
+		return this.$repo(opts).findBy(columnOrClause);
 	}
 
 	static findByOrFail<T extends BaseModel>(
 		this: ModelClass<T>,
 		column: string,
 		value: unknown,
+		options?: ModelClientOptions,
 	): Promise<T>;
 	static findByOrFail<T extends BaseModel>(
 		this: ModelClass<T>,
 		clause: Record<string, unknown>,
+		options?: ModelClientOptions,
 	): Promise<T>;
 	static findByOrFail<T extends BaseModel>(
 		this: ModelClass<T>,
 		columnOrClause: string | Record<string, unknown>,
-		value?: unknown,
+		valueOrOptions?: unknown,
+		options?: ModelClientOptions,
 	): Promise<T> {
-		return typeof columnOrClause === "string"
-			? this.$repo().findByOrFail(columnOrClause, value)
-			: this.$repo().findByOrFail(columnOrClause);
+		if (typeof columnOrClause === "string") {
+			return this.$repo(options).findByOrFail(columnOrClause, valueOrOptions);
+		}
+		const opts = isClientOptions(valueOrOptions) ? valueOrOptions : undefined;
+		return this.$repo(opts).findByOrFail(columnOrClause);
 	}
 
 	static findMany<T extends BaseModel>(
 		this: ModelClass<T>,
 		ids: Array<string | number>,
+		options?: ModelClientOptions,
 	): Promise<T[]> {
-		return this.$repo().findMany(ids);
+		return this.$repo(options).findMany(ids);
 	}
 
 	static findManyBy<T extends BaseModel>(
 		this: ModelClass<T>,
 		column: string,
 		values: Array<string | number>,
+		options?: ModelClientOptions,
 	): Promise<T[]>;
 	static findManyBy<T extends BaseModel>(
 		this: ModelClass<T>,
 		clause: Record<string, unknown>,
+		options?: ModelClientOptions,
 	): Promise<T[]>;
 	static findManyBy<T extends BaseModel>(
 		this: ModelClass<T>,
 		columnOrClause: string | Record<string, unknown>,
-		values?: Array<string | number>,
+		valuesOrOptions?: Array<string | number> | ModelClientOptions,
+		options?: ModelClientOptions,
 	): Promise<T[]> {
-		return typeof columnOrClause === "string"
-			? this.$repo().findManyBy(columnOrClause, values ?? [])
-			: this.$repo().findManyBy(columnOrClause);
+		if (typeof columnOrClause === "string") {
+			const values = Array.isArray(valuesOrOptions) ? valuesOrOptions : [];
+			return this.$repo(options).findManyBy(columnOrClause, values);
+		}
+		const opts = isClientOptions(valuesOrOptions) ? valuesOrOptions : undefined;
+		return this.$repo(opts).findManyBy(columnOrClause);
 	}
 
-	static all<T extends BaseModel>(this: ModelClass<T>): Promise<T[]> {
-		return this.$repo().all();
+	static all<T extends BaseModel>(
+		this: ModelClass<T>,
+		options?: ModelClientOptions,
+	): Promise<T[]> {
+		return this.$repo(options).all();
 	}
 
 	static query<T extends BaseModel>(
 		this: ModelClass<T>,
+		options?: ModelClientOptions,
 	): ReturnType<BaseRepository<T>["query"]> {
-		return this.$repo().query();
+		return this.$repo(options).query();
 	}
 
-	static first<T extends BaseModel>(this: ModelClass<T>): Promise<T | null> {
-		return this.$repo().query().first();
+	static first<T extends BaseModel>(
+		this: ModelClass<T>,
+		options?: ModelClientOptions,
+	): Promise<T | null> {
+		return this.$repo(options).query().first();
 	}
 
-	static firstOrFail<T extends BaseModel>(this: ModelClass<T>): Promise<T> {
-		return this.$repo().query().firstOrFail();
+	static firstOrFail<T extends BaseModel>(
+		this: ModelClass<T>,
+		options?: ModelClientOptions,
+	): Promise<T> {
+		return this.$repo(options).query().firstOrFail();
 	}
 
 	// — Static creators (AdonisJS Lucid) —
@@ -170,93 +270,108 @@ export abstract class BaseModel extends BaseEntity {
 	static create<T extends BaseModel>(
 		this: ModelClass<T>,
 		data: Partial<Record<string, unknown>>,
+		options?: ModelClientOptions & { allowExtraProperties?: boolean },
 	): Promise<T> {
-		return this.$repo().create(data);
+		return this.$repo(options).create(data, {
+			allowExtraProperties: options?.allowExtraProperties ?? false,
+		});
 	}
 
 	static createMany<T extends BaseModel>(
 		this: ModelClass<T>,
 		rows: Array<Partial<Record<string, unknown>>>,
+		options?: ModelClientOptions,
 	): Promise<T[]> {
-		return this.$repo().createMany(rows);
+		return this.$repo(options).createMany(rows);
 	}
 
 	/** {@link create} without firing lifecycle hooks (AdonisJS Lucid `createQuietly`). */
 	static createQuietly<T extends BaseModel>(
 		this: ModelClass<T>,
 		data: Partial<Record<string, unknown>>,
+		options?: ModelClientOptions,
 	): Promise<T> {
-		return this.$repo().createQuietly(data);
+		return this.$repo(options).createQuietly(data);
 	}
 
 	/** {@link createMany} without firing lifecycle hooks (AdonisJS Lucid `createManyQuietly`). */
 	static createManyQuietly<T extends BaseModel>(
 		this: ModelClass<T>,
 		rows: Array<Partial<Record<string, unknown>>>,
+		options?: ModelClientOptions,
 	): Promise<T[]> {
-		return this.$repo().createManyQuietly(rows);
+		return this.$repo(options).createManyQuietly(rows);
 	}
 
 	static firstOrCreate<T extends BaseModel>(
 		this: ModelClass<T>,
 		search: Record<string, unknown>,
 		values?: Record<string, unknown>,
+		options?: ModelClientOptions,
 	): Promise<T> {
-		return this.$repo().firstOrCreate(search, values);
+		return this.$repo(options).firstOrCreate(search, values);
 	}
 
 	static firstOrNew<T extends BaseModel>(
 		this: ModelClass<T>,
 		search: Record<string, unknown>,
 		values?: Record<string, unknown>,
+		options?: ModelClientOptions,
 	): Promise<T> {
-		return this.$repo().firstOrNew(search, values);
+		return this.$repo(options).firstOrNew(search, values);
 	}
 
 	static updateOrCreate<T extends BaseModel>(
 		this: ModelClass<T>,
 		search: Record<string, unknown>,
 		values: Record<string, unknown>,
+		options?: ModelClientOptions,
 	): Promise<T> {
-		return this.$repo().updateOrCreate(search, values);
+		return this.$repo(options).updateOrCreate(search, values);
 	}
 
 	static updateOrCreateMany<T extends BaseModel>(
 		this: ModelClass<T>,
 		key: string | string[],
 		rows: Array<Record<string, unknown>>,
+		options?: ModelClientOptions,
 	): Promise<T[]> {
-		return this.$repo().updateOrCreateMany(key, rows);
+		return this.$repo(options).updateOrCreateMany(key, rows);
 	}
 
 	static fetchOrCreateMany<T extends BaseModel>(
 		this: ModelClass<T>,
 		key: string | string[],
 		rows: Array<Record<string, unknown>>,
+		options?: ModelClientOptions,
 	): Promise<T[]> {
-		return this.$repo().fetchOrCreateMany(key, rows);
+		return this.$repo(options).fetchOrCreateMany(key, rows);
 	}
 
 	static fetchOrNewUpMany<T extends BaseModel>(
 		this: ModelClass<T>,
 		key: string | string[],
 		rows: Array<Record<string, unknown>>,
+		options?: ModelClientOptions,
 	): Promise<T[]> {
-		return this.$repo().fetchOrNewUpMany(key, rows);
+		return this.$repo(options).fetchOrNewUpMany(key, rows);
 	}
 
 	/** Empty this model's table (AdonisJS `Model.truncate`). `cascade` is Postgres-only. */
 	static truncate<T extends BaseModel>(
 		this: ModelClass<T>,
 		cascade = false,
+		options?: ModelClientOptions,
 	): Promise<void> {
-		return this.$repo().truncate(cascade);
+		return this.$repo(options).truncate(cascade);
 	}
 
 	// — Instance persistence (AdonisJS Lucid) —
 
 	/** Transaction bound to this instance via {@link useTransaction}, if any. */
 	#trx?: DatabaseConnection;
+	/** Named connection bound at runtime via {@link useConnection}, if any. */
+	#connectionOverride?: string;
 
 	/** The transaction bound to this instance, if any (AdonisJS Lucid `$trx`). */
 	get $trx(): DatabaseConnection | undefined {
@@ -294,8 +409,30 @@ export abstract class BaseModel extends BaseEntity {
 	 * BaseModel subclass at runtime; TS types it only as `Function`, hence the
 	 * single unavoidable narrowing (the pattern Lucid's own BaseModel uses).
 	 */
+	/**
+	 * Bind this instance to a named connection at runtime (AdonisJS Lucid
+	 * `model.useConnection`) — subsequent `save()`/`delete()`/relations run on it.
+	 * A per-instance override of the class's `static connection`. Chainable.
+	 */
+	useConnection(name: string): this {
+		this.#connectionOverride = name;
+		return this;
+	}
+
 	#repo(): BaseRepository<this> {
 		const model = this.constructor as ModelClass<this>;
+		if (this.#connectionOverride !== undefined) {
+			const conn = getConnection(this.#connectionOverride);
+			if (!conn) {
+				throw new AtlasError(
+					"MISSING_CONNECTION",
+					`Model '${model.name}': no connection named '${this.#connectionOverride}' is registered.`,
+				);
+			}
+			model.$boot();
+			const repo = new BaseRepository<this>(model, conn);
+			return this.#trx ? repo.useTransaction(this.#trx) : repo;
+		}
 		const repo = model.$repo();
 		return this.#trx ? repo.useTransaction(this.#trx) : repo;
 	}

package/src/BaseRepository.ts

@@ -36,6 +36,7 @@ import {
 import { fireHooks } from "./decorators/hooks.js";
 import { AtlasError, EntityNotFoundError } from "./errors.js";
 import { isAtlasStrictMode, ModelQuery } from "./ModelQuery.js";
+import { DatabaseQueryBuilder } from "./query/DatabaseQueryBuilder.js";
 import {
 	type AtlasDialect,
 	compileStatementNative,
@@ -122,6 +123,14 @@ function isUniqueKeyViolation(err: unknown): boolean {
  * Drivers backed by `AsyncDatabaseConnection` (`createNapiConnection`)
  * satisfy this interface out-of-the-box.
  */
+/** Options for {@link BaseRepository.create} (Adonis Lucid `create` options). */
+export interface CreateOptions {
+	/** Skip lifecycle hooks + event dispatch (atlas's legacy `quiet` flag). */
+	quiet?: boolean;
+	/** Silently drop keys that are not columns instead of throwing (Lucid default: throw). */
+	allowExtraProperties?: boolean;
+}
+
 export interface DatabaseConnection {
 	/**
 	 * Run a write statement; returns rowsAffected.
@@ -232,6 +241,18 @@ export function computeCastTypes(
 	return out;
 }
 
+/** A model instance that can bind to a transaction (BaseModel `useTransaction`). */
+interface TransactionBindable {
+	useTransaction(trx: DatabaseConnection): unknown;
+}
+
+/** Structural guard: does this entity expose `useTransaction` (i.e. is a BaseModel)? */
+function isTransactionBindable(entity: object): entity is TransactionBindable {
+	return (
+		"useTransaction" in entity && typeof entity.useTransaction === "function"
+	);
+}
+
 export class BaseRepository<T extends BaseEntity> {
 	#entityClass: EntityConstructor<T>;
 	#tableName: string;
@@ -636,11 +657,17 @@ export class BaseRepository<T extends BaseEntity> {
 	 * Build an entity from a plain object and persist it. Fires `beforeCreate` →
 	 * `beforeSave` → INSERT → `afterCreate` → `afterSave` (AdonisJS/Lucid order:
 	 * the specific hook runs before the general `beforeSave`).
+	 *
+	 * An unknown key throws by default (Lucid); pass `{ allowExtraProperties: true }`
+	 * to drop unknown keys instead. A bare boolean is the legacy `quiet` flag.
 	 */
 	async create(
 		data: Partial<Record<string, unknown>>,
-		quiet = false,
+		options: boolean | CreateOptions = false,
 	): Promise<T> {
+		// Back-compat: a bare boolean is the legacy `quiet` flag.
+		const { quiet = false, allowExtraProperties = false } =
+			typeof options === "boolean" ? { quiet: options } : options;
 		const entity = new this.#entityClass();
 		for (const [key, value] of Object.entries(data)) {
 			if (
@@ -650,6 +677,18 @@ export class BaseRepository<T extends BaseEntity> {
 				const prop = this.#toProperty(key);
 				entity.assertMassAssignable(prop);
 				entity.setProp(prop, value);
+			} else if (key.startsWith("$")) {
+				// Framework-internal (`$extras`, `$trx`, …) — leaks in when an entity
+				// instance is passed as data. Not a user column and not a typo; skip.
+			} else if (!allowExtraProperties) {
+				// Adonis Lucid throws on an unknown property by default (a typo'd or
+				// stray key is a bug, not something to silently drop). Opt out with
+				// `create(data, { allowExtraProperties: true })`.
+				throw new AtlasError(
+					"E_UNKNOWN_COLUMN",
+					`Cannot assign '${key}' — it is not a column on ${this.#entityClass.name}. ` +
+						"Pass { allowExtraProperties: true } to drop unknown keys instead.",
+				);
 			}
 		}
 		if (!quiet) {
@@ -1366,18 +1405,52 @@ export class BaseRepository<T extends BaseEntity> {
 			return result;
 		}
 		// No explicit `@Column({ prepare })`: lower a `@column.date()` /
-		// `@column.dateTime()` value to its ISO 8601 string for the SQL bind. A raw
-		// JS `Date` is accepted leniently; otherwise the Chronos adapter's prepare
-		// serialises a `DateTime` — via a STRUCTURAL check, so an instance from a
-		// duplicated `@c9up/chronos` copy (another realm) round-trips instead of
-		// being passed raw to the N-API bind.
+		// `@column.dateTime()` value to its ISO 8601 string for the SQL bind.
+		// Branch order mirrors Lucid's `prepareDateColumn` (strings pass through,
+		// `DateTime` is formatted, anything else throws naming the column) — see
+		// `#prepareDateString` for the one named deviation.
 		if (this.#dateColumns[propertyKey] && value != null) {
+			if (typeof value === "string") {
+				return this.#prepareDateString(propertyKey, value);
+			}
+			// A raw JS `Date` is accepted where Lucid throws: `toISOString()` is
+			// unambiguous UTC, so the strictness would buy nothing. Named deviation.
 			if (value instanceof Date) return value.toISOString();
+			// Otherwise the Chronos adapter's prepare serialises a `DateTime` — via
+			// a STRUCTURAL check, so an instance from a duplicated `@c9up/chronos`
+			// copy (another realm) round-trips instead of being passed raw to the
+			// N-API bind.
 			return dateTimeAtlasAdapter.prepare(value);
 		}
 		return value;
 	}
 
+	/**
+	 * Lower a string assigned to a `@column.date()` / `@column.dateTime()`.
+	 *
+	 * Lucid lets every string through untouched (`prepareDateColumn`, first
+	 * branch), and atlas does the same — with ONE named deviation: a *naive*
+	 * datetime (no `Z`, no offset) is rejected. Such a string has no instant
+	 * attached, so the chronos read path resolves it in the JS runtime's local
+	 * zone: the very same row then hydrates to a different instant on a
+	 * developer laptop in Europe/Zurich and on a CI host running UTC. Silently
+	 * storing a value that means two different things is the failure this guard
+	 * exists to prevent; date-only strings and offset-bearing ones are
+	 * unambiguous and pass exactly like Lucid.
+	 */
+	#prepareDateString(propertyKey: string, value: string): string {
+		const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value.trim());
+		const hasZone = /(?:Z|[+-]\d{2}:?\d{2})$/.test(value.trim());
+		if (dateOnly || hasZone) return value;
+		throw new AtlasError(
+			"INVALID_DATE_COLUMN_VALUE",
+			`${this.#entityClass.name}.${propertyKey}: "${value}" is a naive datetime — it carries no timezone, so it would read back differently depending on the machine.`,
+			{
+				hint: 'Add an offset ("2026-08-10T12:00:00Z"), pass a chronos DateTime, or use a date-only string ("2026-08-10").',
+			},
+		);
+	}
+
 	#applyConsume(propertyKey: string, value: unknown, model?: unknown): unknown {
 		const consume = this.#columnConsumes.get(propertyKey);
 		if (consume) {
@@ -1892,6 +1965,17 @@ export class BaseRepository<T extends BaseEntity> {
 			enumerable: false,
 			configurable: true,
 		});
+		// Adonis Lucid `$trx` propagation: an instance loaded or created THROUGH a
+		// transaction-bound repo binds to that transaction, so its own
+		// `save()`/`delete()` stay inside it (and reset when the trx settles, via
+		// the release hook `useTransaction` registers). Previously only an explicit
+		// `model.useTransaction(trx)` did this, so a row read with
+		// `Model.query({ client: trx })` could later save OUTSIDE the transaction.
+		// Only BaseModel exposes `useTransaction`; a plain BaseEntity persists via
+		// the repo directly, so it needs no instance binding.
+		if (this.#durableParent !== undefined && isTransactionBindable(entity)) {
+			entity.useTransaction(this.#db);
+		}
 	}
 
 	/**
@@ -2245,7 +2329,10 @@ export class BaseRepository<T extends BaseEntity> {
 				// Resolve the related PK to its DB column (multi-word / columnName),
 				// mirroring the eager-preload fix — a raw property name here targets
 				// the wrong column in the correlated EXISTS.
-				const relatedPkProp = getPrimaryKey(relatedClass) ?? "id";
+				// The related-side key the pivot's otherKey references — the related
+				// PK unless `relatedKey` overrides it (Adonis Lucid `relatedKey`).
+				const relatedPkProp =
+					pivot.relatedKey ?? getPrimaryKey(relatedClass) ?? "id";
 				const relatedPk =
 					getColumnMetadata(relatedClass).find(
 						(c) => c.propertyKey === relatedPkProp,
@@ -2498,7 +2585,7 @@ export class BaseRepository<T extends BaseEntity> {
 			// pivot FK, so the `::cast` must match that column's type.
 			const parentPkCast = this.#castTypes[this.#dbColumn(parentPk)];
 			if (parentPkCast) pivotKeyCasts[pivotFk] = parentPkCast;
-			const relatedPk = getPrimaryKey(relatedClass) ?? "id";
+			const relatedPk = pivot.relatedKey ?? getPrimaryKey(relatedClass) ?? "id";
 			const relatedPkDb =
 				getColumnMetadata(relatedClass).find((c) => c.propertyKey === relatedPk)
 					?.columnName ?? camelToSnake(relatedPk);
@@ -2848,47 +2935,69 @@ export class BaseRepository<T extends BaseEntity> {
 			// runs in ONE transaction via `withParentSaved` (AdonisJS/Lucid parity):
 			// atomic, rolled back on any failure (no orphan related row, no pivot to a
 			// missing parent), with domain events flushed only after commit.
-			const relatedPkProp = getPrimaryKey(relatedClass) ?? "id";
+			const relatedPkProp =
+				pivot.relatedKey ?? getPrimaryKey(relatedClass) ?? "id";
 			const attachRows = (
 				rows: BaseEntity[],
 				trx: TransactionClient,
 				fk: unknown,
+				pivotFor?: (index: number) => Record<string, unknown>,
 			): Promise<void> => {
 				if (rows.length === 0) return Promise.resolve();
 				const arg: Record<string, Record<string, unknown>> = {};
-				for (const r of rows) arg[String(r[relatedPkProp])] = {};
+				rows.forEach((r, i) => {
+					arg[String(r[relatedPkProp])] = pivotFor?.(i) ?? {};
+				});
 				return attach(arg, trx, fk);
 			};
+			// create/save accept per-row pivot attributes (Adonis Lucid `create(values,
+			// pivotAttributes)` / `save(related, pivotAttributes)`) — written onto the
+			// pivot row alongside the FK/otherKey, in the same transaction.
 			const m2mOps = {
-				create: (data: Record<string, unknown>): Promise<BaseEntity> =>
+				create: (
+					data: Record<string, unknown>,
+					pivotAttributes?: Record<string, unknown>,
+				): Promise<BaseEntity> =>
 					withParentSaved(async (fk, rel, trx) => {
 						const created = await rel.create(data);
-						await attachRows([created], trx, fk);
+						await attachRows([created], trx, fk, () => pivotAttributes ?? {});
 						trx.after("commit", () => flushEvents([created]));
 						return created;
 					}),
 				createMany: (
 					rows: Array<Record<string, unknown>>,
+					pivotAttributes?: Array<Record<string, unknown>>,
 				): Promise<BaseEntity[]> =>
 					withParentSaved(async (fk, rel, trx) => {
 						const created = await rel.createMany(rows);
-						await attachRows(created, trx, fk);
+						await attachRows(
+							created,
+							trx,
+							fk,
+							(i) => pivotAttributes?.[i] ?? {},
+						);
 						// NO wrapper flush: rel.createMany now self-dispatches via
 						// #inManagedTx (like saveMany). The pivot rows carry no events; a
 						// second flush would double the related rows' events on a partial
 						// sink failure.
 						return created;
 					}),
-				save: (related: BaseEntity): Promise<void> =>
+				save: (
+					related: BaseEntity,
+					pivotAttributes?: Record<string, unknown>,
+				): Promise<void> =>
 					withParentSaved(async (fk, rel, trx) => {
 						await rel.save(related);
-						await attachRows([related], trx, fk);
+						await attachRows([related], trx, fk, () => pivotAttributes ?? {});
 						trx.after("commit", () => flushEvents([related]));
 					}),
-				saveMany: (related: BaseEntity[]): Promise<BaseEntity[]> =>
+				saveMany: (
+					related: BaseEntity[],
+					pivotAttributes?: Array<Record<string, unknown>>,
+				): Promise<BaseEntity[]> =>
 					withParentSaved(async (fk, rel, trx) => {
 						const saved = await rel.saveMany(related);
-						await attachRows(saved, trx, fk);
+						await attachRows(saved, trx, fk, (i) => pivotAttributes?.[i] ?? {});
 						// NO wrapper flush: rel.saveMany self-dispatches via #inManagedTx
 						// (all-or-nothing). A second flush would double on partial failure.
 						return saved;
@@ -2914,6 +3023,16 @@ export class BaseRepository<T extends BaseEntity> {
 				type: "manyToMany",
 				...m2mOps,
 				query: scopedQuery,
+				// A query builder on the PIVOT table itself, scoped to this parent
+				// (Adonis Lucid `pivotQuery`) — for reading/updating/deleting pivot
+				// rows directly, beyond attach/detach/sync.
+				pivotQuery: () => {
+					guardParent("pivotQuery()");
+					return new DatabaseQueryBuilder(this.#db, dialect, pivotTable).where(
+						pivotFk,
+						readParentId(),
+					);
+				},
 				// async so the guard throw surfaces as a REJECTED promise — a method
 				// typed `Promise<void>` must never throw synchronously.
 				attach: async (ids) => {