@coffre/db 0.10.0 → 0.10.1

package/dist/connect.d.ts

@@ -1,4 +1,4 @@
-import { t as Database } from "./database-BFnO2b2P.js";
+import { t as Database } from "./database-DBtn3jqp.js";
 import { Engine } from "./dialect.js";
 import { ClientConfig } from "pg";
 //#region src/postgres.d.ts

package/dist/connect.js

@@ -1,4 +1,4 @@
-import { createDatabase } from "./index.js";
+import { n as createDatabase } from "./database-BadNeeN-.js";
 import { asPostgresDatabase } from "./portable.js";
 import { t as postgresConnection } from "./postgres-Bmar8y0q.js";
 import pg from "pg";

package/dist/database-BadNeeN-.js

@@ -0,0 +1,146 @@
+import { n as trackCommits } from "./commits-BuW-NL3n.js";
+import { t as schema_exports } from "./schema.js";
+import { engineOf } from "./dialect.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Table, createTableRelationsHelpers, extractTablesRelationalConfig, getTableName, is } from "drizzle-orm";
+import { NodePgDatabase, NodePgDriver } from "drizzle-orm/node-postgres";
+import { PgDialect } from "drizzle-orm/pg-core";
+//#region src/prepared.ts
+/**
+* A select built once per process, or once per isolate on Workers, and run
+* with new values each time. Drizzle rebuilds a query's SQL from its
+* builder at every run, and that was most of a short query's CPU; this
+* builds it from `build` the first time a database of its dialect asks,
+* then hands the SQL and its columns to that call's own session
+* (`session.prepareQuery`), which binds `values` to the placeholders
+* (`sql.placeholder`) and maps the rows as the builder would.
+*
+* `build` must not depend on anything but the database's dialect, and the
+* values go to the driver as they are, not through a column's encoding:
+* strings, numbers, bigints and bytes.
+*
+*   const member = prepared((db) => db.select().from(tablesOf(db).vaultMembers).where(eq(…, sql.placeholder('principal'))));
+*   const [row] = await member(db, { principal });
+*/
+function prepared(build) {
+	const builds = /* @__PURE__ */ new WeakMap();
+	return (db, values = {}) => {
+		const tables = tablesOf(db);
+		let built = builds.get(tables);
+		if (built === void 0) {
+			const builder = build(db);
+			const { fields, joinsNotNullableMap } = builder.prepare();
+			built = {
+				query: builder.toSQL(),
+				fields,
+				joinsNotNullableMap,
+				engine: engineOf(db)
+			};
+			builds.set(tables, built);
+		}
+		const session = db.session;
+		const query = built.engine === "sqlite" ? session.prepareQuery(built.query, built.fields, "all", true) : session.prepareQuery(built.query, built.fields, void 0, true);
+		query.joinsNotNullableMap = built.joinsNotNullableMap;
+		return built.engine === "sqlite" ? query.all(values) : query.execute(values);
+	};
+}
+//#endregion
+//#region src/database.ts
+/**
+* A query made on the database from inside one of its own transactions,
+* rather than through the transaction. With one connection per call, as on
+* Workers, it would wait for the transaction, which waits for it: a call
+* Cloudflare cancels as hung, and nothing says why. So it is refused at
+* once, with this, wherever the database runs.
+*/
+var QueryOutsideTransaction = class extends Error {
+	constructor() {
+		super("query outside its transaction: use tx. A query on the database inside one of its own transactions waits for that transaction, which waits for it");
+		this.name = "QueryOutsideTransaction";
+	}
+};
+/** The transaction a flow of work runs inside, with the pool it holds, while it is open. */
+const inside = new AsyncLocalStorage();
+/**
+* `pool`, refusing a query or a transaction asked from inside a transaction
+* it is already running. Work from any other flow, a concurrent request's,
+* or what the transaction left running once its work was done, goes on as before.
+*/
+function guarded(pool) {
+	return new Proxy(pool, { get(target, key) {
+		const value = Reflect.get(target, key, target);
+		if (typeof value !== "function") return value;
+		if (key !== "query" && key !== "connect") return value.bind(target);
+		return (...args) => {
+			const open = inside.getStore();
+			if (open?.open === true && open.pool === target) throw new QueryOutsideTransaction();
+			return value.apply(target, args);
+		};
+	} });
+}
+/** The refusal `error` is, or was caused by. */
+function brokenRule(error) {
+	for (let cause = error; cause instanceof Error; cause = cause.cause) if (cause instanceof QueryOutsideTransaction) return cause;
+}
+let relational;
+function relationalSchema() {
+	if (relational === void 0) {
+		const { tables, tableNamesMap } = extractTablesRelationalConfig(schema_exports, createTableRelationsHelpers);
+		relational = {
+			fullSchema: schema_exports,
+			schema: tables,
+			tableNamesMap
+		};
+	}
+	return relational;
+}
+function createDatabase(pool) {
+	const dialect = new PgDialect();
+	const config = relationalSchema();
+	const db = new NodePgDatabase(dialect, new NodePgDriver(guarded(pool), dialect).createSession(config), config);
+	const run = db.transaction.bind(db);
+	db.transaction = (async (work, config) => {
+		const open = {
+			pool,
+			open: true
+		};
+		try {
+			return await run((tx) => inside.run(open, async () => {
+				try {
+					return await work(tx);
+				} finally {
+					open.open = false;
+				}
+			}), config);
+		} catch (error) {
+			throw brokenRule(error) ?? error;
+		}
+	});
+	return trackCommits(db);
+}
+/**
+* The tables of the database's own dialect: the Postgres ones on Postgres,
+* the SQLite ones on SQLite. Every query builds on these.
+*/
+function tablesOf(db) {
+	return db._.fullSchema;
+}
+const byName = /* @__PURE__ */ new WeakMap();
+/**
+* The database's own twin of `table`, which may be another dialect's: the
+* server names tables by importing schema.ts, and the database decides
+* which one that means.
+*/
+function own(db, table) {
+	const tables = tablesOf(db);
+	let named = byName.get(tables);
+	if (named === void 0) {
+		named = new Map(Object.values(tables).filter((value) => is(value, Table)).map((value) => [getTableName(value), value]));
+		byName.set(tables, named);
+	}
+	const found = named.get(getTableName(table));
+	if (found === void 0) throw new Error(`no table ${getTableName(table)} in this database`);
+	return found;
+}
+//#endregion
+export { prepared as a, tablesOf as i, createDatabase as n, own as r, QueryOutsideTransaction as t };

