better-supabase 0.7.1 → 0.9.0

package/dist/testing/index.d.ts

@@ -1,27 +1,37 @@
-import { H as Update, L as TableKey, P as SchemaMeta, a as AnyModels, i as AnyFunctions, x as Insert } from "../types-6BdhkmZe.js";
-import { r as Executor } from "../executor-DvsBbNBS.js";
-import { t as SqlClient } from "../executor-DbvExCFC.js";
-import { m as RequestContext, n as AnyPlugin } from "../plugin-FGY8UhYm.js";
-import { n as AuthResolver } from "../resolve-ChTYeTEl.js";
-import { a as CredentialSubject, i as CredentialRef, r as CredentialProvider } from "../provider-D-UEMvSD.js";
-import { k as QueueBackend } from "../queue-CLJurhdy.js";
-import { n as Embedder } from "../knowledge-BXBbT0Tr.js";
-import { o as StreamStore } from "../store-CGjgWu5n.js";
-import { B as DbStats, b as Db, t as BetterSupabase, u as CacheAdapter } from "../define-CJJkkr1-.js";
-import { r as EventSink, t as CloudEvent } from "../cloud-event-C1JCc1bH.js";
-import { t as BetterPostgres } from "../pool-CAu2nLrL.js";
-import { V as SupportSessionStore, i as ServerContext, o as ServerOptions } from "../server-Bh0EVSwU.js";
-import { s as Impersonator } from "../mfa-Daak8ukG.js";
-import { n as SessionActor, r as SessionDelegation } from "../actor-CQTlc1Hh.js";
-import { r as GuardOptions } from "../respond-DprrgyXX.js";
-import { i as AuthorizationProvider } from "../authorization-BFCqamMs.js";
-import { i as AiTaskRun, o as AiTaskRunner, t as AiTask } from "../ai-tasks-Cd1HMFvB.js";
-import { D as ResolvedConfig, _ as GeneratorInput, h as Generator, v as GeneratorModel } from "../config-D44Y7PAv.js";
-import { a as BlockTransportMiddleware } from "../block-hooks-plbZ0AbJ.js";
-import { t as NotificationChannel } from "../channel-_2Mx1Oyu.js";
-import { c as WebhookSecretStore, i as WebhookSigner, m as WebhookTransport } from "../signers-4y62_VIi.js";
-import { T as WorkflowGraph, i as BuilderStarter, r as BuilderStartCall, s as GraphCompiler } from "../types-AYOvcyep.js";
-import { t as EveDocumentBackend } from "../eve-gT2Fpjut.js";
+import { P as SchemaMeta, W as Update, a as AnyModels, i as AnyFunctions, x as Insert, z as TableKey } from "../types-YfwpIE-d.js";
+import { r as Executor } from "../executor-DoE-5iM8.js";
+import { m as RequestContext, n as AnyPlugin } from "../plugin-CDLJRFFg.js";
+import { t as BetterSupabaseEnv } from "../index-CETRk4YO.js";
+import { n as AuthResolver } from "../resolve-w9EpHzuM.js";
+import { a as CredentialSubject, i as CredentialRef, r as CredentialProvider } from "../provider-9gBq9W6k.js";
+import { n as SqlClient } from "../executor-BBHgjUJu.js";
+import { a as BlockTransportMiddleware } from "../block-hooks-BLPWD3Jt.js";
+import { a as SessionActor, o as SessionDelegation } from "../actor-BAhb-d1S.js";
+import { M as QueueBackend } from "../types-CdP0z5tS.js";
+import { n as Embedder } from "../knowledge-BXQ2-V0a.js";
+import { a as AuthorizationProvider } from "../authorization-DpRfs6Wx.js";
+import { o as StreamStore } from "../store-B5qYKsTh.js";
+import { t as ApiModel } from "../model-lUafmeBQ.js";
+import { l as VersionOf, t as AnyDocumentFormat } from "../format-CNwSjXUU.js";
+import { o as Authorizer } from "../authorizer-eiOjo-3l.js";
+import { i as EventSink, t as CloudEvent } from "../cloud-event-5rCEzIgK.js";
+import { Wt as DbStats, _ as Db, s as CacheAdapter, t as BetterSupabase } from "../define-DxHHbNEb.js";
+import { n as Impersonator } from "../impersonation-D5chOkrO.js";
+import { i as AuthorizationHooks } from "../authorization-hooks-DkmrnDX7.js";
+import { t as BetterPostgres } from "../pool-CwOCsX9e.js";
+import { R as SupportSessionStore, i as ServerContext, s as ServerOptions } from "../server-types-OohhIQb2.js";
+import { r as GuardOptions } from "../respond-C7I8kLK_.js";
+import { n as Controller } from "../controller-D845qKh2.js";
+import { i as AiTaskRun, o as AiTaskRunner, t as AiTask } from "../ai-tasks-Ih5oHfyj.js";
+import { r as WebhookInput } from "../signatures-BMdJ7neI.js";
+import { n as Money } from "../money-DFpWzQvk.js";
+import { a as Generator, c as GeneratorModel, s as GeneratorInput, x as ResolvedConfig } from "../codegen-DeoSt1mi.js";
+import { t as NotificationChannel } from "../channel-D-LHCY11.js";
+import { a as DeliveryTransport } from "../delivery-BeHgwS3k.js";
+import { C as PaymentProvider, l as TaxProvider, r as TaxAddress, y as Payment } from "../tax-DDZUB_oc.js";
+import { c as GraphCompiler, i as BuilderStarter, r as BuilderStartCall, z as WorkflowGraph } from "../types-vaoP9S9_.js";
+import { O as IncomingDestination, f as WebhookSecretStore, o as WebhookSigner, v as WebhookTransport } from "../signers-CXt_wA9S.js";
+import { t as EveDocumentBackend } from "../eve-DUF70Vgi.js";
 import { SupabaseClient } from "@supabase/supabase-js";
 import { Message, StateAdapter } from "chat";
 import { webcrypto } from "node:crypto";
