@geekmidas/constructs 10.0.0-alpha.1 → 10.0.0-alpha.100

package/dist/adaptors/testing.cjs

@@ -1,27 +1,66 @@
-const require_chunk = require('../chunk-DWy1uDak.cjs');
-require('../construct-interface-BfjcOD_E.cjs');
-require('../Construct-roId57cU.cjs');
-const require_functions = require('../functions-DukjG8ov.cjs');
-require('../clone-Dy0cR2SZ.cjs');
-const require_Endpoint = require('../Endpoint-BBkV6l0k.cjs');
-const require_publisher = require('../publisher-CqGsXB2X.cjs');
-const require_processAudits = require('../processAudits-Bc8rz6Ev.cjs');
-const require_lazyAccessors = require('../lazyAccessors-DrJj8NpA.cjs');
-const require_HonoEndpointAdaptor = require('../HonoEndpointAdaptor-wMsCyMgt.cjs');
-const __geekmidas_errors = require_chunk.__toESM(require("@geekmidas/errors"));
-const __geekmidas_envkit = require_chunk.__toESM(require("@geekmidas/envkit"));
-const __geekmidas_services = require_chunk.__toESM(require("@geekmidas/services"));
-const __geekmidas_audit = require_chunk.__toESM(require("@geekmidas/audit"));
-const hono = require_chunk.__toESM(require("hono"));
-const msw = require_chunk.__toESM(require("msw"));
-
-//#region src/endpoints/MswEndpointAdaptor.ts
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("../rolldown-runtime-y5ARvAq5.cjs");
+const require_construct_interface = require("../construct-interface.cjs");
+const require_auth = require("../auth.cjs");
+const require_functions = require("../functions-CfzJG9hK.cjs");
+const require_Endpoint = require("../Endpoint-BoUg8ocM.cjs");
+const require_Queue = require("../Queue-A3wfD0it.cjs");
+const require_email = require("../email.cjs");
+const require_kysely = require("../kysely-CO_Dk43W.cjs");
+const require_lazyAccessors = require("../lazyAccessors-hJKGv8Ay.cjs");
+const require_Topic = require("../Topic-GHxcU8AG.cjs");
+const require_HonoEndpointAdaptor = require("../HonoEndpointAdaptor-zVzVLJEO.cjs");
+const require_processAudits = require("../processAudits-DasOZjPl.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let node_crypto = require("node:crypto");
+let _geekmidas_errors = require("@geekmidas/errors");
+let _geekmidas_envkit = require("@geekmidas/envkit");
+let _geekmidas_services = require("@geekmidas/services");
+let hono = require("hono");
+let _geekmidas_audit = require("@geekmidas/audit");
+let _geekmidas_testkit_context = require("@geekmidas/testkit/context");
+let msw = require("msw");
+let _geekmidas_testkit_browser = require("@geekmidas/testkit/browser");
+let _geekmidas_testkit_faker = require("@geekmidas/testkit/faker");
+let _geekmidas_testkit_mailbox = require("@geekmidas/testkit/mailbox");
+let _geekmidas_testkit_transactions = require("@geekmidas/testkit/transactions");
+let msw_node = require("msw/node");
+let vitest = require("vitest");
+let node_fs = require("node:fs");
+let node_tls = require("node:tls");
+node_tls = require_rolldown_runtime.__toESM(node_tls, 1);
+let node_url = require("node:url");
+//#region src/testing/peer.ts
 /**
-* Header used to identify which test context a request belongs to.
-* Each concurrent test registers its own context (services, db transaction, etc.)
-* and the MSW handler looks it up by this header value.
+* The TCP peer a test's in-process requests arrive from.
+*
+* A feature test hands a request straight to a surface's Hono app — no
+* socket, no server — so the app's bindings have no peer to read. Deployed,
+* every request has one, and what a surface trusts follows from it: the auth
+* server honours `x-gkm-client-ip` only from an internal caller, a loopback
+* or private peer with no `Origin` and no forwarding header. With no peer at
+* all the header was dropped, and every test's session check became the same
+* client to Better Auth's rate limiter.
+*
+* So an in-process dispatch says where it came from, the way
+* `@hono/node-server` does: its bindings carry `incoming.socket.remoteAddress`.
+* The address is loopback because that is the truth — the request came from
+* this process. A browser's own address still travels in its
+* `x-forwarded-for`, which makes it outside traffic exactly as it would be
+* behind the stack's proxy.
+*
+* Only a test's dispatch passes these. A runtime with no socket of its own
+* (Lambda, Bun) still has no peer, and a request with no peer is still not an
+* internal caller's.
 */
-const TEST_CONTEXT_HEADER = "x-test-context-id";
+/** The address an in-process request presents as its peer. */
+const IN_PROCESS_PEER_ADDRESS = "127.0.0.1";
+/** Bindings for `app.fetch(request, bindings)` from inside this process. */
+function inProcessBindings() {
+	return { incoming: { socket: { remoteAddress: IN_PROCESS_PEER_ADDRESS } } };
+}
+//#endregion
+//#region src/endpoints/MswEndpointAdaptor.ts
 const MSW_HTTP_METHODS = [
 	"get",
 	"post",
@@ -53,8 +92,8 @@ function createMswHandlers(endpoints, options) {
 	* Creates a fresh ServiceDiscovery and pre-registers all provided services.
 	*/
 	function registerContext(id, ctxOptions) {
-		const envParser = new __geekmidas_envkit.EnvironmentParser({});
-		const serviceDiscovery = new __geekmidas_services.ServiceDiscovery(envParser);
+		const envParser = new _geekmidas_envkit.EnvironmentParser({});
+		const serviceDiscovery = new _geekmidas_services.ServiceDiscovery(envParser);
 		const serviceDefs = [];
 		if (ctxOptions.services) for (const [name, instance] of Object.entries(ctxOptions.services)) serviceDefs.push({
 			serviceName: name,
@@ -69,7 +108,6 @@ function createMswHandlers(endpoints, options) {
 				break;
 			}
 		}
-		if (ctxOptions.publisher) serviceDefs.push(ctxOptions.publisher);
 		if (ctxOptions.auditorStorage !== void 0) {
 			for (const endpoint of endpoints) if (endpoint.auditorStorageService) {
 				serviceDefs.push({
@@ -89,18 +127,18 @@ function createMswHandlers(endpoints, options) {
 		const mswUrl = `${baseURL}${endpoint.route}`;
 		const mswMethod = msw.http[method];
 		handlers.push(mswMethod(mswUrl, async ({ request }) => {
-			const contextId = request.headers.get(TEST_CONTEXT_HEADER);
+			const contextId = request.headers.get(_geekmidas_testkit_context.TEST_CONTEXT_HEADER);
 			const ctx = contextId ? contexts.get(contextId) : void 0;
 			if (!ctx) return new Response(JSON.stringify({
 				error: "Missing or unknown test context ID",
-				hint: `Set the '${TEST_CONTEXT_HEADER}' header to a registered context ID`
+				hint: `Set the '${_geekmidas_testkit_context.TEST_CONTEXT_HEADER}' header to a registered context ID`
 			}), {
 				status: 500,
 				headers: { "content-type": "application/json" }
 			});
 			const app = new hono.Hono();
 			require_HonoEndpointAdaptor.HonoEndpoint.addRoute(endpoint, ctx.serviceDiscovery, app);
-			const response = await app.request(request);
+			const response = await app.request(request, void 0, inProcessBindings());
 			return new Response(response.body, {
 				status: response.status,
 				statusText: response.statusText,
@@ -113,7 +151,6 @@ function createMswHandlers(endpoints, options) {
 		registerContext
 	};
 }
-
 //#endregion
 //#region src/endpoints/TestEndpointAdaptor.ts
 /**
@@ -133,8 +170,10 @@ function serializeCookie(name, value, options) {
 	return cookieString;
 }
 var TestEndpointAdaptor = class TestEndpointAdaptor {
+	endpoint;
+	serviceDiscovery;
 	static getDefaultServiceDiscover(_endpoint) {
-		return __geekmidas_services.ServiceDiscovery.getInstance(new __geekmidas_envkit.EnvironmentParser({}));
+		return _geekmidas_services.ServiceDiscovery.getInstance(new _geekmidas_envkit.EnvironmentParser({}));
 	}
 	constructor(endpoint, serviceDiscovery = TestEndpointAdaptor.getDefaultServiceDiscover(endpoint)) {
 		this.endpoint = endpoint;
@@ -155,10 +194,12 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 			method: this.endpoint.method
 		});
 		const rawDb = ctx.database;
-		return (0, __geekmidas_services.runWithRequestContext)({
+		const operation = `${this.endpoint.method} ${this.endpoint.route}`;
+		return (0, _geekmidas_services.runWithRequestContext)({
 			logger,
 			requestId,
-			startTime
+			startTime,
+			operation
 		}, async () => {
 			const session = await this.endpoint.getSession({
 				logger,
@@ -167,7 +208,7 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				cookie,
 				...rawDb !== void 0 && { db: rawDb }
 			});
-			const isAuthorized = await this.endpoint.authorize({
+			if (!await this.endpoint.authorize({
 				header,
 				cookie,
 				services: ctx.services,
@@ -177,10 +218,9 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				body,
 				query,
 				params
-			});
-			if (!isAuthorized) {
+			})) {
 				logger.warn("Forbidden access attempt");
-				throw new __geekmidas_errors.ForbiddenError("Forbidden access to the endpoint", "You do not have permission to access this resource.");
+				throw new _geekmidas_errors.ForbiddenError("Forbidden access to the endpoint", "You do not have permission to access this resource.");
 			}
 			const auditorStorage = ctx.auditorStorage;
 			let auditContext;
@@ -200,24 +240,22 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				} catch (error) {
 					logger.error(error, "Failed to extract actor for audits");
 				}
-				const auditor = new __geekmidas_audit.DefaultAuditor({
-					actor,
-					storage: auditorStorage,
-					metadata: {
-						endpoint: this.endpoint.route,
-						method: this.endpoint.method
-					}
-				});
 				auditContext = {
-					auditor,
+					auditor: new _geekmidas_audit.DefaultAuditor({
+						actor,
+						storage: auditorStorage,
+						metadata: {
+							endpoint: this.endpoint.route,
+							method: this.endpoint.method
+						}
+					}),
 					storage: auditorStorage
 				};
 			}
 			const audits = this.endpoint.audits;
 			if (!auditContext && audits?.length) logger.warn("No auditor storage service available");
-			const result = await require_processAudits.executeWithAuditTransaction(auditContext, async (auditor) => {
-				const trx = auditor?.getTransaction?.();
-				const db = trx ?? rawDb;
+			const { output, metadata } = await require_processAudits.executeWithAuditTransaction(auditContext, async (auditor) => {
+				const db = auditor?.getTransaction?.() ?? rawDb;
 				const responseBuilder = new require_Endpoint.ResponseBuilder();
 				const response = await this.endpoint.handler({
 					body,
@@ -232,36 +270,33 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 					db
 				}, responseBuilder);
 				let data = response;
-				let metadata$1 = responseBuilder.getMetadata();
+				let metadata = responseBuilder.getMetadata();
 				if (require_Endpoint.Endpoint.hasMetadata(response)) {
 					data = response.data;
-					metadata$1 = response.metadata;
+					metadata = response.metadata;
 				}
-				const output$1 = await this.endpoint.parseOutput(data);
 				return {
-					output: output$1,
-					metadata: metadata$1,
+					output: await this.endpoint.parseOutput(data),
+					metadata,
 					responseBuilder
 				};
-			}, async (result$1, auditor) => {
+			}, async (result, auditor) => {
 				if (!audits?.length) return;
 				for (const audit of audits) {
-					if (audit.when && !audit.when(result$1.output)) continue;
-					const payload = audit.payload(result$1.output);
-					const entityId = audit.entityId?.(result$1.output);
+					if (audit.when && !audit.when(result.output)) continue;
+					const payload = audit.payload(result.output);
+					const entityId = audit.entityId?.(result.output);
 					auditor.audit(audit.type, payload, {
 						table: audit.table,
 						entityId
 					});
 				}
 			}, { db: rawDb });
-			const { output, metadata } = result;
-			ctx.publisher && await this.serviceDiscovery.register([ctx.publisher]);
-			await require_publisher.publishConstructEvents(this.endpoint, output, this.serviceDiscovery);
+			await require_functions.publishConstructEvents(this.endpoint, output, this.serviceDiscovery, this.endpoint.logger, ctx.services);
 			const headers = { ...metadata.headers || {} };
 			if (metadata.cookies && metadata.cookies.size > 0) {
 				const setCookieValues = [];
-				for (const [name, cookie$1] of metadata.cookies.entries()) setCookieValues.push(serializeCookie(name, cookie$1.value, cookie$1.options));
+				for (const [name, cookie] of metadata.cookies.entries()) setCookieValues.push(serializeCookie(name, cookie.value, cookie.options));
 				headers["set-cookie"] = setCookieValues;
 			}
 			return {
@@ -272,16 +307,16 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 		});
 	}
 	async request(ctx) {
-		const response = await this.fullRequest(ctx);
-		return response.body;
+		return (await this.fullRequest(ctx)).body;
 	}
 };
-
 //#endregion
 //#region src/functions/TestFunctionAdaptor.ts
 var TestFunctionAdaptor = class TestFunctionAdaptor {
+	fn;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery(_fn) {
-		return __geekmidas_services.ServiceDiscovery.getInstance(new __geekmidas_envkit.EnvironmentParser({}));
+		return _geekmidas_services.ServiceDiscovery.getInstance(new _geekmidas_envkit.EnvironmentParser({}));
 	}
 	constructor(fn, serviceDiscovery = TestFunctionAdaptor.getDefaultServiceDiscovery(fn)) {
 		this.fn = fn;
@@ -295,16 +330,12 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 		else services = await this.serviceDiscovery.register(this.fn.services);
 		let db;
 		if ("db" in ctx && ctx.db !== void 0) db = ctx.db;
-		else if (this.fn.databaseService) {
-			const dbServices = await this.serviceDiscovery.register([this.fn.databaseService]);
-			db = dbServices[this.fn.databaseService.serviceName];
-		}
+		else if (this.fn.databaseService) db = (await this.serviceDiscovery.register([this.fn.databaseService]))[this.fn.databaseService.serviceName];
 		let auditor;
 		if ("auditor" in ctx && ctx.auditor !== void 0) auditor = ctx.auditor;
 		else if (this.fn.auditorStorageService) {
-			const auditServices = await this.serviceDiscovery.register([this.fn.auditorStorageService]);
-			const storage = auditServices[this.fn.auditorStorageService.serviceName];
-			auditor = new __geekmidas_audit.DefaultAuditor({
+			const storage = (await this.serviceDiscovery.register([this.fn.auditorStorageService]))[this.fn.auditorStorageService.serviceName];
+			auditor = new _geekmidas_audit.DefaultAuditor({
 				actor: {
 					id: "system",
 					type: "system"
@@ -317,11 +348,10 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 			});
 		}
 		const requestId = `test-${Date.now()}`;
-		const startTime = Date.now();
-		return (0, __geekmidas_services.runWithRequestContext)({
+		return (0, _geekmidas_services.runWithRequestContext)({
 			logger,
 			requestId,
-			startTime
+			startTime: Date.now()
 		}, async () => {
 			const response = await this.fn.fn({
 				input: parsedInput,
@@ -338,26 +368,28 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 					await auditor.flush();
 				}
 			}
-			await require_publisher.publishEvents(logger, this.serviceDiscovery, this.fn.events, output, this.fn.publisherService);
+			await require_functions.publishEvents(logger, this.serviceDiscovery, this.fn.events, output, services);
 			return output;
 		});
 	}
 };
-
 //#endregion
 //#region src/queue/TestQueueAdaptor.ts
 /**
 * In-memory test driver for a {@link Queue} worker. Hand it a batch of messages
 * and it registers the queue's services, runs the handler in a request context,
-* and returns the handler result — no SQS/pg-boss required.
+* and returns the handler result — no SQS/pg-boss required. A queue with a
+* database gets `db` registered from it, or the one the request passes.
 *
 * @example
 * const adapter = new TestQueueAdaptor(ordersQueue);
 * await adapter.invoke({ messages: [{ orderId: '123' }] });
 */
 var TestQueueAdaptor = class TestQueueAdaptor {
+	queue;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery() {
-		return __geekmidas_services.ServiceDiscovery.getInstance(new __geekmidas_envkit.EnvironmentParser({}));
+		return _geekmidas_services.ServiceDiscovery.getInstance(new _geekmidas_envkit.EnvironmentParser({}));
 	}
 	constructor(queue, serviceDiscovery = TestQueueAdaptor.getDefaultServiceDiscovery()) {
 		this.queue = queue;
@@ -366,25 +398,35 @@ var TestQueueAdaptor = class TestQueueAdaptor {
 	async invoke(request) {
 		const logger = this.queue.logger.child({ test: true });
 		const services = request.services ?? await this.serviceDiscovery.register(this.queue.services);
+		const db = request.db !== void 0 ? request.db : await this.getDatabase();
 		const requestId = `test-${Date.now()}`;
 		const startTime = Date.now();
-		return (0, __geekmidas_services.runWithRequestContext)({
+		const operation = `queue ${this.queue.name}`;
+		return (0, _geekmidas_services.runWithRequestContext)({
 			logger,
 			requestId,
-			startTime
+			startTime,
+			operation
 		}, () => this.queue.handler({
 			messages: request.messages,
 			services,
-			logger
+			logger,
+			db
 		}));
 	}
+	async getDatabase() {
+		const service = this.queue.databaseService;
+		if (!service) return void 0;
+		return (await this.serviceDiscovery.register([service]))[service.serviceName];
+	}
 };
-
 //#endregion
 //#region src/subscribers/TestSubscriberAdaptor.ts
 var TestSubscriberAdaptor = class TestSubscriberAdaptor {
+	subscriber;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery() {
-		return __geekmidas_services.ServiceDiscovery.getInstance(new __geekmidas_envkit.EnvironmentParser({}));
+		return _geekmidas_services.ServiceDiscovery.getInstance(new _geekmidas_envkit.EnvironmentParser({}));
 	}
 	constructor(subscriber, serviceDiscovery = TestSubscriberAdaptor.getDefaultServiceDiscovery()) {
 		this.subscriber = subscriber;
@@ -395,19 +437,23 @@ var TestSubscriberAdaptor = class TestSubscriberAdaptor {
 		let services;
 		if (request.services) services = request.services;
 		else services = await this.serviceDiscovery.register(this.subscriber.services);
+		const db = request.db !== void 0 ? request.db : await this.getDatabase();
 		const filteredEvents = this.filterEvents(request.events);
 		if (filteredEvents.length === 0) return { batchItemFailures: [] };
 		const requestId = `test-${Date.now()}`;
 		const startTime = Date.now();
-		return (0, __geekmidas_services.runWithRequestContext)({
+		const operation = `subscriber ${this.subscriber.topicName ?? "test"}`;
+		return (0, _geekmidas_services.runWithRequestContext)({
 			logger,
 			requestId,
-			startTime
+			startTime,
+			operation
 		}, async () => {
 			const result = await this.subscriber.handler({
 				events: filteredEvents,
 				services,
-				logger
+				logger,
+				db
 			});
 			let output = result;
 			if (this.subscriber.outputSchema && result) {
@@ -415,21 +461,628 @@ var TestSubscriberAdaptor = class TestSubscriberAdaptor {
 				if (validationResult.issues) throw new Error("Subscriber output validation failed");
 				output = validationResult.value;
 			}
-			await require_publisher.publishEvents(logger, this.serviceDiscovery, this.subscriber.events, output, this.subscriber.publisherService);
 			return output;
 		});
 	}
+	async getDatabase() {
+		const service = this.subscriber.databaseService;
+		if (!service) return void 0;
+		return (await this.serviceDiscovery.register([service]))[service.serviceName];
+	}
 	filterEvents(events) {
 		if (!this.subscriber.subscribedEvents) return events;
 		return events.filter((event) => this.subscriber.subscribedEvents.includes(event.type));
 	}
 };
-
 //#endregion
-exports.TEST_CONTEXT_HEADER = TEST_CONTEXT_HEADER;
+//#region src/testing/manifest.ts
+/**
+* The test manifest: what `gkm test` knows about an app, written down for the
+* suite it starts.
+*
+* `gkm test` discovers the constructs, reconciles the test stage and resolves
+* its environment — then, until this existed, threw all of it away and left a
+* test to declare it again by hand. The manifest keeps it: which construct and
+* endpoint is exported where, and the environment the test stage resolved,
+* under the keys the constructs themselves derive. A feature test is built from
+* it, so nothing a test says can drift from what the app declares.
+*/
+/** The environment variable `gkm test` names the manifest in. */
+const TEST_MANIFEST_ENV = "GKM_TEST_MANIFEST";
+/**
+* Read a test manifest: from a path, a `file:` URL, or — given nothing — the
+* one `gkm test` named in `GKM_TEST_MANIFEST`.
+*/
+function loadTestManifest(from) {
+	const location = from ?? process.env["GKM_TEST_MANIFEST"];
+	if (!location) throw new NoTestManifest();
+	trustLocalEdge();
+	const path = location instanceof URL || location.startsWith("file:") ? (0, node_url.fileURLToPath)(location) : location;
+	return JSON.parse((0, node_fs.readFileSync)(path, "utf-8"));
+}
+let trusted = false;
+/**
+* Trust the local edge's certificate authority in this thread.
+*
+* `NODE_EXTRA_CA_CERTS` does it for a process started with it — which a
+* suite started by `gkm test` is, and one started by plain `vitest` or an
+* editor is not: its setup only learns the path once Vitest is running, and a
+* worker *thread* shares that process and keeps a TLS store of its own. Every
+* feature test loads the manifest, so this is the one place each worker passes
+* through.
+*/
+function trustLocalEdge() {
+	const certificate = process.env.NODE_EXTRA_CA_CERTS;
+	if (trusted || !certificate || !(0, node_fs.existsSync)(certificate)) return;
+	trusted = true;
+	node_tls.default.setDefaultCACertificates([...node_tls.default.getCACertificates("default"), (0, node_fs.readFileSync)(certificate, "utf-8")]);
+}
+/** A feature test ran without a manifest to build itself from. */
+var NoTestManifest = class extends Error {
+	constructor() {
+		super(`No test manifest: run the suite with \`gkm test\`, or add \`globalSetup: ['@geekmidas/cli/vitest']\` to the root vitest config — either writes one and names it in ${TEST_MANIFEST_ENV}.`);
+		this.name = "NoTestManifest";
+	}
+};
+//#endregion
+//#region src/testing/featureTest.ts
+/**
+* `featureTest`: an app, driven the way it runs deployed.
+*
+* A browser signs in and calls the API; the API calls the auth server; each
+* over its URL, each database in its own transaction. Nothing runs as a server:
+* every URL an app's constructs answer on is served in-process through MSW,
+* from the real handler, for the test that made the request. Everything else
+* with a real local equivalent — Postgres, Mailpit, MinIO — is used directly.
+*
+* It is built from the test manifest `gkm test` writes — the constructs and
+* endpoints the app exports, and the environment the test stage resolved — so
+* a test declares none of it. `gkm test` also generates the configured `it`
+* and a `Browser` with a typed client per surface:
+*
+* ```ts
+* import { it } from '#test';
+*
+* it('shows the signed-in user their profile', async ({ browser, mailbox }) => {
+*   await browser.auth.signIn.magicLink({ email: 'ada@shop.test' });
+*   await browser.visit((await mailbox('ada@shop.test').last()).link!);
+*   expect(await browser.api.get('/profile')).toMatchObject({ email: 'ada@shop.test' });
+* });
+* ```
+*/
+/** Every test in flight in this process, by id. */
+const contexts = /* @__PURE__ */ new Map();
+/** Databases already resolving to test transactions — patched once each. */
+const bound = /* @__PURE__ */ new WeakSet();
+function featureTest(options = {}) {
+	const manifest = options.manifest ?? loadTestManifest();
+	const BrowserClass = options.browser ?? _geekmidas_testkit_browser.Browser;
+	let app;
+	let factoryDatabases = [];
+	let owned = [];
+	let network;
+	let restoreFetch = () => {};
+	(0, vitest.beforeAll)(async () => {
+		app = await load(manifest, options.modules ?? {});
+		owned = ownDatabases(app, manifest);
+		factoryDatabases = databasesFor(options.factories ?? {}, owned);
+		for (const database of app.databases) bindToTests(database);
+		network = (0, msw_node.setupServer)(...surfaceHandlers(app.endpoints, manifest.env), ...app.auths.map((auth) => authHandler(auth, manifest.env, app.envParser)), ...Object.entries(options.fakes ?? {}).flatMap(([id, fake]) => fakeHandler(id, fake, manifest.env)));
+		network.listen({ onUnhandledRequest(request, print) {
+			if (isLocal(new URL(request.url))) return;
+			print.error();
+		} });
+		const restoreStamp = (0, _geekmidas_testkit_context.installContextFetch)();
+		const stamped = globalThis.fetch;
+		globalThis.fetch = deliveringFetch(stamped, (id) => {
+			const state = contexts.get(id);
+			return state ? deliver(app, state, id) : Promise.resolve();
+		});
+		restoreFetch = () => {
+			globalThis.fetch = stamped;
+			restoreStamp();
+		};
+	});
+	(0, vitest.afterAll)(() => {
+		restoreFetch();
+		network?.close();
+	});
+	const run = (name, fn) => async () => {
+		const id = (0, node_crypto.randomUUID)();
+		_geekmidas_testkit_faker.faker.seed(seedOf(name));
+		const state = {
+			transactions: new _geekmidas_testkit_transactions.TransactionRegistry(),
+			discovery: new _geekmidas_services.ServiceDiscovery(app.envParser),
+			surfaces: /* @__PURE__ */ new Map(),
+			auth: /* @__PURE__ */ new Map(),
+			addresses: /* @__PURE__ */ new Set(),
+			published: /* @__PURE__ */ new Map(),
+			pending: [],
+			delivering: false
+		};
+		const readMail = app.readMail;
+		if (readMail) state.mailbox = (address) => {
+			state.addresses.add(address);
+			return readMail(address);
+		};
+		contexts.set(id, state);
+		await state.discovery.register(recorders(app.channels, state));
+		try {
+			await (0, _geekmidas_testkit_context.runInTestContext)(id, async () => {
+				const browser = new BrowserClass();
+				const restore = browser.install();
+				try {
+					const transaction = (database) => state.transactions.get(database.id, urlOf(database, app.envParser), database.clientConfig);
+					const db = { get: (name) => {
+						const database = owned.find((candidate) => candidate.service.serviceName === name);
+						if (!database) throw new UnknownDatabase(name, owned.map((candidate) => candidate.service.serviceName));
+						return transaction(database);
+					} };
+					const built = /* @__PURE__ */ new Map();
+					await fn({
+						browser,
+						db,
+						factories: { get: (name) => {
+							const database = factoryDatabases.find(([candidate]) => candidate === name)?.[1];
+							if (!database) throw new UnknownFactory(name, factoryDatabases.map(([candidate]) => candidate));
+							let factory = built.get(name);
+							if (!factory) {
+								factory = transaction(database).then(options.factories[name]);
+								built.set(name, factory);
+							}
+							return factory;
+						} },
+						faker: _geekmidas_testkit_faker.faker,
+						mailbox: (address) => {
+							if (!state.mailbox) throw new NoInbox();
+							return state.mailbox(address);
+						},
+						published: (channel) => [...state.published.get(channel.id) ?? []],
+						services: { get: (name) => resolveService(app, state, name) },
+						subscriber: (subscriber) => thenDeliver(new TestSubscriberAdaptor(subscriber, state.discovery), () => deliver(app, state, id)),
+						queue: (queue) => thenDeliver(new TestQueueAdaptor(queue, state.discovery), () => deliver(app, state, id))
+					});
+				} finally {
+					restore();
+				}
+			});
+		} finally {
+			contexts.delete(id);
+			await Promise.all([state.transactions.rollbackAll(), ...[...state.addresses].map((address) => app.readMail?.(address).clear())]);
+		}
+	};
+	const it = ((name, fn, timeout) => (0, vitest.test)(name, run(name, fn), timeout));
+	it.only = (name, fn, timeout) => vitest.test.only(name, run(name, fn), timeout);
+	it.skip = (name, fn, timeout) => vitest.test.skip(name, run(name, fn), timeout);
+	return it;
+}
+/**
+* A test's faker seed, from its name: the same test draws the same data on
+* every run, and two tests draw different data.
+*/
+function seedOf(name) {
+	let hash = 0;
+	for (const char of name) hash = Math.imul(hash, 31) + char.charCodeAt(0) | 0;
+	return hash >>> 0;
+}
+/**
+* Import what the manifest points at.
+*
+* The same modules the app runs, so a construct here *is* the app's construct —
+* the one its endpoints were built from — never a copy declared again.
+*/
+async function load(manifest, modules) {
+	const envParser = new _geekmidas_envkit.EnvironmentParser({ ...manifest.env });
+	const imported = async ({ file, export: name }) => (modules[file] ?? await import(file))[name];
+	const constructs = await Promise.all(Object.values(manifest.constructs).map(({ source }) => imported(source)));
+	const endpoints = (await Promise.all(manifest.endpoints.map(({ source }) => imported(source)))).filter((value) => require_Endpoint.Endpoint.isEndpoint(value));
+	const subscribers = (await Promise.all((manifest.subscribers ?? []).map(async ({ source }) => ({
+		name: source.export,
+		subscriber: await imported(source)
+	})))).filter((entry) => entry.subscriber?.__IS_SUBSCRIBER__ === true);
+	const unique = (values) => [...new Set(values)];
+	const databases = unique(constructs.filter((value) => value instanceof require_kysely.KyselyDatabase));
+	const auths = unique(constructs.filter((value) => value instanceof require_auth.BetterAuth));
+	const emails = unique(constructs.filter((value) => value instanceof require_email.Email));
+	const consumables = unique(constructs.filter(require_construct_interface.isConsumable));
+	const channels = unique(constructs.filter((value) => value instanceof require_Topic.Topic || value instanceof require_Queue.Queue));
+	const inbox = emails.map((email) => manifest.env[(0, _geekmidas_manifest.provideKey)(email.id, "inboxUrl")]).find(Boolean);
+	return {
+		envParser,
+		endpoints,
+		databases,
+		auths,
+		emails,
+		channels,
+		consumables,
+		subscribers,
+		...inbox ? { readMail: (0, _geekmidas_testkit_mailbox.createMailbox)({ inbox }) } : {}
+	};
+}
+/**
+* A publisher that records rather than sends, under the name a topic or queue
+* is injected by — `services.users` — which is also the one `.event(users, …)`
+* publishes through.
+*/
+function recorders(channels, state) {
+	return channels.map((channel) => {
+		const publisher = { async publish(messages) {
+			const sent = messages.map(({ type, payload }) => ({
+				type,
+				payload
+			}));
+			state.published.set(channel.id, [...state.published.get(channel.id) ?? [], ...sent]);
+			state.pending.push({
+				channel,
+				messages: sent
+			});
+		} };
+		return {
+			serviceName: channel.service.serviceName,
+			register: () => publisher
+		};
+	});
+}
+/**
+* The databases a test is handed: the app's own. A schema tenant an auth server
+* owns is reached through that server, as the app reaches it, and a reader is
+* the same database through a read-only role — neither is another database to
+* test against.
+*/
+function ownDatabases(app, manifest) {
+	const owners = new Set(app.auths.map((auth) => auth.databaseId));
+	return app.databases.filter((database) => !owners.has(database.id) && manifest.constructs[database.id]?.kind !== "database-reader");
+}
+/** Each factory's database, found by the service name it is keyed by. */
+function databasesFor(factories, databases) {
+	return Object.keys(factories).map((name) => {
+		const database = databases.find((candidate) => candidate.service.serviceName === name);
+		if (!database) throw new UnknownFactory(name, databases.map((candidate) => candidate.service.serviceName));
+		return [name, database];
+	});
+}
+/**
+* Make a database resolve, inside a test, to that test's transaction.
+*
+* Everything reaches a database through its service — an endpoint through
+* service discovery, the auth server through its tenant directly — so this is
+* the one place a test's connection can be handed over. Outside a test it is
+* the database it always was.
+*/
+/** Rounds of delivery before a chain of consumers is called a loop. */
+const MAX_DELIVERY_ROUNDS = 25;
+/**
+* Deliver what this test published, in-process, as the broker would — and
+* keep delivering what the consumers publish in turn, until nothing is left.
+*
+* - A queue's messages go to its one consumer, as a batch.
+* - A topic's events go to every subscriber that named their type, and only
+*   those: fan-out, as the filter policy (SNS) or the per-subscriber queue
+*   (pg-boss) does it.
+* - Each payload is checked against the consumer's schema first. Turning an
+*   SNS envelope or an SQS record into `{ type, payload }` is each adaptor's
+*   job and tested there; what is tested here is what the handler is handed.
+* - Consumers run as the server side of this test, so their databases are
+*   this test's transactions and their writes roll back with it.
+* - A consumer that throws fails the test. Deployed, the message would be
+*   retried; here a retry would only hide the bug.
+*/
+async function deliver(app, state, id) {
+	if (state.delivering) return;
+	state.delivering = true;
+	try {
+		for (let round = 0; state.pending.length > 0; round++) {
+			if (round === MAX_DELIVERY_ROUNDS) throw new DeliveryDidNotSettle(MAX_DELIVERY_ROUNDS, [...new Set(state.pending.map(({ channel }) => channel.id))]);
+			for (const { channel, messages } of state.pending.splice(0)) if (channel instanceof require_Queue.Queue) await toQueue(channel, messages, state, id);
+			else await toSubscribers(channel, messages, app, state, id);
+		}
+	} finally {
+		state.delivering = false;
+	}
+}
+async function toQueue(queue, messages, state, id) {
+	const payloads = [];
+	for (const message of messages) payloads.push(await accepted(queue.messageSchema, message, `queue '${queue.name}'`));
+	await (0, _geekmidas_testkit_context.runAsServer)(id, () => new TestQueueAdaptor(queue, state.discovery).invoke({ messages: payloads })).catch((error) => {
+		throw new DeliveryFailed(`queue '${queue.name}'`, messages, error);
+	});
+}
+async function toSubscribers(topic, messages, app, state, id) {
+	for (const { name, subscriber } of app.subscribers) {
+		if (subscriber.topicName !== topic.name) continue;
+		const named = messages.filter(({ type }) => (subscriber.subscribedEvents ?? []).includes(type));
+		if (named.length === 0) continue;
+		const consumer = `subscriber '${name}'`;
+		const events = [];
+		for (const message of named) {
+			const schema = topic.eventSchemas[message.type];
+			events.push({
+				type: message.type,
+				payload: await accepted(schema, message, consumer)
+			});
+		}
+		await (0, _geekmidas_testkit_context.runAsServer)(id, () => new TestSubscriberAdaptor(subscriber, state.discovery).invoke({ events })).catch((error) => {
+			throw new DeliveryFailed(consumer, named, error);
+		});
+	}
+}
+/** The payload, if the consumer's schema takes it — what the handler is handed. */
+async function accepted(schema, message, consumer) {
+	const standard = schema?.["~standard"];
+	if (!standard) return message.payload;
+	const result = await standard.validate(message.payload);
+	if (result.issues) throw new MessageRejected(consumer, message, result.issues);
+	return result.value;
+}
+/** `fetch`, delivering what the test published once each of its requests answers. */
+function deliveringFetch(inner, settle) {
+	return async (input, init) => {
+		const context = (0, _geekmidas_testkit_context.currentTestContext)();
+		const response = await inner(input, init);
+		if (context?.side === "client") await settle(context.id);
+		return response;
+	};
+}
+/** An adaptor whose `invoke` delivers what it published before returning. */
+function thenDeliver(adaptor, settle) {
+	const invoke = adaptor.invoke.bind(adaptor);
+	adaptor.invoke = (async (...args) => {
+		const result = await invoke(...args);
+		await settle();
+		return result;
+	});
+	return adaptor;
+}
+function bindToTests(database) {
+	if (bound.has(database)) return;
+	bound.add(database);
+	const service = database.service;
+	const register = service.register;
+	service.register = (options) => {
+		const context = (0, _geekmidas_testkit_context.currentTestContext)();
+		const state = context && contexts.get(context.id);
+		if (!state) return register(options);
+		return state.transactions.get(database.id, urlOf(database, options.envParser), database.clientConfig);
+	};
+}
+function urlOf(database, envParser) {
+	return envParser.create((get) => ({ url: get((0, _geekmidas_manifest.provideKey)(database.id, "url")).string() })).parse().url;
+}
+/** Each surface's endpoints, served at its URL for the test that asked. */
+function surfaceHandlers(endpoints, env) {
+	const bySurface = /* @__PURE__ */ new Map();
+	for (const endpoint of endpoints) {
+		const surface = endpoint.surface?.id;
+		if (!surface) continue;
+		bySurface.set(surface, [...bySurface.get(surface) ?? [], endpoint]);
+	}
+	return [...bySurface].flatMap(([surface, served]) => {
+		const base = env[(0, _geekmidas_manifest.provideKey)(surface, "url")];
+		if (!base) return [];
+		return msw.http.all(`${trim(base)}/*`, ({ request }) => serve(request, async (state) => {
+			let app = state.surfaces.get(surface);
+			if (!app) {
+				app = Promise.resolve().then(() => {
+					const hono$1 = new hono.Hono();
+					require_HonoEndpointAdaptor.HonoEndpoint.addRoutes(served, state.discovery, hono$1);
+					return hono$1;
+				});
+				state.surfaces.set(surface, app);
+			}
+			return (await app).fetch(request, inProcessBindings());
+		}));
+	});
+}
+/**
+* An external API's app fake, answering at the URL the test stage resolved for
+* it — so a handler that calls Polar calls the fake, and the test sets up
+* nothing.
+*
+* Not per test, unlike a surface: a fake stands in for somebody else's server,
+* which no test's transaction reaches. An image fake has no handler here — its
+* container answers on localhost, which is let through.
+*/
+function fakeHandler(id, fake, env) {
+	const base = env[(0, _geekmidas_manifest.provideKey)(id, "url")];
+	if (fake.kind !== "app" || !base) return [];
+	return [msw.http.all(`${trim(base)}/*`, ({ request }) => fake.handler.fetch(request))];
+}
+/**
+* A construct's client for this test, by service name — through the test's own
+* discovery, so a topic or queue is its recorder and a database its
+* transaction, exactly as the test's endpoints get them.
+*/
+async function resolveService(app, state, name) {
+	const construct = app.consumables.find((candidate) => candidate.service.serviceName === name);
+	if (!construct) throw new UnknownService(name, app.consumables.map((candidate) => candidate.service.serviceName));
+	return (await state.discovery.register([construct.service]))[name];
+}
+/** An auth server, served at its URL, on the transaction of the test that asked. */
+function authHandler(auth, env, envParser) {
+	const base = trim(env[(0, _geekmidas_manifest.provideKey)(auth.id, "url")] ?? "");
+	return msw.http.all(`${base}/*`, ({ request }) => serve(request, async (state) => {
+		let app = state.auth.get(auth);
+		if (!app) {
+			app = auth.server({
+				envParser,
+				context: _geekmidas_services.serviceContext
+			}).then(({ app }) => app);
+			state.auth.set(auth, app);
+		}
+		return (await app).fetch(request, inProcessBindings());
+	}));
+}
+/** Handle a request as the server side of the test it was made for. */
+async function serve(request, handle) {
+	const id = (0, _geekmidas_testkit_context.testContextOf)(request);
+	const state = id ? contexts.get(id) : void 0;
+	if (!id || !state) throw new UnknownTestContext(request.url, id);
+	return (0, _geekmidas_testkit_context.runAsServer)(id, () => handle(state));
+}
+function trim(url) {
+	return url.replace(/\/$/, "");
+}
+function isLocal(url) {
+	return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname.endsWith(".localhost");
+}
+/**
+* Sign a test's browser in the way a person does: ask the auth server for a
+* magic link, open the email it sent, follow the link.
+*
+* What the generated `browser.signIn(email)` calls. The address's mail is
+* cleared first — so the link is this request's, not one an earlier test left
+* — and cleared again after the test, like any address a test reads. Returns
+* the session the auth server then reports, as better-auth hands it back.
+*/
+async function signInWithMagicLink(browser, auth, email = freshAddress()) {
+	const context = (0, _geekmidas_testkit_context.currentTestContext)();
+	const state = context && contexts.get(context.id);
+	if (!state) throw new UnknownTestContext("signIn", context?.id);
+	if (!state.mailbox) throw new NoInbox();
+	const inbox = state.mailbox(email);
+	await inbox.clear();
+	const requested = await auth.signIn.magicLink({ email });
+	if (requested.error) throw new SignInFailed(email, `the auth server refused the magic link: ${requested.error.message ?? "no reason given"}`);
+	const mail = await inbox.last();
+	if (!mail.link) throw new SignInFailed(email, "its email held no link");
+	await browser.visit(mail.link);
+	const { data } = await auth.getSession();
+	if (!data) throw new SignInFailed(email, "the auth server reported no session after the link was opened");
+	return data;
+}
+/**
+* An address nobody else signs in as — what `browser.signIn()` uses when the
+* test does not care who it is.
+*
+* Unique rather than only seeded: tests in other files run at the same time,
+* against the same Mailpit and the same unique columns, and a seeded address
+* repeats wherever two tests share a name. The readable half is the seeded
+* faker's, so a failure still names somebody.
+*/
+function freshAddress() {
+	return `${_geekmidas_testkit_faker.faker.internet.username().toLowerCase().replace(/[^a-z0-9]/g, "")}.${(0, node_crypto.randomUUID)().slice(0, 8)}@example.test`;
+}
+/** `browser.signIn` finished without a session. */
+var SignInFailed = class extends Error {
+	email;
+	reason;
+	constructor(email, reason) {
+		super(`Signing ${email} in failed: ${reason}.`);
+		this.email = email;
+		this.reason = reason;
+		this.name = "SignInFailed";
+	}
+};
+/** A request reached an in-process server without a test to belong to. */
+var UnknownTestContext = class extends Error {
+	url;
+	id;
+	constructor(url, id) {
+		super(id ? `${url} was requested for test ${id}, which is not running. A request that outlives its test — an un-awaited call — lands here.` : `${url} was requested outside any test. Make the request inside a featureTest, so it reaches that test's transactions.`);
+		this.url = url;
+		this.id = id;
+		this.name = "UnknownTestContext";
+	}
+};
+/** `mailbox` was used in an app that declares no Email construct. */
+var NoInbox = class extends Error {
+	constructor() {
+		super("mailbox() reads the inbox of the app's Email construct, and none was found in featureTest's modules — or `gkm test` did not inject its <ID>_INBOX_URL.");
+		this.name = "NoInbox";
+	}
+};
+/** `db.get(name)` named no database the test is handed. */
+var UnknownDatabase = class extends Error {
+	database;
+	known;
+	constructor(database, known) {
+		super(`db.get('${database}') names no database of this app's. ` + (known.length > 0 ? `Its databases: ${known.join(", ")}. ` : "It declares no database of its own. ") + "A tenant an auth server owns is reached through that server, and a reader through the database it reads.");
+		this.database = database;
+		this.known = known;
+		this.name = "UnknownDatabase";
+	}
+};
+/** A factory keyed by a service name no database the app declares has. */
+var UnknownFactory = class extends Error {
+	factory;
+	known;
+	constructor(factory, known) {
+		super(`There is a test factory for '${factory}', and no database this app declares is called that. ` + (known.length > 0 ? `Its databases: ${known.join(", ")}. ` : "It declares no database. ") + `Name the file after the database construct: test/factories/<construct>.ts.`);
+		this.factory = factory;
+		this.known = known;
+		this.name = "UnknownFactory";
+	}
+};
+/** A published message the consumer's own schema refuses. */
+var MessageRejected = class extends Error {
+	consumer;
+	published;
+	issues;
+	constructor(consumer, published, issues) {
+		super(`${consumer} refuses '${published.type}': ${issues.map((issue) => issue.message).join("; ")}. What is published must be what the consumer's schema takes — fix the producer, or the schema.`);
+		this.consumer = consumer;
+		this.published = published;
+		this.issues = issues;
+		this.name = "MessageRejected";
+	}
+};
+/** A consumer that threw while handling what the test published. */
+var DeliveryFailed = class extends Error {
+	consumer;
+	messages;
+	cause;
+	constructor(consumer, messages, cause) {
+		super(`${consumer} failed handling ${messages.map(({ type }) => `'${type}'`).join(", ")}: ${cause?.message ?? String(cause)}. Deployed, the message would be retried; here the failure is the result.`, { cause });
+		this.consumer = consumer;
+		this.messages = messages;
+		this.cause = cause;
+		this.name = "DeliveryFailed";
+	}
+};
+/** Consumers that kept publishing to each other without settling. */
+var DeliveryDidNotSettle = class extends Error {
+	rounds;
+	channels;
+	constructor(rounds, channels) {
+		super(`Delivery did not settle after ${rounds} rounds — consumers are still publishing to ${channels.join(", ")}. A consumer that publishes to what triggers it loops forever deployed too.`);
+		this.rounds = rounds;
+		this.channels = channels;
+		this.name = "DeliveryDidNotSettle";
+	}
+};
+/** `services.get(name)` for a name no construct of the app is served by. */
+var UnknownService = class extends Error {
+	serviceName;
+	available;
+	constructor(serviceName, available) {
+		super(`The app declares no construct served as '${serviceName}'. Its services are: ${available.join(", ") || "none"}.`);
+		this.serviceName = serviceName;
+		this.available = available;
+		this.name = "UnknownService";
+	}
+};
+//#endregion
+exports.DeliveryDidNotSettle = DeliveryDidNotSettle;
+exports.DeliveryFailed = DeliveryFailed;
+exports.IN_PROCESS_PEER_ADDRESS = IN_PROCESS_PEER_ADDRESS;
+exports.MessageRejected = MessageRejected;
+exports.NoInbox = NoInbox;
+exports.NoTestManifest = NoTestManifest;
+exports.SignInFailed = SignInFailed;
+exports.TEST_CONTEXT_HEADER = _geekmidas_testkit_context.TEST_CONTEXT_HEADER;
+exports.TEST_MANIFEST_ENV = TEST_MANIFEST_ENV;
 exports.TestEndpointAdaptor = TestEndpointAdaptor;
 exports.TestFunctionAdaptor = TestFunctionAdaptor;
 exports.TestQueueAdaptor = TestQueueAdaptor;
 exports.TestSubscriberAdaptor = TestSubscriberAdaptor;
+exports.UnknownDatabase = UnknownDatabase;
+exports.UnknownFactory = UnknownFactory;
+exports.UnknownService = UnknownService;
+exports.UnknownTestContext = UnknownTestContext;
 exports.createMswHandlers = createMswHandlers;
+exports.featureTest = featureTest;
+exports.inProcessBindings = inProcessBindings;
+exports.loadTestManifest = loadTestManifest;
+exports.signInWithMagicLink = signInWithMagicLink;
+
 //# sourceMappingURL=testing.cjs.map