package/dist/{database-BFnO2b2P.d.ts → database-DBtn3jqp.d.ts}

@@ -1,7 +1,31 @@
 import { m as schema_d_exports } from "./schema-NBVA9q-s.js";
-import { Table } from "drizzle-orm";
+import { Query, Table } from "drizzle-orm";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import pg from "pg";
+//#region src/prepared.d.ts
+/** The part of a select builder `prepared` reads, once. */
+type Select = PromiseLike<unknown> & {
+  toSQL(): Query;
+  prepare(...name: never[]): unknown;
+};
+/**
+ * A select built once per process, or once per isolate on Workers, and run
+ * with new values each time. Drizzle rebuilds a query's SQL from its
+ * builder at every run, and that was most of a short query's CPU; this
+ * builds it from `build` the first time a database of its dialect asks,
+ * then hands the SQL and its columns to that call's own session
+ * (`session.prepareQuery`), which binds `values` to the placeholders
+ * (`sql.placeholder`) and maps the rows as the builder would.
+ *
+ * `build` must not depend on anything but the database's dialect, and the
+ * values go to the driver as they are, not through a column's encoding:
+ * strings, numbers, bigints and bytes.
+ *
+ *   const member = prepared((db) => db.select().from(tablesOf(db).vaultMembers).where(eq(…, sql.placeholder('principal'))));
+ *   const [row] = await member(db, { principal });
+ */
+declare function prepared<Q extends Select>(build: (db: Queryable) => Q): (db: Queryable, values?: Record<string, unknown>) => Promise<Awaited<Q>>;
+//#endregion
 //#region src/database.d.ts
 /**
  * A database, typed as Postgres whichever it is; see portable.ts for why
@@ -46,4 +70,4 @@ declare function tablesOf(db: Queryable): typeof schema_d_exports;
  */
 declare function own<T extends Table>(db: Queryable, table: T): T;
 //#endregion
-export { Transaction as a, tablesOf as c, Queryable as i, PoolLike as n, createDatabase as o, QueryOutsideTransaction as r, own as s, Database as t };
+export { Transaction as a, tablesOf as c, Queryable as i, prepared as l, PoolLike as n, createDatabase as o, QueryOutsideTransaction as r, own as s, Database as t };

package/dist/dialect.d.ts

@@ -1,4 +1,4 @@
-import { i as Queryable } from "./database-BFnO2b2P.js";
+import { i as Queryable } from "./database-DBtn3jqp.js";
 import { SQL, SQLWrapper } from "drizzle-orm";
 import { PgTable } from "drizzle-orm/pg-core";
 //#region src/dialect.d.ts

package/dist/grants.d.ts

@@ -1,4 +1,4 @@
-import { i as Queryable } from "./database-BFnO2b2P.js";
+import { i as Queryable } from "./database-DBtn3jqp.js";
 import { Authenticity, Newest } from "./log.js";
 import { StoredEntry } from "@coffre/core/audit";
 import { Conversion, ConversionInput, InstanceRole, Scope } from "@coffre/core/access";

package/dist/grants.js

@@ -1,21 +1,25 @@
-import { tablesOf } from "./index.js";
 import { tombstone, truth } from "./dialect.js";
-import { LOOK_BACK, entryColumns, newestAuthentic } from "./log.js";
+import { a as prepared, i as tablesOf } from "./database-BadNeeN-.js";
+import { entryColumns, newestAuthentic } from "./log.js";
 import { and, asc, desc, eq, gt, inArray, isNull, lt, or, sql } from "drizzle-orm";
 import { EVERYWHERE, administers, convertEveryProjectGrants, isInstanceRole, isScope, normalScope, unscoped } from "@coffre/core/access";
 import { ACCESS_ACTIONS } from "@coffre/core/vault";
 //#region src/grants.ts
 /** Grants, lapsed ones too unless `liveAt` says when to judge them: one member's, or everyone's. */
 async function readGrants(db, filter = {}) {
-	const { vaultGrants, environments } = tablesOf(db);
-	return (await db.select({
-		grant: vaultGrants,
-		environmentProjectId: environments.projectId
-	}).from(vaultGrants).leftJoin(environments, eq(environments.id, vaultGrants.environmentId)).where(and(filter.principal === void 0 ? void 0 : eq(vaultGrants.principal, filter.principal), filter.liveAt === void 0 ? void 0 : or(isNull(vaultGrants.expiresAt), gt(vaultGrants.expiresAt, filter.liveAt))))).map(({ grant, environmentProjectId }) => ({
+	return (filter.principal !== void 0 && filter.liveAt === void 0 ? await grantsOf(db, { principal: filter.principal }) : await grantRows(db, filter.principal === void 0 ? void 0 : eq(tablesOf(db).vaultGrants.principal, filter.principal), filter.liveAt)).map(({ grant, environmentProjectId }) => ({
 		...grant,
 		projectId: grant.projectId ?? environmentProjectId
 	}));
 }
+function grantRows(db, principal, liveAt) {
+	const { vaultGrants, environments } = tablesOf(db);
+	return db.select({
+		grant: vaultGrants,
+		environmentProjectId: environments.projectId
+	}).from(vaultGrants).leftJoin(environments, eq(environments.id, vaultGrants.environmentId)).where(and(principal, liveAt === void 0 ? void 0 : or(isNull(vaultGrants.expiresAt), gt(vaultGrants.expiresAt, liveAt))));
+}
+const grantsOf = prepared((db) => grantRows(db, eq(tablesOf(db).vaultGrants.principal, sql.placeholder("principal"))));
 /** Add a grant; an environment's row names only the environment. */
 async function insertGrant(db, grant) {
 	const { vaultGrants } = tablesOf(db);
@@ -226,18 +230,30 @@ async function reportStands(db, principal, check) {
 	const access = await newestAccess(db, principal, check);
 	if (access === "unreached") return true;
 	const after = typeof access === "string" ? -1n : access.seq;
-	const report = await newestAuthentic((before) => tamperReportsAbout(db, principal, LOOK_BACK.page, after, before), check);
+	const report = await newestAuthentic((limit, before) => tamperReportsAbout(db, principal, limit, after, before), check);
 	return report === "unreached" || typeof report !== "string";
 }
 /** The newest access entry about `principal` that `check` finds the vault's own. */
 function newestAccess(db, principal, check) {
-	return newestAuthentic((before) => accessEntriesAbout(db, principal, LOOK_BACK.page, before), check);
+	return newestAuthentic((limit, before) => accessEntriesAbout(db, principal, limit, before), check);
 }
 /** Up to `limit` of the vault's allowed access entries about `principal` before `before` (the newest when undefined), newest first. */
 async function accessEntriesAbout(db, principal, limit, before) {
+	return before === void 0 ? await newestAccessEntries(db, {
+		principal,
+		limit
+	}) : await accessEntriesBefore(db, {
+		principal,
+		limit,
+		before
+	});
+}
+function accessEntries(db, before) {
 	const { auditLog } = tablesOf(db);
-	return await db.select(entryColumns(db)).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.subjectPrincipal, principal), inArray(auditLog.action, [...ACCESS_ACTIONS]), eq(auditLog.decision, "allow"), before === void 0 ? void 0 : lt(auditLog.seq, before))).orderBy(desc(auditLog.seq)).limit(limit);
+	return db.select(entryColumns(db)).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.subjectPrincipal, sql.placeholder("principal")), inArray(auditLog.action, [...ACCESS_ACTIONS]), eq(auditLog.decision, "allow"), before)).orderBy(desc(auditLog.seq)).limit(sql.placeholder("limit"));
 }
