better-supabase 0.8.0 → 0.9.0

package/dist/testing/index.js

@@ -1,22 +1,26 @@
 import { t as DbException } from "../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../errors-2M6CKMP4.js";
-import { d as temporalText } from "../temporal-BJGitm-h.js";
-import { t as temporal } from "../temporal-required-BtynQtM-.js";
-import { a as ok } from "../result-DEqHCMKP.js";
-import { t as BetterSupabase } from "../define-CFQcvM20.js";
+import { n as dbError } from "../errors-8i6tSICm.js";
+import { d as temporalText } from "../temporal-CB5Fpo5d.js";
+import { t as temporal } from "../temporal-required-DqRzr7i0.js";
+import { a as ok } from "../result-BlgnMB0H.js";
+import { t as BetterSupabase } from "../define-B2ln373W.js";
 import { t as isList } from "../guards-6F2bCtQR.js";
-import { a as toBase64Url, r as fromBase64, t as base64ToText } from "../base64-D2gsioCY.js";
-import { o as resolveConfig } from "../config-DlKvtt95.js";
+import { a as toBase64Url, r as fromBase64, t as base64ToText } from "../base64-BmeCBgGo.js";
+import { o as resolveConfig } from "../config-BA1K4OPk.js";
 import { ENV_VARIABLES } from "../env/index.js";
-import { n as postgresExecutor } from "../executor-B_Hfobee.js";
-import "../replicas-CwrYp5Zj.js";
-import { a as tenantCredentialRef } from "../provider-DxRTex4x.js";
-import { i as requestOf, n as checkPermission, r as defineAuthorizer } from "../authorizer-ayxUDXXP.js";
-import { n as parseDbStats } from "../timing-CyTQPubY.js";
-import { n as rawError } from "../block-transport-bAKh-dGc.js";
-import { a as isScopeName, c as templateFunctions, l as templatePlaceholders, n as TEMPLATE_PLACEHOLDERS, s as scopeProblems, u as templateProblems } from "../access-sql-CrSbK1q-.js";
+import { t as defineController } from "../controller-D6NyNrlZ.js";
+import "../replicas-BvIL4_jL.js";
+import { a as tenantCredentialRef } from "../provider-DKh2xFZb.js";
+import { n as rawError } from "../block-transport-G4t1umrR.js";
+import { t as postgresExecutor } from "../executor-D1kYY5BA.js";
+import { i as requestOf, n as checkPermission, r as defineAuthorizer } from "../authorizer-DH7DjkL3.js";
+import { n as parseDbStats } from "../timing-BMCWgpdZ.js";
+import { t as mailHeaders } from "../delivery-B1mKaOen.js";
 import { toCloudEvents } from "../events/index.js";
-import { t as buildApiModel } from "../build-hPwk3_X5.js";
+import { d as money, l as isRate } from "../money-95Rff2vT.js";
+import { t as SHIPPING_LINE } from "../tax-D_kSCdWU.js";
+import { a as isScopeName, c as templateFunctions, l as templatePlaceholders, n as TEMPLATE_PLACEHOLDERS, s as scopeProblems, u as templateProblems } from "../access-sql-DUSSMaC3.js";
+import { t as buildApiModel } from "../build-Cm0T5MVG.js";
 import { timestamps } from "../plugins/timestamps/index.js";
 import { softDelete } from "../plugins/soft-delete/index.js";
 import { tenant } from "../plugins/tenant/index.js";
@@ -151,11 +155,11 @@ async function findSigningKeys(from) {
 		const supabase = join(dir, "supabase");
 		const toml = join(supabase, "config.toml");
 		if (existsSync(toml)) {
-			const configured = SIGNING_KEYS_PATH.exec(await readFile(toml, "utf8"))?.[1];
+			const configured = SIGNING_KEYS_PATH.exec(await readFile(toml, "utf-8"))?.[1];
 			const path = resolve(supabase, configured ?? "signing_keys.json");
 			if (existsSync(path)) return path;
 		}
-		if (dirname(dir) === dir) return void 0;
+		if (dirname(dir) === dir) return;
 	}
 }
 const isSigningKey = (value) => typeof value === "object" && value !== null && "kid" in value && typeof value.kid === "string" && "d" in value && typeof value.d === "string";
