better-supabase 0.0.0 → 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,751 @@
+import { n as dbError } from "../errors-Bl3rkOzo.js";
+import { i as ok } from "../result-DWXatkd6.js";
+import { t as BetterSupabase } from "../define-QGkq04oe.js";
+import { r as resolveConfig } from "../config-D-aR2ZoN.js";
+import { t as ENV_VARIABLES } from "../env-BEToab0I.js";
+import { n as postgresExecutor } from "../executor-Ceq60hPM.js";
+import { o as toCloudEvents } from "../events-BuzTgn2D.js";
+import { n as isSeed, t as defineSeed } from "../seed-CzecODcJ.js";
+import { createClient } from "@supabase/supabase-js";
+//#region src/testing/jwt.ts
+const encoder = new TextEncoder();
+function base64url(input) {
+	const bytes = typeof input === "string" ? encoder.encode(input) : input;
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/**
+* Signs an HS256 access token the local Supabase stack accepts. Test-only:
+* production tokens come from Supabase Auth.
+*/
+async function signTestJwt(secret, claims) {
+	const { expiresIn = 3600, ...rest } = claims;
+	const now = Math.floor(Date.now() / 1e3);
+	const payload = {
+		aud: "authenticated",
+		role: "authenticated",
+		aal: "aal1",
+		iat: now,
+		exp: now + expiresIn,
+		...rest
+	};
+	const header = base64url(JSON.stringify({
+		alg: "HS256",
+		typ: "JWT"
+	}));
+	const body = base64url(JSON.stringify(payload));
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(`${header}.${body}`));
+	return `${header}.${body}.${base64url(new Uint8Array(signature))}`;
+}
+function base64urlDecode(input) {
+	const binary = atob(input.replaceAll("-", "+").replaceAll("_", "/"));
+	return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+/**
+* Accepts `signTestJwt` tokens as users, for API servers tested against the
+* local stack: `createServer(sb, { auth: { resolvers: [localAuth(secret)] } })`.
+* Tokens that are not HS256-signed with `secret` fall through. Test-only.
+*/
+function localAuth(secret) {
+	const key = crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["verify"]);
+	return {
+		name: "local-hs256",
+		async resolve(request) {
+			const token = /^Bearer (.+)$/i.exec(request.headers.get("authorization") ?? "")?.[1];
+			const [header, body, signature] = token?.split(".") ?? [];
+			if (!token || !header || !body || !signature) return void 0;
+			if (!await crypto.subtle.verify("HMAC", await key, base64urlDecode(signature), encoder.encode(`${header}.${body}`)).catch(() => false)) return void 0;
+			const claims = JSON.parse(new TextDecoder().decode(base64urlDecode(body)));
+			if (typeof claims.exp === "number" && claims.exp * 1e3 < Date.now()) return {
+				kind: "invalid",
+				error: dbError("unauthorized", "The token has expired")
+			};
+			return {
+				kind: "user",
+				token,
+				claims,
+				user: {
+					id: claims.sub,
+					...typeof claims.role === "string" ? { role: claims.role } : {},
+					...typeof claims.email === "string" ? { email: claims.email } : {}
+				},
+				source: "bearer",
+				expiresAt: typeof claims.exp === "number" ? claims.exp : null
+			};
+		}
+	};
+}
+/** An in-memory ES256 key pair that signs tokens like Supabase Auth's asymmetric keys. */
+async function createTestSigner() {
+	const pair = await crypto.subtle.generateKey({
+		name: "ECDSA",
+		namedCurve: "P-256"
+	}, true, ["sign", "verify"]);
+	const kid = crypto.randomUUID();
+	return {
+		jwks: { keys: [{
+			...await crypto.subtle.exportKey("jwk", pair.publicKey),
+			kid,
+			alg: "ES256",
+			use: "sig"
+		}] },
+		async sign(claims) {
+			const { expiresIn = 3600, ...rest } = claims;
+			const now = Math.floor(Date.now() / 1e3);
+			const payload = {
+				aud: "authenticated",
+				role: "authenticated",
+				aal: "aal1",
+				iat: now,
+				exp: now + expiresIn,
+				...rest
+			};
+			const header = base64url(JSON.stringify({
+				alg: "ES256",
+				typ: "JWT",
+				kid
+			}));
+			const body = base64url(JSON.stringify(payload));
+			const signature = await crypto.subtle.sign({
+				name: "ECDSA",
+				hash: "SHA-256"
+			}, pair.privateKey, encoder.encode(`${header}.${body}`));
+			return `${header}.${body}.${base64url(new Uint8Array(signature))}`;
+		}
+	};
+}
+//#endregion
+//#region src/testing/as-user.ts
+/** The local CLI stack's default JWT secret. */
+const LOCAL_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long";
+function env$1(...names) {
+	if (typeof process === "undefined") return void 0;
+	for (const name of names) {
+		const value = process.env[name];
+		if (value) return value;
+	}
+}
+/**
+* A test user against the local stack: a signed token and repositories that
+* run as that user, for live RLS tests.
+*
+* ```ts
+* const alice = await asUser(sb, { sub: aliceId, org_id: acme });
+* expect(await alice.db.customers.count().orThrow()).toBe(3);
+* ```
+*/
+async function asUser(sb, claims, stack = {}) {
+	const url = stack.url ?? env$1(...ENV_VARIABLES.url) ?? "http://127.0.0.1:54321";
+	const publishableKey = stack.publishableKey ?? env$1(...ENV_VARIABLES.publishableKey, "SUPABASE_ANON_KEY");
+	if (!publishableKey) throw new TypeError("asUser needs publishableKey or $SUPABASE_PUBLISHABLE_KEY. Run `better-supabase env` to write it to .env.local.");
+	const token = await signTestJwt(stack.jwtSecret ?? env$1("SUPABASE_JWT_SECRET") ?? "super-secret-jwt-token-with-at-least-32-characters-long", claims);
+	const full = {
+		role: "authenticated",
+		...claims
+	};
+	const context = {
+		actor: {
+			id: claims.sub,
+			kind: "user",
+			role: full.role ?? "authenticated",
+			...typeof claims.email === "string" ? { email: claims.email } : {}
+		},
+		claims: full
+	};
+	const supabase = createClient(url, publishableKey, { accessToken: () => Promise.resolve(token) });
+	return {
+		token,
+		claims: full,
+		supabase,
+		db: sb.connect(supabase, context),
+		sql: stack.postgres ? sb.connect(postgresExecutor(stack.postgres.asUser(full)), context) : void 0
+	};
+}
+//#endregion
+//#region src/testing/budget.ts
+function isPrefetch(response) {
+	const headers = response.request().headers();
+	return headers["next-router-prefetch"] !== void 0 || headers["purpose"] === "prefetch" || (headers["sec-purpose"]?.includes("prefetch") ?? false);
+}
+function settle(promise, ms) {
+	let timer;
+	return Promise.race([promise, new Promise((done) => {
+		timer = setTimeout(done, ms);
+	})]).finally(() => clearTimeout(timer));
+}
+/**
+* Measures every document and RSC navigation response during `during` and
+* fails when one render makes more database calls or waves than allowed.
+* Needs `createNext(sb, { debug })` and `next.debugRoute()` in the app.
+*/
+async function expectDbBudget(page, expectation) {
+	const seen = [];
+	const listener = (response) => {
+		const headers = response.headers();
+		const id = headers["x-bs-request-id"];
+		const stats = headers["x-bs-stats"];
+		if (!id || !stats || !expectation.prefetches && isPrefetch(response)) return;
+		seen.push({
+			response,
+			id,
+			url: new URL(stats, response.url()).href
+		});
+	};
+	page.on("response", listener);
+	try {
+		await (expectation.during ? expectation.during() : page.reload());
+	} finally {
+		page.off("response", listener);
+	}
+	if (seen.length === 0) throw new Error("expectDbBudget: no response carried x-bs-request-id. Enable createNext(sb, { debug: { enabled: true } }) and run the proxy.");
+	await Promise.all(seen.map(({ response }) => settle(response.finished(), expectation.timeoutMs ?? 1e4)));
+	const renders = [];
+	for (const { response, id, url } of seen) {
+		const reply = await page.request.get(url);
+		if (!reply.ok()) throw new Error(`expectDbBudget: ${url} answered ${reply.status()}. Mount next.debugRoute() at that path.`);
+		renders.push({
+			url: response.url(),
+			requestId: id,
+			stats: await reply.json()
+		});
+	}
+	const over = renders.filter(({ stats }) => expectation.maxCalls !== void 0 && stats.calls > expectation.maxCalls || expectation.maxWaves !== void 0 && stats.waves > expectation.maxWaves);
+	if (over.length > 0) {
+		const lines = over.map(({ url, stats }) => `  ${url}: ${stats.calls} calls in ${stats.waves} waves (${stats.tables.join(", ")})`);
+		throw new Error(`expectDbBudget: over the budget of ${expectation.maxCalls ?? "∞"} calls and ${expectation.maxWaves ?? "∞"} waves:\n${lines.join("\n")}`);
+	}
+	return renders;
+}
+//#endregion
+//#region src/testing/conformance.ts
+/** Thrown by a conformance kit when any check fails. Lists every failure, not just the first. */
+var ConformanceError = class extends Error {
+	report;
+	constructor(report) {
+		const failed = report.checks.filter((check) => !check.ok);
+		super(`${report.subject} failed ${failed.length} of ${report.checks.length} conformance checks:\n${failed.map((check) => `  - ${check.name}: ${check.message ?? "failed"}`).join("\n")}`);
+		this.name = "ConformanceError";
+		this.report = report;
+	}
+};
+var Violation = class extends Error {};
+function expect(condition, message) {
+	if (!condition) throw new Violation(message);
+}
+async function conform(subject, checks) {
+	const results = [];
+	for (const entry of checks) {
+		if (!entry) continue;
+		const [name, run] = entry;
+		try {
+			await run();
+			results.push({
+				name,
+				ok: true
+			});
+		} catch (cause) {
+			const message = cause instanceof Violation ? cause.message : `threw ${cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause)}`;
+			results.push({
+				name,
+				ok: false,
+				message
+			});
+		}
+	}
+	const report = {
+		subject,
+		checks: results
+	};
+	if (results.some((check) => !check.ok)) throw new ConformanceError(report);
+	return report;
+}
+function deepFreeze(value) {
+	if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const key of Reflect.ownKeys(value)) deepFreeze(value[key]);
+	}
+	return value;
+}
+const frozenCopy = (value) => deepFreeze(structuredClone(value));
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const recorder = (ops) => ({
+	name: "recorder",
+	execute: (op) => {
+		ops.push(op);
+		return Promise.resolve(ok({
+			rows: [],
+			count: 0
+		}));
+	}
+});
+/** The operation `run` sends to the executor, built by `sb` without touching a database. */
+async function captureOp(sb, run) {
+	const ops = [];
+	await run(sb.connect(recorder(ops)));
+	const [op] = ops;
+	if (!op) throw new Error("the repository call did not reach the executor");
+	return op;
+}
+function tableKey(sb, table) {
+	const key = table ?? Object.keys(sb.meta.tables)[0];
+	if (!key || !(key in sb.meta.tables)) throw new TypeError(`better-supabase: unknown table "${String(key)}"`);
+	return key;
+}
+const hasName = (subject) => ["has a name", () => expect(typeof subject.name === "string" && subject.name.length > 0, "name must be a non-empty string")];
+/**
+* Proves an `Executor` meets the contract: rows keyed by the selection's
+* aliases, counts, `aborted` errors, failures returned as `Result`s rather
+* than thrown, and (with `create`) a write round trip.
+*
+* ```ts
+* it('conforms', () => testExecutor(myExecutor, { sb, table: 'tags', create: { name: 'x' } }));
+* ```
+*/
+function testExecutor(executor, options) {
+	const { sb } = options;
+	const table = tableKey(sb, options.table);
+	const context = { errorMappers: [] };
+	const read = () => captureOp(sb, (db) => db[table].findMany({ limit: 2 }));
+	const create = options.create;
+	return conform(`Executor "${executor.name}"`, [
+		hasName(executor),
+		["reads rows keyed by the selection aliases", async () => {
+			const op = await read();
+			const result = await executor.execute(op, context);
+			expect(result.ok, `select failed: ${result.ok ? "" : result.error.message}`);
+			expect(Array.isArray(result.data.rows), "rows must be an array");
+			expect(result.data.rows.length <= 2, `limit 2 returned ${result.data.rows.length} rows`);
+			expect(result.data.count === null || typeof result.data.count === "number", "count must be a number or null");
+			if (op.kind !== "select") return;
+			const aliases = new Set(op.selection.columns.map((column) => column.alias));
+			for (const row of result.data.rows) {
+				const extra = Object.keys(row).filter((key) => !aliases.has(key));
+				expect(extra.length === 0, `rows must use selection aliases; got ${extra.join(", ")}`);
+			}
+		}],
+		["counts rows", async () => {
+			const op = await captureOp(sb, (db) => db[table].count());
+			const result = await executor.execute(op, context);
+			expect(result.ok, `count failed: ${result.ok ? "" : result.error.message}`);
+			expect(typeof result.data.count === "number" && result.data.count >= 0, "count must be a number");
+		}],
+		["returns an aborted error for an aborted signal", async () => {
+			const controller = new AbortController();
+			controller.abort();
+			const result = await executor.execute(await read(), {
+				...context,
+				signal: controller.signal
+			});
+			expect(!result.ok, "an aborted request must fail");
+			expect(result.error.kind === "aborted", `expected kind "aborted", got "${result.error.kind}"`);
+		}],
+		["returns failures as results instead of throwing", async () => {
+			const op = await read();
+			const missing = {
+				...op,
+				table: {
+					...op.table,
+					name: "__better_supabase_missing__"
+				}
+			};
+			const result = await executor.execute(missing, context);
+			expect(!result.ok, "a missing table must fail");
+			expect(typeof result.error.kind === "string" && typeof result.error.message === "string", "errors must be DbErrors");
+		}],
+		executor.rpc && ["returns rpc failures as results", async () => {
+			expect(!(await executor.rpc("__better_supabase_missing__", {}, {
+				...context,
+				schema: "public"
+			})).ok, "calling a missing function must fail");
+		}],
+		executor.functionSources && ["reads from SelectOp.source instead of the table", async () => {
+			const op = await read();
+			if (op.kind !== "select") return;
+			expect(!(await executor.execute({
+				...op,
+				source: {
+					schema: op.table.schema,
+					name: "__better_supabase_missing__",
+					args: {}
+				}
+			}, context)).ok, "a missing source function must fail; reading the table ignores source");
+		}],
+		executor.batch && ["batch returns one result per operation, in order", async () => {
+			const rows = await read();
+			const count = await captureOp(sb, (db) => db[table].count());
+			const missing = {
+				...rows,
+				table: {
+					...rows.table,
+					name: "__better_supabase_missing__"
+				}
+			};
+			const results = await executor.batch([
+				rows,
+				count,
+				missing
+			], context);
+			expect(results.length === 3, `expected 3 results, got ${results.length}`);
+			const [first, second, third] = results;
+			expect(first?.ok === true && Array.isArray(first.data.rows), "the first operation must return rows");
+			expect(second?.ok === true && typeof second.data.count === "number", "the second operation must return a count");
+			expect(third?.ok === false, "a failing operation must fail on its own, as a result");
+		}],
+		create && ["round-trips a write", async () => {
+			const repository = sb.connect(executor)[table];
+			const created = await repository.create(create);
+			expect(created.ok, `create failed: ${JSON.stringify(created.error)}`);
+			const row = created.data;
+			for (const [key, value] of Object.entries(create)) expect(same(row[key], value), `created row has ${key} = ${JSON.stringify(row[key])}`);
+			const [primary] = sb.meta.tables[table].primaryKey;
+			expect(primary, "write checks need a table with a primary key");
+			const removed = await repository.delete(row[primary]);
+			expect(removed.ok, `delete failed: ${JSON.stringify(removed.error)}`);
+			const again = await repository.findFirst({ where: { [primary]: row[primary] } });
+			expect(again.ok && again.data === null, "the deleted row is still readable");
+		}]
+	]);
+}
+/**
+* Proves a `CacheAdapter` accepts table and row targets, repeated and
+* concurrent calls, and never mutates its input.
+*/
+function testCacheAdapter(adapter, options = {}) {
+	const table = options.table ?? "customers";
+	const invalidate = (target) => Promise.resolve(adapter.invalidate(deepFreeze(target)));
+	return conform(`CacheAdapter "${adapter.name}"`, [
+		hasName(adapter),
+		["invalidates a table", () => invalidate({
+			table,
+			tables: [table],
+			ids: []
+		})],
+		["invalidates rows of a tenant", () => invalidate({
+			table,
+			tables: [table],
+			ids: ["1", "a,b"],
+			tenant: "org_1"
+		})],
+		["accepts repeated and concurrent calls", async () => {
+			await invalidate({
+				table,
+				tables: [table],
+				ids: ["1"]
+			});
+			await Promise.all(Array.from({ length: 10 }, (_, index) => invalidate({
+				table,
+				tables: [table],
+				ids: [String(index)]
+			})));
+		}],
+		["accepts tables it has never seen", () => invalidate({
+			table: "__better_supabase_unknown__",
+			tables: ["__better_supabase_unknown__"],
+			ids: []
+		})],
+		["invalidates tables reached through foreign keys", () => invalidate({
+			table,
+			tables: [table, `${table}_children`],
+			ids: ["1"]
+		})]
+	]);
+}
+/** Proves an `EventSink` accepts empty and full batches without mutating them, and delivers them when readable. */
+function testEventSink(sink, options = {}) {
+	const events = toCloudEvents({
+		table: "customers",
+		kind: "insert",
+		rows: [{
+			id: "1",
+			name: "Acme"
+		}, {
+			id: "2",
+			name: "Globex"
+		}],
+		context: { tenant: "org_1" }
+	}, { source: "/better-supabase/conformance" });
+	return conform("EventSink", [
+		["accepts an empty batch", () => sink.send(deepFreeze([]))],
+		["accepts a batch without mutating it", () => sink.send(frozenCopy(events))],
+		options.received && ["delivers every event", async () => {
+			const ids = new Set((await options.received()).map((event) => event.id));
+			const missing = events.filter((event) => !ids.has(event.id));
+			expect(missing.length === 0, `${missing.length} of ${events.length} events were not delivered`);
+		}]
+	]);
+}
+async function resolveSafely(resolver, request) {
+	try {
+		return await resolver.resolve(request);
+	} catch (cause) {
+		throw new Violation(`resolve() threw: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+}
+/**
+* Proves an `AuthResolver` passes on requests it doesn't understand, fails
+* closed (`invalid`, never anon) on bad credentials, and never throws.
+*/
+function testAuthResolver(resolver, options) {
+	return conform(`AuthResolver "${resolver.name}"`, [
+		hasName(resolver),
+		["passes on requests without its credentials", async () => {
+			const state = await resolveSafely(resolver, options.unrelated ?? new Request("https://example.com/"));
+			expect(state === void 0, `expected undefined, got kind "${state?.kind}"`);
+		}],
+		["fails closed on invalid credentials", async () => {
+			expect(options.invalid.length > 0, "pass at least one invalid request");
+			for (const request of options.invalid) {
+				const state = await resolveSafely(resolver, request);
+				expect(state?.kind === "invalid", `expected kind "invalid", got "${state?.kind ?? "undefined"}"`);
+				expect(typeof state.error.kind === "string", "invalid states carry a DbError");
+			}
+		}],
+		options.valid && ["resolves valid credentials", async () => {
+			for (const { request, userId } of options.valid) {
+				const state = await resolveSafely(resolver, request);
+				expect(state?.kind === "user" || state?.kind === "service", `expected a user or service, got "${state?.kind}"`);
+				if (userId !== void 0) expect(state.kind === "user" && state.user.id === userId, `expected user ${userId}`);
+			}
+		}]
+	]);
+}
+function relativeImport(from, to) {
+	const fromParts = from.split("/").slice(0, -1);
+	const toParts = to.split("/");
+	let common = 0;
+	while (common < fromParts.length && fromParts[common] === toParts[common]) common += 1;
+	const path = [...Array.from({ length: fromParts.length - common }, () => ".."), ...toParts.slice(common)].join("/");
+	return path.startsWith(".") ? path : `./${path}`;
+}
+const EMPTY_INTROSPECTION = {
+	version: 1,
+	schemas: [],
+	tables: [],
+	foreignTables: [],
+	views: [],
+	materializedViews: [],
+	columns: [],
+	primaryKeys: [],
+	relationships: [],
+	functions: [],
+	types: []
+};
+/** Proves a `Generator` writes relative, unique paths, is deterministic and doesn't mutate its input. */
+function testGenerator(generator, options) {
+	const config = options.config ?? resolveConfig({}, "/project");
+	const input = () => ({
+		meta: frozenCopy(options.meta),
+		introspection: frozenCopy(options.introspection ?? EMPTY_INTROSPECTION),
+		extras: frozenCopy(options.extras ?? {
+			tables: [],
+			buckets: [],
+			realtime: []
+		}),
+		config,
+		output: `${config.root}/${config.output}`,
+		importPath: (from, to) => relativeImport(from, to)
+	});
+	return conform(`Generator "${generator.name}"`, [
+		hasName(generator),
+		["writes files inside the project", async () => {
+			const files = await generator.generate(input());
+			expect(Array.isArray(files), "generate() must return an array");
+			for (const file of files) {
+				expect(typeof file.path === "string" && typeof file.contents === "string", "files need a path and contents");
+				expect(!file.path.startsWith("/") && !/^[A-Za-z]:/.test(file.path), `${file.path} must be relative`);
+				expect(!file.path.split(/[\\/]/).includes(".."), `${file.path} must stay inside the project`);
+			}
+			const paths = files.map((file) => file.path);
+			expect(new Set(paths).size === paths.length, "paths must be unique");
+		}],
+		["is deterministic and does not mutate its input", async () => {
+			const first = await generator.generate(input());
+			const second = await generator.generate(input());
+			expect(same(first, second), "two runs on the same input differ");
+		}]
+	]);
+}
+/**
+* Proves a `Plugin` targets API v1, installs cleanly, keeps `transformQuery`
+* and `beforeMutation` pure and deterministic, and keeps executors'
+* results intact when it wraps them.
+*/
+function testPlugin(plugin, options) {
+	const { sb } = options;
+	const table = tableKey(sb, options.table);
+	const context = options.context ?? {};
+	const hook = (op) => ({
+		table: op.table,
+		schema: sb.meta,
+		context,
+		options: {},
+		now: () => /* @__PURE__ */ new Date(0)
+	});
+	const create = options.create;
+	return conform(`Plugin "${plugin.name}"`, [
+		hasName(plugin),
+		["targets plugin API v1", () => expect(plugin.apiVersion === 1, `apiVersion is ${String(plugin.apiVersion)}`)],
+		["installs and builds repositories", () => {
+			const db = sb.use(plugin).connect(recorder([]), context);
+			for (const key of Object.keys(sb.meta.tables)) expect(db[key], `db.${key} is missing`);
+		}],
+		plugin.transformQuery && ["transformQuery is pure and deterministic", async () => {
+			const op = await captureOp(sb, (db) => db[table].findMany({ limit: 1 }));
+			const first = plugin.transformQuery(frozenCopy(op), hook(op));
+			const second = plugin.transformQuery(frozenCopy(op), hook(op));
+			expect(typeof first === "object" && first !== null && first.kind === op.kind, "must return an operation of the same kind");
+			expect(same(first, second), "two calls with the same input differ");
+		}],
+		plugin.beforeMutation && create && ["beforeMutation is pure and deterministic", async () => {
+			const op = await captureOp(sb, (db) => db[table].create(create));
+			if (op.kind === "select") throw new Violation("create did not produce a mutation");
+			const first = await plugin.beforeMutation(frozenCopy(op), hook(op));
+			const second = await plugin.beforeMutation(frozenCopy(op), hook(op));
+			expect(first.kind === op.kind, "must return a mutation of the same kind");
+			expect(same(first, second), "two calls with the same input differ");
+		}],
+		plugin.wrapExecutor && ["wrapExecutor keeps results intact", async () => {
+			const op = await captureOp(sb, (db) => db[table].findMany({ limit: 1 }));
+			const data = {
+				rows: [{ marker: "conformance" }],
+				count: 1
+			};
+			const wrapped = plugin.wrapExecutor({
+				name: "inner",
+				execute: () => Promise.resolve(ok(data))
+			});
+			expect(typeof wrapped.name === "string", "the wrapped executor needs a name");
+			const result = await wrapped.execute(op, { errorMappers: [] });
+			expect(result.ok && same(result.data, data), "the wrapped executor changed the result");
+		}],
+		plugin.mapError && ["mapError returns a DbError or undefined", () => {
+			const fallback = dbError("unexpected", "internal error");
+			const mapped = plugin.mapError({
+				code: "XX000",
+				message: "internal error"
+			}, fallback);
+			expect(mapped === void 0 || typeof mapped === "object" && typeof mapped.kind === "string", "must return a DbError or undefined");
+		}]
+	]);
+}
+//#endregion
+//#region src/testing/isolation.ts
+const scalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+function keyOf(table, row) {
+	return Object.fromEntries(table.primaryKey.map((column) => [column, row[column]]));
+}
+async function rowsOf(outcome) {
+	const result = await outcome;
+	if (!result.ok) throw new Error(result.error.message);
+	return Array.isArray(result.data) ? result.data : [result.data];
+}
+function env(names) {
+	if (typeof process === "undefined") return void 0;
+	for (const name of names) {
+		const value = process.env[name];
+		if (value) return value;
+	}
+}
+/**
+* Checks row-level security between two tenants against a running stack: for
+* each table, a user of one tenant must not select, insert, update or delete
+* the other tenant's rows. Runs without `sb`'s plugins, so the `tenant()`
+* plugin can't hide a missing policy. Throws a `ConformanceError` naming each
+* table and command that leaks; removes every row it created.
+*
+* ```ts
+* await expectTenantIsolation(sb, {
+*   tenants: [
+*     { id: ACME, claims: { sub: alice, org_id: ACME } },
+*     { id: GLOBEX, claims: { sub: bob, org_id: GLOBEX } },
+*   ],
+*   tables: {
+*     tags: {
+*       row: (tenant, n) => ({ organizationId: tenant.id, name: `iso-${n}` }),
+*       update: { name: 'changed' },
+*     },
+*   },
+* });
+* ```
+*/
+async function expectTenantIsolation(sb, options) {
+	const stack = options.stack ?? {};
+	const bare = new BetterSupabase(sb.schema);
+	const url = stack.url ?? env(ENV_VARIABLES.url) ?? "http://127.0.0.1:54321";
+	const secretKey = stack.secretKey ?? env(ENV_VARIABLES.secretKey);
+	if (!secretKey) throw new TypeError("expectTenantIsolation needs stack.secretKey or $SUPABASE_SECRET_KEY to seed rows.");
+	const admin = bare.connect(createClient(url, secretKey, { auth: {
+		persistSession: false,
+		autoRefreshToken: false
+	} }));
+	await options.seed?.();
+	const tenants = options.tenants;
+	const users = await Promise.all(tenants.map(async (tenant) => (await asUser(bare, tenant.claims, stack)).db));
+	const label = (tenant) => tenant.name ?? tenant.id;
+	const cleanup = [];
+	const reads = [];
+	const deletes = [];
+	try {
+		for (const [key, spec] of Object.entries(options.tables)) {
+			const table = bare.meta.tables[key];
+			if (!table || table.primaryKey.length === 0) throw new TypeError(`expectTenantIsolation: "${key}" is not a table with a primary key`);
+			const seeded = [];
+			for (const tenant of tenants) {
+				const [row] = await rowsOf(admin[key].create(spec.row(tenant, 0)));
+				const where = keyOf(table, row);
+				cleanup.push(() => admin[key].deleteMany({ where }));
+				seeded.push(row);
+			}
+			for (const [self, other] of [[0, 1], [1, 0]]) {
+				const user = users[self][key];
+				const who = label(tenants[self]);
+				const whose = `${label(tenants[other])}'s`;
+				const own = keyOf(table, seeded[self]);
+				const target = keyOf(table, seeded[other]);
+				const current = async () => (await rowsOf(admin[key].findMany({ where: target })))[0];
+				reads.push([`${key}: ${who} reads its own row`, async () => {
+					expect((await rowsOf(user.findMany({ where: own }))).length === 1, `${who} can't read its own row, so the other checks prove nothing; check its claims and memberships`);
+				}], [`${key}: ${who} can't select ${whose} rows`, async () => {
+					expect((await rowsOf(user.findMany({ where: target }))).length === 0, `select returned ${whose} row`);
+				}], [`${key}: ${who} can't insert ${whose} rows`, async () => {
+					const row = spec.row(tenants[other], 1);
+					const result = await user.create(row, { returning: false });
+					if (result.ok) {
+						const where = Object.fromEntries(Object.entries(row).filter(([, value]) => scalar(value)));
+						cleanup.push(() => admin[key].deleteMany({ where }));
+					}
+					expect(!result.ok, `insert of a row for ${whose} tenant succeeded`);
+					expect(result.error.kind === "forbidden", `insert failed with ${result.error.kind} (${result.error.message}), not an RLS error; check the row factory`);
+				}], [`${key}: ${who} can't update ${whose} rows`, async () => {
+					const before = await current();
+					const patch = spec.update;
+					expect(Object.entries(patch).some(([column, value]) => before?.[column] !== value), "update must change the row to detect a leak");
+					await user.updateMany({
+						where: target,
+						data: patch,
+						returning: false
+					});
+					const after = await current();
+					expect(Object.entries(patch).every(([column]) => after?.[column] === before?.[column]), `update changed ${whose} row`);
+				}]);
+				deletes.push([`${key}: ${who} can't delete ${whose} rows`, async () => {
+					await user.deleteMany({ where: target });
+					expect(await current() !== void 0, `delete removed ${whose} row`);
+				}]);
+			}
+		}
+		return await conform("Tenant isolation", [...reads, ...deletes]);
+	} finally {
+		for (const remove of cleanup.reverse()) await remove();
+	}
+}
+//#endregion
+export { ConformanceError, LOCAL_JWT_SECRET, asUser, createTestSigner, defineSeed, expectDbBudget, expectTenantIsolation, isSeed, localAuth, signTestJwt, testAuthResolver, testCacheAdapter, testEventSink, testExecutor, testGenerator, testPlugin };