@stratal/framework 0.0.27 → 0.1.0

package/dist/database/index.mjs

@@ -1,12 +1,13 @@
-import { t as __decorate } from "../decorate-B7nr7eBl.mjs";
-import { DI_TOKENS, Transient, inject, lazy } from "stratal/di";
+import { t as __decorate } from "../decorate-RQD1h28J.mjs";
+import { DI_TOKENS, Request, inject, lazy } from "stratal/di";
 import { Module } from "stratal/module";
-import { DatabaseError, HttpException } from "stratal/errors";
+import { ApplicationError, DatabaseError, HttpException } from "stratal/errors";
 import { I18nModule } from "stratal/i18n";
 import { Command } from "stratal/quarry";
 import { ORMError, ORMErrorReason, ZenStackClient } from "@zenstackhq/orm";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { withZodI18n, z } from "stratal/validation";
+import { array, custom, looseObject, minLength, object, optional, refine, string } from "zod/mini";
+import { withZodI18n } from "stratal/validation";
 //#region src/database/commands/zenstack.command.ts
 /**
 * Base command for ZenStack CLI wrappers.
@@ -123,6 +124,259 @@ var MigrateStatusCommand = class extends ZenStackCommand {
 	}
 };
 //#endregion
+//#region src/database/errors/cursor-model-unavailable.error.ts
+/**
+* Raised when `db.$cursor.<model>` cannot reach a model delegate on the client
+* it was built for — the schema declares the model, the client does not answer
+* for it.
+*
+* This is a **programming error**, not bad input: the reader is built from the
+* schema's own model list, so reaching it means the client and the schema it was
+* given have come apart — a model sliced out of the client's options, or a
+* hand-assembled client. No request recovers from it and no retry helps. It
+* deliberately carries no HTTP status, so it is never mistaken for something the
+* client sent wrong.
+*
+* `model` names the client key at fault, and is reported to observability so the
+* raise site stays distinguishable without matching on message text.
+*/
+var CursorModelUnavailableError = class extends ApplicationError {
+	model;
+	constructor(model) {
+		super(`[stratal:database] $cursor cannot reach the "${model}" model on this client. The schema declares it, so the client was built with a different schema or with this model sliced out.`);
+		this.model = model;
+	}
+	reportContext() {
+		return { model: this.model };
+	}
+};
+//#endregion
+//#region src/database/errors/cursor-ordering.error.ts
+/**
+* Raised when a `$cursor` read is asked for an ordering it cannot address a row
+* in: no `orderBy`, a clause with no `asc`/`desc` direction, an ordering
+* without the unique column that breaks ties, or an ordering column that is
+* absent from the returned row or null on it.
+*
+* This is a **programming error**, not bad input — no request can recover from
+* it and no retry helps, because the query as written cannot produce a stable
+* position. Handlers should let it surface as a `500` and report it; the fix is
+* always in the caller's `orderBy`, `uniqueBy` or `select`. It deliberately
+* carries no HTTP status, so it is never mistaken for something the client sent
+* wrong.
+*
+* `field` names the ordering column at fault where one is identifiable, and is
+* reported to observability so the raise sites stay distinguishable without
+* matching on message text.
+*/
+var CursorOrderingError = class extends ApplicationError {
+	field;
+	constructor(message, field) {
+		super(message);
+		this.field = field;
+	}
+	reportContext() {
+		return this.field === void 0 ? void 0 : { field: this.field };
+	}
+};
+//#endregion
+//#region src/database/errors/malformed-cursor.error.ts
+/**
+* Raised when a pagination cursor cannot be read: it is not the base64url
+* payload `$cursor` mints, or it decodes to something that is not a cursor.
+*
+* This is **bad input**, not a broken query. A cursor travels in a query string,
+* so a truncated link, a hand-edited URL, or one minted by an older build all
+* land here, and the request itself is still answerable. It carries its own
+* `400`, so a handler lets it surface rather than catching it to serve the
+* first page — the same refusal any other damaged parameter gets.
+*/
+var MalformedCursorError = class extends HttpException {
+	constructor(cause) {
+		super(400, "[stratal:database] Malformed pagination cursor.", cause);
+	}
+};
+//#endregion
+//#region src/database/pagination/cursor.ts
+const CURSOR_DIRECTION_KEY = "_next";
+/**
+* base64url, so a cursor survives a query string without escaping.
+*
+* The UTF-8 round trip is load-bearing, not ceremony: `btoa` accepts only
+* Latin-1, and `JSON.stringify` leaves non-ASCII characters as they are. An
+* ordering column is whatever the caller ordered by — a `title`, a `name`, a
+* `slug` — so one row whose value carries CJK, Cyrillic or an emoji would throw
+* `DOMException` while every ASCII row encoded fine. The first page would still
+* answer, because it mints no cursor; the 500 would land on the follow-up.
+*/
+function base64UrlEncode(input) {
+	const bytes = new TextEncoder().encode(input);
+	const binary = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("");
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(input) {
+	const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+	const binary = atob(padded.padEnd(padded.length + (4 - padded.length % 4) % 4, "="));
+	return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+}
+/**
+* Encodes the ordering values of a row plus the direction it points.
+*
+* The whole ordering tuple travels, not a row id, so the cursor still resolves
+* after the row it was built from is deleted — which is the case cursors are
+* for. The direction rides along because a caller sends every cursor under one
+* query parameter name and nothing else distinguishes forward from backward.
+*/
+function encodeCursor(values, direction) {
+	return base64UrlEncode(JSON.stringify({
+		...values,
+		[CURSOR_DIRECTION_KEY]: direction === "next"
+	}));
+}
+/** Reads a cursor minted by {@link encodeCursor}. Throws on anything else. */
+function decodeCursor(cursor) {
+	let parsed;
+	try {
+		parsed = JSON.parse(base64UrlDecode(cursor));
+	} catch (cause) {
+		throw new MalformedCursorError(cause);
+	}
+	if (typeof parsed !== "object" || parsed === null || !(CURSOR_DIRECTION_KEY in parsed)) throw new MalformedCursorError();
+	const { [CURSOR_DIRECTION_KEY]: pointsToNext, ...values } = parsed;
+	return {
+		values,
+		direction: pointsToNext ? "next" : "prev"
+	};
+}
+function normalizeOrderBy(orderBy) {
+	return (Array.isArray(orderBy) ? orderBy : [orderBy]).flatMap((clause) => Object.entries(clause)).map(([field, direction]) => {
+		if (direction !== "asc" && direction !== "desc") throw new CursorOrderingError(`[stratal:database] $cursor needs a direction for "${field}"; got ${JSON.stringify(direction)}.`, field);
+		return [field, direction];
+	});
+}
+/**
+* Builds the keyset condition for "the rows after (or before) this position".
+*
+* For `updatedAt desc, id desc` this is
+* `updatedAt < :updatedAt OR (updatedAt = :updatedAt AND id < :id)` — one
+* disjunct per ordering column, each pinning the columns to its left to
+* equality. Reading backwards flips every comparison.
+*/
+function buildKeysetCondition(order, values, direction) {
+	const disjuncts = [];
+	for (let i = 0; i < order.length; i++) {
+		const conjunct = {};
+		for (let j = 0; j < i; j++) {
+			const [field] = order[j];
+			conjunct[field] = values[field];
+		}
+		const [field, sort] = order[i];
+		conjunct[field] = { [sort === "desc" === (direction === "next") ? "lt" : "gt"]: values[field] };
+		disjuncts.push(conjunct);
+	}
+	return { OR: disjuncts };
+}
+/** The ordering values of a row, which is what a cursor is made of. */
+function cursorValuesOf(row, order) {
+	const values = {};
+	for (const [field] of order) {
+		if (!(field in row)) throw new CursorOrderingError(`[stratal:database] Cannot build a cursor: the ordering column "${field}" is not on the returned row. Either it is not a field of this model, or a \`select\` dropped it.`, field);
+		const value = row[field];
+		if (value === null || value === void 0) throw new CursorOrderingError(`[stratal:database] Cannot build a cursor: the ordering column "${field}" is null. \$cursor cannot order on a nullable column — null has no position in an ordering.`, field);
+		values[field] = value;
+	}
+	return values;
+}
+/**
+* Reads one page of rows by cursor.
+*
+* Fetches one row more than asked for, which is how the next page is known to
+* exist without a `COUNT` — and a count is what a growing list cannot give a
+* stable answer to anyway.
+*
+* @example
+* ```typescript
+* const page = await db.$cursor.$from(threadUnion, {
+*   cursor: ctx.query('cursor'),
+*   take: 20,
+*   orderBy: [{ updatedAt: 'desc' }, { id: 'desc' }],
+*   where: { boardId },
+* })
+* ```
+*/
+async function readCursorPage(delegate, args) {
+	const order = normalizeOrderBy(args.orderBy);
+	if (order.length === 0) throw new CursorOrderingError("[stratal:database] $cursor requires `orderBy`. A cursor addresses a row's position in an ordering, so there is no position to address without one.");
+	const uniqueBy = args.uniqueBy ?? "id";
+	if (!order.some(([field]) => field === uniqueBy)) throw new CursorOrderingError(`[stratal:database] $cursor requires the ordering to include the unique column "${uniqueBy}", otherwise tied rows share a position and paging over them skips or repeats. Add it last — e.g. \`orderBy: [{ ${order[0][0]}: '${order[0][1]}' }, { ${uniqueBy}: '${order[0][1]}' }]\` — or name a different unique column with \`uniqueBy\`.`);
+	const decoded = args.cursor ? decodeCursor(args.cursor) : null;
+	const readingBackwards = decoded?.direction === "prev";
+	const queryOrder = readingBackwards ? order.map(([field, sort]) => [field, sort === "asc" ? "desc" : "asc"]) : order;
+	const conditions = [];
+	if (args.where) conditions.push(args.where);
+	if (decoded) conditions.push(buildKeysetCondition(order, decoded.values, decoded.direction));
+	const query = {
+		...conditions.length > 0 ? { where: conditions.length === 1 ? conditions[0] : { AND: conditions } } : {},
+		orderBy: queryOrder.map(([field, sort]) => ({ [field]: sort })),
+		take: args.take + 1,
+		...args.include ? { include: args.include } : {},
+		...args.select ? { select: args.select } : {},
+		...args.omit ? { omit: args.omit } : {}
+	};
+	const rows = await delegate.findMany(query);
+	const hasExtraRow = rows.length > args.take;
+	const page = hasExtraRow ? rows.slice(0, args.take) : rows;
+	const data = readingBackwards ? [...page].reverse() : page;
+	const first = data[0];
+	const last = data[data.length - 1];
+	const nextCursor = last === void 0 ? null : readingBackwards ? encodeCursor(cursorValuesOf(last, order), "next") : hasExtraRow ? encodeCursor(cursorValuesOf(last, order), "next") : null;
+	const prevCursor = first === void 0 ? null : readingBackwards ? hasExtraRow ? encodeCursor(cursorValuesOf(first, order), "prev") : null : decoded ? encodeCursor(cursorValuesOf(first, order), "prev") : null;
+	return {
+		data,
+		perPage: args.take,
+		cursorName: args.cursorName ?? "cursor",
+		cursor: args.cursor ?? null,
+		nextCursor,
+		prevCursor
+	};
+}
+//#endregion
+//#region src/database/pagination/cursor-reader.ts
+/**
+* Builds the reader eagerly, one entry per model the schema declares.
+*
+* A plain object rather than a `Proxy`: the model list is known here, and a
+* proxy would answer every property — `then`, `constructor`, an inspector's
+* probe — with something that looks like a reader.
+*
+* The delegate is resolved per call, not captured: ZenStack builds a fresh CRUD
+* handler on each model access, and holding one would pin it for the life of
+* the client.
+*/
+function createCursorReader(client, schema) {
+	const source = client;
+	const modelEntries = Object.keys(schema.models ?? {}).map((model) => {
+		const key = model.charAt(0).toLowerCase() + model.slice(1);
+		return [key, { findMany: (args) => {
+			const delegate = source[key];
+			if (!delegate) throw new CursorModelUnavailableError(key);
+			const { cursor, take, orderBy, uniqueBy, cursorName, where, include, select, omit } = args;
+			return readCursorPage(delegate, {
+				cursor,
+				take,
+				orderBy,
+				uniqueBy,
+				cursorName,
+				where,
+				include,
+				select,
+				omit
+			});
+		} }];
+	});
+	return Object.assign(Object.fromEntries(modelEntries), { $from: (delegate, args) => readCursorPage(delegate, args) });
+}
+//#endregion
 //#region src/database/errors/record-not-found.error.ts
 var RecordNotFoundError = class extends HttpException {
 	details;
@@ -158,19 +412,31 @@ function parseDatabaseError(error) {
 	const dbErrorCode = error.dbErrorCode;
 	if (dbErrorCode) {
 		if (dbErrorCode === "23505") return new UniqueConstraintError([error.model ?? "unknown"], error);
-		if (dbErrorCode === "23503") return new DatabaseError("Foreign key constraint violation", error);
-		if (dbErrorCode === "23502") return new DatabaseError("Required field is missing", error);
-		if (dbErrorCode === "23514") return new DatabaseError("Database constraint violated", error);
-		if (dbErrorCode === "42P01") return new DatabaseError("Table does not exist", error);
-		if (dbErrorCode === "42703") return new DatabaseError("Column does not exist", error);
-		if (dbErrorCode.startsWith("42")) return new DatabaseError("Database syntax or access error", error);
-		if (dbErrorCode.startsWith("08")) return new DatabaseError("Database connection failed", error);
-		if (dbErrorCode === "57014") return new DatabaseError("Database query timeout", error);
-		if (dbErrorCode.startsWith("40")) return new DatabaseError("Transaction conflict or deadlock", error);
-		if (dbErrorCode === "53300") return new DatabaseError("Too many database connections", error);
+		if (dbErrorCode === "23503") return new DatabaseError(withCode("Foreign key constraint violation", dbErrorCode), error);
+		if (dbErrorCode === "23502") return new DatabaseError(withCode("Required field is missing", dbErrorCode), error);
+		if (dbErrorCode === "23514") return new DatabaseError(withCode("Database constraint violated", dbErrorCode), error);
+		if (dbErrorCode === "42P01") return new DatabaseError(withCode("Table does not exist", dbErrorCode), error);
+		if (dbErrorCode === "42703") return new DatabaseError(withCode("Column does not exist", dbErrorCode), error);
+		if (dbErrorCode.startsWith("42")) return new DatabaseError(withCode("Database syntax or access error", dbErrorCode), error);
+		if (dbErrorCode.startsWith("22")) return new DatabaseError(withCode("Invalid data value for column", dbErrorCode), error);
+		if (dbErrorCode.startsWith("08")) return new DatabaseError(withCode("Database connection failed", dbErrorCode), error);
+		if (dbErrorCode === "57014") return new DatabaseError(withCode("Database query timeout", dbErrorCode), error);
+		if (dbErrorCode.startsWith("40")) return new DatabaseError(withCode("Transaction conflict or deadlock", dbErrorCode), error);
+		if (dbErrorCode === "53300") return new DatabaseError(withCode("Too many database connections", dbErrorCode), error);
+		return new DatabaseError(withCode("Database error", dbErrorCode), error);
 	}
 	return new DatabaseError("Database error", error);
 }
+/**
+* Append the raw SQLSTATE to a human message so an operator can tell distinct
+* failures apart in production logs. The 5-character SQLSTATE is a fixed
+* PostgreSQL error code (e.g. `22021`), not query text, values, or schema — it
+* carries no sensitive data, so it is safe to surface where the full driver
+* message and stack are deliberately withheld.
+*/
+function withCode(message, dbErrorCode) {
+	return `${message} [SQLSTATE ${dbErrorCode}]`;
+}
 //#endregion
 //#region src/database/plugins/error-handler.plugin.ts
 /**
@@ -324,20 +590,37 @@ var SchemaSwitcher = class {
 };
 //#endregion
 //#region src/database/database.helpers.ts
-const databaseConnectionSchema = z.object({
-	name: z.string().min(1, withZodI18n("database.connectionNameRequired")),
-	schema: z.object({}).loose(),
-	dialect: z.function(),
-	plugins: z.array(z.object({}).loose()).optional(),
-	computedFields: z.object({}).loose().optional()
+const databaseConnectionSchema = object({
+	name: string().check(minLength(1, withZodI18n("database.connectionNameRequired"))),
+	schema: looseObject({}),
+	dialect: custom((value) => typeof value === "function"),
+	plugins: optional(array(looseObject({}))),
+	computedFields: optional(looseObject({}))
 });
-z.object({
-	default: z.string().min(1, withZodI18n("database.defaultConnectionRequired")),
-	connections: z.array(databaseConnectionSchema).min(1, withZodI18n("database.connectionRequired"))
-}).refine((config) => {
+object({
+	default: string().check(minLength(1, withZodI18n("database.defaultConnectionRequired"))),
+	connections: array(databaseConnectionSchema).check(minLength(1, withZodI18n("database.connectionRequired")))
+}).check(refine((config) => {
 	const names = config.connections.map((c) => c.name);
 	return new Set(names).size === names.length;
-}, withZodI18n("database.duplicateConnections")).refine((config) => config.connections.some((c) => c.name === config.default), withZodI18n("database.defaultConnectionNotFound"));
+}, withZodI18n("database.duplicateConnections")), refine((config) => config.connections.some((c) => c.name === config.default), withZodI18n("database.defaultConnectionNotFound")));
+/**
+* Puts `$cursor` on a client, base or transaction.
+*
+* Defined on the client rather than contributed as a ZenStack plugin because
+* the client proxy hands a plugin's member back unbound, and this one has to
+* reach the client's own model delegates. Non-enumerable so it stays out of
+* enumeration of the client, and skipped when already present — a reentrant
+* `$transaction` hands back a client that has been through here.
+*/
+function defineCursorReader(client, schema) {
+	if ("$cursor" in client) return;
+	Object.defineProperty(client, "$cursor", {
+		value: createCursorReader(client, schema),
+		enumerable: false,
+		configurable: true
+	});
+}
 /**
 * Wrap a ZenStack client so `$transaction` is reentrant: when a transaction is
 * already open on this connection (tracked per-connection via
@@ -354,8 +637,13 @@ z.object({
 *
 * ZenStackClient's constructor returns a Proxy (for dynamic model accessors), so
 * a subclass method override is shadowed — hence the proxy wrapper here.
+*
+* `prepareTransactionClient` runs against every transaction client before the
+* callback sees it, which is how the built-in members reach it. ZenStack builds
+* that client itself and types it with its own contract, so there is no other
+* point at which it passes through this package.
 */
-function makeReentrantTransaction(client, activeTransaction) {
+function makeReentrantTransaction(client, activeTransaction, prepareTransactionClient) {
 	return new Proxy(client, { get(target, prop, receiver) {
 		if (prop === Symbol.asyncDispose) return () => target.$disconnect();
 		if (prop !== "$transaction") return Reflect.get(target, prop, receiver);
@@ -364,7 +652,10 @@ function makeReentrantTransaction(client, activeTransaction) {
 			const active = activeTransaction.getStore();
 			if (active) return typeof input === "function" ? input(active) : active.$transaction(input, options);
 			if (typeof input !== "function") return transaction.call(target, input, options);
-			return transaction.call(target, (tx) => activeTransaction.run(tx, () => input(tx)), options);
+			return transaction.call(target, (tx) => {
+				prepareTransactionClient?.(tx);
+				return activeTransaction.run(tx, () => input(tx));
+			}, options);
 		};
 	} });
 }
@@ -384,12 +675,13 @@ function createDatabaseService(conn, eventRegistry) {
 				plugins,
 				computedFields: conn.computedFields
 			});
-			const client = makeReentrantTransaction(this, activeTransaction);
+			defineCursorReader(this, conn.schema);
+			const client = makeReentrantTransaction(this, activeTransaction, (tx) => defineCursorReader(tx, conn.schema));
 			for (const ref of instances) if (ref.deref() === void 0) instances.delete(ref);
 			instances.add(new WeakRef(client));
 			return client;
 		}
-		static async disposeInstances() {
+		static async disposeInstances(logger) {
 			const live = [...instances];
 			instances.clear();
 			await Promise.all(live.map(async (ref) => {
@@ -398,12 +690,12 @@ function createDatabaseService(conn, eventRegistry) {
 				try {
 					await client.$disconnect();
 				} catch (error) {
-					console.error(`[stratal] Failed to disconnect database client "${conn.name}":`, error);
+					logger.error(`Failed to disconnect database client "${conn.name}"`, error instanceof Error ? error : new Error(String(error)));
 				}
 			}));
 		}
 	};
-	DatabaseClient = __decorate([Transient()], DatabaseClient);
+	DatabaseClient = __decorate([Request()], DatabaseClient);
 	return DatabaseClient;
 }
 //#endregion
@@ -449,7 +741,7 @@ let DatabaseModule = _DatabaseModule = class DatabaseModule {
 		};
 	}
 	async onInitialize(context) {
-		const config = context.container.resolve(DATABASE_TOKENS.Options);
+		const config = await context.container.resolve(DATABASE_TOKENS.Options);
 		const eventRegistry = (await context.container.resolve(DI_TOKENS.LazyModuleLoader).load(() => import("stratal/events").then((m) => m.EventsModule))).get(DI_TOKENS.EventRegistry);
 		for (const conn of config.connections) {
 			const Service = createDatabaseService(conn, eventRegistry);
@@ -460,7 +752,7 @@ let DatabaseModule = _DatabaseModule = class DatabaseModule {
 		context.logger.info("DatabaseModule initialized");
 	}
 	async onShutdown(context) {
-		await Promise.all(this.services.map((service) => service.disposeInstances()));
+		await Promise.all(this.services.map((service) => service.disposeInstances(context.logger)));
 		this.services.length = 0;
 		context.logger.info("DatabaseModule shutdown");
 	}
@@ -478,11 +770,98 @@ DatabaseModule = _DatabaseModule = __decorate([Module({
 	]
 })], DatabaseModule);
 //#endregion
+//#region src/database/pool.ts
+/**
+* Env binding the framework reads to decide DB connection topology. Set by
+* `@stratal/testing` (the test harness runs against a DIRECT Postgres with no
+* Hyperdrive in front); never set in dev / staging / production.
+*/
+const DB_SHARED_POOL_ENV = "STRATAL_DB_SHARED_POOL";
+/**
+* Build the lazy pool factory a consumer hands to its ZenStack dialect,
+* choosing the connection topology from the environment instead of hard-coding
+* one. The consumer writes `dialect: () => new PostgresDialect({ pool })` where
+* `pool = createPoolFactory(env, () => new Pool(poolConfig))` — so the prod-vs-
+* test decision lives here, in the framework, not as an `IS_TEST` branch in app
+* config.
+*
+* - **Default (dev / staging / production):** returns a FRESH pool on every
+*   call. The dialect is rebuilt per request resolution, so each request owns
+*   its own pool/socket — mandatory on workerd, where a pool opened in one
+*   request's I/O context cannot be reused by another (the cross-request I/O is
+*   cancelled and the request hangs forever). Hyperdrive fronts these pools and
+*   multiplexes the real server connections, so they never accumulate.
+* - **Shared (`DB_SHARED_POOL_ENV === 'true'`):** memoizes ONE pool per
+*   connection, reused across every resolution. `@stratal/testing` sets this
+*   because the test harness hits a direct Postgres with no Hyperdrive — a fresh
+*   pool per resolution would exhaust `max_connections` across parallel test
+*   files. One shared pool per connection mirrors what Hyperdrive does in prod.
+*
+*   This single pool is forced **persistent** ({@link withPersistentConnection}):
+*   its idle reaper is disabled regardless of the config `makePool` passed. A pool
+*   reused for the whole worker run must never idle-close — a non-zero
+*   `idleTimeoutMillis` reaps its connection between operations, and under real
+*   network latency (a CI Postgres service, not a local socket) that eviction
+*   races in-flight and subsequent queries → "Connection terminated unexpectedly",
+*   cascading into half-applied writes and cross-test row leakage. It passes on a
+*   fast local socket and only surfaces under latency, so consumers can't be
+*   trusted to configure it right — the shared branch enforces it. The consumer's
+*   own idle settings still apply to the fresh-per-resolution prod pools (below).
+*
+* Either way the pool is created LAZILY: `makePool` is invoked by Kysely on the
+* first query, inside the request's I/O context — never at module-eval / global
+* scope, which workerd forbids ("Disallowed operation within global scope").
+*/
+function createPoolFactory(env, makePool) {
+	if (!(env["STRATAL_DB_SHARED_POOL"] === "true")) return () => Promise.resolve(makePool());
+	let pool;
+	return () => Promise.resolve(pool ??= withPersistentConnection(withIdempotentEnd(makePool())));
+}
+/**
+* Force a SHARED pool to keep its connection: disable the idle reaper so it is
+* never torn down between operations. The shared pool is ONE connection reused
+* for the whole worker run, so a non-zero `idleTimeoutMillis` (correct for the
+* fresh-per-resolution prod pools, wrong for this long-lived one) reaps it mid-
+* run; under real network latency that eviction races in-flight/next queries →
+* "Connection terminated unexpectedly", cascading into half-applied writes and
+* cross-test row leakage. `pg` reads `options.idleTimeoutMillis`/`allowExitOnIdle`
+* when a client is released, so clearing them on the constructed pool disables
+* future reaping without the consumer having to special-case their pool config.
+* A no-op for pools that don't expose `options` (non-`pg` implementations).
+*/
+function withPersistentConnection(pool) {
+	const candidate = pool;
+	if (candidate.options) {
+		candidate.options.idleTimeoutMillis = 0;
+		candidate.options.allowExitOnIdle = false;
+	}
+	return pool;
+}
+/**
+* A SHARED pool is handed to every `@Transient` `DatabaseClient`'s dialect, so on
+* shutdown `DatabaseModule.onShutdown` → `disposeInstances` calls `$disconnect()`
+* (→ Kysely `destroy()` → `pool.end()`) once PER live client instance — all of
+* them targeting the single shared pool. pg-pool throws "Called end on pool more
+* than once" on the 2nd+ call, which `disposeInstances` then logs once per extra
+* instance (harmless but noisy, and a real correctness wart). Each owner releasing
+* its reference is legitimate, so make `end()` idempotent: tear the socket down
+* exactly once and have every caller await that same teardown. Fresh-per-resolution
+* pools (the dev/staging/prod default) are untouched — each is already ended once.
+*/
+function withIdempotentEnd(pool) {
+	const candidate = pool;
+	if (typeof candidate.end !== "function") return pool;
+	const end = candidate.end.bind(candidate);
+	let ending;
+	candidate.end = () => ending ??= end();
+	return pool;
+}
+//#endregion
 //#region src/database/decorators/inject-db.decorator.ts
 function InjectDB(name) {
 	return inject(connectionSymbol(name));
 }
 //#endregion
-export { DATABASE_TOKENS, DatabaseModule, DbGenerateCommand, DbPullCommand, DbPushCommand, ErrorHandlerPlugin, EventEmitterPlugin, InjectDB, MigrateDeployCommand, MigrateDevCommand, MigrateResetCommand, MigrateStatusCommand, RecordNotFoundError, SchemaSwitcher, UniqueConstraintError, ZenStackCommand, connectionSymbol, databaseMessages, fromZenStackError };
+export { CursorModelUnavailableError, CursorOrderingError, DATABASE_TOKENS, DB_SHARED_POOL_ENV, DatabaseModule, DbGenerateCommand, DbPullCommand, DbPushCommand, ErrorHandlerPlugin, EventEmitterPlugin, InjectDB, MalformedCursorError, MigrateDeployCommand, MigrateDevCommand, MigrateResetCommand, MigrateStatusCommand, RecordNotFoundError, SchemaSwitcher, UniqueConstraintError, ZenStackCommand, connectionSymbol, createCursorReader, createPoolFactory, databaseMessages, decodeCursor, encodeCursor, fromZenStackError };
 
 //# sourceMappingURL=index.mjs.map