@classytic/arc-testkit 0.3.0 → 0.5.0

package/README.md

@@ -60,6 +60,20 @@ const t = await bootModuleApp(mods, {
 | `TestkitContext` | what a module factory receives: `{ connection, mongoUri }` |
 | `BootModuleAppOptions` | `{ replset?, app?, backend? }` |
 
+## Cost and plan assertions (MongoDB)
+
+```ts
+import { assertConstantCommands, countCommands } from '@classytic/arc-testkit/mongo-commands';
+import { assertIndexServed } from '@classytic/arc-testkit/mongo-explain';
+
+// What the driver sent (the connection needs `monitorCommands: true` — it refuses otherwise).
+const { total, byCollection } = await countCommands(conn, () => placeOrder(), { collections: ['orders'] });
+// Same commands at every size, and at least one: a per-item read fails here.
+await assertConstantCommands(conn, (n) => reader.page(n), [5, 50]);
+// No COLLSCAN, an index scanned, optionally a named one and a docs-examined ceiling.
+assertIndexServed(await Model.find(filter).explain('executionStats'), { index: 'org_state', maxDocsExamined: 40 });
+```
+
 ## License
 
 MIT © Classytic

package/dist/mongo-commands.d.mts

@@ -0,0 +1,29 @@
+import { Connection } from "mongoose";
+//#region src/mongo-commands.d.ts
+type MongoClientLike = ReturnType<Connection["getClient"]>;
+interface CountCommandsOptions {
+  /** Count only commands against these collections. */
+  readonly collections?: readonly string[];
+  /** Count only these command names (`find`, `aggregate`, `insert`, …). */
+  readonly commands?: readonly string[];
+  /** Never count these command names — e.g. `createIndexes` a model may run lazily. */
+  readonly ignore?: readonly string[];
+}
+interface WireCommand {
+  readonly command: string;
+  /** The collection the command targets; `undefined` for session, transaction and admin commands. */
+  readonly collection: string | undefined;
+}
+interface CommandCount<T> {
+  readonly result: T;
+  readonly total: number;
+  /** Counted commands, in the order the driver sent them. */
+  readonly commands: readonly WireCommand[];
+  /** Counts keyed by collection (`(none)` for commands without one). */
+  readonly byCollection: Readonly<Record<string, number>>;
+  readonly byCommand: Readonly<Record<string, number>>;
+}
+declare function countCommands<T>(source: Connection | MongoClientLike, fn: () => Promise<T>, options?: CountCommandsOptions): Promise<CommandCount<T>>;
+declare function assertConstantCommands<T>(source: Connection | MongoClientLike, run: (size: number) => Promise<T>, sizes: readonly number[], options?: CountCommandsOptions): Promise<readonly CommandCount<T>[]>;
+//#endregion
+export { CommandCount, CountCommandsOptions, WireCommand, assertConstantCommands, countCommands };

package/dist/mongo-commands.mjs

@@ -0,0 +1,54 @@
+//#region src/mongo-commands.ts
+async function countCommands(source, fn, options = {}) {
+	const client = "getClient" in source ? source.getClient() : source;
+	if (client.options.monitorCommands !== true) throw new Error("[arc-testkit] countCommands: the client was created without `monitorCommands: true` — the driver emits no command events, so every count would read 0");
+	const commands = [];
+	const onStarted = (e) => {
+		const collection = collectionOf(e.commandName, e.command);
+		if (options.ignore?.includes(e.commandName)) return;
+		if (options.commands && !options.commands.includes(e.commandName)) return;
+		if (options.collections && (collection === void 0 || !options.collections.includes(collection))) return;
+		commands.push({
+			command: e.commandName,
+			collection
+		});
+	};
+	client.on("commandStarted", onStarted);
+	let result;
+	try {
+		result = await fn();
+	} finally {
+		client.off("commandStarted", onStarted);
+	}
+	return {
+		result,
+		total: commands.length,
+		commands,
+		byCollection: tally(commands.map((c) => c.collection ?? "(none)")),
+		byCommand: tally(commands.map((c) => c.command))
+	};
+}
+async function assertConstantCommands(source, run, sizes, options = {}) {
+	if (new Set(sizes).size < 2) throw new Error("[arc-testkit] assertConstantCommands: needs at least two distinct sizes");
+	const counts = [];
+	for (const size of sizes) counts.push(await countCommands(source, () => run(size), options));
+	const shape = (c) => c.commands.map((w) => `${w.collection ?? "(none)"}.${w.command}`).join(", ");
+	const [first] = counts;
+	if (!first || first.total === 0) throw new Error(`[arc-testkit] assertConstantCommands: size ${sizes[0]} sent no counted command — the measurement saw nothing`);
+	if (counts.some((c) => shape(c) !== shape(first))) {
+		const lines = counts.map((c, i) => `  at ${sizes[i]}: ${c.total} [${shape(c)}]`).join("\n");
+		throw new Error(`[arc-testkit] assertConstantCommands: the commands grow with the size\n${lines}`);
+	}
+	return counts;
+}
+function collectionOf(name, command) {
+	const target = name === "getMore" ? command.collection : command[name];
+	return typeof target === "string" ? target : void 0;
+}
+function tally(keys) {
+	const out = {};
+	for (const k of keys) out[k] = (out[k] ?? 0) + 1;
+	return out;
+}
+//#endregion
+export { assertConstantCommands, countCommands };

package/dist/mongo-explain.d.mts

@@ -0,0 +1,34 @@
+//#region src/mongo-explain.d.ts
+/**
+ * Read a MongoDB `explain()` result — find, aggregate, classic or SBE — as the WINNING plan's stage
+ * names, the indexes it scans, and its execution stats (`executionStats` verbosity). Rejected plans
+ * and query predicates are never read. `assertIndexServed` fails on a COLLSCAN, on a plan scanning
+ * no index (an explain of an empty or missing collection), and on every option not met.
+ *
+ * ```ts
+ * const explain = await Model.find({ organizationId, state: "posted" }).explain("executionStats");
+ * assertIndexServed(explain, { index: "org_state_date", maxDocsExamined: 40 });
+ * ```
+ */
+interface ExplainSummary {
+  /** Stage names of the winning plan(s), outermost first. */
+  readonly stages: readonly string[];
+  /** Index names the winning plan scans (`_id_` for an id lookup). */
+  readonly indexes: readonly string[];
+  /** From the first `executionStats` block; `undefined` under `queryPlanner` verbosity. */
+  readonly docsExamined: number | undefined;
+  readonly keysExamined: number | undefined;
+  readonly returned: number | undefined;
+}
+interface IndexServedOptions {
+  /** Every one of these must be scanned. */
+  readonly index?: string | readonly string[];
+  /** Every one of these stages must appear — e.g. `OR` for a `$or` served arm by arm. */
+  readonly stages?: readonly string[];
+  /** Ceiling on `totalDocsExamined`; requires `executionStats` verbosity. */
+  readonly maxDocsExamined?: number;
+}
+declare function summarizeExplain(explain: unknown): ExplainSummary;
+declare function assertIndexServed(explain: unknown, options?: IndexServedOptions): ExplainSummary;
+//#endregion
+export { ExplainSummary, IndexServedOptions, assertIndexServed, summarizeExplain };

package/dist/mongo-explain.mjs

@@ -0,0 +1,67 @@
+//#region src/mongo-explain.ts
+/** Keys whose subtree is a rejected alternative or a query predicate — never plan structure. */
+const SKIPPED = /* @__PURE__ */ new Set([
+	"rejectedPlans",
+	"allPlansExecution",
+	"command",
+	"parsedQuery",
+	"filter",
+	"slotBasedPlan"
+]);
+const ID_LOOKUPS = /* @__PURE__ */ new Set(["IDHACK", "EXPRESS_IDHACK"]);
+function summarizeExplain(explain) {
+	const stages = [];
+	const indexes = [];
+	let stats;
+	const walk = (node, inPlan) => {
+		if (Array.isArray(node)) {
+			for (const item of node) walk(item, inPlan);
+			return;
+		}
+		if (!isRecord(node)) return;
+		if (inPlan && typeof node.stage === "string") {
+			stages.push(node.stage);
+			if (typeof node.indexName === "string") indexes.push(node.indexName);
+			else if (ID_LOOKUPS.has(node.stage)) indexes.push("_id_");
+		}
+		for (const [key, value] of Object.entries(node)) {
+			if (SKIPPED.has(key)) continue;
+			if (key === "executionStats" && isRecord(value) && typeof value.totalDocsExamined === "number") stats ??= value;
+			walk(value, inPlan || key === "winningPlan");
+		}
+	};
+	walk(explain, false);
+	return {
+		stages,
+		indexes: [...new Set(indexes)],
+		docsExamined: numberOr(stats?.totalDocsExamined),
+		keysExamined: numberOr(stats?.totalKeysExamined),
+		returned: numberOr(stats?.nReturned)
+	};
+}
+function assertIndexServed(explain, options = {}) {
+	const plan = summarizeExplain(explain);
+	const fail = (msg) => {
+		throw new Error(`[arc-testkit] assertIndexServed: ${msg} — plan [${plan.stages.join(" > ")}], indexes [${plan.indexes.join(", ")}]`);
+	};
+	if (plan.stages.length === 0) fail("no winning plan found — pass the result of explain()");
+	if (plan.stages.includes("COLLSCAN")) fail("the plan scans the collection");
+	if (plan.indexes.length === 0) fail("the plan scans no index — is the collection empty or missing?");
+	const unused = (typeof options.index === "string" ? [options.index] : options.index ?? []).filter((i) => !plan.indexes.includes(i));
+	if (unused.length > 0) fail(`index ${unused.map((i) => `"${i}"`).join(", ")} is not scanned`);
+	const absent = (options.stages ?? []).filter((s) => !plan.stages.includes(s));
+	if (absent.length > 0) fail(`stage ${absent.join(", ")} is not in the plan`);
+	if (options.maxDocsExamined !== void 0) {
+		if (plan.docsExamined === void 0) fail("maxDocsExamined needs explain('executionStats')");
+		else if (plan.docsExamined > options.maxDocsExamined) fail(`examined ${plan.docsExamined} documents, ceiling ${options.maxDocsExamined}`);
+	}
+	return plan;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function numberOr(value) {
+	return typeof value === "number" ? value : void 0;
+}
+//#endregion
+export { assertIndexServed, summarizeExplain };

package/dist/mongo.d.mts

@@ -0,0 +1,87 @@
+import { TestServerProvider } from "./pool.mjs";
+import { Connection } from "mongoose";
+//#region src/mongo.d.ts
+/** WiredTiger cache per server, in GB. 0.25 is mongod's own floor. */
+declare function cacheSizeGB(): number;
+/** mongod CLI args that bound a test server's footprint. */
+declare function mongodMemoryArgs(): string[];
+/**
+ * Worker count bounded by cores AND memory.
+ *
+ * Cores alone is the trap: a 28-core box still has 32 GB, and a worker costs an
+ * app plus every server it holds live. `envVar` lets a host keep its existing
+ * override name rather than forcing a rename through every CI config.
+ */
+declare function safeWorkerCount(envVar?: string): number;
+/** How many servers the run may boot, bounded by FREE memory at call time. */
+declare function safePoolSize(requested: number): number;
+/** Splice a database name into a mongodb:// URI, preserving its query string. */
+declare function withDbName(baseUri: string, dbName: string): string;
+/**
+ * Block until every registered model's index build has finished.
+ *
+ * Mongoose's `autoIndex` fires `createIndex` in the BACKGROUND and does not
+ * await it. On a private, otherwise-idle mongod those builds always won the
+ * race against the first request, so suites asserting DB-ENFORCED constraints
+ * ("a second active shift on one register → 409", "exactly one winner of the
+ * allocation race") passed on luck. Pool the server under N parallel workers
+ * and the builds queue — and those same suites flake.
+ *
+ * The connection is injectable because a suite may hold one that is not
+ * mongoose's default. That parameter existed in one of the two forks of this
+ * function and not the other; the fail-loud note below existed in the other and
+ * not the one. This is the union.
+ *
+ * Deliberately NOT `.catch(() => undefined)`. Swallowing defeats the point: a
+ * unique index that failed to build leaves the suite asserting a constraint
+ * that does not exist, and it would pass for the wrong reason — precisely the
+ * failure this function was added to remove.
+ */
+declare function awaitIndexBuilds(connection?: {
+  readyState: number;
+  models: Record<string, {
+    init(): Promise<unknown>;
+  }>;
+}): Promise<void>;
+/** The subset of the mongoose module this adapter uses. */
+interface MongooseLike {
+  connection: {
+    readyState: number;
+    models: Record<string, {
+      init(): Promise<unknown>;
+    }>;
+    dropDatabase(): Promise<unknown>;
+    deleteModel(filter: RegExp): unknown;
+  };
+  connect(uri: string): Promise<unknown>;
+  disconnect(): Promise<unknown>;
+}
+interface MongoServerProviderOptions {
+  /** Extra mongod args, appended after the memory bounds. */
+  readonly args?: readonly string[];
+  /** Await index builds after each lease connects. Default true — see above. */
+  readonly awaitIndexes?: boolean;
+  /**
+   * The mongoose instance to bind. Default: `await import("mongoose")`.
+   *
+   * INJECT IT when the caller might resolve a different copy than this package
+   * does. Models are registered on a mongoose instance, so a lease that
+   * connects instance A while the code under test registers on instance B
+   * yields a connection with no models on it — and the failure surfaces later,
+   * as an empty collection or a missing index, never as "wrong mongoose".
+   *
+   * A workspace that hoists exactly one copy is fine on the default; one that
+   * lets packages resolve their own is not, and cannot tell from the outside.
+   */
+  readonly mongoose?: MongooseLike;
+}
+/**
+ * The Mongo `TestServerProvider`.
+ *
+ * `transactional` is a 1-node replica set: the smallest shape that supports
+ * transactions, and a strict superset of a standalone. That is what lets the
+ * pool serve both kinds from one process when sharing is on.
+ */
+declare function mongoServerProvider(options?: MongoServerProviderOptions): TestServerProvider<Connection>;
+//#endregion
+export { MongoServerProviderOptions, MongooseLike, awaitIndexBuilds, cacheSizeGB, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, withDbName };

package/dist/mongo.mjs

@@ -0,0 +1,229 @@
+import { cpus, freemem, totalmem } from "node:os";
+//#region src/mongo.ts
+/**
+* `@classytic/arc-testkit/mongo` — the Mongo adapter for the driver-agnostic pool.
+*
+* Implements `TestServerProvider` in two methods and owns the one thing that is
+* genuinely Mongo-specific: how a mongod is bounded, started, and how an
+* isolated database is minted and dropped on it.
+*
+* ## The memory numbers are not arbitrary
+*
+* mongod sizes its WiredTiger cache from HOST RAM — `max(256MB, 50% of
+* (RAM - 1GB))` — so EVERY server believes it may take half the machine. It
+* does not reserve that up front (capping changes idle footprint by ~3%), but
+* it grows into it under load, which is exactly what a test run is. With N
+* workers each holding servers live, the run is bounded by memory long before
+* it is bounded by cores.
+*
+* Measured on one fleet's heaviest project: 10 workers → 32 mongods, box at
+* 29.6/31.7 GB. 4 workers → 16 mongods, 22.6 GB, same tests passing.
+*
+* That measurement lived in two hand-synced copies in two repos, with a comment
+* asking future readers to keep them in step. They diverged by 118 lines. It
+* lives here now because a number nobody can re-derive is exactly the kind of
+* thing that must have ONE home.
+*/
+/** WiredTiger cache per server, in GB. 0.25 is mongod's own floor. */
+function cacheSizeGB() {
+	const raw = Number(process.env.TEST_MONGO_CACHE_GB);
+	return Number.isFinite(raw) && raw >= .25 ? raw : .25;
+}
+/** mongod CLI args that bound a test server's footprint. */
+function mongodMemoryArgs() {
+	return [
+		"--wiredTigerCacheSizeGB",
+		String(cacheSizeGB()),
+		"--setParameter",
+		"diagnosticDataCollectionEnabled=false"
+	];
+}
+/**
+* Worker count bounded by cores AND memory.
+*
+* Cores alone is the trap: a 28-core box still has 32 GB, and a worker costs an
+* app plus every server it holds live. `envVar` lets a host keep its existing
+* override name rather than forcing a rename through every CI config.
+*/
+function safeWorkerCount(envVar = "ARC_TEST_WORKERS") {
+	const explicit = Number(process.env[envVar]);
+	if (Number.isFinite(explicit) && explicit >= 1) return Math.trunc(explicit);
+	const byCores = Math.min(10, Math.max(2, cpus().length - 2));
+	const byMemory = Math.floor(totalmem() / 1024 ** 3 * .25 / 1.5);
+	return Math.max(2, Math.min(byCores, byMemory || byCores));
+}
+/** How many servers the run may boot, bounded by FREE memory at call time. */
+function safePoolSize(requested) {
+	const perServerGB = cacheSizeGB() + .15;
+	const budgetGB = freemem() / 1024 ** 3 * .5;
+	const affordable = Math.floor(budgetGB / perServerGB);
+	return Math.max(1, Math.min(requested, affordable || 1));
+}
+/** Splice a database name into a mongodb:// URI, preserving its query string. */
+function withDbName(baseUri, dbName) {
+	const q = baseUri.indexOf("?");
+	const query = q === -1 ? "" : baseUri.slice(q);
+	let head = q === -1 ? baseUri : baseUri.slice(0, q);
+	const schemeEnd = head.indexOf("://") + 3;
+	const slash = head.indexOf("/", schemeEnd);
+	if (slash !== -1) head = head.slice(0, slash);
+	return `${head}/${dbName}${query}`;
+}
+let mmsCache;
+/**
+* Load `mongodb-memory-server` by RESOLVED PATH, not by specifier.
+*
+* Consumers commonly alias the bare specifier to a shim (to keep a binary
+* download out of a lane that never starts a server). Importing it by name
+* from here would resolve back through that alias and recurse.
+*/
+function loadMms() {
+	mmsCache ??= (async () => {
+		const { createRequire } = await import("node:module");
+		const { pathToFileURL } = await import("node:url");
+		const mod = await import(pathToFileURL(createRequire(import.meta.url).resolve("mongodb-memory-server")).href);
+		return mod.MongoMemoryServer ? mod : mod.default;
+	})();
+	return mmsCache;
+}
+/**
+* Block until every registered model's index build has finished.
+*
+* Mongoose's `autoIndex` fires `createIndex` in the BACKGROUND and does not
+* await it. On a private, otherwise-idle mongod those builds always won the
+* race against the first request, so suites asserting DB-ENFORCED constraints
+* ("a second active shift on one register → 409", "exactly one winner of the
+* allocation race") passed on luck. Pool the server under N parallel workers
+* and the builds queue — and those same suites flake.
+*
+* The connection is injectable because a suite may hold one that is not
+* mongoose's default. That parameter existed in one of the two forks of this
+* function and not the other; the fail-loud note below existed in the other and
+* not the one. This is the union.
+*
+* Deliberately NOT `.catch(() => undefined)`. Swallowing defeats the point: a
+* unique index that failed to build leaves the suite asserting a constraint
+* that does not exist, and it would pass for the wrong reason — precisely the
+* failure this function was added to remove.
+*/
+async function awaitIndexBuilds(connection) {
+	const conn = connection ?? (await import("mongoose")).default.connection;
+	if (conn.readyState !== 1) return;
+	const models = Object.values(conn.models);
+	await Promise.all(models.map((model) => model.init()));
+}
+/**
+* The Mongo `TestServerProvider`.
+*
+* `transactional` is a 1-node replica set: the smallest shape that supports
+* transactions, and a strict superset of a standalone. That is what lets the
+* pool serve both kinds from one process when sharing is on.
+*/
+function mongoServerProvider(options = {}) {
+	const args = [...mongodMemoryArgs(), ...options.args ?? []];
+	const awaitIndexes = options.awaitIndexes ?? true;
+	return {
+		name: "mongodb-memory-server",
+		async start(kind, opts) {
+			const mms = await loadMms();
+			/**
+			* A caller-supplied `createOptions` REPLACES the defaults rather than
+			* merging with them, because the suites that pass one are flipping fail
+			* points and know exactly what mongod they need — merging would silently
+			* re-impose args they deliberately omitted.
+			*
+			* The memory cap is on the default path, and that matters MORE here, not
+			* less: this is what a bare `vitest <file>` and every `forcePrivate` suite
+			* gets, so leaving it uncapped reintroduces mongod's
+			* half-the-machine cache default exactly where nobody is watching.
+			*/
+			const create = opts?.createOptions;
+			const server = kind === "transactional" ? await mms.MongoMemoryReplSet.create(create ?? { replSet: {
+				count: 1,
+				storageEngine: "wiredTiger",
+				args
+			} }) : await mms.MongoMemoryServer.create(create ?? { instance: { args } });
+			return {
+				uri: server.getUri(),
+				stop: async () => {
+					await server.stop();
+				}
+			};
+		},
+		/**
+		* Wait for index builds — AFTER the app has booted and registered its models.
+		*
+		* Doing this inside `lease()` waits for an EMPTY model registry and returns
+		* instantly. That is indistinguishable from working right up until a suite
+		* asserting a DB-enforced constraint flakes: a unique index missing so a
+		* duplicate returns 201 instead of 409, an allocation race returning
+		* [200, 200] instead of [200, 409], a `$geoNear` query with no index.
+		* All three happened.
+		*/
+		async afterBoot() {
+			if (!awaitIndexes) return;
+			await awaitIndexBuilds((options.mongoose ?? (await import("mongoose")).default).connection);
+		},
+		/** The lease's URI, without connecting anything. */
+		namespaceUri(server, namespace) {
+			return withDbName(server.uri, namespace);
+		},
+		/**
+		* Drop a namespace leased via `namespaceUri`.
+		*
+		* Opens a throwaway connection to do it, because by definition nothing here
+		* holds one — the caller owned the connection and has already closed it.
+		* A failed drop leaks ONE database on an ephemeral server and is never a
+		* test failure: isolation is guaranteed by the unique name, not by the drop.
+		*/
+		async dropNamespace(server, namespace) {
+			const mod = (await import("mongoose")).default;
+			try {
+				const conn = await mod.createConnection(withDbName(server.uri, namespace)).asPromise();
+				await conn.dropDatabase().catch(() => void 0);
+				await conn.close().catch(() => void 0);
+			} catch {}
+		},
+		/**
+		* Binds mongoose's DEFAULT connection, deliberately — NOT `createConnection`.
+		*
+		* Kernels register their models against the default connection, so a lease
+		* that opened a side connection would hand arc a handle with no models on
+		* it. Nothing would throw; the suite would simply query empty collections.
+		* This mirrors arc's own built-in `mongoMemoryDatabase` where it matters.
+		*/
+		async lease(server, namespace) {
+			const mongoose = options.mongoose ?? (await import("mongoose")).default;
+			const uri = withDbName(server.uri, namespace);
+			if (mongoose.connection.readyState !== 0) await mongoose.disconnect();
+			await mongoose.connect(uri);
+			/**
+			* Clear the model registry for this boot.
+			*
+			* mongoose LOCKS a schema on first `model()`, and the registry outlives a
+			* single boot within one file — so a second boot in the same test file
+			* dies on "model X already exists", or worse, silently reuses the first
+			* boot's schema.
+			*/
+			mongoose.connection.deleteModel(/.*/);
+			return {
+				uri,
+				connection: mongoose.connection,
+				/**
+				* DROP the database, then disconnect. Dropping is what preserves the
+				* isolation contract a private server gave for free: a suite asserting
+				* on empty collections must still see an empty world. The SERVER keeps
+				* running — stopping it here would break every other lease on it.
+				*/
+				teardown: async () => {
+					if (mongoose.connection.readyState !== 0) {
+						await mongoose.connection.dropDatabase().catch(() => void 0);
+						await mongoose.disconnect().catch(() => void 0);
+					}
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { awaitIndexBuilds, cacheSizeGB, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, withDbName };

package/dist/pool.d.mts

@@ -0,0 +1,190 @@
+import { TestDatabase, TestDatabaseFactory } from "@classytic/arc/testing";
+//#region src/pool.d.ts
+/** Which server shape a suite needs. */
+type ServerKind = "standalone" | "transactional";
+/** A running server the pool may hand out namespaces on. */
+interface TestServerHandle {
+  /** Base connection string, WITHOUT a namespace selected. */
+  readonly uri: string;
+  stop(): Promise<void>;
+}
+/**
+ * What a driver must supply. Two methods, deliberately.
+ *
+ * Anything a third method would carry (naming, isolation, refcounts, handshake)
+ * is the same in every driver, so putting it here would duplicate it per driver
+ * — which is precisely the failure this module exists to end.
+ */
+interface TestServerProvider<TConn> {
+  /** Human name, used only in diagnostics. */
+  readonly name: string;
+  /**
+   * Boot the expensive server. Called AT MOST ONCE per kind per process, and
+   * only when a suite actually leases — never eagerly.
+   */
+  start(kind: ServerKind, opts?: {
+    createOptions?: unknown;
+  }): Promise<TestServerHandle>;
+  /**
+   * Hand out an isolated namespace on an already-running server, CONNECTED.
+   *
+   * MUST be cheap — a name mint, not a process spawn. The returned
+   * `teardown()` MUST drop only that namespace and MUST NOT stop the server.
+   */
+  lease(server: TestServerHandle, namespace: string): Promise<TestDatabase<TConn>>;
+  /**
+   * Optional: the same isolated namespace as a URI, WITHOUT connecting.
+   *
+   * For callers that own their own connection — a suite handed a URI to connect
+   * itself, or a shim standing in for the driver's own server class. Routing
+   * those through `lease()` would bind a connection they never asked for and
+   * then have them connect a second time over it.
+   *
+   * URI composition is genuinely driver-specific (a database path segment in
+   * Mongo, a `search_path` in Postgres, a file path in SQLite), which is why it
+   * is here and not in the pool. Optional because a driver with no URI concept
+   * can legitimately not offer it.
+   */
+  namespaceUri?(server: TestServerHandle, namespace: string): string;
+  /** Optional: drop a namespace leased via `namespaceUri`. */
+  dropNamespace?(server: TestServerHandle, namespace: string): Promise<void>;
+  /**
+   * Optional: settle driver work that can only happen AFTER the app has booted.
+   *
+   * `lease()` runs before arc constructs anything, so at that point the app has
+   * registered no models, no schemas and no indexes — any "wait for the schema
+   * to be ready" work done there waits for an empty set and returns instantly.
+   *
+   * That is not a hypothetical ordering nicety. Doing Mongo's index-build wait
+   * inside `lease()` looked right and silently did nothing: three suites that
+   * assert DB-ENFORCED constraints went flaky — a unique index missing so a
+   * duplicate returned 201 instead of 409, an allocation race returning
+   * [200, 200] instead of [200, 409], and a `$geoNear` query failing outright
+   * for want of its index. On a private idle server those builds always won the
+   * race; pooled under N workers they queue.
+   *
+   * Called by `withPool` after the boot function resolves.
+   */
+  afterBoot?(): Promise<void>;
+}
+interface TestDatabasePoolOptions {
+  /**
+   * Env-var prefix for the cross-worker handshake. Two runs with different
+   * prefixes (a spine run and a host run) can share a machine without either
+   * adopting the other's servers.
+   */
+  readonly envPrefix?: string;
+  /**
+   * Which kinds to serve from ONE server.
+   *
+   * Default `true`: a single transactional server (e.g. a 1-node replica set)
+   * answers both kinds, because it is a strict superset of a standalone. This
+   * halves resident memory, and memory — not CPU — is what bounds a large test
+   * run: a worker costs an app plus every server it keeps live.
+   *
+   * Set `false` to boot a genuinely separate standalone. The ONLY reason to is
+   * enforcement: on a real standalone, a suite that quietly requires
+   * transactions FAILS instead of passing on a capability it never declared.
+   * That is a real property — but it costs an entire server process, and once
+   * lanes are enforced the same fact is better stated by a declaration than
+   * bought with RAM.
+   */
+  readonly shareTransactionalServer?: boolean;
+  /**
+   * Stop servers once the last lease is released. Off by default: a batch run
+   * ends anyway and `globalSetup`'s teardown handles it, while an early stop
+   * between two suites would pay the boot cost again. Worth enabling for watch
+   * mode, where idle periods are long and frequent.
+   */
+  readonly stopWhenIdle?: boolean;
+  /**
+   * How many servers to run PER KIND. Default 1.
+   *
+   * One shared server is a bottleneck once enough workers hammer it: every
+   * lease's writes, index builds and drops queue behind every other worker's.
+   * N servers spread that load, and `slotOf` pins each worker to one of them so
+   * a given worker's sequential files never contend with each other either.
+   *
+   * Size it against MEMORY, not cores — see `safePoolSize` in the mongo adapter.
+   * A worker costs an app plus every server it holds live, and mongod sizes its
+   * cache from host RAM, so the run hits a memory wall long before a CPU one.
+   */
+  readonly poolSize?: number;
+  /**
+   * Which pool slot this process owns. Default: the vitest worker id.
+   *
+   * `VITEST_POOL_ID` is 1-based and stable for a worker's lifetime, so every
+   * file that worker runs lands on the same server. Outside a worker (a script,
+   * a single-process run) it falls back to slot 0, which is correct: one
+   * process, one server.
+   */
+  readonly slotOf?: (poolSize: number) => number;
+  /**
+   * Server kinds `globalSetup.setup()` starts EAGERLY and publishes.
+   *
+   * This is not an optimisation — it is what makes pooling work at all across
+   * more than one process, and getting it wrong is expensive in a way that
+   * still passes.
+   *
+   * The memo inside this module is per-PROCESS. vitest runs N worker processes,
+   * so with nothing pre-booted every worker finds no published URI, boots its
+   * own server, and the run ends up with N of them instead of one. Measured
+   * when this defaulted to empty: **173 mongod processes at peak**, the run
+   * ~2x slower, and one pass going red from resource exhaustion. Every test
+   * still passed on the run that completed — the only symptom was the machine.
+   *
+   * `setup()` runs in the vitest MAIN process before any worker starts, so a
+   * server started there can be published on the environment that every worker
+   * inherits. That is the only point at which one server can be guaranteed.
+   *
+   * Default `["transactional"]`: one server, a strict superset of a standalone,
+   * serving both kinds. Pass `[]` for a genuinely lazy pool — correct only when
+   * the run is single-process, or when nothing will lease.
+   */
+  readonly preboot?: readonly ServerKind[];
+  /** Escape hatch: force per-suite private servers (the unpooled behaviour). */
+  readonly disabled?: boolean;
+}
+interface TestDatabasePool<TConn> {
+  /** Hand to `bootModuleApp({ database })`. */
+  readonly factory: TestDatabaseFactory<TConn>;
+  /** Wrap a boot function so it defaults to the pool. */
+  withPool<TResult, TModules, TOptions extends {
+    database?: unknown;
+  }>(boot: (modules: TModules, options?: TOptions) => TResult | Promise<TResult>): (modules: TModules, options?: TOptions) => Promise<TResult>;
+  /**
+   * An isolated namespace as a URI, for a caller that owns its own connection.
+   * Throws if the driver does not implement `namespaceUri`.
+   */
+  leaseNamespace(kind?: ServerKind, opts?: {
+    exact?: boolean;
+    forcePrivate?: boolean;
+    createOptions?: unknown;
+  }): Promise<{
+    uri: string;
+    namespace: string;
+    release(): Promise<void>;
+  }>;
+  /** vitest `globalSetup` pair. Starts NOTHING; it only publishes the handshake. */
+  readonly globalSetup: {
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+  };
+  /** Diagnostics — servers actually started in THIS process. */
+  stats(): {
+    started: ServerKind[];
+    servers: number;
+    leases: number;
+    live: number;
+  };
+}
+declare function createTestDatabasePool<TConn>(provider: TestServerProvider<TConn>, options?: TestDatabasePoolOptions): TestDatabasePool<TConn>;
+/**
+ * Publish a started server so other worker PROCESSES reuse it.
+ *
+ * Only a process that owns servers calls this — typically an eager
+ * `globalSetup` in a run that prefers boot-cost-up-front over laziness.
+ */
+declare function publishPoolServers(servers: Partial<Record<ServerKind, readonly string[]>>, envPrefix?: string): void;
+//#endregion
+export { ServerKind, TestDatabasePool, TestDatabasePoolOptions, TestServerHandle, TestServerProvider, createTestDatabasePool, publishPoolServers };

package/dist/pool.mjs

@@ -0,0 +1,410 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+//#region src/pool.ts
+/**
+* `@classytic/arc-testkit/pool` — a POOLED `TestDatabaseFactory`, driver-agnostic.
+*
+* ## The gap this fills
+*
+* `@classytic/arc/testing` defines the seam and says who should fill it:
+*
+*   > Arc core never names a driver: kits ship factories (`mongoMemoryDatabase`
+*   > is the built-in default; a sqlitekit/pgkit testkit ships its own).
+*
+* Arc's built-in default provisions a SERVER PER SUITE. That is correct and
+* unsurprising for one package; across a workspace it is the dominant cost —
+* measured in one fleet at ~72 server spin-ups per run, ~0.9s to boot and up to
+* ~1.5s to stop each, plus the resident memory of every one held live at once.
+*
+* So two consumers independently built the same missing thing: boot the
+* expensive server ONCE per run, hand each suite an isolated logical namespace
+* on it. Both then drifted — measured across their five shared filenames,
+* 18 to 285 differing lines each, in BOTH directions (one grew an injectable
+* connection, the other grew a fail-loud index guard; neither got both). One of
+* them even carried the instruction "keep the two in sync". Hand-sync is not a
+* mechanism, and it did not hold.
+*
+* ## Why pooling belongs HERE and not in a driver package
+*
+* "One expensive server, many cheap isolated namespaces" is not a Mongo idea.
+* It is a schema in Postgres, a database in MySQL or Mongo, a file in SQLite.
+* Everything that is genuinely hard — laziness, the cross-worker handshake,
+* refcounted shutdown, teardown ordering, name minting that cannot collide
+* across parallel worker processes — is driver-agnostic. Only two operations
+* are not, and those are the port.
+*
+* ## The port
+*
+* ```ts
+* const pool = createTestDatabasePool(mongoServerProvider());
+* // vitest globalSetup
+* export const { setup, teardown } = pool.globalSetup;
+* // a suite
+* const boot = pool.withPool(bootModuleApp);
+* ```
+*
+* A driver implements two methods. Everything else is this module's problem.
+*/
+/**
+* A namespace name nothing else in the run can produce.
+*
+* pid + monotonic counter + randomness, because all three failure modes are
+* real: two worker PROCESSES minting concurrently, two suites in ONE process
+* minting in the same millisecond, and a pid reused by the OS across runs.
+*/
+let counter = 0;
+function mintNamespace() {
+	counter += 1;
+	return `arct${process.pid}x${counter}${randomBytes(3).toString("hex")}`;
+}
+function createTestDatabasePool(provider, options = {}) {
+	const prefix = options.envPrefix ?? "ARC_TESTKIT";
+	const shareTransactional = options.shareTransactionalServer ?? true;
+	const uriEnv = (kind) => `${prefix}_POOL_${kind.toUpperCase()}_URI`;
+	const handshakeFile = join(tmpdir(), `${prefix.toLowerCase()}-pool.json`);
+	/**
+	* Which server actually serves a kind.
+	*
+	* With sharing on, a standalone request is answered by the transactional
+	* server — a superset, so nothing a standalone can DO is lost.
+	*
+	* `exact` is for when what matters is what a standalone CANNOT do. A suite
+	* proving a path fails closed without transactions is the motivating case:
+	* hand it the shared replica set and the path succeeds, the assertion
+	* inverts, and the test now proves the opposite of its own name while still
+	* looking meaningful. (Found exactly that way — one real suite, named
+	* "REQUIRES a transaction BY DEFAULT — fails closed on standalone Mongo".)
+	*
+	* A driver shim is the other case: calling `MongoMemoryServer.create()`
+	* rather than `MongoMemoryReplSet.create()` IS the declaration.
+	*
+	* Note the asymmetry — sharing is safe for capability and unsafe for the
+	* absence of it, so `exact` defaults to false and is opted into.
+	*/
+	const resolveKind = (kind, exact = false) => exact || !shareTransactional ? kind : "transactional";
+	const poolSize = Math.max(1, Math.trunc(options.poolSize ?? 1));
+	/**
+	* Which of the `poolSize` servers this process uses.
+	*
+	* `VITEST_POOL_ID` is 1-based and stable for a worker's lifetime, so every
+	* file that worker runs lands on the SAME server: N workers spread over N
+	* servers, and one worker's sequential files never contend with each other.
+	* Anything unparseable means "not a worker" and takes slot 0 — one process,
+	* one server, which is the correct reading and not a silent default.
+	*/
+	const slotOf = options.slotOf ?? ((size) => {
+		if (size <= 1) return 0;
+		const raw = process.env.VITEST_POOL_ID ?? process.env.VITEST_WORKER_ID;
+		const n = Number(raw);
+		if (!Number.isFinite(n) || n < 1) return 0;
+		return (Math.trunc(n) - 1) % size;
+	});
+	/**
+	* In-process memo, keyed by `${resolvedKind}#${slot}`.
+	*
+	* The SLOT is part of the key, not just the kind: with a pool of N, one
+	* process may legitimately hold handles to different servers (a standalone in
+	* slot 2, a transactional in slot 2), and keying by kind alone would hand the
+	* second request the first one's server.
+	*/
+	const starting = /* @__PURE__ */ new Map();
+	const started = /* @__PURE__ */ new Map();
+	/**
+	* Private (`forcePrivate`) servers, which live outside `started` because they
+	* are deliberately not shared and not memoised.
+	*
+	* Tracked anyway so an interrupted process still stops them. They are the
+	* MOST likely to be stranded: a suite asking for one is usually a suite doing
+	* something violent enough to crash, and its `release()` then never runs.
+	* Entries are removed on release so this cannot grow into a leak of its own.
+	*/
+	const privateHandles = /* @__PURE__ */ new Set();
+	let leases = 0;
+	let live = 0;
+	function readHandshake() {
+		try {
+			return JSON.parse(readFileSync(handshakeFile, "utf8"));
+		} catch {
+			return {};
+		}
+	}
+	/**
+	* A URI published by whoever booted the server, or undefined.
+	*
+	* Env vars are the primary channel — vitest workers inherit them from the
+	* main process. The file is the fallback for pools that respawn workers with
+	* a pristine environment, which is not hypothetical: it is the difference
+	* between reusing one server and every worker booting its own.
+	*/
+	function publishedUris(kind) {
+		const fromEnv = process.env[uriEnv(kind)];
+		if (fromEnv && fromEnv.length > 0) return fromEnv.split(",").filter((u) => u.length > 0);
+		return readHandshake()[kind]?.filter((u) => u.length > 0) ?? [];
+	}
+	/**
+	* Get a running server for `kind`, booting at most one per (kind, slot).
+	*
+	* `slot` is explicit for the pre-boot path, which must start ALL of them; it
+	* is omitted everywhere else, where this process's own slot is the answer.
+	*
+	* The memo is stored BEFORE the await so two suites racing in the same worker
+	* share one boot. Storing it after would let both observe an empty map and
+	* start a server each — the exact cost this module exists to remove, and
+	* invisible because both would work.
+	*/
+	async function serverFor(kind, exact = false, slot) {
+		const resolved = resolveKind(kind, exact);
+		const published = publishedUris(resolved);
+		const width = published.length > 0 ? published.length : poolSize;
+		const index = slot ?? slotOf(width);
+		const key = `${resolved}#${index}`;
+		const existing = started.get(key);
+		if (existing) return existing;
+		const uri = published[index];
+		if (uri) {
+			const borrowed = {
+				uri,
+				stop: async () => {}
+			};
+			started.set(key, borrowed);
+			return borrowed;
+		}
+		const inflight = starting.get(key);
+		if (inflight) return inflight;
+		const boot = (async () => {
+			const handle = await provider.start(resolved);
+			started.set(key, handle);
+			hookProcessExit();
+			return handle;
+		})();
+		starting.set(key, boot);
+		try {
+			return await boot;
+		} finally {
+			starting.delete(key);
+		}
+	}
+	/** A private server nobody else can reach, stopped with its lease. */
+	async function privateServer(kind, exact, createOptions) {
+		const handle = await provider.start(resolveKind(kind, exact), { createOptions });
+		privateHandles.add(handle);
+		hookProcessExit();
+		return handle;
+	}
+	/**
+	* Stop this process's servers when it dies WITHOUT a teardown.
+	*
+	* `globalSetup.teardown()` covers the orderly path and nothing else. Ctrl-C, a
+	* CI job cancelling, an IDE stopping a run, a watchdog timeout — none of them
+	* reach it, and every one strands the whole pool. Servers are child processes
+	* with no parent-death linkage on Windows, so they simply keep running.
+	*
+	* That is not hypothetical: interrupting runs during this package's own
+	* development stranded 71, then 165, then 75 mongods, each holding its
+	* WiredTiger cache, on a 32 GB box. Nothing reported it — the next run just
+	* started on a machine with less memory than the one before.
+	*
+	* `exit` handlers must be SYNCHRONOUS, so the async `stop()` is not awaited
+	* there; it is a best-effort kill on the way out. The signal handlers get to
+	* await properly, which is the path that actually matters for Ctrl-C.
+	*/
+	let exitHooked = false;
+	function hookProcessExit() {
+		if (exitHooked) return;
+		exitHooked = true;
+		const onSignal = (signal) => {
+			stopAll().finally(() => {
+				process.removeListener(signal, onSignal);
+				process.kill(process.pid, signal);
+			});
+		};
+		for (const signal of [
+			"SIGINT",
+			"SIGTERM",
+			"SIGHUP",
+			"SIGBREAK"
+		]) process.once(signal, onSignal);
+		process.once("exit", () => {
+			for (const handle of started.values()) handle.stop();
+			for (const handle of privateHandles) handle.stop();
+		});
+	}
+	async function stopAll() {
+		const handles = [...started.values(), ...privateHandles];
+		started.clear();
+		starting.clear();
+		privateHandles.clear();
+		await Promise.all(handles.map((h) => h.stop().catch(() => void 0)));
+	}
+	const factory = async (opts) => {
+		const req = opts;
+		const kind = req?.replset === true ? "transactional" : "standalone";
+		/**
+		* `exact` rides on the options bag rather than a separate factory, because
+		* arc owns the `database` seam's call site: a suite passes a factory and
+		* arc invokes it. A second factory could not be selected from there.
+		*/
+		const exact = req?.exact === true;
+		/**
+		* `forcePrivate` — a server nobody else can reach, for THIS lease.
+		*
+		* Not a performance escape hatch: some suites mutate SERVER-GLOBAL state
+		* (fail points, `setParameter`, a forced stepdown) to prove behaviour under
+		* failure. On a shared server that corrupts every other worker's run, and
+		* the damage surfaces as unrelated suites failing for reasons that make no
+		* sense where they land.
+		*
+		* Distinct from `disabled`, which turns pooling off for the WHOLE pool.
+		* This is per-lease, so one hostile suite does not deoptimise the run.
+		*/
+		const forcePrivate = req?.forcePrivate === true;
+		/**
+		* Driver-specific server options for a PRIVATE lease — often the whole
+		* reason a suite asks for one. A fail-point suite needs its own
+		* `setParameter`, and that is exactly the kind of setting that must never
+		* reach a shared server. Ignored on the pooled path, deliberately: honouring
+		* it there would let one suite silently reconfigure every other worker's.
+		*/
+		const createOptions = req?.createOptions;
+		if (options.disabled || forcePrivate) {
+			const server = await privateServer(kind, exact, createOptions);
+			const db = await provider.lease(server, mintNamespace());
+			return {
+				...db,
+				teardown: async () => {
+					await db.teardown().catch(() => void 0);
+					privateHandles.delete(server);
+					await server.stop().catch(() => void 0);
+				}
+			};
+		}
+		const server = await serverFor(kind, exact);
+		const db = await provider.lease(server, mintNamespace());
+		leases += 1;
+		live += 1;
+		let released = false;
+		return {
+			...db,
+			/**
+			* Idempotent: arc calls teardown on the boot-failure path AND on close,
+			* and a double-drop would surface as a confusing driver error on a run
+			* that had already gone red for an unrelated reason.
+			*/
+			teardown: async () => {
+				if (released) return;
+				released = true;
+				live -= 1;
+				await db.teardown();
+				if (options.stopWhenIdle && live === 0) await stopAll();
+			}
+		};
+	};
+	return {
+		factory,
+		async leaseNamespace(kind = "standalone", opts) {
+			if (!provider.namespaceUri) throw new Error(`[arc-testkit] provider "${provider.name}" does not implement \`namespaceUri\`, so it cannot hand out an unconnected namespace. Use \`factory\` (which connects) instead.`);
+			/**
+			* `forcePrivate` applies here too, and for the same reason as on
+			* `factory`: this is the path a driver SHIM takes, and a suite reaching
+			* for the driver's own server class is exactly the kind that flips
+			* server-global state.
+			*/
+			const isPrivate = options.disabled === true || opts?.forcePrivate === true;
+			const server = isPrivate ? await privateServer(kind, opts?.exact ?? false, opts?.createOptions) : await serverFor(kind, opts?.exact);
+			const namespace = mintNamespace();
+			leases += 1;
+			live += 1;
+			let released = false;
+			return {
+				uri: provider.namespaceUri(server, namespace),
+				namespace,
+				release: async () => {
+					if (released) return;
+					released = true;
+					live -= 1;
+					if (isPrivate) {
+						privateHandles.delete(server);
+						await server.stop().catch(() => void 0);
+						return;
+					}
+					await provider.dropNamespace?.(server, namespace);
+					if (options.stopWhenIdle && live === 0) await stopAll();
+				}
+			};
+		},
+		withPool(boot) {
+			return async (modules, options_) => {
+				const app = await boot(modules, {
+					database: factory,
+					...options_ ?? {}
+				});
+				await provider.afterBoot?.();
+				return app;
+			};
+		},
+		globalSetup: {
+			/**
+			* Clear stale state, then pre-boot and PUBLISH the shared servers.
+			*
+			* The clear comes first: a handshake file left by a killed run points at
+			* a dead server, and the connection error that produces surfaces deep
+			* inside a suite as a broken test rather than as stale state.
+			*
+			* The pre-boot is the load-bearing part. See `preboot` — worker processes
+			* cannot share an in-process memo, so a server not started HERE, in the
+			* main process, becomes one server PER WORKER.
+			*/
+			async setup() {
+				if (existsSync(handshakeFile)) rmSync(handshakeFile, { force: true });
+				if (options.disabled) return;
+				const kinds = options.preboot ?? ["transactional"];
+				if (kinds.length === 0) return;
+				const plan = kinds.flatMap((kind) => Array.from({ length: poolSize }, (_, slot) => ({
+					kind,
+					slot
+				})));
+				const handles = await Promise.all(plan.map((p) => serverFor(p.kind, true, p.slot)));
+				const published = {};
+				plan.forEach((p, i) => {
+					const uri = handles[i]?.uri;
+					if (!uri) return;
+					if (!published[p.kind]) published[p.kind] = [];
+					published[p.kind][p.slot] = uri;
+					if (p.kind === "transactional" && shareTransactional) {
+						if (!published.standalone) published.standalone = [];
+						published.standalone[p.slot] = uri;
+					}
+				});
+				publishPoolServers(published, prefix);
+			},
+			async teardown() {
+				rmSync(handshakeFile, { force: true });
+				await stopAll();
+			}
+		},
+		stats: () => ({
+			started: [...new Set([...started.keys()].map((k) => k.split("#")[0]))],
+			servers: started.size,
+			leases,
+			live
+		})
+	};
+}
+/**
+* Publish a started server so other worker PROCESSES reuse it.
+*
+* Only a process that owns servers calls this — typically an eager
+* `globalSetup` in a run that prefers boot-cost-up-front over laziness.
+*/
+function publishPoolServers(servers, envPrefix = "ARC_TESTKIT") {
+	const file = join(tmpdir(), `${envPrefix.toLowerCase()}-pool.json`);
+	for (const [kind, uris] of Object.entries(servers)) {
+		const list = (uris ?? []).filter(Boolean);
+		if (list.length > 0) process.env[`${envPrefix}_POOL_${kind.toUpperCase()}_URI`] = list.join(",");
+	}
+	writeFileSync(file, JSON.stringify(servers));
+}
+//#endregion
+export { createTestDatabasePool, publishPoolServers };

package/package.json

@@ -1,12 +1,28 @@
 {
   "name": "@classytic/arc-testkit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Boot a real @classytic/arc app around the module(s) under test on in-memory MongoDB — the ecosystem test harness. Thin Mongo-typed wrapper over @classytic/arc/testing (arc 2.22+). If your arc module boots green here, it composes into any arc host.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
+    },
+    "./pool": {
+      "types": "./dist/pool.d.mts",
+      "default": "./dist/pool.mjs"
+    },
+    "./mongo": {
+      "types": "./dist/mongo.d.mts",
+      "default": "./dist/mongo.mjs"
+    },
+    "./mongo-commands": {
+      "types": "./dist/mongo-commands.d.mts",
+      "default": "./dist/mongo-commands.mjs"
+    },
+    "./mongo-explain": {
+      "types": "./dist/mongo-explain.d.mts",
+      "default": "./dist/mongo-explain.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -33,7 +49,7 @@
     "mongodb-memory-server": ">=10.0.0"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.33.0",
+    "@classytic/arc": ">=2.43.0",
     "mongoose": ">=9.4.1"
   },
   "keywords": [