@@ -167,7 +171,7 @@ const isSigningKey = (value) => typeof value === "object" && value !== null && "
 async function localSigningKey(path) {
 	const file = path ?? process.env["SUPABASE_SIGNING_KEYS_PATH"] ?? await findSigningKeys(process.cwd());
 	if (!file || !existsSync(file)) throw new TypeError("No local signing key. Run `better-supabase keys`, set `signing_keys_path` in supabase/config.toml and restart the stack, or pass { alg: \"HS256\" } to sign with the local JWT secret.");
-	const keys = JSON.parse(await readFile(file, "utf8"));
+	const keys = JSON.parse(await readFile(file, "utf-8"));
 	const first = Array.isArray(keys) ? keys[0] : void 0;
 	if (!isSigningKey(first)) throw new TypeError(`${file} has no private ES256 key first.`);
 	return first;
@@ -181,7 +185,7 @@ async function signLocalJwt(claims, path) {
 /** 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;
+	if (typeof process === "undefined") return;
 	for (const name of names) {
 		const value = process.env[name];
 		if (value) return value;
@@ -601,7 +605,7 @@ async function rowsOf(outcome) {
 	return Array.isArray(result.data) ? result.data : [result.data];
 }
 function env(names) {
-	if (typeof process === "undefined") return void 0;
+	if (typeof process === "undefined") return;
 	for (const name of names) {
 		const value = process.env[name];
 		if (value) return value;
@@ -718,11 +722,27 @@ const chain = {
 	sub: "agent-runner",
 	act: { sub: "mcp-client-42" }
 };
+const agentAct = {
+	kind: "agent",
+	sub: "agent-7",
+	tools: ["search_knowledge"],
+	act: chain
+};
+const agentActReadOnly = {
+	kind: "agent",
+	sub: "agent-7",
+	tools: ["search_knowledge"],
+	read_only: true,
+	act: chain
+};
 /**
 * `supportSession` and `supportSessionReadOnly` are what `supportClaims`
 * mints (`act.kind: "support"`), `impersonation` what `actingAs` mints
-* (`act.kind: "impersonation"`), `oauthClient` a Supabase OAuth server token
-* and `agentChain` an RFC 8693 chain without `kind`.
+* (`act.kind: "impersonation"`), `oauthClient` a Supabase OAuth server
+* token (its identity scopes `openid` and `email` are left out of the
+* delegation), `agentChain` an RFC 8693 chain without `kind`, and
+* `agentRun` and `agentRunReadOnly` what `agentClaims` mints over that
+* chain (`act.kind: "agent"`, with `readOnly: true` for the second).
 */
 const supabaseClaimFixtures = {
 	supportSession: {
@@ -814,11 +834,7 @@ const supabaseClaimFixtures = {
 				kind: "oauth-client",
 				id: client
 			},
-			delegation: { scopes: [
-				"openid",
-				"email",
-				"posts:read"
-			] }
+			delegation: { scopes: ["posts:read"] }
 		}
 	},
 	agentChain: {
@@ -838,6 +854,149 @@ const supabaseClaimFixtures = {
 				chain
 			}
 		}
+	},
+	agentRun: {
+		claims: {
+			...base,
+			scope: "posts:read",
+			act: agentAct
+		},
+		expect: {
+			actor: {
+				kind: "agent",
+				id: "agent-7",
+				tools: ["search_knowledge"],
+				readOnly: false,
+				chain: agentAct
+			},
+			delegation: {
+				scopes: ["posts:read"],
+				chain: agentAct
+			}
+		}
+	},
+	agentRunReadOnly: {
+		claims: {
+			...base,
+			scope: "posts:read",
+			act: agentActReadOnly
+		},
+		expect: {
+			actor: {
+				kind: "agent",
+				id: "agent-7",
+				tools: ["search_knowledge"],
+				readOnly: true,
+				chain: agentActReadOnly
+			},
+			delegation: {
+				scopes: ["posts:read"],
+				chain: agentActReadOnly
+			}
+		}
+	}
+};
+const refused = {
+	kind: "invalid",
+	reason: "actor",
+	code: "ACTOR_INVALID"
+};
+/**
+* `legacySupportSession` is a 0.5.0 support token: `session_id` without
+* `kind`. better-supabase refuses it instead of reading it as a support
+* session; mint a new one with `supportClaims`. The others are malformed
+* levels: a support or agent `read_only` that is not a boolean, an agent
+* with a `session_id`, an empty tool name or `tools` that is not a list, a
+* `kind` better-supabase does not know, and a nested level without `sub`.
+*/
+const supabaseInvalidClaimFixtures = {
+	legacySupportSession: {
+		claims: {
+			...base,
+			act: {
+				sub: admin,
+				session_id: supportSessionId,
+				reason: "ticket 42"
+			}
+		},
+		expect: refused
+	},
+	supportReadOnlyNotBoolean: {
+		claims: {
+			...base,
+			act: {
+				kind: "support",
+				sub: admin,
+				session_id: supportSessionId,
+				read_only: "false"
+			}
+		},
+		expect: refused
+	},
+	agentWithSessionId: {
+		claims: {
+			...base,
+			act: {
+				kind: "agent",
+				sub: "agent-7",
+				session_id: supportSessionId
+			}
+		},
+		expect: refused
+	},
+	agentEmptyToolName: {
+		claims: {
+			...base,
+			act: {
+				kind: "agent",
+				sub: "agent-7",
+				tools: ["search_knowledge", ""]
+			}
+		},
+		expect: refused
+	},
+	agentToolsNotArray: {
+		claims: {
+			...base,
+			act: {
+				kind: "agent",
+				sub: "agent-7",
+				tools: "search_knowledge"
+			}
+		},
+		expect: refused
+	},
+	agentReadOnlyNotBoolean: {
+		claims: {
+			...base,
+			act: {
+				kind: "agent",
+				sub: "agent-7",
+				read_only: "true"
+			}
+		},
+		expect: refused
+	},
+	unknownKind: {
+		claims: {
+			...base,
+			act: {
+				kind: "delegate",
+				sub: "agent-7"
+			}
+		},
+		expect: refused
+	},
+	levelWithoutSub: {
+		claims: {
+			...base,
+			act: {
+				kind: "agent",
+				sub: "agent-7",
+				act: { client_id: client }
+			}
+		},
+		expect: refused
 	}
 };
 //#endregion
@@ -892,7 +1051,7 @@ function order(meta, keys) {
 }
 function statement(table, rows) {
 	const entries = Object.entries(rows);
-	if (entries.length === 0) return void 0;
+	if (entries.length === 0) return;
 	const columns = [];
 	for (const [, row] of entries) for (const [key, value] of Object.entries(row)) {
 		if (value === void 0 || columns.includes(key)) continue;
@@ -1220,6 +1379,319 @@ function testEventSink(sink, options = {}) {
 	]);
 }
 //#endregion
