@c9up/atlas 0.1.9 → 0.1.11

package/src/BaseRepository.ts

@@ -210,6 +210,18 @@ export class BaseRepository<T extends BaseEntity> {
 		options?: { dialect?: AtlasDialect },
 	) {
 		this.#entityClass = entityClass;
+		if (db == null) {
+			// A null/undefined connection almost always means IoC constructor
+			// injection failed (missing decorator metadata) — fail with a clear
+			// message instead of the cryptic `reading 'dialect' of undefined`.
+			throw new AtlasError(
+				"MISSING_CONNECTION",
+				`BaseRepository for '${entityClass.name}' requires a DatabaseConnection (got ${db === null ? "null" : "undefined"}).`,
+				{
+					hint: "The connection was not injected. Check IoC constructor injection is wired — decorator metadata (emitDecoratorMetadata) or @Inject(token) on the connection parameter.",
+				},
+			);
+		}
 		this.#db = db;
 
 		// Dialect resolution order: explicit option > connection.dialect > process default.
@@ -351,15 +363,10 @@ export class BaseRepository<T extends BaseEntity> {
 	// ─── Finders ──────────────────────────────────────────────
 
 	async find(id: string | number | bigint): Promise<T | null> {
-		const wheres: Array<Record<string, unknown>> = [
-			{ 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<Row>(sql, params);
-		const row = rows[0];
-		if (!row) return null;
-		return this.#hydrate(row);
+		// Route through the query builder so the read hooks (beforeFind/afterFind)
+		// fire and a `beforeFind` hook can mutate the query — the previous direct
+		// `#compileSelect` fast path bypassed every read hook silently.
+		return this.query().where(this.#primaryKey, id).first();
 	}
 
 	async findOrFail(id: string | number): Promise<T> {
@@ -373,60 +380,34 @@ export class BaseRepository<T extends BaseEntity> {
 	}
 
 	async findBy(column: string, value: unknown): Promise<T | null> {
-		const col = this.#resolveColumn(column);
-		const wheres: Array<Record<string, unknown>> = [
-			{ column: col, operator: "=", value, type: "and" },
-		];
-		this.#appendSoftScope(wheres);
-		const { sql, params } = this.#compileSelect({ wheres, limit: 1 });
-		const rows = await this.#db.query<Row>(sql, params);
-		const row = rows[0];
-		if (!row) return null;
-		return this.#hydrate(row);
+		// Through the builder for read-hook parity (see `find`).
+		return this.query().where(column, value).first();
 	}
 
 	async all(): Promise<T[]> {
-		const wheres: Array<Record<string, unknown>> = [];
-		this.#appendSoftScope(wheres);
-		return this.#runSelect({ wheres });
+		// Through the builder so beforeFetch/afterFetch fire. The builder applies
+		// the soft-delete scope by default, exactly like the old fast path.
+		return this.query().exec();
 	}
 
 	async allWithTrashed(): Promise<T[]> {
-		return this.#runSelect({});
+		return this.query().withTrashed().exec();
 	}
 
 	async onlyTrashed(): Promise<T[]> {
 		if (!this.#softDeletes) return [];
-		return this.#runSelect({
-			wheres: [
-				{
-					column: "deleted_at",
-					operator: "IS NOT NULL",
-					value: null,
-					type: "and",
-				},
-			],
-		});
+		return this.query().onlyTrashed().exec();
 	}
 
 	async where(column: string, value: unknown): Promise<T[]> {
-		const col = this.#resolveColumn(column);
-		const wheres: Array<Record<string, unknown>> = [
-			{ 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" }],
-		});
+		// Order by the primary key (DESC = most recent insert first when the PK is
+		// an auto-increment integer or a monotonic UUID). The ordering contract is
+		// "most recent first by PK" for `repo.where(col, val)` as a convenience
+		// finder. Through the builder for read-hook parity (see `find`).
+		return this.query()
+			.where(column, value)
+			.orderBy(this.#primaryKey, "desc")
+			.exec();
 	}
 
 	// ─── Create / Save / Delete ───────────────────────────────
@@ -450,6 +431,7 @@ export class BaseRepository<T extends BaseEntity> {
 		await this.#insert(entity);
 		await fireHooks(this.#entityClass, "afterCreate", entity);
 		await fireHooks(this.#entityClass, "afterSave", entity);
+		await this.#dispatchDomainEvents(entity);
 		return entity;
 	}
 
@@ -494,6 +476,17 @@ export class BaseRepository<T extends BaseEntity> {
 		}
 		await fireHooks(this.#entityClass, "afterSave", entity);
 
+		await this.#dispatchDomainEvents(entity);
+	}
+
+	/**
+	 * Flush the entity's accumulated domain events through `onDomainEvents`.
+	 * On dispatch failure the events are re-queued on the entity and the error
+	 * propagates, so a caller can retry without losing them. Shared by `save`,
+	 * `create` and `createMany` — every persistence path that produces a live
+	 * entity must dispatch, otherwise events silently vanish on batch inserts.
+	 */
+	async #dispatchDomainEvents(entity: BaseEntity): Promise<void> {
 		const events = entity.flushDomainEvents();
 		if (events.length > 0 && this.onDomainEvents) {
 			try {
@@ -576,6 +569,9 @@ export class BaseRepository<T extends BaseEntity> {
 			await fireHooks(this.#entityClass, "afterCreate", e);
 			await fireHooks(this.#entityClass, "afterSave", e);
 		}
+		for (const e of entities) {
+			await this.#dispatchDomainEvents(e);
+		}
 		return entities;
 	}
 
@@ -908,43 +904,6 @@ export class BaseRepository<T extends BaseEntity> {
 
 	// ─── Private helpers ──────────────────────────────────────
 
-	#compileSelect(opts: {
-		wheres?: Array<Record<string, unknown>>;
-		orderBy?: Array<Record<string, unknown>>;
-		limit?: number;
-	}): { sql: string; params: unknown[] } {
-		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: [],
-			// Cast WHERE params on native-typed columns (uuid/timestamp/…) so a
-			// `WHERE id = $1` on a uuid PK emits `$1::uuid` — otherwise Postgres
-			// rejects it with `operator does not exist: uuid = text`.
-			casts: this.#castTypes,
-		};
-		const compiled = compileStatementNative(spec, this.#dialect);
-		return { sql: compiled.statements[0], params: compiled.params };
-	}
-
-	async #runSelect(opts: {
-		wheres?: Array<Record<string, unknown>>;
-		orderBy?: Array<Record<string, unknown>>;
-		limit?: number;
-	}): Promise<T[]> {
-		const { sql, params } = this.#compileSelect(opts);
-		const rows = await this.#db.query<Row>(sql, params);
-		return rows.map((r) => this.#hydrate(r));
-	}
-
 	async #runDelete(wheres: Array<Record<string, unknown>>): Promise<void> {
 		const compiled = compileStatementNative(
 			{ kind: "delete", table: this.#tableName, wheres },
@@ -1023,17 +982,6 @@ export class BaseRepository<T extends BaseEntity> {
 		return {};
 	}
 
-	#appendSoftScope(wheres: Array<Record<string, unknown>>): void {
-		if (this.#softDeletes) {
-			wheres.push({
-				column: "deleted_at",
-				operator: "IS NULL",
-				value: null,
-				type: "and",
-			});
-		}
-	}
-
 	async #insert(entity: T): Promise<void> {
 		// Auto-generate the PK when declared via `@PrimaryKey({ generated })`.
 		this.#applyPrimaryKeyGenerator(entity);
@@ -1314,6 +1262,10 @@ export class BaseRepository<T extends BaseEntity> {
 		const relatedRepo = new BaseRepository<BaseEntity>(relatedClass, this.#db, {
 			dialect: this.#dialect,
 		});
+		// Propagate the domain-event sink so entities persisted through a relation
+		// proxy (user.related('posts').create(...)) dispatch their events too —
+		// otherwise the related entity's events silently vanish.
+		relatedRepo.onDomainEvents = this.onDomainEvents;
 		const db = this.#db;
 
 		// FK column naming: belongsTo stores the FK on THIS side; has* / m2m on the OTHER side.

package/src/ModelQuery.ts

@@ -10,12 +10,14 @@
 import type { BaseEntity } from "./BaseEntity.js";
 import type { DatabaseConnection } from "./BaseRepository.js";
 import {
+	getColumnMetadata,
 	getEntityMetadata,
 	getPrimaryKey,
 	getRelationMetadata,
 	hasSoftDeletes,
 	type RelationMetadata,
 } from "./decorators/entity.js";
+import { fireHooks } from "./decorators/hooks.js";
 import {
 	type AtlasDialect,
 	compileStatementNative,
@@ -937,11 +939,15 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
-	/** Execute and return the first matching entity or null. */
+	/** Execute and return the first matching entity or null. Fires beforeFind/afterFind. */
 	async first(): Promise<T | null> {
 		this.#limit = 1;
-		const results = await this.exec();
-		return results[0] ?? null;
+		await fireHooks(this.#entityClass, "beforeFind", this);
+		// Bypass exec() so the multi-row beforeFetch/afterFetch hooks don't ALSO
+		// fire — first() is the single-row terminal and owns beforeFind/afterFind.
+		const result = (await this.#doExec())[0] ?? null;
+		await fireHooks(this.#entityClass, "afterFind", result);
+		return result;
 	}
 
 	/** Execute and return the first matching entity or throw. */
@@ -1035,12 +1041,19 @@ export class ModelQuery<T extends BaseEntity> {
 	 */
 	#cachedExec?: Promise<T[]>;
 
-	/** Execute and return all matching entities, with preloaded relations. */
+	/** Execute and return all matching entities, with preloaded relations. Fires beforeFetch/afterFetch. */
 	exec(): Promise<T[]> {
-		this.#cachedExec ??= this.#doExec();
+		this.#cachedExec ??= this.#execWithFetchHooks();
 		return this.#cachedExec;
 	}
 
+	async #execWithFetchHooks(): Promise<T[]> {
+		await fireHooks(this.#entityClass, "beforeFetch", this);
+		const results = await this.#doExec();
+		await fireHooks(this.#entityClass, "afterFetch", results);
+		return results;
+	}
+
 	async #doExec(): Promise<T[]> {
 		const { sql, params } = this.toSQL();
 		const rawRows = await this.#db.query<Record<string, unknown>>(sql, params);
@@ -1099,12 +1112,28 @@ export class ModelQuery<T extends BaseEntity> {
 		const relatedMeta = getEntityMetadata(relatedClass);
 		if (!relatedMeta) return null;
 
+		// 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<string>();
+		for (const col of getColumnMetadata(relatedClass)) {
+			validColumns.add(col.propertyKey);
+			validColumns.add(camelToSnake(col.propertyKey));
+		}
+		validColumns.add(relatedPkName);
+		validColumns.add(camelToSnake(relatedPkName));
+
 		const hydrate = (row: Record<string, unknown>): BaseEntity => {
 			const entity = new relatedClass();
 			for (const [key, value] of Object.entries(row)) {
 				const camelKey = snakeToCamel(key);
-				const targetKey =
-					camelKey in entity ? camelKey : key in entity ? key : null;
+				const targetKey = validColumns.has(camelKey)
+					? camelKey
+					: validColumns.has(key)
+						? key
+						: null;
 				if (targetKey !== null) entity.setProp(targetKey, value);
 			}
 			return entity;
@@ -1351,12 +1380,14 @@ export class ModelQuery<T extends BaseEntity> {
 			);
 		}
 		const pivot = ctx.relation.pivot;
+		// Default pivot FK = `<model_snake>_id`, derived from the entity CLASS name
+		// (singular by convention), consistent with hasMany/hasOne/belongsTo. Do NOT
+		// singularize the plural TABLE name by stripping a trailing `s` — that breaks
+		// on `status`/`address`/`campus` (→ `statu_id`). Explicit pivot keys win.
 		const foreignKey =
-			pivot.foreignKey ??
-			`${camelToSnake(this.#tableName.replace(/s$/, ""))}_id`;
+			pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 		const otherKey =
-			pivot.otherKey ??
-			`${camelToSnake(ctx.relatedTable.replace(/s$/, ""))}_id`;
+			pivot.otherKey ?? `${camelToSnake(ctx.relatedClass.name)}_id`;
 		const pk = getPrimaryKey(this.#entityClass) ?? "id";
 
 		const ids = entities.map((e) => e[pk]).filter((v) => v != null);
@@ -1576,12 +1607,12 @@ export class ModelQuery<T extends BaseEntity> {
 					);
 				}
 				const pivot = relation.pivot;
+				// Default pivot FK from the CLASS name (singular), not the plural table
+				// name stripped of a trailing `s` — see the eager loader above.
 				const foreignKey =
-					pivot.foreignKey ??
-					`${camelToSnake(parentTable.replace(/s$/, ""))}_id`;
+					pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 				const otherKey =
-					pivot.otherKey ??
-					`${camelToSnake(relatedTable.replace(/s$/, ""))}_id`;
+					pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
 				const relatedPk = getPrimaryKey(relatedClass) ?? "id";
 				sub.#pushWhereRaw(
 					`${q(relatedTable)}.${q(relatedPk)} IN ` +
@@ -1590,6 +1621,16 @@ export class ModelQuery<T extends BaseEntity> {
 				);
 				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;
 	}
@@ -1802,6 +1843,9 @@ export class ModelQuery<T extends BaseEntity> {
 	async paginate(page: number, perPage: number): Promise<Paginator<T>> {
 		const p = Math.max(1, Math.floor(page));
 		const pp = Math.max(1, Math.floor(perPage));
+		// beforePaginate runs BEFORE cloning so a hook mutating the query (e.g. a
+		// tenant scope) propagates into both the COUNT and the data fetch.
+		await fireHooks(this.#entityClass, "beforePaginate", this);
 		// Parallel COUNT(*) + data fetch
 		const countQ = this.clone();
 		countQ.#select = ["COUNT(*) AS count"];
@@ -1815,7 +1859,10 @@ export class ModelQuery<T extends BaseEntity> {
 		const dataQ = this.clone();
 		dataQ.#limit = pp;
 		dataQ.#offset = (p - 1) * pp;
-		const items = await dataQ.exec();
+		// `#doExec` (not `exec`) so the generic beforeFetch/afterFetch don't fire on
+		// top of the paginate hooks — paginate is its own terminal.
+		const items = await dataQ.#doExec();
+		await fireHooks(this.#entityClass, "afterPaginate", items);
 		return new Paginator<T>(items, { total, perPage: pp, currentPage: p });
 	}
 
@@ -1880,7 +1927,9 @@ export class ModelQuery<T extends BaseEntity> {
 			direction: "asc" as const,
 		}));
 		clone.#limit = lim + 1;
-		const rows = await clone.exec();
+		// `#doExec` (not `exec`) — cursorPaginate is an atlas-specific terminal, not a
+		// Lucid hook point; don't fire the generic beforeFetch/afterFetch on its clone.
+		const rows = await clone.#doExec();
 		const hasMore = rows.length > lim;
 		const items = hasMore ? rows.slice(0, lim) : rows;
 		const last = items[items.length - 1] as Record<string, unknown> | undefined;

package/src/adapters/NapiDbAdapter.ts

@@ -46,10 +46,27 @@ interface NapiModule {
 			min: number,
 			max: number,
 			pragmas?: Array<[string, string]>,
+			connectRetries?: number,
+			connectBackoffMs?: number,
+			connectTimeoutMs?: number,
 		): Promise<NapiReamDatabase>;
 	};
 }
 
+/** Connection retry / timeout knobs (see {@link createNapiConnection}). */
+export interface ConnectRetryOptions {
+	/** Extra attempts if the initial connect fails (default 0 — single attempt). */
+	retries?: number;
+	/** Base backoff in ms between attempts; grows exponentially, capped at 30s (default 200). */
+	backoffMs?: number;
+	/**
+	 * Per-attempt acquire timeout in ms (sqlx `acquire_timeout`). sqlx already
+	 * retries connection establishment internally up to this window (~30s by
+	 * default), so lower it to make each retry give up faster.
+	 */
+	timeoutMs?: number;
+}
+
 /**
  * Connect to a database via the Rust NAPI driver.
  *
@@ -62,13 +79,10 @@ export async function createNapiConnection(
 	poolMin = 1,
 	poolMax = 10,
 	pragmas?: Record<string, string | number>,
+	retry?: ConnectRetryOptions,
 ): Promise<AsyncDatabaseConnection> {
+	// Throws with the underlying cause if the binary can't be loaded.
 	const native = await loadNativeDb();
-	if (!native) {
-		throw new Error(
-			"[ATLAS] Rust DB driver (atlas-db-napi) not available. Build with: cargo build --release",
-		);
-	}
 
 	// Validate sqlite pragmas before crossing the NAPI boundary.
 	// PRAGMA syntax doesn't take bound parameters — the Rust side will
@@ -109,6 +123,9 @@ export async function createNapiConnection(
 		poolMin,
 		poolMax,
 		pragmaList,
+		retry?.retries,
+		retry?.backoffMs,
+		retry?.timeoutMs,
 	);
 
 	return {
@@ -149,7 +166,7 @@ export async function createNapiConnection(
 // shared with AtlasProvider.
 
 /** Load the native DB binding from the prebuilt `.node` binary in the package root. */
-async function loadNativeDb(): Promise<NapiModule | null> {
+async function loadNativeDb(): Promise<NapiModule> {
 	const platform = process.platform;
 	const arch = process.arch;
 	// Same naming convention as napi-rs / src/query/native.ts: the build emits
@@ -172,7 +189,14 @@ async function loadNativeDb(): Promise<NapiModule | null> {
 		// The binary lives at the package root (../../db.<suffix>.node from src/adapters/)
 		const binaryPath = join(here, "..", "..", binaryName);
 		return require(binaryPath) as NapiModule;
-	} catch {
-		return null;
+	} catch (err) {
+		// Surface the real cause (missing file, ABI mismatch, dlopen error) — a
+		// bare `return null` previously erased it and left the caller throwing a
+		// generic "not available" message that was impossible to debug.
+		throw new Error(
+			`[ATLAS] Failed to load Rust DB driver '${binaryName}' for ${platform}-${arch}. ` +
+				"Build with: cargo build --release",
+			{ cause: err },
+		);
 	}
 }

package/src/configure.ts

@@ -11,24 +11,23 @@ interface Codemods {
 export async function configure(codemods: Codemods): Promise<void> {
 	await codemods.addProvider("@c9up/atlas/provider");
 	await codemods.addEnvVars({
-		DB_CONNECTION: "postgres",
 		DB_HOST: "localhost",
 		DB_PORT: "5432",
 		DB_DATABASE: "ream",
 		DB_USER: "postgres",
-		DB_PASSWORD: "secret",
+		DB_PASSWORD: "change-me",
 	});
 	await codemods.writeFile(
 		"config/database.ts",
 		`import { defineConfig } from '@c9up/atlas'
 
 export default defineConfig({
-  connection: process.env.DB_CONNECTION ?? 'postgres',
+  default: 'postgres',
   connections: {
     postgres: {
-      host: process.env.DB_HOST ?? 'localhost',
-      port: Number(process.env.DB_PORT ?? '5432'),
-      database: process.env.DB_DATABASE ?? 'ream',
+      url:
+        process.env.DATABASE_URL ??
+        \`postgres://\${process.env.DB_USER ?? 'postgres'}:\${process.env.DB_PASSWORD ?? ''}@\${process.env.DB_HOST ?? 'localhost'}:\${process.env.DB_PORT ?? '5432'}/\${process.env.DB_DATABASE ?? 'ream'}\`,
     },
   },
 })

package/src/decorators/entity.ts

@@ -9,7 +9,7 @@ import {
 	COLUMN_SERIALIZE_KEY,
 	COMPUTED_KEY,
 	type ColumnSerializeConfig,
-} from "../BaseEntity.js";
+} from "../metadata-keys.js";
 
 const ENTITY_KEY = Symbol("atlas:entity");
 const COLUMNS_KEY = Symbol("atlas:columns");

package/src/index.ts

@@ -7,7 +7,10 @@
 import "reflect-metadata";
 
 export { SQLITE_PROD_PRAGMAS } from "./AtlasProvider.js";
-export type { AsyncDatabaseConnection } from "./adapters/NapiDbAdapter.js";
+export type {
+	AsyncDatabaseConnection,
+	ConnectRetryOptions,
+} from "./adapters/NapiDbAdapter.js";
 export { createNapiConnection } from "./adapters/NapiDbAdapter.js";
 export type { DomainEvent } from "./BaseEntity.js";
 export { BaseEntity } from "./BaseEntity.js";

package/src/metadata-keys.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared entity metadata keys + serialize config.
+ *
+ * Extracted from `BaseEntity` so the decorator layer (`decorators/entity.ts`)
+ * can read them without importing `BaseEntity` — that import-back formed a
+ * runtime cycle `BaseEntity` ↔ `entity` (fallow 2026-06-14). Agnostic: pure
+ * `Symbol.for` keys + a plain interface, zero runtime dependencies.
+ */
+
+/** Symbol metadata key for the computed-property registry on an entity class. */
+export const COMPUTED_KEY = Symbol.for("atlas:computed");
+
+/** Symbol metadata key for the serialize-as / serializer overrides on columns. */
+export const COLUMN_SERIALIZE_KEY = Symbol.for("atlas:columnSerialize");
+
+/** Per-column serialization config (populated by @Column options). */
+export interface ColumnSerializeConfig {
+	/** Rename this column at toJSON time (e.g. `password` → `passwordHash`). Null = hidden. */
+	serializeAs?: string | null;
+	/** Transform function applied to the value at toJSON time. */
+	serialize?: (value: unknown) => unknown;
+}

package/src/query/native.ts

@@ -67,6 +67,16 @@ export interface CompiledStatement {
  */
 const castRegistry = new Map<string, Record<string, string>>();
 
+/**
+ * Drop every registered cast. Called by `AtlasProvider.shutdown()` so a re-boot
+ * (tests, hot-reload) starts from a clean registry rather than accumulating casts
+ * across runs — two suites declaring the same table with different column types
+ * would otherwise pollute each other depending on execution order.
+ */
+export function clearCastRegistry(): void {
+	castRegistry.clear();
+}
+
 /**
  * Register an entity table's cast map (MERGES — a FK cast another entity already
  * published for this table via `registerColumnCast` survives, regardless of
@@ -143,7 +153,8 @@ export function compileStatementNative(
 ): CompiledStatement {
 	if (!native) {
 		throw new Error(
-			`[ATLAS_NAPI_NOT_FOUND] Rust query compiler not available: ${loadError ?? "binary not found"}`,
+			"[ATLAS_NAPI_NOT_FOUND] Rust query compiler not available. Build with: cargo build --release",
+			loadError !== undefined ? { cause: loadError } : undefined,
 		);
 	}
 	const json = native.compileStatement(

package/src/schema/MigrationRunner.ts

@@ -312,7 +312,10 @@ export class MigrationRunner {
 				table: this.#tableName,
 				select: ["name"],
 				wheres: [{ column: "batch", operator: "=", value: batch, type: "and" }],
-				orderBy: [{ column: "name", direction: "desc" }],
+				// Reverse INSERTION order (auto-increment `id`), not name order — a
+				// date- or hash-prefixed naming scheme would otherwise roll back in
+				// the wrong sequence. `id DESC` is always the inverse of application.
+				orderBy: [{ column: "id", direction: "desc" }],
 				groupBy: [],
 				having: [],
 				limit: null,
@@ -499,7 +502,7 @@ export class MigrationRunner {
 	/** Load and instantiate a migration class. */
 	async #loadMigration(name: string): Promise<Migration> {
 		this.#assertSafeName(name);
-		assertPathInsideBase(
+		await assertPathInsideBase(
 			this.#migrationsDir,
 			`${name}.ts`,
 			"MIGRATION_INVALID",

package/src/schema/Seeder.ts

@@ -1,15 +1,20 @@
 /**
  * Seeder — populate the database with default / reference / test data.
  *
- * The canonical pattern:
+ * The canonical pattern (idempotent via `upsert`, keyed on a unique column):
  *
  *     export default class CountrySeeder extends BaseSeeder {
  *       async run() {
- *         // Idempotent via updateOrCreateMany — safe to re-run.
- *         await Country.updateOrCreateMany('isoCode', [
- *           { isoCode: 'FR', name: 'France' },
- *           { isoCode: 'IN', name: 'India' },
- *         ])
+ *         const countries = new BaseRepository(Country, this.db)
+ *         // Conflict on isoCode → update name. Safe to re-run.
+ *         await countries.upsert(
+ *           [
+ *             { isoCode: 'FR', name: 'France' },
+ *             { isoCode: 'IN', name: 'India' },
+ *           ],
+ *           ['isoCode'],
+ *           ['name'],
+ *         )
  *       }
  *     }
  *
@@ -39,7 +44,7 @@ export abstract class BaseSeeder {
 		this.db = db;
 	}
 
-	/** The seeder body. Should be idempotent — `updateOrCreateMany` is the recommended pattern. */
+	/** The seeder body. Should be idempotent — `repo.upsert(...)` is the recommended pattern. */
 	abstract run(): Promise<void> | void;
 }
 
@@ -51,10 +56,7 @@ export const Seeder = BaseSeeder;
  * sequentially so ordering is deterministic and side effects are visible to
  * subsequent seeders.
  */
-export async function runSeeders(
-	seeders: BaseSeeder[],
-	_db?: DatabaseConnection,
-): Promise<void> {
+export async function runSeeders(seeders: BaseSeeder[]): Promise<void> {
 	for (const seeder of seeders) {
 		await seeder.run();
 	}
@@ -102,7 +104,7 @@ export async function runSeederDirectory(
 	const executed: string[] = [];
 	for (const file of selected) {
 		assertSafeName(file, "E_SEEDER_INVALID", "seeder");
-		const resolved = assertPathInsideBase(
+		const resolved = await assertPathInsideBase(
 			dir,
 			file,
 			"E_SEEDER_INVALID_PATH",

package/src/services/db.ts

@@ -22,6 +22,16 @@ export function setDb(connection: AsyncDatabaseConnection): void {
 	instance = connection;
 }
 
+/**
+ * @internal Unbind the singleton IF it still points at `connection` (called by
+ * `AtlasProvider.shutdown()`). Ownership-guarded: when a second provider rebound
+ * the singleton, the older provider's shutdown must not clear the newer binding.
+ * Without this, `db.*` after shutdown would dereference a closed connection.
+ */
+export function clearDb(connection: AsyncDatabaseConnection): void {
+	if (instance === connection) instance = undefined;
+}
+
 /** @internal Read the singleton (or `undefined` pre-boot). */
 export function getDb(): AsyncDatabaseConnection | undefined {
 	return instance;