+const newestAccessEntries = prepared((db) => accessEntries(db));
+const accessEntriesBefore = prepared((db) => accessEntries(db, lt(tablesOf(db).auditLog.seq, sql.placeholder("before"))));
 /**
 * Up to `limit` of the vault's reports that `principal`'s row was changed
 * around it (`TAMPER_CODES`), after `after` and before `before` (the newest

package/dist/hyperdrive.d.ts

@@ -1,4 +1,4 @@
-import { n as PoolLike } from "./database-BFnO2b2P.js";
+import { n as PoolLike } from "./database-DBtn3jqp.js";
 import pg from "pg";
 //#region src/hyperdrive.d.ts
 /** Postgres through a Hyperdrive binding: `postgres(env.HYPERDRIVE)`. */

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import { m as schema_d_exports } from "./schema-NBVA9q-s.js";
-import { a as Transaction, c as tablesOf, i as Queryable, n as PoolLike, o as createDatabase, r as QueryOutsideTransaction, s as own, t as Database } from "./database-BFnO2b2P.js";
-export { Database, PoolLike, QueryOutsideTransaction, Queryable, Transaction, createDatabase, own, schema_d_exports as schema, tablesOf };
+import { a as Transaction, c as tablesOf, i as Queryable, l as prepared, n as PoolLike, o as createDatabase, r as QueryOutsideTransaction, s as own, t as Database } from "./database-DBtn3jqp.js";
+export { Database, PoolLike, QueryOutsideTransaction, Queryable, Transaction, createDatabase, own, prepared, schema_d_exports as schema, tablesOf };

package/dist/index.js

@@ -1,90 +1,3 @@
-import { n as trackCommits } from "./commits-BuW-NL3n.js";
 import { t as schema_exports } from "./schema.js";
-import { AsyncLocalStorage } from "node:async_hooks";
-import { Table, getTableName, is } from "drizzle-orm";
-import { drizzle } from "drizzle-orm/node-postgres";
-//#region src/database.ts
-/**
-* A query made on the database from inside one of its own transactions,
-* rather than through the transaction. With one connection per call, as on
-* Workers, it would wait for the transaction, which waits for it: a call
-* Cloudflare cancels as hung, and nothing says why. So it is refused at
-* once, with this, wherever the database runs.
-*/
-var QueryOutsideTransaction = class extends Error {
-	constructor() {
-		super("query outside its transaction: use tx. A query on the database inside one of its own transactions waits for that transaction, which waits for it");
-		this.name = "QueryOutsideTransaction";
-	}
-};
-/** The transaction a flow of work runs inside, with the pool it holds, while it is open. */
-const inside = new AsyncLocalStorage();
-/**
-* `pool`, refusing a query or a transaction asked from inside a transaction
-* it is already running. Work from any other flow, a concurrent request's,
-* or what the transaction left running once its work was done, goes on as before.
-*/
-function guarded(pool) {
-	return new Proxy(pool, { get(target, key) {
-		const value = Reflect.get(target, key, target);
-		if (typeof value !== "function") return value;
-		if (key !== "query" && key !== "connect") return value.bind(target);
-		return (...args) => {
-			const open = inside.getStore();
-			if (open?.open === true && open.pool === target) throw new QueryOutsideTransaction();
-			return value.apply(target, args);
-		};
-	} });
-}
-/** The refusal `error` is, or was caused by. */
-function brokenRule(error) {
-	for (let cause = error; cause instanceof Error; cause = cause.cause) if (cause instanceof QueryOutsideTransaction) return cause;
-}
-function createDatabase(pool) {
-	const db = drizzle(guarded(pool), { schema: schema_exports });
-	const run = db.transaction.bind(db);
-	db.transaction = (async (work, config) => {
-		const open = {
-			pool,
-			open: true
-		};
-		try {
-			return await run((tx) => inside.run(open, async () => {
-				try {
-					return await work(tx);
-				} finally {
-					open.open = false;
-				}
-			}), config);
-		} catch (error) {
-			throw brokenRule(error) ?? error;
-		}
-	});
-	return trackCommits(db);
-}
-/**
-* The tables of the database's own dialect: the Postgres ones on Postgres,
-* the SQLite ones on SQLite. Every query builds on these.
-*/
-function tablesOf(db) {
-	return db._.fullSchema;
-}
-const byName = /* @__PURE__ */ new WeakMap();
-/**
-* The database's own twin of `table`, which may be another dialect's: the
-* server names tables by importing schema.ts, and the database decides
-* which one that means.
-*/
-function own(db, table) {
-	const tables = tablesOf(db);
-	let named = byName.get(tables);
-	if (named === void 0) {
-		named = new Map(Object.values(tables).filter((value) => is(value, Table)).map((value) => [getTableName(value), value]));
-		byName.set(tables, named);
-	}
-	const found = named.get(getTableName(table));
-	if (found === void 0) throw new Error(`no table ${getTableName(table)} in this database`);
-	return found;
-}
-//#endregion
-export { QueryOutsideTransaction, createDatabase, own, schema_exports as schema, tablesOf };
+import { a as prepared, i as tablesOf, n as createDatabase, r as own, t as QueryOutsideTransaction } from "./database-BadNeeN-.js";
+export { QueryOutsideTransaction, createDatabase, own, prepared, schema_exports as schema, tablesOf };

package/dist/log.d.ts