+//#region src/testing/kits/payment-provider.ts
+const kindOf$2 = (result) => result.ok ? "ok" : result.error.kind;
+const half = (value) => ({
+	amount: value.amount / 2n,
+	currency: value.currency
+});
+/**
+* Runs the `PaymentProvider` contract against `provider`: the API version,
+* refused amounts, a created payment and its fields, an idempotency key
+* that pays once, `not_found` for an unknown payment, and, with the
+* options that drive them, capture and refunds of an authorized payment
+* and webhook verification. Every call carries a fresh reference, so the
+* kit runs against a test account without cleanup.
+*/
+function testPaymentProvider(provider, options = {}) {
+	const amount = options.amount ?? money(1000n, "EUR");
+	const reference = () => `conformance-${crypto.randomUUID()}`;
+	const { authorize, webhook } = options;
+	const authorized = async () => {
+		const created = await provider.createPayment({
+			amount,
+			reference: reference(),
+			capture: "manual"
+		}).orThrow();
+		await authorize?.(created);
+		return created;
+	};
+	return conform(`PaymentProvider "${provider.name}"`, [
+		["has apiVersion 1 and a name", () => {
+			const version = provider.apiVersion;
+			expect(version === 1, `apiVersion is ${String(version)}`);
+			expect(provider.name.length > 0, "name is empty");
+		}],
+		["refuses a zero amount and a number instead of Money", async () => {
+			const zero = await provider.createPayment({
+				amount: {
+					amount: 0n,
+					currency: amount.currency
+				},
+				reference: reference()
+			});
+			expect(kindOf$2(zero) === "invalid_input", `zero gave ${kindOf$2(zero)}`);
+			const plain = await provider.createPayment({
+				amount: 1e3,
+				reference: reference()
+			});
+			expect(kindOf$2(plain) === "invalid_input", `a number gave ${kindOf$2(plain)}`);
+		}],
+		["creates a payment with its amount, reference and provider", async () => {
+			const ref = reference();
+			const payment = await provider.createPayment({
+				amount,
+				reference: ref
+			}).orThrow();
+			expect(payment.id.length > 0, "the payment has no id");
+			expect(payment.provider === provider.name, `provider is ${payment.provider}`);
+			expect(payment.reference === ref, `reference is ${payment.reference}`);
+			expect(payment.amount.amount === amount.amount && payment.amount.currency === amount.currency, `amount is ${String(payment.amount.amount)} ${payment.amount.currency}`);
+			expect(payment.refunded.amount === 0n, "a new payment has refunds");
+			expect(typeof payment.amount.amount === "bigint", "the amount is not a bigint");
+		}],
+		["pays once for one idempotency key", async () => {
+			const key = crypto.randomUUID();
+			const input = {
+				amount,
+				reference: reference()
+			};
+			const first = await provider.createPayment(input, { idempotencyKey: key }).orThrow();
+			const again = await provider.createPayment(input, { idempotencyKey: key }).orThrow();
+			expect(first.id === again.id, "the same key created a second payment");
+		}],
+		["returns not_found for an unknown payment", async () => {
+			const id = `conformance_missing_${crypto.randomUUID()}`;
+			const captured = await provider.capture(id);
+			expect(kindOf$2(captured) === "not_found", `capture gave ${kindOf$2(captured)}`);
+			const refunded = await provider.refund(id);
+			expect(kindOf$2(refunded) === "not_found", `refund gave ${kindOf$2(refunded)}`);
+		}],
+		provider.get !== void 0 && ["reads a payment back", async () => {
+			const created = await provider.createPayment({
+				amount,
+				reference: reference()
+			}).orThrow();
+			const read = await provider.get?.(created.id).orThrow();
+			expect(read?.id === created.id, "get returned another payment");
+			expect(read.reference === created.reference, "get lost the reference");
+		}],
+		authorize !== void 0 && ["captures an authorized payment", async () => {
+			const payment = await authorized();
+			const captured = await provider.capture(payment.id).orThrow();
+			expect(captured.status === "succeeded", `status is ${captured.status}`);
+			expect(captured.captured.amount === amount.amount, `captured ${String(captured.captured.amount)}`);
+		}],
+		authorize !== void 0 && ["refunds part of a payment and refuses more than is left", async () => {
+			const payment = await authorized();
+			await provider.capture(payment.id).orThrow();
+			const part = half(amount);
+			const refund = await provider.refund(payment.id, { amount: part }).orThrow();
+			expect(refund.paymentId === payment.id, "the refund names another payment");
+			expect(refund.amount.amount === part.amount, `refunded ${String(refund.amount.amount)}`);
+			expect(refund.status === "succeeded" || refund.status === "pending", `refund status is ${refund.status}`);
+			const tooMuch = await provider.refund(payment.id, { amount });
+			expect(kindOf$2(tooMuch) === "invalid_input", `refunding more than is left gave ${kindOf$2(tooMuch)}`);
+		}],
+		provider.cancel !== void 0 && ["cancels a payment that was not captured", async () => {
+			const created = await provider.createPayment({
+				amount,
+				reference: reference(),
+				capture: "manual"
+			}).orThrow();
+			const canceled = await provider.cancel?.(created.id).orThrow();
+			expect(canceled?.status === "canceled", `status is ${String(canceled?.status)}`);
+		}],
+		webhook !== void 0 && ["parses a signed webhook and refuses a tampered one", async () => {
+			const payment = await provider.createPayment({
+				amount,
+				reference: reference()
+			}).orThrow();
+			const { valid, tampered } = await webhook(payment);
+			const events = await provider.parseWebhook(valid).orThrow();
+			expect(events.length > 0, "a signed delivery gave no events");
+			for (const event of events) {
+				expect(event.id.length > 0, "an event has no id");
+				expect(event.paymentId === payment.id, `an event names payment ${event.paymentId}`);
+			}
+			const refused = await provider.parseWebhook(tampered);
+			expect(kindOf$2(refused) === "unauthorized", `a tampered delivery gave ${kindOf$2(refused)}`);
+		}]
+	]);
+}
+//#endregion
+//#region src/testing/kits/tax-provider.ts
+const kindOf$1 = (result) => result.ok ? "ok" : result.error.kind;
+const sum = (values) => values.reduce((total, value) => total + value.amount, 0n);
+/**
+* Runs the `TaxProvider` contract against `provider`: the API version,
+* refused carts, a quote with one line per cart line in order and a total
+* that adds up, inclusive prices, shipping, exempt customers, commit, and
+* full and partial reversals with their limits. Every commit carries a
+* fresh reference, so the kit runs against a test account without cleanup.
+*/
+function testTaxProvider(provider, options) {
+	const currency = options.currency ?? "EUR";
+	const { address, taxCategory } = options;
+	const expectTax = options.expectTax ?? true;
+	const line = (id, minor, inclusive = false) => ({
+		id,
+		amount: money(minor, currency),
+		inclusive,
+		...taxCategory === void 0 ? {} : { taxCategory }
+	});
+	const cart = (overrides = {}) => ({
+		currency,
+		address,
+		lines: [line("a", 10000n), line("b", 2500n)],
+		...overrides
+	});
+	const reference = () => `conformance-${crypto.randomUUID()}`;
+	const committed = async () => {
+		const quote = await provider.quote(cart()).orThrow();
+		return provider.commit({
+			quote,
+			reference: reference()
+		}).orThrow();
+	};
+	const addsUp = (quote) => {
+		expect(quote.totalTax.amount === sum(quote.lines.map((each) => each.tax)), "totalTax is not the sum of the lines' tax");
+		for (const each of quote.lines) {
+			expect(isRate(each.rate), `line ${each.lineId} has rate "${each.rate}"`);
+			expect(each.tax.currency === currency && each.taxable.currency === currency, `line ${each.lineId} is not in ${currency}`);
+		}
+	};
+	return conform(`TaxProvider "${provider.name}"`, [
+		["has apiVersion 1 and a name", () => {
+			const version = provider.apiVersion;
+			expect(version === 1, `apiVersion is ${String(version)}`);
+			expect(provider.name.length > 0, "name is empty");
+		}],
+		["refuses a cart that mixes currencies or has no country", async () => {
+			const other = currency === "USD" ? "EUR" : "USD";
+			const mixed = await provider.quote(cart({ lines: [{
+				id: "a",
+				amount: money(100n, other)
+			}] }));
+			expect(kindOf$1(mixed) === "invalid_input", `mixed currencies gave ${kindOf$1(mixed)}`);
+			const nowhere = await provider.quote(cart({ address: {
+				...address,
+				country: ""
+			} }));
+			expect(kindOf$1(nowhere) === "invalid_input", `no country gave ${kindOf$1(nowhere)}`);
+		}],
+		["quotes one line per cart line, in order, with a total that adds up", async () => {
+			const quote = await provider.quote(cart()).orThrow();
+			expect(quote.provider === provider.name, `provider is ${quote.provider}`);
+			expect(quote.lines.map((each) => each.lineId).join(",") === "a,b", `lines are ${quote.lines.map((each) => each.lineId).join(",")}`);
+			expect(quote.lines[0]?.taxable.amount === 10000n, "line a lost its amount");
+			addsUp(quote);
+			expect(expectTax ? quote.totalTax.amount > 0n : quote.totalTax.amount === 0n, `totalTax is ${String(quote.totalTax.amount)}`);
+		}],
+		["splits an inclusive price into taxable and tax", async () => {
+			const only = (await provider.quote(cart({ lines: [line("a", 12100n, true)] })).orThrow()).lines[0];
+			expect(only?.inclusive === true, "the line is not inclusive");
+			expect(only.taxable.amount + only.tax.amount === 12100n, "taxable and tax don't add up to the price");
+		}],
+		["quotes shipping as the last line", async () => {
+			const quote = await provider.quote(cart({ shipping: { amount: money(500n, currency) } })).orThrow();
+			expect(quote.lines.at(-1)?.lineId === SHIPPING_LINE, "the last line is not shipping");
+			addsUp(quote);
+		}],
+		["charges an exempt customer no tax", async () => {
+			const quote = await provider.quote(cart({ customer: { exempt: true } })).orThrow();
+			expect(quote.totalTax.amount === 0n, `totalTax is ${String(quote.totalTax.amount)}`);
+		}],
+		["commits a quote as a transaction", async () => {
+			const quote = await provider.quote(cart()).orThrow();
+			const ref = reference();
+			const transaction = await provider.commit({
+				quote,
+				reference: ref
+			}).orThrow();
+			expect(transaction.id.length > 0, "the transaction has no id");
+			expect(transaction.reference === ref, "the reference changed");
+			expect(transaction.totalTax.amount === quote.totalTax.amount, "the transaction's tax differs from the quote");
+		}],
+		["reverses a whole sale", async () => {
+			const sale = await committed();
+			const reversal = await provider.reverse({
+				transaction: sale,
+				reference: reference()
+			}).orThrow();
+			expect(reversal.totalTax.amount === -sale.totalTax.amount, `reversed ${String(reversal.totalTax.amount)} of ${String(sale.totalTax.amount)}`);
+		}],
+		["reverses part of a line and refuses more than was sold", async () => {
+			const sale = await committed();
+			const sold = sale.lines[0];
+			expect(sold !== void 0, "the sale has no lines");
+			const part = {
+				lineId: sold.lineId,
+				amount: money(sold.taxable.amount / 2n, currency),
+				tax: money(sold.tax.amount / 2n, currency)
+			};
+			const reversal = await provider.reverse({
+				transaction: sale,
+				reference: reference(),
+				lines: [part]
+			}).orThrow();
+			expect(reversal.totalTax.amount === -part.tax.amount, `reversed ${String(reversal.totalTax.amount)}`);
+			const tooMuch = await provider.reverse({
+				transaction: sale,
+				reference: reference(),
+				lines: [{
+					...part,
+					amount: money(sold.taxable.amount + 1n, currency)
+				}]
+			});
+			expect(kindOf$1(tooMuch) === "invalid_input", `reversing more than was sold gave ${kindOf$1(tooMuch)}`);
+			const unknown = await provider.reverse({
+				transaction: sale,
+				reference: reference(),
+				lines: [{
+					...part,
+					lineId: "conformance-unknown"
+				}]
+			});
+			expect(kindOf$1(unknown) === "invalid_input", `an unknown line gave ${kindOf$1(unknown)}`);
+		}]
+	]);
+}
+//#endregion
+//#region src/testing/kits/incoming-destination.ts
+/**
+* Proves an `IncomingDestination` accepts a delivery once per endpoint and
+* message id: a repeat reports the first id as a duplicate, while another
+* message id or another endpoint is new.
+* It delivers four messages with random endpoint ids; the destination keeps them.
+*/
+function testIncomingDestination(destination, options) {
+	const endpoint = crypto.randomUUID();
+	const delivery = (messageId, endpointId = endpoint) => ({
+		endpoint: {
+			id: endpointId,
+			tenant: options.tenant,
+			metadata: {}
+		},
+		source: options.source ?? "conformance",
+		messageId,
+		type: "conformance.test",
+		payload: {
+			type: "conformance.test",
+			messageId
+		},
+		headers: {}
+	});
+	return conform(`IncomingDestination "${destination.name}"`, [
+		hasName(destination),
+		["has apiVersion 1", () => {
+			const version = destination.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["reports a repeated endpoint and message id as a duplicate of the first", async () => {
+			const first = await destination.deliver(delivery("m1"));
+			expect(!first.duplicate, "the first delivery must not be a duplicate");
+			const again = await destination.deliver(delivery("m1"));
+			expect(again.duplicate, "a repeated delivery must be a duplicate");
+			expect(String(again.id) === String(first.id), "a duplicate must return the first delivery's id");
+		}],
+		["treats another message id or another endpoint as a new delivery", async () => {
+			expect(!(await destination.deliver(delivery("m2"))).duplicate, "another message id must be new");
+			expect(!(await destination.deliver(delivery("m1", crypto.randomUUID()))).duplicate, "the same id on another endpoint must be new");
+		}]
+	]);
+}
+//#endregion
 //#region src/testing/kits/plugin.ts
 /**
 * Proves a `Plugin` targets API v1, installs cleanly on its own and next to
@@ -1429,6 +1901,16 @@ function testQueueBackend(backend, options) {
 			const job = await claimOne();
 			expect(job, "read must return the sent message");
 			await backend.complete(job);
+		}],
+		backend.sendOnce && ["sends once per key, counting completed messages, when it has sendOnce", async () => {
+			const key = `once-${Date.now()}`;
+			const first = await backend.sendOnce?.(queue, { n: 5 }, 0, 3, key);
+			expect(first && !first.duplicate, "the first sendOnce must send");
+			const job = await claimOne();
+			expect(job?.id === first.id, "read must return the sent message");
+			await backend.complete(job);
+			const again = await backend.sendOnce?.(queue, { n: 5 }, 0, 3, key);
+			expect(again?.duplicate === true && again.id === first.id, "sendOnce after completion must return the first id as a duplicate");
 		}]
 	]);
 }
@@ -1517,6 +1999,113 @@ function testSupportSessionStore(store, options) {
 	]);
 }
 //#endregion
+//#region src/testing/kits/controller-binding.ts
+const PROBE_INITIAL = {
+	count: 0,
+	label: "initial"
+};
+function probe() {
+	let starts = 0;
+	let stops = 0;
+	let disposed = false;
+	let made;
+	const idle = () => void 0;
+	let emit = idle;
+	return {
+		create: () => {
+			const controller = defineController(PROBE_INITIAL, (state) => ({
+				actions: {
+					increment: () => {
+						state.set((current) => ({ count: current.count + 1 }));
+					},
+					rename: (label) => {
+						state.set({ label });
+					}
+				},
+				start: () => {
+					starts += 1;
+					emit = (patch) => {
+						state.set(patch);
+					};
+					return () => {
+						stops += 1;
+						emit = idle;
+					};
+				}
+			}));
+			made = {
+				...controller,
+				dispose: () => {
+					disposed = true;
+					controller.dispose();
+				}
+			};
+			return made;
+		},
+		emit: (patch) => {
+			emit(patch);
+		},
+		starts: () => starts,
+		stops: () => stops,
+		disposed: () => disposed,
+		controller: () => made
+	};
+}
+/**
+* Proves a framework binding over a block controller renders the initial
+* snapshot, follows each change, passes the actions through and stops the
+* controller's work (and disposes it) on unmount.
+*/
+function testControllerBinding(name, harness) {
+	const settle = async () => {
+		await harness.settle?.();
+	};
+	const mounted = async (run) => {
+		const current = probe();
+		const binding = await harness.mount(current.create);
+		try {
+			await settle();
+			await run(binding, current);
+		} finally {
+			await binding.unmount();
+		}
+	};
+	return conform(`ControllerBinding "${name}"`, [
+		["renders the initial snapshot", () => mounted((binding, current) => {
+			const state = binding.read();
+			expect(state.count === PROBE_INITIAL.count && state.label === PROBE_INITIAL.label, `rendered ${JSON.stringify(state)} instead of the initial snapshot`);
+			expect(current.starts() === 1, `the controller started ${current.starts()} times on mount, not once`);
+		})],
+		["renders a change from the controller", () => mounted(async (binding, current) => {
+			current.emit({ label: "changed" });
+			await settle();
+			expect(binding.read().label === "changed", `rendered label ${JSON.stringify(binding.read().label)} after the controller changed it`);
+			current.emit({ count: 5 });
+			await settle();
+			expect(binding.read().count === 5, `rendered count ${binding.read().count} after a second change`);
+		})],
+		["passes the controller's actions through", () => mounted(async (binding, current) => {
+			expect(binding.actions.increment === current.controller()?.actions.increment, "the binding's actions are not the controller's");
+			binding.actions.increment();
+			binding.actions.rename("renamed");
+			await settle();
+			const state = binding.read();
+			expect(state.count === 1 && state.label === "renamed", `rendered ${JSON.stringify(state)} after the actions ran`);
+		})],
+		["stops the controller on unmount", async () => {
+			const current = probe();
+			const binding = await harness.mount(current.create);
+			await settle();
+			await binding.unmount();
+			await settle();
+			expect(current.stops() === current.starts() && current.starts() > 0, `the controller started ${current.starts()} times and stopped ${current.stops()} times`);
+			if (harness.disposes ?? true) expect(current.disposed(), "unmount didn't dispose the controller");
+			current.emit({ count: 9 });
+			await settle();
+		}]
+	]);
+}
+//#endregion
 //#region src/testing/adapter.ts
 const MODULE_SERVER = {
 	env: {
@@ -1726,6 +2315,14 @@ function testAuthorizationProvider(provider) {
 				for (const scope of permission.scopes ?? []) expect(scopes.has(scope), `permission "${permission.key}" names unknown scope "${scope}"`);
 			}
 		}],
+		provider.operations && ["operations name listed permissions", () => {
+			const keys = provider.permissions === void 0 ? void 0 : new Set(provider.permissions.map((entry) => entry.key));
+			for (const [name, operation] of Object.entries(provider.operations)) {
+				expect(name !== "", "an operation name is empty");
+				expect(operation.permission !== "", `operation "${name}" names no permission`);
+				if (keys) expect(keys.has(operation.permission), `operation "${name}" needs "${operation.permission}", which permissions doesn't list`);
+			}
+		}],
 		provider.memberships && ["memberships name known scopes", () => {
 			for (const membership of provider.memberships) {
 				expect(TABLE.test(membership.table), `membership table "${membership.table}" is not schema.table`);
@@ -1770,6 +2367,185 @@ function testAuthorizationProvider(provider) {
 	]);
 }
 //#endregion
+//#region src/testing/authorization-hooks.ts
+/**
+* Proves `AuthorizationHooks` target API v1 and fail closed for strangers:
+* fan-out returns only subscribers it was given, an identity nobody linked
+* and a forged ticket resolve to `null`, a requester never approves their
+* own request, an unknown publisher can neither publish nor run, an
+* unlinked chat author gets nothing, an admin with no claims cannot start
+* a support session and never approves their own, and a delegated token
+* with no scopes maps to no permissions.
+*/
+function testAuthorizationHooks(hooks) {
+	const stranger = crypto.randomUUID();
+	const event = {
+		type: "conformance.checked",
+		tenant: crypto.randomUUID(),
+		actorId: stranger,
+		payload: {}
+	};
+	const subscribers = [{
+		principal: crypto.randomUUID(),
+		kind: "user"
+	}, {
+		principal: crypto.randomUUID(),
+		kind: "service"
+	}];
+	const subset = async (policy, where) => {
+		const kept = await policy(event, subscribers);
+		for (const entry of kept) expect(subscribers.includes(entry), `${where} returned a subscriber it was not given`);
+		expect((await policy(event, [])).length === 0, `${where} returned subscribers from an empty list`);
+	};
+	const supportStart = (extra) => {
+		const now = Math.floor(Date.now() / 1e3);
+		const claims = {
+			sub: stranger,
+			role: "authenticated",
+			aud: "authenticated",
+			iss: "conformance",
+			exp: now + 60,
+			iat: now,
+			...extra
+		};
+		return {
+			admin: {
+				kind: "user",
+				token: "",
+				claims,
+				user: {
+					id: stranger,
+					role: "authenticated"
+				},
+				source: "conformance",
+				expiresAt: claims.exp
+			},
+			targetUserId: crypto.randomUUID(),
+			reason: "conformance",
+			readOnly: true,
+			metadata: {}
+		};
+	};
+	const { delivery, identities, approverOf, tickets, automation, chat, delegation } = hooks;
+	return conform(`AuthorizationHooks "${hooks.name}"`, [
+		["targets API v1 and has a name", () => {
+			expect(hooks.apiVersion === 1, `apiVersion is ${String(hooks.apiVersion)}`);
+			expect(hooks.name !== "", "name is empty");
+		}],
+		delivery?.subscribers && ["subscribers returns a subset", () => subset(delivery.subscribers, "delivery.subscribers")],
+		delivery?.audience && ["audience returns a subset", () => subset(delivery.audience, "delivery.audience")],
+		identities && ["an unlinked identity is null", async () => {
+			expect(await identities.principalByIdentity({
+				kind: "email",
+				value: `${stranger}@conformance.invalid`
+			}) === null, "an address nobody linked resolved to someone");
+		}],
+		approverOf && ["a requester never approves their own request", async () => {
+			expect(!await approverOf({
+				userId: stranger,
+				claims: { sub: stranger }
+			}, {
+				kind: "tool",
+				subject: crypto.randomUUID(),
+				tenant: event.tenant,
+				requester: stranger
+			}), "approverOf allowed the requester");
+		}],
+		tickets && ["a forged ticket is null", async () => {
+			expect(await tickets.subject(`forged.${stranger}.ticket`) === null, "a forged ticket resolved to a context");
+		}],
+		automation?.mayPublish && ["an unknown publisher may not publish", async () => {
+			expect(!await automation.mayPublish({
+				publisher: stranger,
+				tenant: event.tenant,
+				permissions: ["conformance.write"],
+				claims: {
+					sub: stranger,
+					role: "authenticated"
+				}
+			}), "mayPublish allowed a publisher nobody knows");
+		}],
+		automation?.runAs && ["an unknown publisher runs as no one", async () => {
+			expect(await automation.runAs({
+				publisher: stranger,
+				tenant: event.tenant,
+				permissions: ["conformance.read"]
+			}) === null, "runAs returned claims for an unknown publisher");
+		}],
+		chat?.onAction && ["an unlinked chat author is refused", async () => {
+			const decided = await chat.onAction({
+				id: "approve",
+				author: {
+					kind: "chat",
+					provider: "conformance",
+					value: stranger
+				}
+			}, null);
+			expect(decided === void 0 || !decided.allowed, "onAction allowed an author with no identity link");
+		}],
+		hooks.support && ["an admin with no claims cannot start a support session", async () => {
+			expect(await hooks.support.authorize(supportStart({})) === false, "support.authorize allowed an admin with no claims");
+		}],
+		hooks.support && ["an admin never approves their own support session", async () => {
+			const decision = await hooks.support.authorize(supportStart({
+				user_role: "admin",
+				app_role: "admin"
+			}));
+			expect(typeof decision !== "object" || decision.approvedBy !== stranger, "support.authorize named the admin as their own approver");
+		}],
+		delegation && ["a delegation with no scopes grants no permissions", async () => {
+			expect((await delegation.permissions({
+				userId: stranger,
+				tenant: event.tenant,
+				clientId: "conformance",
+				scopes: []
+			})).length === 0, "delegation.permissions granted keys to a token with no scopes");
+		}]
+	]);
+}
+//#endregion
+//#region src/testing/delivery-transport.ts
+const KEY = "00000000-0000-4000-8000-00000000d0f0";
+/**
+* Runs the `DeliveryTransport` contract against `transport`: API version 1,
+* the `email` channel, a provider name, and one frozen sample message it
+* sends without mutating, with the delivery id as its idempotency key.
+* Throws a `ConformanceError` listing every failed check.
+*/
+function testDeliveryTransport(transport, options = {}) {
+	const message = deepFreeze({
+		from: "Conformance <conformance@example.test>",
+		to: options.to ?? "delivered@example.test",
+		subject: "Conformance check",
+		text: "Conformance check",
+		category: "notification",
+		headers: mailHeaders("notification", { url: "https://example.test/unsubscribe" })
+	});
+	return conform(`DeliveryTransport "${transport.provider}"`, [
+		["has apiVersion 1", () => {
+			const version = transport.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["sends on the email channel", () => {
+			const channel = transport.channel;
+			expect(channel === "email", `channel must be "email", got ${String(channel)}`);
+		}],
+		["has a provider name", () => {
+			expect(typeof transport.provider === "string" && transport.provider !== "", "provider must be a non-empty string");
+		}],
+		["sends a message without mutating it and returns a valid receipt", async () => {
+			const receipt = await transport.send(message, { idempotencyKey: KEY });
+			if (receipt === void 0) return;
+			expect(receipt.providerMessageId === void 0 || typeof receipt.providerMessageId === "string", "providerMessageId must be a string");
+		}],
+		options.received && ["passes the idempotency key and the headers to the provider", async () => {
+			const found = (await options.received()).find((entry) => entry.idempotencyKey === KEY);
+			expect(found, `no message arrived with idempotency key ${KEY}`);
+			for (const [name, value] of Object.entries(message.headers)) expect(found.headers[name] === value, `header ${name} must be "${value}", got ${String(found.headers[name])}`);
+		}]
+	]);
+}
+//#endregion
 //#region src/testing/authorizer.ts
 const OUTCOMES = /* @__PURE__ */ new Set([
 	"granted",
@@ -1900,7 +2676,7 @@ function testAuthorizer(authorizer, options) {
 * context, and it ignores `subject.properties.claims`.
 */
 function staticAuthorizer(options) {
-	const approvals = new Set(options.approvals ?? []);
+	const approvals = new Set(options.approvals);
 	const evaluate = (request) => {
 		const { subject, action } = request;
 		if (approvals.has(action)) return {
@@ -2390,7 +3166,8 @@ function sample(channel, email) {
 			priority: null,
 			createdAt,
 			readAt: null,
-			resolvedAt: null
+			resolvedAt: null,
+			fields: Object.freeze({})
 		}),
 		text: Object.freeze({ title: "Conformance check" })
 	});
@@ -2626,7 +3403,7 @@ function testChatState(state, options) {
 				"d"
 			]) await state.appendToList(key, value, { maxLength: 3 });
 			const list = await state.getList(key);
-			expect(list.join() === "b,c,d", `list is ${list.join()}`);
+			expect(list.join(",") === "b,c,d", `list is ${list.join(",")}`);
 			expect((await state.getList(fresh())).length === 0, "missing list is not empty");
 		}],
 		["queues per thread, keeps the newest maxSize and reports the depth", async () => {
@@ -2898,4 +3675,327 @@ function testCredentialProvider(provider, options) {
 	]);
 }
 //#endregion
-export { ConformanceError, LOCAL_JWT_SECRET, asUser, createTestSigner, defineSeed, expectDbBudget, expectInstant, expectTenantIsolation, isSeed, liteStack, localAuth, localSigningKey, signLocalJwt, signTestJwt, signTestJwtWithKey, staticAuthorizer, supabaseClaimFixtures, testAdapter, testAiTaskRunner, testAuthResolver, testAuthorizationProvider, testAuthorizer, testBlockTransportMiddleware, testBuilderStarter, testCacheAdapter, testChatState, testCredentialProvider, testDocumentFormat, testEmbedder, testEveDocumentBackend, testEventSink, testExecutor, testGenerator, testGraphCompiler, testNotificationChannel, testPlugin, testQueueBackend, testStreamStore, testSupportSessionStore, testWebhookSecretStore, testWebhookSigner, testWebhookTransport };
+//#region src/testing/act-cases.ts
+/**
+* The RFC 8693 `act` chains better-supabase accepts and refuses, as plain
+* JSON (`better-supabase/testing/act-cases.json`), so another library that
+* reads the same claims can run the same cases.
+*/
+const actCases = {
+	version: 1,
+	cases: [
+		{
+			"name": "no actor",
+			"claims": {},
+			"valid": true,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "oauth client_id",
+			"claims": { "client_id": "client-1" },
+			"valid": true,
+			"kind": "oauth-client",
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "chain without kind",
+			"claims": { "act": {
+				"sub": "agent-runner",
+				"act": { "sub": "mcp-client-42" }
+			} },
+			"valid": true,
+			"kind": "oauth-client",
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "support, read_only missing",
+			"claims": { "act": {
+				"kind": "support",
+				"sub": "admin-1",
+				"session_id": "session-1"
+			} },
+			"valid": true,
+			"kind": "support",
+			"readOnly": true,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "support, read_only true",
+			"claims": { "act": {
+				"kind": "support",
+				"sub": "admin-1",
+				"session_id": "session-1",
+				"read_only": true
+			} },
+			"valid": true,
+			"kind": "support",
+			"readOnly": true,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "support, read_only false",
+			"claims": { "act": {
+				"kind": "support",
+				"sub": "admin-1",
+				"session_id": "session-1",
+				"read_only": false
+			} },
+			"valid": true,
+			"kind": "support",
+			"readOnly": false,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "support, read_only as a string",
+			"claims": { "act": {
+				"kind": "support",
+				"sub": "admin-1",
+				"session_id": "session-1",
+				"read_only": "false"
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "support without session_id",
+			"claims": { "act": {
+				"kind": "support",
+				"sub": "admin-1",
+				"read_only": false
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "session_id without kind (0.5.0 support)",
+			"claims": { "act": {
+				"sub": "admin-1",
+				"session_id": "session-1"
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "impersonation",
+			"claims": { "act": {
+				"kind": "impersonation",
+				"sub": "admin-1",
+				"reason": "ticket 42"
+			} },
+			"valid": true,
+			"kind": "impersonation",
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "impersonation, read_only false",
+			"claims": { "act": {
+				"kind": "impersonation",
+				"sub": "admin-1",
+				"read_only": false
+			} },
+			"valid": true,
+			"kind": "impersonation",
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "agent, every tool",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7"
+			} },
+			"valid": true,
+			"kind": "agent",
+			"readOnly": false,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "agent, listed tools",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"tools": ["search_knowledge"]
+			} },
+			"valid": true,
+			"kind": "agent",
+			"readOnly": false,
+			"tools": ["search_knowledge"],
+			"mayWrite": true
+		},
+		{
+			"name": "agent, no tools",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"tools": []
+			} },
+			"valid": true,
+			"kind": "agent",
+			"readOnly": false,
+			"tools": [],
+			"mayWrite": true
+		},
+		{
+			"name": "agent, read_only true",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"read_only": true
+			} },
+			"valid": true,
+			"kind": "agent",
+			"readOnly": true,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "agent, read_only false",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"read_only": false
+			} },
+			"valid": true,
+			"kind": "agent",
+			"readOnly": false,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "agent, read_only as a string",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"read_only": "true"
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "agent over an OAuth client",
+			"claims": {
+				"scope": "posts:read",
+				"act": {
+					"kind": "agent",
+					"sub": "agent-7",
+					"tools": ["search_knowledge"],
+					"act": { "sub": "mcp-client-42" }
+				}
+			},
+			"valid": true,
+			"kind": "agent",
+			"readOnly": false,
+			"tools": ["search_knowledge"],
+			"mayWrite": true
+		},
+		{
+			"name": "agent, tools not a list",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"tools": "search_knowledge"
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "agent, empty tool name",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"tools": [""]
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "agent with session_id",
+			"claims": { "act": {
+				"kind": "agent",
+				"sub": "agent-7",
+				"session_id": "session-1"
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "unknown kind",
+			"claims": { "act": {
+				"kind": "robot",
+				"sub": "robot-1"
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": false
+		},
+		{
+			"name": "act not an object",
+			"claims": { "act": "agent-7" },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "act without sub",
+			"claims": { "act": { "kind": "agent" } },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		},
+		{
+			"name": "nested level without sub",
+			"claims": { "act": {
+				"sub": "agent-runner",
+				"act": { "sub": "" }
+			} },
+			"valid": false,
+			"kind": null,
+			"readOnly": null,
+			"tools": null,
+			"mayWrite": true
+		}
+	]
+};
+//#endregion
+export { ConformanceError, LOCAL_JWT_SECRET, PROBE_INITIAL, actCases, asUser, createTestSigner, defineSeed, expectDbBudget, expectInstant, expectTenantIsolation, isSeed, liteStack, localAuth, localSigningKey, signLocalJwt, signTestJwt, signTestJwtWithKey, staticAuthorizer, supabaseClaimFixtures, supabaseInvalidClaimFixtures, testAdapter, testAiTaskRunner, testAuthResolver, testAuthorizationHooks, testAuthorizationProvider, testAuthorizer, testBlockTransportMiddleware, testBuilderStarter, testCacheAdapter, testChatState, testControllerBinding, testCredentialProvider, testDeliveryTransport, testDocumentFormat, testEmbedder, testEveDocumentBackend, testEventSink, testExecutor, testGenerator, testGraphCompiler, testIncomingDestination, testNotificationChannel, testPaymentProvider, testPlugin, testQueueBackend, testStreamStore, testSupportSessionStore, testTaxProvider, testWebhookSecretStore, testWebhookSigner, testWebhookTransport };