@@ -98,6 +108,8 @@ interface LocalStack {
   readonly secretKey?: string;
   /** Enables `sql`: the same user over direct Postgres. */
   readonly postgres?: BetterPostgres;
+  /** `fetch` for the user's supabase-js client, e.g. `liteStack().fetch`. */
+  readonly fetch?: typeof fetch;
 }
 interface TestUser<M extends AnyModels, F extends AnyFunctions, E> {
   readonly token: string;
@@ -122,6 +134,55 @@ interface TestUser<M extends AnyModels, F extends AnyFunctions, E> {
  */
 export declare function asUser<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, claims: TestJwtClaims, stack?: LocalStack): Promise<TestUser<M, F, E>>;
 //#endregion
+//#region src/testing/lite.d.ts
+interface LiteStackOptions {
+  /**
+   * `sqlite-postgres` (default) stores data in in-memory SQLite and
+   * translates your Postgres SQL, as `lite init` does. `pglite` runs real
+   * Postgres in-process, with `rpc()` and `DEFAULT auth.uid()`.
+   */
+  readonly driver?: "sqlite-postgres" | "pglite";
+  /** Migration SQL, applied in order before `schemas`. DDL only; put rows in `seed`. */
+  readonly migrations?: readonly string[];
+  /** Declarative schema SQL (`supabase/schemas/*.sql`), applied after `migrations`. */
+  readonly schemas?: readonly string[];
+  /** Seed SQL, run after the schema as the database owner (RLS does not apply). */
+  readonly seed?: string | readonly string[];
+  /** The shared HS256 secret. Defaults to a random one. */
+  readonly jwtSecret?: string;
+}
+interface LiteStack extends AsyncDisposable {
+  /** A placeholder URL: requests never leave the process. */
+  readonly url: string;
+  readonly publishableKey: string;
+  readonly secretKey: string;
+  readonly jwtSecret: string;
+  /** Routes requests to the in-process Lite app. Pass it as `fetch` to `createServer`. */
+  readonly fetch: typeof globalThis.fetch;
+  /** The settings `createServer(betterSupabase, { env, backend: "lite", fetch })` takes. */
+  readonly env: BetterSupabaseEnv;
+  /** supabase-js with the publishable key, as an anonymous caller. */
+  readonly supabase: SupabaseClient;
+  /** supabase-js with the secret key: bypasses RLS, for setup. */
+  readonly admin: SupabaseClient;
+  /** A user with an HS256 token, as `asUser` signs it, whose clients route through `fetch`. */
+  asUser<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, claims: TestJwtClaims): Promise<TestUser<M, F, E>>;
+  /** Closes the database. */
+  close(): Promise<void>;
+}
+/**
+ * Supabase Lite in this process, for tests without Docker: an in-memory
+ * database with your schema, Auth with fresh API keys, and supabase-js
+ * clients whose requests go straight to Lite's `fetch` handler (no port).
+ *
+ * ```ts
+ * await using stack = await liteStack({ schemas: [await readFile("supabase/schemas/notes.sql", "utf8")] });
+ * const alice = await stack.asUser(betterSupabase, { sub: aliceId });
+ * expect(await alice.db.notes.count().orThrow()).toBe(1);
+ * ```
+ */
+export declare function liteStack(options?: LiteStackOptions): Promise<LiteStack>;
+//#endregion
 //#region src/testing/budget.d.ts
 /** The part of a Playwright `Request` the budget check reads. */
 interface BudgetRequest {
@@ -276,102 +337,6 @@ export declare class ConformanceError extends Error {
   readonly report: ConformanceReport;
   constructor(report: ConformanceReport);
 }
-type AnySupabase$1 = BetterSupabase<any, any, any, any>;
-interface TestExecutorOptions {
-  /** A definition whose schema matches the executor's database. Install no plugins. */
-  readonly betterSupabase: AnySupabase$1;
-  /** App key of a table with rows the executor can read. Defaults to the first table. */
-  readonly table?: string;
-  /** A row to insert and delete again, to check writes. Skips write checks when omitted. */
-  readonly create?: Readonly<Record<string, unknown>>;
-}
-/**
- * Proves an `Executor` meets the contract: rows keyed by the selection's
- * aliases, counts, `aborted` errors, failures returned as `Result`s rather
- * than thrown, and (with `create`) a write round trip and a `deleteMany`
- * that `maxAffected` refuses without deleting anything.
- *
- * ```ts
- * it('conforms', () => testExecutor(myExecutor, { betterSupabase, table: 'tags', create: { name: 'x' } }));
- * ```
- */
-export declare function testExecutor(executor: Executor, options: TestExecutorOptions): Promise<ConformanceReport>;
-/**
- * Proves a `CacheAdapter` accepts table and row targets, repeated and
- * concurrent calls, and never mutates its input.
- */
-export declare function testCacheAdapter(adapter: CacheAdapter, options?: {
-  readonly table?: string;
-}): Promise<ConformanceReport>;
-interface TestEventSinkOptions {
-  /** Events the sink delivered, for sinks that can be read back (an outbox, a test queue). */
-  readonly received?: () => readonly CloudEvent[] | Promise<readonly CloudEvent[]>;
-}
-/** Proves an `EventSink` accepts empty and full batches without mutating them, and delivers them when readable. */
-export declare function testEventSink(sink: EventSink, options?: TestEventSinkOptions): Promise<ConformanceReport>;
-interface TestQueueBackendOptions {
-  /** A queue the kit may fill and drain; use a fresh name per run. */
-  readonly queue: string;
-  /** Check that a repeated dedupe key returns the first id. Defaults to `backend.leases`. */
-  readonly dedupe?: boolean;
-}
-/**
- * Proves a `QueueBackend` round-trips payloads, hides claimed messages for
- * their lease, counts attempts, retries and dead-letters on `fail`, and
- * (when it has `leases`) rejects a stale attempt and extends a lease. It
- * writes to `options.queue` on the backend's real store.
- */
-export declare function testQueueBackend(backend: QueueBackend, options: TestQueueBackendOptions): Promise<ConformanceReport>;
-interface TestSupportSessionStoreOptions {
-  /** A user who may start support sessions in the store. */
-  readonly admin: {
-    readonly id: string;
-    readonly claims: Readonly<Record<string, unknown>>;
-  };
-  /** Two other users the admin may view the app as. */
-  readonly targets: readonly [string, string];
-}
-/**
- * Proves a `SupportSessionStore` starts sessions with the input it was
- * given, shows a running session only to its admin, ends the admin's
- * previous session on start, ends a session once, and lists sessions.
- * It writes sessions to the store; they are all ended when it returns.
- */
-export declare function testSupportSessionStore(store: SupportSessionStore, options: TestSupportSessionStoreOptions): Promise<ConformanceReport>;
-interface TestAuthResolverOptions {
-  /** Requests with credentials this resolver owns but that must not verify. */
-  readonly invalid: readonly Request[];
-  /** Requests that must resolve to a user or service, optionally with the expected user id. */
-  readonly valid?: readonly {
-    readonly request: Request;
-    readonly userId?: string;
-  }[];
-  /** A request without this resolver's credentials. Defaults to a bare GET. */
-  readonly unrelated?: Request;
-}
-/**
- * Proves an `AuthResolver` passes on requests it doesn't understand, fails
- * closed (`invalid`, never anon) on bad credentials, and never throws.
- */
-export declare function testAuthResolver(resolver: AuthResolver, options: TestAuthResolverOptions): Promise<ConformanceReport>;
-interface TestPluginOptions {
-  /** The definition without this plugin. */
-  readonly betterSupabase: AnySupabase$1;
-  /** Table to exercise. Defaults to the first table. */
-  readonly table?: string;
-  /** Context the plugin needs, such as `{ tenant }` for `tenant()`. */
-  readonly context?: RequestContext;
-  /** Row for `create`, to exercise `beforeMutation`. */
-  readonly create?: Readonly<Record<string, unknown>>;
-}
-/**
- * Proves a `Plugin` targets API v1, installs cleanly on its own and next to
- * the first-party plugins in either order, adds repository methods without
- * replacing base ones, keeps `context`, `transformQuery` and
- * `beforeMutation` pure and deterministic, and keeps executors'
- * results intact when it wraps them.
- */
-export declare function testPlugin(plugin: AnyPlugin, options: TestPluginOptions): Promise<ConformanceReport>;
 //#endregion
 //#region src/testing/isolation.d.ts
 interface IsolationTenant {
@@ -441,18 +406,48 @@ interface SupabaseClaimFixture {
     readonly actor: SessionActor;
     /** Set for support and impersonated sessions only. */
     readonly impersonator?: Impersonator;
-    /** Set for an `oauth-client` actor only. */
+    /** Set for an `oauth-client` actor, and an `agent` on a token with a `scope`. */
     readonly delegation?: SessionDelegation;
   };
 }
-type SupabaseClaimFixtureName = "supportSession" | "supportSessionReadOnly" | "impersonation" | "oauthClient" | "agentChain";
+type SupabaseClaimFixtureName = "supportSession" | "supportSessionReadOnly" | "impersonation" | "oauthClient" | "agentChain" | "agentRun" | "agentRunReadOnly";
 /**
  * `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).
  */
 export declare const supabaseClaimFixtures: Readonly<Record<SupabaseClaimFixtureName, SupabaseClaimFixture>>;
+/**
+ * Claims whose `act` chain better-supabase refuses, so the session must
+ * not pass as the user alone. `resolveAuth` and `toSession` both answer
+ * with this verdict.
+ */
+interface SupabaseInvalidClaimFixture {
+  /** Without `iat` and `exp`, so a test signer sets them. */
+  readonly claims: {
+    readonly sub: string;
+    readonly [claim: string]: unknown;
+  };
+  readonly expect: {
+    readonly kind: "invalid";
+    readonly reason: "actor";
+    readonly code: "ACTOR_INVALID";
+  };
+}
+type SupabaseInvalidClaimFixtureName = "legacySupportSession" | "supportReadOnlyNotBoolean" | "agentWithSessionId" | "agentEmptyToolName" | "agentToolsNotArray" | "agentReadOnlyNotBoolean" | "unknownKind" | "levelWithoutSub";
+/**
+ * `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`.
+ */
+export declare const supabaseInvalidClaimFixtures: Readonly<Record<SupabaseInvalidClaimFixtureName, SupabaseInvalidClaimFixture>>;
 //#endregion
 //#region src/testing/seed.d.ts
 /** Named rows per table, in app casing: `{ customers: { acme: { ... } } }`. */
@@ -484,6 +479,220 @@ export declare function isSeed(value: unknown): value is Seed<unknown>;
  */
 export declare function defineSeed<M extends AnyModels, D, F extends AnyFunctions, E, const S extends SeedFixtures<M>>(betterSupabase: BetterSupabase<M, D, F, E>, fixtures: S & ExactSeed<M, S>): Seed<S>;
 //#endregion
+//#region src/testing/kits/auth-resolver.d.ts
+interface TestAuthResolverOptions {
+  /** Requests with credentials this resolver owns but that must not verify. */
+  readonly invalid: readonly Request[];
+  /** Requests that must resolve to a user or service, optionally with the expected user id. */
+  readonly valid?: readonly {
+    readonly request: Request;
+    readonly userId?: string;
+  }[];
+  /** A request without this resolver's credentials. Defaults to a bare GET. */
+  readonly unrelated?: Request;
+}
+/**
+ * Proves an `AuthResolver` passes on requests it doesn't understand, fails
+ * closed (`invalid`, never anon) on bad credentials, and never throws.
+ */
+export declare function testAuthResolver(resolver: AuthResolver, options: TestAuthResolverOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/cache-adapter.d.ts
+/**
+ * Proves a `CacheAdapter` accepts table and row targets, repeated and
+ * concurrent calls, and never mutates its input.
+ */
+export declare function testCacheAdapter(adapter: CacheAdapter, options?: {
+  readonly table?: string;
+}): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/event-sink.d.ts
+interface TestEventSinkOptions {
+  /** Events the sink delivered, for sinks that can be read back (an outbox, a test queue). */
+  readonly received?: () => readonly CloudEvent[] | Promise<readonly CloudEvent[]>;
+}
+/** Proves an `EventSink` accepts empty and full batches without mutating them, and delivers them when readable. */
+export declare function testEventSink(sink: EventSink, options?: TestEventSinkOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/executor.d.ts
+type AnySupabase$1 = BetterSupabase<any, any, any, any>;
+interface TestExecutorOptions {
+  /** A definition whose schema matches the executor's database. Install no plugins. */
+  readonly betterSupabase: AnySupabase$1;
+  /** App key of a table with rows the executor can read. Defaults to the first table. */
+  readonly table?: string;
+  /** A row to insert and delete again, to check writes. Skips write checks when omitted. */
+  readonly create?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Proves an `Executor` meets the contract: rows keyed by the selection's
+ * aliases, counts, `aborted` errors, failures returned as `Result`s rather
+ * than thrown, and (with `create`) a write round trip and a `deleteMany`
+ * that `maxAffected` refuses without deleting anything.
+ *
+ * ```ts
+ * it('conforms', () => testExecutor(myExecutor, { betterSupabase, table: 'tags', create: { name: 'x' } }));
+ * ```
+ */
+export declare function testExecutor(executor: Executor, options: TestExecutorOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/payment-provider.d.ts
+interface TestPaymentProviderOptions {
+  /** What the kit charges. Defaults to 10.00 EUR. */
+  readonly amount?: Money;
+  /**
+   * Has the customer approve a `manual` payment, so it reaches
+   * `authorized` (with Stripe, confirm it with a test card). Without it
+   * the capture and refund checks are skipped.
+   */
+  readonly authorize?: (payment: Payment) => void | Promise<void>;
+  /**
+   * A delivery the provider's endpoint would receive for `payment`, signed
+   * with the provider's secret, and the same delivery with its body
+   * changed. Without it the webhook checks are skipped.
+   */
+  readonly webhook?: (payment: Payment) => Promise<{
+    readonly valid: WebhookInput;
+    readonly tampered: WebhookInput;
+  }>;
+}
+/**
+ * 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.
+ */
+export declare function testPaymentProvider(provider: PaymentProvider, options?: TestPaymentProviderOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/tax-provider.d.ts
+interface TestTaxProviderOptions {
+  /** An address the provider taxes, such as `{ country: "NL" }`. */
+  readonly address: TaxAddress;
+  /** Defaults to `EUR`. */
+  readonly currency?: string;
+  /** The category of the kit's lines; unset uses the provider's default. */
+  readonly taxCategory?: string;
+  /** The address has tax above zero. Defaults to `true`. */
+  readonly expectTax?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function testTaxProvider(provider: TaxProvider, options: TestTaxProviderOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/incoming-destination.d.ts
+interface TestIncomingDestinationOptions {
+  /** The tenant the test deliveries belong to. */
+  readonly tenant: string;
+  /** Defaults to `conformance`. */
+  readonly source?: string;
+}
+/**
+ * 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.
+ */
+export declare function testIncomingDestination(destination: IncomingDestination, options: TestIncomingDestinationOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/plugin.d.ts
+interface TestPluginOptions {
+  /** The definition without this plugin. */
+  readonly betterSupabase: AnySupabase$1;
+  /** Table to exercise. Defaults to the first table. */
+  readonly table?: string;
+  /** Context the plugin needs, such as `{ tenant }` for `tenant()`. */
+  readonly context?: RequestContext;
+  /** Row for `create`, to exercise `beforeMutation`. */
+  readonly create?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Proves a `Plugin` targets API v1, installs cleanly on its own and next to
+ * the first-party plugins in either order, adds repository methods without
+ * replacing base ones, keeps `context`, `transformQuery` and
+ * `beforeMutation` pure and deterministic, and keeps executors'
+ * results intact when it wraps them.
+ */
+export declare function testPlugin(plugin: AnyPlugin, options: TestPluginOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/queue-backend.d.ts
+interface TestQueueBackendOptions {
+  /** A queue the kit may fill and drain; use a fresh name per run. */
+  readonly queue: string;
+  /** Check that a repeated dedupe key returns the first id. Defaults to `backend.leases`. */
+  readonly dedupe?: boolean;
+}
+/**
+ * Proves a `QueueBackend` round-trips payloads, hides claimed messages for
+ * their lease, counts attempts, retries and dead-letters on `fail`, and
+ * (when it has `leases`) rejects a stale attempt and extends a lease. It
+ * writes to `options.queue` on the backend's real store.
+ */
+export declare function testQueueBackend(backend: QueueBackend, options: TestQueueBackendOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/support-session-store.d.ts
+interface TestSupportSessionStoreOptions {
+  /** A user who may start support sessions in the store. */
+  readonly admin: {
+    readonly id: string;
+    readonly claims: Readonly<Record<string, unknown>>;
+  };
+  /** Two other users the admin may view the app as. */
+  readonly targets: readonly [string, string];
+}
+/**
+ * Proves a `SupportSessionStore` starts sessions with the input it was
+ * given, shows a running session only to its admin, ends the admin's
+ * previous session on start, ends a session once, lists sessions and, with
+ * `expire`, leaves running sessions alone.
+ * It writes sessions to the store; they are all ended when it returns.
+ */
+export declare function testSupportSessionStore(store: SupportSessionStore, options: TestSupportSessionStoreOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/controller-binding.d.ts
+/** The state of the probe controller a binding is tested over. */
+interface ProbeSnapshot {
+  readonly count: number;
+  readonly label: string;
+}
+interface ProbeActions {
+  readonly increment: () => void;
+  readonly rename: (label: string) => void;
+}
+type ProbeController = Controller<ProbeSnapshot, ProbeActions>;
+/** A binding mounted over one controller, the way a component uses it. */
+interface MountedBinding {
+  /** The state the binding renders now. */
+  readonly read: () => ProbeSnapshot;
+  /** The actions the binding hands the component. */
+  readonly actions: ProbeActions;
+  readonly unmount: () => void | Promise<void>;
+}
+interface ControllerBindingHarness {
+  /** Mounts the binding over the controller `create` returns, as a component would. */
+  readonly mount: (create: () => ProbeController) => MountedBinding | Promise<MountedBinding>;
+  /** Lets the framework apply pending updates: a tick, a flush. */
+  readonly settle?: () => void | Promise<void>;
+  /**
+   * Whether unmounting disposes the controller. React keeps it for
+   * StrictMode's second mount and only stops its work. Default true.
+   */
+  readonly disposes?: boolean;
+}
+export declare const PROBE_INITIAL: ProbeSnapshot;
+/**
+ * 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.
+ */
+export declare function testControllerBinding(name: string, harness: ControllerBindingHarness): Promise<ConformanceReport>;
+//#endregion
 //#region src/testing/adapter.d.ts
 type AnySupabase = BetterSupabase<any, any, any, any>;
 /** What the adapter module asks a handler to do with the caller's context. */
@@ -540,6 +749,102 @@ export declare function testBlockTransportMiddleware(middleware: BlockTransportM
  */
 export declare function testAuthorizationProvider(provider: AuthorizationProvider): Promise<ConformanceReport>;
 //#endregion
+//#region src/testing/authorization-hooks.d.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.
+ */
+export declare function testAuthorizationHooks(hooks: AuthorizationHooks): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/delivery-transport.d.ts
+/** What the provider received for one message, as the test's fake reports it. */
+interface ReceivedDelivery {
+  readonly idempotencyKey: string;
+  readonly headers: Readonly<Record<string, string>>;
+}
+interface TestDeliveryTransportOptions {
+  /** The sample's recipient. Defaults to `delivered@example.test`. */
+  readonly to?: string;
+  /**
+   * What the provider received, read after the kit sends. When given, the
+   * kit checks that the idempotency key and the headers arrived as sent.
+   */
+  readonly received?: () => Promise<readonly ReceivedDelivery[]>;
+}
+/**
+ * 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.
+ */
+export declare function testDeliveryTransport(transport: DeliveryTransport, options?: TestDeliveryTransportOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/authorizer.d.ts
+interface TestAuthorizerOptions<Ref> {
+  /** Permission references to check; give at least one. */
+  readonly permissions: readonly Ref[];
+  /** A permission the authorizer grants for `context`, checked end to end. */
+  readonly granted?: {
+    readonly permission: Ref;
+    readonly context: RequestContext;
+  };
+  /** A permission reference the authorizer doesn't know; it must never be granted. */
+  readonly unknown?: Ref;
+}
+/**
+ * Proves an `Authorizer` targets API v1, keys every permission to the same
+ * string each time (and after a JSON round trip, so references are plain
+ * JSON), answers every request with a known outcome without mutating it,
+ * keeps the request order in `evaluations`, decides from the subject rather
+ * than the input (forged roles, claims and memberships in the resource
+ * properties or the context never turn a denial into a grant), never grants an unknown permission, and grants
+ * `options.granted` through `checkPermission`.
+ */
+export declare function testAuthorizer<Ref>(authorizer: Authorizer<Ref>, options: TestAuthorizerOptions<Ref>): Promise<ConformanceReport>;
+interface StaticAuthorizerOptions<Ref extends string> {
+  /**
+   * Permissions per role. The role is the subject's `role` property (the
+   * Postgres role: `authenticated`, `service_role`), or its type (`anon`).
+   */
+  readonly roles?: Readonly<Record<string, readonly Ref[]>>;
+  /** Permissions per subject id, on top of the role's. */
+  readonly grants?: Readonly<Record<string, readonly Ref[]>>;
+  /** Permissions that answer `approval-required` with the approval id `approval:<permission>`. */
+  readonly approvals?: readonly Ref[];
+}
+/**
+ * An in-memory `Authorizer` for tests and examples: permissions come from
+ * the subject's `role` and id only, never from the request's resource or
+ * context, and it ignores `subject.properties.claims`.
+ */
+export declare function staticAuthorizer<Ref extends string>(options: StaticAuthorizerOptions<Ref>): Authorizer<Ref>;
+//#endregion
+//#region src/testing/document-format.d.ts
+interface TestDocumentFormatOptions<V extends string = string> {
+  /**
+   * The model to lower. Defaults to a small model with a route, a stream,
+   * a webhook, a Realtime channel and a workflow.
+   */
+  readonly model?: ApiModel;
+  /** The versions to lower. Defaults to every version the format lists. */
+  readonly versions?: readonly V[];
+}
+/**
+ * Proves a `DocumentFormat` targets API v1, lists versions with pins and a
+ * known status, defaults to a version it lists that is not a preview, and,
+ * for every version: lowers the model without mutating it (also when the
+ * model is frozen), renders the same document twice, renders plain JSON or
+ * text, reports diagnostics with a kebab-case code, a severity and a
+ * message, finds no error in its own output with `lint`, and names a bare,
+ * stable file.
+ */
+export declare function testDocumentFormat<F extends AnyDocumentFormat>(format: F, options?: TestDocumentFormatOptions<VersionOf<F>>): Promise<ConformanceReport>;
+//#endregion
 //#region src/testing/generator.d.ts
 interface TestGeneratorOptions {
   /** Schema metadata to generate from: `schema.meta` from your generated module. */
@@ -719,4 +1024,33 @@ interface TestCredentialProviderOptions {
  */
 export declare function testCredentialProvider(provider: CredentialProvider, options: TestCredentialProviderOptions): Promise<ConformanceReport>;
 //#endregion
-export type { AdapterRun, BudgetPage, BudgetRequest, BudgetResponse, ConformanceCheck, ConformanceReport, DbBudgetExpectation, ExactSeed, InstantBrowserContext, InstantExpectation, InstantLocator, InstantPage, IsolationTable, IsolationTables, IsolationTenant, LocalStack, MeasuredRender, ResponseBudgetExpectation, ResponseDbStats, Seed, SeedFixtures, SigningJwk, SupabaseClaimFixture, SupabaseClaimFixtureName, TenantIsolationOptions, TestAdapterOptions, TestAiTaskRunnerOptions, TestAuthResolverOptions, TestBuilderStarterOptions, TestChatStateOptions, TestCredentialProviderOptions, TestEmbedderOptions, TestEveDocumentBackendOptions, TestEventSinkOptions, TestExecutorOptions, TestGeneratorOptions, TestGraphCompilerOptions, TestJwtClaims, TestNotificationChannelOptions, TestPluginOptions, TestQueueBackendOptions, TestSigner, TestStreamStoreOptions, TestSupportSessionStoreOptions, TestUser, TestWebhookSecretStoreOptions, TestWebhookSignerOptions, TestWebhookTransportOptions };
+//#region src/testing/act-cases.d.ts
+/** One `act` claim set, with what `actorOf` and `actor_may_write()` say about it. */
+interface ActCase {
+  readonly name: string;
+  /** Only the claims the verdict reads: `act`, `client_id` and `scope`. */
+  readonly claims: Readonly<Record<string, unknown>>;
+  /** `false` when the chain is invalid and the session must be refused. */
+  readonly valid: boolean;
+  /** The actor's kind; `null` without an actor or for an invalid chain. */
+  readonly kind: SessionActor["kind"] | null;
+  /** The actor's `readOnly` (support and agent); `null` otherwise. */
+  readonly readOnly: boolean | null;
+  /** An agent's `tools`; `null` when it lists none, which means every tool. */
+  readonly tools: readonly string[] | null;
+  /** What `better_supabase.actor_may_write()` returns for these claims. */
+  readonly mayWrite: boolean;
+}
+/** `better-supabase/testing/act-cases.json`, versioned so other parsers can pin it. */
+interface ActCases {
+  readonly version: 1;
+  readonly cases: readonly ActCase[];
+}
+/**
+ * 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.
+ */
+export declare const actCases: ActCases;
+//#endregion
+export type { ActCase, ActCases, AdapterRun, BudgetPage, BudgetRequest, BudgetResponse, ConformanceCheck, ConformanceReport, ControllerBindingHarness, DbBudgetExpectation, ExactSeed, InstantBrowserContext, InstantExpectation, InstantLocator, InstantPage, IsolationTable, IsolationTables, IsolationTenant, LiteStack, LiteStackOptions, LocalStack, MeasuredRender, MountedBinding, ProbeActions, ProbeController, ProbeSnapshot, ReceivedDelivery, ResponseBudgetExpectation, ResponseDbStats, Seed, SeedFixtures, SigningJwk, StaticAuthorizerOptions, SupabaseClaimFixture, SupabaseClaimFixtureName, SupabaseInvalidClaimFixture, SupabaseInvalidClaimFixtureName, TenantIsolationOptions, TestAdapterOptions, TestAiTaskRunnerOptions, TestAuthResolverOptions, TestAuthorizerOptions, TestBuilderStarterOptions, TestChatStateOptions, TestCredentialProviderOptions, TestDeliveryTransportOptions, TestDocumentFormatOptions, TestEmbedderOptions, TestEveDocumentBackendOptions, TestEventSinkOptions, TestExecutorOptions, TestGeneratorOptions, TestGraphCompilerOptions, TestIncomingDestinationOptions, TestJwtClaims, TestNotificationChannelOptions, TestPaymentProviderOptions, TestPluginOptions, TestQueueBackendOptions, TestSigner, TestStreamStoreOptions, TestSupportSessionStoreOptions, TestTaxProviderOptions, TestUser, TestWebhookSecretStoreOptions, TestWebhookSignerOptions, TestWebhookTransportOptions };