@@ -1,4 +1,4 @@
-import { a as Transaction, i as Queryable } from "./database-BFnO2b2P.js";
+import { a as Transaction, i as Queryable } from "./database-DBtn3jqp.js";
 import { SQL } from "drizzle-orm";
 import { LogKey, StoredEntry } from "@coffre/core/audit";
 //#region src/log.d.ts
@@ -462,6 +462,19 @@ export declare function withinBytes(db: Queryable, where: SQL | undefined, limit
   cut: boolean;
   count: number;
 } | null>;
+/**
+ * The first entry missing from the log up to `seq`, and the one found in
+ * its place, or null when every one is there. Seqs are the primary key, so
+ * a stretch is whole exactly when its count is its length: one pass over
+ * the key's index, never the entries. Only a log with a gap pays for more,
+ * a count per halving to find where.
+ *
+ *   entries 0..9, 4 cut:  { expected: 4n, found: 5n }
+ */
+export declare function missingEntry(db: Queryable, seq: bigint): Promise<{
+  expected: bigint;
+  found: bigint | null;
+} | null>;
 /**
  * How a reader tells the vault's own entries from those forged in its name:
  * by their MAC, which only the vault holds the key to check. Each it finds
@@ -488,10 +501,11 @@ export declare const LOOK_BACK: {
 export type Newest = StoredEntry | 'none' | 'forged' | 'unreached';
 /**
  * The newest of the entries `page` reads, newest first and before a seq,
- * that `check` finds authentic, read back a page at a time: 'none' when
- * there are none at all, 'forged' when every one is in the vault's name but
- * not its own, and 'unreached' once it has read LOOK_BACK such entries
- * (1024), whether or not more are left.
+ * that `check` finds authentic: the newest alone first, which it is unless
+ * entries were forged in the vault's name since, then back a page at a
+ * time. 'none' when there are none at all, 'forged' when every one is in
+ * the vault's name but not its own, and 'unreached' once it has read
+ * LOOK_BACK such entries (1024), whether or not more are left.
  */
-export declare function newestAuthentic(page: (before: bigint | undefined) => Promise<StoredEntry[]>, check: Authenticity): Promise<Newest>;
+export declare function newestAuthentic(page: (limit: number, before: bigint | undefined) => Promise<StoredEntry[]>, check: Authenticity): Promise<Newest>;
 //#endregion

package/dist/log.js

@@ -1,7 +1,7 @@
 import { t as afterCommit } from "./commits-BuW-NL3n.js";
-import { tablesOf } from "./index.js";
 import { clockMillis, forUpdate } from "./dialect.js";
-import { and, asc, desc, eq, lt, sql } from "drizzle-orm";
+import { a as prepared, i as tablesOf } from "./database-BadNeeN-.js";
+import { and, asc, count, desc, eq, gt, gte, lt, lte, sql } from "drizzle-orm";
 import { GENESIS_HASH, sealEntry } from "@coffre/core/audit";
 //#region src/log.ts
 /** The log's head does not name its last entry: something moved it, or cut the log behind it. */
@@ -52,14 +52,17 @@ function forgetLogHeads() {
 * again in the same transaction is free.
 */
 async function lockLogHead(tx) {
-	const { auditChainHead } = tablesOf(tx);
-	const [head] = await forUpdate(tx, tx.select({
-		nextSeq: auditChainHead.nextSeq,
-		headHash: auditChainHead.headHash
-	}).from(auditChainHead).where(eq(auditChainHead.onlyRow, true)));
+	const [head] = await lockedHead(tx);
 	if (head === void 0) throw new Error("audit_chain_head is missing; refusing to write an unchained entry");
 	return head;
 }
+const lockedHead = prepared((db) => {
+	const { auditChainHead } = tablesOf(db);
+	return forUpdate(db, db.select({
+		nextSeq: auditChainHead.nextSeq,
+		headHash: auditChainHead.headHash
+	}).from(auditChainHead).where(eq(auditChainHead.onlyRow, true)));
+});
 /**
 * Append `entries` under `key`. `check`, when given, runs once the head is
 * locked and before anything is written: a writer's own condition on the
@@ -71,11 +74,8 @@ async function appendEntries(tx, key, entries, check) {
 	const { auditChainHead, auditLog } = tablesOf(tx);
 	const head = await lockLogHead(tx);
 	await check?.(tx);
-	const [{ now }] = await tx.select({ now: clockMillis(tx) }).from(auditChainHead);
-	const [last] = await tx.select({
-		seq: auditLog.seq,
-		hash: auditLog.hash
-	}).from(auditLog).orderBy(desc(auditLog.seq)).limit(1);
+	const [{ now }] = await clockNow(tx);
+	const [last] = await lastEntry(tx);
 	const expected = last === void 0 ? {
 		nextSeq: 0n,
 		headHash: GENESIS_HASH
@@ -136,6 +136,14 @@ async function appendEntries(tx, key, entries, check) {
 		occurredAt: now
 	};
 }
+const clockNow = prepared((db) => db.select({ now: clockMillis(db) }).from(tablesOf(db).auditChainHead));
+const lastEntry = prepared((db) => {
+	const { auditLog } = tablesOf(db);
+	return db.select({
+		seq: auditLog.seq,
+		hash: auditLog.hash
+	}).from(auditLog).orderBy(desc(auditLog.seq)).limit(1);
+});
 /** An entry's columns, as the chain's codec reads them (`StoredEntry`). */
 function entryColumns(db) {
 	const { auditLog } = tablesOf(db);
@@ -198,21 +206,64 @@ async function withinBytes(db, where, limit, order = "asc") {
 		count
 	};
 }
+/**
+* The first entry missing from the log up to `seq`, and the one found in
+* its place, or null when every one is there. Seqs are the primary key, so
+* a stretch is whole exactly when its count is its length: one pass over
+* the key's index, never the entries. Only a log with a gap pays for more,
+* a count per halving to find where.
+*
+*   entries 0..9, 4 cut:  { expected: 4n, found: 5n }
+*/
+async function missingEntry(db, seq) {
+	const { auditLog } = tablesOf(db);
+	const whole = async (to) => {
+		const [{ n }] = await db.select({ n: count() }).from(auditLog).where(and(gte(auditLog.seq, 0n), lte(auditLog.seq, to)));
+		return BigInt(n) === to + 1n;
+	};
+	if (seq < 0n || await whole(seq)) return null;
+	let [low, high] = [0n, seq];
+	while (low < high) {
+		const middle = (low + high) / 2n;
+		if (await whole(middle)) low = middle + 1n;
+		else high = middle;
+	}
+	const [next] = await db.select({ seq: auditLog.seq }).from(auditLog).where(gt(auditLog.seq, low)).orderBy(asc(auditLog.seq)).limit(1);
+	return {
+		expected: low,
+		found: next?.seq ?? null
+	};
+}
 /** Up to `limit` of the entries in the vault's name, allowed, of one `action`, before `before` (the newest when undefined), newest first. */
 async function newestVaultEntries(db, action, limit, before) {
+	return before === void 0 ? await newestEntries(db, {
+		action,
+		limit
+	}) : await entriesBefore(db, {
+		action,
+		limit,
+		before
+	});
+}
+function vaultEntries(db, before) {
 	const { auditLog } = tablesOf(db);
-	return await db.select(entryColumns(db)).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.action, action), eq(auditLog.decision, "allow"), before === void 0 ? void 0 : lt(auditLog.seq, before))).orderBy(desc(auditLog.seq)).limit(limit);
+	return db.select(entryColumns(db)).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.action, sql.placeholder("action")), eq(auditLog.decision, "allow"), before)).orderBy(desc(auditLog.seq)).limit(sql.placeholder("limit"));
 }
+const newestEntries = prepared((db) => vaultEntries(db));
+const entriesBefore = prepared((db) => vaultEntries(db, lt(tablesOf(db).auditLog.seq, sql.placeholder("before"))));
 /**
 * The number of the newest entry in the vault's name, allowed, of one
 * `action`, or null for none: whether one was appended since, and nothing
 * of what it says, so its MAC is not checked. One indexed read.
 */
 async function newestVaultSeq(db, action) {
-	const { auditLog } = tablesOf(db);
-	const [row] = await db.select({ seq: auditLog.seq }).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.action, action), eq(auditLog.decision, "allow"))).orderBy(desc(auditLog.seq)).limit(1);
+	const [row] = await newestSeq(db, { action });
 	return row?.seq ?? null;
 }
+const newestSeq = prepared((db) => {
+	const { auditLog } = tablesOf(db);
+	return db.select({ seq: auditLog.seq }).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.action, sql.placeholder("action")), eq(auditLog.decision, "allow"))).orderBy(desc(auditLog.seq)).limit(1);
+});
 /** How many entries in its name the vault reads back, a page at a time, for its own newest of a kind (`newestAuthentic`). */
 const LOOK_BACK = {
 	page: 32,
@@ -220,23 +271,27 @@ const LOOK_BACK = {
 };
 /**
 * The newest of the entries `page` reads, newest first and before a seq,
-* that `check` finds authentic, read back a page at a time: 'none' when
-* there are none at all, 'forged' when every one is in the vault's name but
-* not its own, and 'unreached' once it has read LOOK_BACK such entries
-* (1024), whether or not more are left.
+* that `check` finds authentic: the newest alone first, which it is unless
+* entries were forged in the vault's name since, then back a page at a
+* time. 'none' when there are none at all, 'forged' when every one is in
+* the vault's name but not its own, and 'unreached' once it has read
+* LOOK_BACK such entries (1024), whether or not more are left.
 */
 async function newestAuthentic(page, check) {
+	const most = LOOK_BACK.page * LOOK_BACK.pages;
+	let read = 0;
 	let before;
-	for (let read = 0; read < LOOK_BACK.pages; read += 1) {
-		const entries = await page(before);
+	for (let limit = 1; read < most; limit = Math.min(LOOK_BACK.page, most - read)) {
+		const entries = await page(limit, before);
 		for (const entry of entries) {
 			if (check.authentic(entry)) return entry;
 			check.forged(entry);
 		}
-		if (entries.length < LOOK_BACK.page) return before === void 0 && entries.length === 0 ? "none" : "forged";
+		read += entries.length;
+		if (entries.length < limit) return read === 0 ? "none" : "forged";
 		before = entries.at(-1).seq;
 	}
 	return "unreached";
 }
 //#endregion
-export { BATCH_BYTES, LOOK_BACK, LogHeadMismatch, LogRewound, appendEntries, entryColumns, forgetLogHeads, lockLogHead, newestAuthentic, newestVaultEntries, newestVaultSeq, withinBytes };
+export { BATCH_BYTES, LOOK_BACK, LogHeadMismatch, LogRewound, appendEntries, entryColumns, forgetLogHeads, lockLogHead, missingEntry, newestAuthentic, newestVaultEntries, newestVaultSeq, withinBytes };

package/dist/portable.d.ts

@@ -1,5 +1,5 @@
 import { m as schema_d_exports } from "./schema-NBVA9q-s.js";
-import { t as Database } from "./database-BFnO2b2P.js";
+import { t as Database } from "./database-DBtn3jqp.js";
 import { t as schema_sqlite_d_exports } from "./schema-sqlite.js";
 import { LibSQLDatabase } from "drizzle-orm/libsql";
 //#region src/portable.d.ts

package/dist/schema-version.d.ts

@@ -1,4 +1,4 @@
-import { i as Queryable } from "./database-BFnO2b2P.js";
+import { i as Queryable } from "./database-DBtn3jqp.js";
 import { Engine } from "./dialect.js";
 //#region src/schema-version.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -79,7 +79,7 @@
     "drizzle-orm": "0.45.2",
     "pg": "8.16.3",
     "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.10.0"
+    "@coffre/core": "0.10.1"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/database.ts

@@ -1,7 +1,16 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-import { getTableName, is, Table } from 'drizzle-orm';
-import { drizzle, type NodePgDatabase } from 'drizzle-orm/node-postgres';
+import {
+  createTableRelationsHelpers,
+  extractTablesRelationalConfig,
+  getTableName,
+  is,
+  Table,
+  type ExtractTablesWithRelations,
+  type RelationalSchemaConfig,
+} from 'drizzle-orm';
+import { NodePgDatabase, NodePgDriver } from 'drizzle-orm/node-postgres';
+import { PgDialect } from 'drizzle-orm/pg-core';
 import type pg from 'pg';
 
 import { trackCommits } from './commits.ts';
@@ -74,8 +83,29 @@ function brokenRule(error: unknown): QueryOutsideTransaction | undefined {
   return undefined;
 }
 
+/**
+ * What Drizzle makes of the schema, which `drizzle(pool, { schema })` works
+ * out again from every table at each call: on Workers, a database is made
+ * per call, and this was a fifth of a vault call's CPU. The schema never
+ * changes, so it is worked out once per process or isolate, a settled value.
+ */
+type Relational = RelationalSchemaConfig<ExtractTablesWithRelations<typeof schema>>;
+let relational: Relational | undefined;
+
+function relationalSchema(): Relational {
+  if (relational === undefined) {
+    const { tables, tableNamesMap } = extractTablesRelationalConfig(schema, createTableRelationsHelpers);
+    // Drizzle's own construct passes the same untyped tables on as these.
+    relational = { fullSchema: schema, schema: tables as Relational['schema'], tableNamesMap };
+  }
+  return relational;
+}
+
 export function createDatabase(pool: PoolLike): Database {
-  const db = drizzle(guarded(pool) as pg.Pool, { schema });
+  // What `drizzle(pool, { schema })` builds, but for the schema's config, made once.
+  const dialect = new PgDialect();
+  const config = relationalSchema();
+  const db: Database = new NodePgDatabase(dialect, new NodePgDriver(guarded(pool) as pg.Pool, dialect).createSession(config), config);
   // Each transaction's work runs knowing which one it is in, until that work is done. Not until
   // the COMMIT comes back: the transaction waits on nothing then, so what the work left running
   // may ask for a query, which waits for the transaction to end rather than for itself.
@@ -132,3 +162,5 @@ export function own<T extends Table>(db: Queryable, table: T): T {
   if (found === undefined) throw new Error(`no table ${getTableName(table)} in this database`);
   return found as T;
 }
+
+export { prepared } from './prepared.ts';

package/src/grants.ts

@@ -18,8 +18,9 @@ import { ACCESS_ACTIONS } from '@coffre/core/vault';
 import { and, asc, desc, eq, gt, inArray, isNull, like, lt, or, sql, type SQL } from 'drizzle-orm';
 
 import { tablesOf, type Queryable } from './database.ts';
+import { prepared } from './prepared.ts';
 import { tombstone, truth } from './dialect.ts';
-import { entryColumns, LOOK_BACK, newestAuthentic, newestVaultEntries, type Authenticity, type Newest } from './log.ts';
+import { entryColumns, newestAuthentic, newestVaultEntries, type Authenticity, type Newest } from './log.ts';
 
 /**
  * One grant, as `vault_grants` holds it: on a project (`environmentId`
@@ -46,20 +47,24 @@ export async function readGrants(
   db: Queryable,
   filter: { principal?: string; liveAt?: number } = {},
 ): Promise<GrantRow[]> {
+  // A member's grants, which every check reads, built once (`prepared`); any other filter, as asked.
+  const rows = filter.principal !== undefined && filter.liveAt === undefined
+    ? await grantsOf(db, { principal: filter.principal })
+    : await grantRows(db, filter.principal === undefined ? undefined : eq(tablesOf(db).vaultGrants.principal, filter.principal), filter.liveAt);
+  return rows.map(({ grant, environmentProjectId }) => ({ ...grant, projectId: grant.projectId ?? environmentProjectId }));
+}
+
+function grantRows(db: Queryable, principal: SQL | undefined, liveAt?: number) {
   const { vaultGrants, environments } = tablesOf(db);
-  const rows = await db
+  return db
     .select({ grant: vaultGrants, environmentProjectId: environments.projectId })
     .from(vaultGrants)
     .leftJoin(environments, eq(environments.id, vaultGrants.environmentId))
-    .where(
-      and(
-        filter.principal === undefined ? undefined : eq(vaultGrants.principal, filter.principal),
-        filter.liveAt === undefined ? undefined : or(isNull(vaultGrants.expiresAt), gt(vaultGrants.expiresAt, filter.liveAt)),
-      ),
-    );
-  return rows.map(({ grant, environmentProjectId }) => ({ ...grant, projectId: grant.projectId ?? environmentProjectId }));
+    .where(and(principal, liveAt === undefined ? undefined : or(isNull(vaultGrants.expiresAt), gt(vaultGrants.expiresAt, liveAt))));
 }
 
+const grantsOf = prepared((db) => grantRows(db, eq(tablesOf(db).vaultGrants.principal, sql.placeholder('principal'))));
+
 /** Add a grant; an environment's row names only the environment. */
 export async function insertGrant(db: Queryable, grant: GrantRow): Promise<void> {
   const { vaultGrants } = tablesOf(db);
@@ -289,35 +294,43 @@ export async function reportStands(db: Queryable, principal: string, check: Auth
   const access = await newestAccess(db, principal, check);
   if (access === 'unreached') return true;
   const after = typeof access === 'string' ? -1n : access.seq;
-  const report = await newestAuthentic((before) => tamperReportsAbout(db, principal, LOOK_BACK.page, after, before), check);
+  const report = await newestAuthentic((limit, before) => tamperReportsAbout(db, principal, limit, after, before), check);
   return report === 'unreached' || typeof report !== 'string';
 }
 
 /** The newest access entry about `principal` that `check` finds the vault's own. */
 export function newestAccess(db: Queryable, principal: string, check: Authenticity): Promise<Newest> {
-  return newestAuthentic((before) => accessEntriesAbout(db, principal, LOOK_BACK.page, before), check);
+  return newestAuthentic((limit, before) => accessEntriesAbout(db, principal, limit, before), check);
 }
 
 /** Up to `limit` of the vault's allowed access entries about `principal` before `before` (the newest when undefined), newest first. */
 export async function accessEntriesAbout(db: Queryable, principal: string, limit: number, before?: bigint): Promise<StoredEntry[]> {
+  const rows = before === undefined ? await newestAccessEntries(db, { principal, limit }) : await accessEntriesBefore(db, { principal, limit, before });
+  return rows as StoredEntry[];
+}
+
+function accessEntries(db: Queryable, before?: SQL) {
   const { auditLog } = tablesOf(db);
-  const rows = await db
+  return db
     .select(entryColumns(db))
     .from(auditLog)
     .where(
       and(
         eq(auditLog.author, 'vault'),
-        eq(auditLog.subjectPrincipal, principal),
+        eq(auditLog.subjectPrincipal, sql.placeholder('principal')),
         inArray(auditLog.action, [...ACCESS_ACTIONS]),
         eq(auditLog.decision, 'allow'),
-        before === undefined ? undefined : lt(auditLog.seq, before),
+        before,
       ),
     )
     .orderBy(desc(auditLog.seq))
-    .limit(limit);
-  return rows as StoredEntry[];
+    .limit(sql.placeholder('limit'));
 }
 
+// What every check of a member reads first, built once (`prepared`).
+const newestAccessEntries = prepared((db) => accessEntries(db));
+const accessEntriesBefore = prepared((db) => accessEntries(db, lt(tablesOf(db).auditLog.seq, sql.placeholder('before'))));
+
 /**
  * Up to `limit` of the vault's reports that `principal`'s row was changed
  * around it (`TAMPER_CODES`), after `after` and before `before` (the newest

package/src/log.ts

@@ -1,8 +1,9 @@
 import { GENESIS_HASH, sealEntry, type LogFields, type LogKey, type StoredEntry } from '@coffre/core/audit';
-import { and, asc, desc, eq, lt, sql, type SQL } from 'drizzle-orm';
+import { and, asc, count, desc, eq, gt, gte, lt, lte, sql, type SQL } from 'drizzle-orm';
 
 import { afterCommit } from './commits.ts';
 import { tablesOf, type Queryable, type Transaction } from './database.ts';
+import { prepared } from './prepared.ts';
 import { clockMillis, forUpdate } from './dialect.ts';
 
 /**
@@ -99,18 +100,19 @@ export function forgetLogHeads(): void {
  * again in the same transaction is free.
  */
 export async function lockLogHead(tx: Transaction): Promise<{ nextSeq: bigint; headHash: Buffer }> {
-  const { auditChainHead } = tablesOf(tx);
-  const [head] = await forUpdate(
-    tx,
-    tx
-      .select({ nextSeq: auditChainHead.nextSeq, headHash: auditChainHead.headHash })
-      .from(auditChainHead)
-      .where(eq(auditChainHead.onlyRow, true)),
-  );
+  const [head] = await lockedHead(tx);
   if (head === undefined) throw new Error('audit_chain_head is missing; refusing to write an unchained entry');
   return head;
 }
 
+const lockedHead = prepared((db) => {
+  const { auditChainHead } = tablesOf(db);
+  return forUpdate(
+    db,
+    db.select({ nextSeq: auditChainHead.nextSeq, headHash: auditChainHead.headHash }).from(auditChainHead).where(eq(auditChainHead.onlyRow, true)),
+  );
+});
+
 /**
  * Append `entries` under `key`. `check`, when given, runs once the head is
  * locked and before anything is written: a writer's own condition on the
@@ -129,12 +131,8 @@ export async function appendEntries(
   // Every append queues here, if its transaction has not already.
   const head = await lockLogHead(tx);
   await check?.(tx);
-  const [{ now }] = await tx.select({ now: clockMillis(tx) }).from(auditChainHead);
-  const [last] = await tx
-    .select({ seq: auditLog.seq, hash: auditLog.hash })
-    .from(auditLog)
-    .orderBy(desc(auditLog.seq))
-    .limit(1);
+  const [{ now }] = await clockNow(tx);
+  const [last] = await lastEntry(tx);
 
   const expected = last === undefined ? { nextSeq: 0n, headHash: GENESIS_HASH } : { nextSeq: last.seq + 1n, headHash: last.hash };
   if (head.nextSeq !== expected.nextSeq || !head.headHash.equals(expected.headHash)) {
@@ -188,6 +186,13 @@ export async function appendEntries(
   return { seqStart: head.nextSeq, ...written, occurredAt: now };
 }
 
+const clockNow = prepared((db) => db.select({ now: clockMillis(db) }).from(tablesOf(db).auditChainHead));
+
+const lastEntry = prepared((db) => {
+  const { auditLog } = tablesOf(db);
+  return db.select({ seq: auditLog.seq, hash: auditLog.hash }).from(auditLog).orderBy(desc(auditLog.seq)).limit(1);
+});
+
 // --- reading the vault's entries back ---------------------------------------------
 
 /** An entry's columns, as the chain's codec reads them (`StoredEntry`). */
@@ -257,6 +262,33 @@ export async function withinBytes(
   return { from: sizes[0]!.seq, to: sizes[count - 1]!.seq, cut: count < sizes.length, count };
 }
 
+/**
+ * The first entry missing from the log up to `seq`, and the one found in
+ * its place, or null when every one is there. Seqs are the primary key, so
+ * a stretch is whole exactly when its count is its length: one pass over
+ * the key's index, never the entries. Only a log with a gap pays for more,
+ * a count per halving to find where.
+ *
+ *   entries 0..9, 4 cut:  { expected: 4n, found: 5n }
+ */
+export async function missingEntry(db: Queryable, seq: bigint): Promise<{ expected: bigint; found: bigint | null } | null> {
+  const { auditLog } = tablesOf(db);
+  const whole = async (to: bigint) => {
+    const [{ n }] = await db.select({ n: count() }).from(auditLog).where(and(gte(auditLog.seq, 0n), lte(auditLog.seq, to)));
+    return BigInt(n) === to + 1n;
+  };
+  if (seq < 0n || (await whole(seq))) return null;
+  // The first stretch from 0 that is not whole ends at the missing entry.
+  let [low, high] = [0n, seq];
+  while (low < high) {
+    const middle = (low + high) / 2n;
+    if (await whole(middle)) low = middle + 1n;
+    else high = middle;
+  }
+  const [next] = await db.select({ seq: auditLog.seq }).from(auditLog).where(gt(auditLog.seq, low)).orderBy(asc(auditLog.seq)).limit(1);
+  return { expected: low, found: (next?.seq as bigint | undefined) ?? null };
+}
+
 /**
  * How a reader tells the vault's own entries from those forged in its name:
  * by their MAC, which only the vault holds the key to check. Each it finds
@@ -266,38 +298,42 @@ export type Authenticity = { authentic: (entry: StoredEntry) => boolean; forged:
 
 /** Up to `limit` of the entries in the vault's name, allowed, of one `action`, before `before` (the newest when undefined), newest first. */
 export async function newestVaultEntries(db: Queryable, action: string, limit: number, before?: bigint): Promise<StoredEntry[]> {
+  const rows = before === undefined ? await newestEntries(db, { action, limit }) : await entriesBefore(db, { action, limit, before });
+  return rows as StoredEntry[];
+}
+
+function vaultEntries(db: Queryable, before?: SQL) {
   const { auditLog } = tablesOf(db);
-  const rows = await db
+  return db
     .select(entryColumns(db))
     .from(auditLog)
-    .where(
-      and(
-        eq(auditLog.author, 'vault'),
-        eq(auditLog.action, action),
-        eq(auditLog.decision, 'allow'),
-        before === undefined ? undefined : lt(auditLog.seq, before),
-      ),
-    )
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, sql.placeholder('action')), eq(auditLog.decision, 'allow'), before))
     .orderBy(desc(auditLog.seq))
-    .limit(limit);
-  return rows as StoredEntry[];
+    .limit(sql.placeholder('limit'));
 }
 
+const newestEntries = prepared((db) => vaultEntries(db));
+const entriesBefore = prepared((db) => vaultEntries(db, lt(tablesOf(db).auditLog.seq, sql.placeholder('before'))));
+
 /**
  * The number of the newest entry in the vault's name, allowed, of one
  * `action`, or null for none: whether one was appended since, and nothing
  * of what it says, so its MAC is not checked. One indexed read.
  */
 export async function newestVaultSeq(db: Queryable, action: string): Promise<bigint | null> {
+  const [row] = await newestSeq(db, { action });
+  return (row?.seq as bigint | undefined) ?? null;
+}
+
+const newestSeq = prepared((db) => {
   const { auditLog } = tablesOf(db);
-  const [row] = await db
+  return db
     .select({ seq: auditLog.seq })
     .from(auditLog)
-    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, action), eq(auditLog.decision, 'allow')))
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, sql.placeholder('action')), eq(auditLog.decision, 'allow')))
     .orderBy(desc(auditLog.seq))
     .limit(1);
-  return (row?.seq as bigint | undefined) ?? null;
-}
+});
 
 /** How many entries in its name the vault reads back, a page at a time, for its own newest of a kind (`newestAuthentic`). */
 export const LOOK_BACK = { page: 32, pages: 32 };
@@ -307,20 +343,24 @@ export type Newest = StoredEntry | 'none' | 'forged' | 'unreached';
 
 /**
  * The newest of the entries `page` reads, newest first and before a seq,
- * that `check` finds authentic, read back a page at a time: 'none' when
- * there are none at all, 'forged' when every one is in the vault's name but
- * not its own, and 'unreached' once it has read LOOK_BACK such entries
- * (1024), whether or not more are left.
+ * that `check` finds authentic: the newest alone first, which it is unless
+ * entries were forged in the vault's name since, then back a page at a
+ * time. 'none' when there are none at all, 'forged' when every one is in
+ * the vault's name but not its own, and 'unreached' once it has read
+ * LOOK_BACK such entries (1024), whether or not more are left.
  */
-export async function newestAuthentic(page: (before: bigint | undefined) => Promise<StoredEntry[]>, check: Authenticity): Promise<Newest> {
+export async function newestAuthentic(page: (limit: number, before: bigint | undefined) => Promise<StoredEntry[]>, check: Authenticity): Promise<Newest> {
+  const most = LOOK_BACK.page * LOOK_BACK.pages;
+  let read = 0;
   let before: bigint | undefined;
-  for (let read = 0; read < LOOK_BACK.pages; read += 1) {
-    const entries = await page(before);
+  for (let limit = 1; read < most; limit = Math.min(LOOK_BACK.page, most - read)) {
+    const entries = await page(limit, before);
     for (const entry of entries) {
       if (check.authentic(entry)) return entry;
       check.forged(entry);
     }
-    if (entries.length < LOOK_BACK.page) return before === undefined && entries.length === 0 ? 'none' : 'forged';
+    read += entries.length;
+    if (entries.length < limit) return read === 0 ? 'none' : 'forged';
     before = entries.at(-1)!.seq;
   }
   return 'unreached';

package/src/prepared.ts

@@ -0,0 +1,60 @@
+import type { Query } from 'drizzle-orm';
+
+import { tablesOf, type Queryable } from './database.ts';
+import { engineOf } from './dialect.ts';
+
+/** What Drizzle works out from a select builder before it can run it, once per dialect. */
+type Built = { query: Query; fields: unknown; joinsNotNullableMap: unknown; engine: 'postgres' | 'sqlite' };
+
+/** The part of a select builder `prepared` reads, once. */
+type Select = PromiseLike<unknown> & { toSQL(): Query; prepare(...name: never[]): unknown };
+
+/**
+ * A select built once per process, or once per isolate on Workers, and run
+ * with new values each time. Drizzle rebuilds a query's SQL from its
+ * builder at every run, and that was most of a short query's CPU; this
+ * builds it from `build` the first time a database of its dialect asks,
+ * then hands the SQL and its columns to that call's own session
+ * (`session.prepareQuery`), which binds `values` to the placeholders
+ * (`sql.placeholder`) and maps the rows as the builder would.
+ *
+ * `build` must not depend on anything but the database's dialect, and the
+ * values go to the driver as they are, not through a column's encoding:
+ * strings, numbers, bigints and bytes.
+ *
+ *   const member = prepared((db) => db.select().from(tablesOf(db).vaultMembers).where(eq(…, sql.placeholder('principal'))));
+ *   const [row] = await member(db, { principal });
+ */
+export function prepared<Q extends Select>(
+  build: (db: Queryable) => Q,
+): (db: Queryable, values?: Record<string, unknown>) => Promise<Awaited<Q>> {
+  // By the dialect's tables: one Postgres build, one SQLite build.
+  const builds = new WeakMap<object, Built>();
+  return (db, values = {}) => {
+    const tables = tablesOf(db);
+    let built = builds.get(tables);
+    if (built === undefined) {
+      const builder = build(db);
+      // Drizzle's own preparation, which runs nothing, says which columns come back and which joins may be null.
+      // Unnamed on Postgres: no statement is prepared on the server, whose connections a call does not keep.
+      const { fields, joinsNotNullableMap } = (builder as unknown as { prepare(): { fields: unknown; joinsNotNullableMap: unknown } }).prepare();
+      built = { query: builder.toSQL(), fields, joinsNotNullableMap, engine: engineOf(db) };
+      builds.set(tables, built);
+    }
+    const session = (db as unknown as { session: Session }).session;
+    const query = built.engine === 'sqlite'
+      ? session.prepareQuery(built.query, built.fields, 'all', true)
+      : session.prepareQuery(built.query, built.fields, undefined, true);
+    query.joinsNotNullableMap = built.joinsNotNullableMap;
+    return (built.engine === 'sqlite' ? query.all(values) : query.execute(values)) as Promise<Awaited<Q>>;
+  };
+}
+
+/** Drizzle's session, Postgres's or SQLite's, as `prepared` calls it. */
+type Session = {
+  prepareQuery(query: Query, fields: unknown, nameOrMethod: string | undefined, isResponseInArrayMode: boolean): {
+    joinsNotNullableMap: unknown;
+    execute(values: Record<string, unknown>): Promise<unknown>;
+    all(values: Record<string, unknown>): Promise<unknown>;
+  };
+};