@hot-updater/test-utils 1.0.0-rc.17 → 1.0.0-rc.22

package/README.md

@@ -1,40 +1,49 @@
 # @hot-updater/test-utils
 
-Vitest suites for Hot Updater database adapters, providers and servers. The
-official providers and example servers run these same suites.
+Test suites and helpers for Hot Updater storage adapters, database adapters,
+providers, server plugins, client plugins and servers. The official adapters,
+providers, plugins and example servers run these same suites.
 
 ```bash
 pnpm add -D @hot-updater/test-utils @hot-updater/server vitest
 ```
 
+It uses the other Hot Updater packages only through their public API, and
+takes them as peer dependencies. `@hot-updater/server` and
+`@hot-updater/plugin-insights` are optional: the database suites load the
+server when they run, and the Insights suites use the plugin's types. The SQL
+test executors of `@hot-updater/test-utils/node` take `pg`, `mysql2` or
+`@electric-sql/pglite`, whichever you test on.
+
 ## Database adapters and providers
 
 Register three suites against a disposable test database:
 
-- `setupDatabaseAdapterConformanceSuite` runs the storage adapter contract case
+- `setupDatabaseAdapterConformanceSuite` runs the database adapter contract case
   by case: value round-trips, ordering, guards, all-or-nothing writes, unique
   and multi-valued indexes, paging under capped native pages, and concurrent
   writers.
 - `setupReadBudgetTestSuite` checks what each read of core and the built-in
-  plugins costs at the adapter, using `createMeasuredDatabase` from
-  `@hot-updater/server/db`. `postgresRowsExamined` and `mysqlRowsExamined` also
-  count the rows a SQL database examined.
+  plugins costs at the adapter, on `createMeasuredDatabase`: `createHotUpdater`
+  over `meterReads({ name, adapter: verifyAdapter(adapter) })` from
+  `@hot-updater/plugin-core`. `postgresRowsExamined` and `mysqlRowsExamined`
+  also count the rows a SQL database examined.
 - `setupDatabaseTestSuite` runs core, Bundles and the Release Catalog contract
   through the admin and client HTTP APIs of `createHotUpdater`, then the suites
   of the server plugins listed in `plugins`, such as the Insights plugin's
-  `insightsTestSuite()` from `@hot-updater/server/plugins/insights/testing`.
+  `insightsTestSuite()`.
 
 Connect your database's lifecycle and the real server:
 
 ```ts
 import { createHotUpdater } from "@hot-updater/server";
-import { createDatabasePluginApis } from "@hot-updater/server/db";
 import {
   createInsightsModel,
   insights,
 } from "@hot-updater/server/plugins/insights";
-import { insightsTestSuite } from "@hot-updater/server/plugins/insights/testing";
+
 import {
+  insightsTestSuite,
   setupDatabaseTestSuite,
   startHttpTestServer,
 } from "@hot-updater/test-utils";
@@ -63,9 +72,14 @@ setupDatabaseTestSuite({
   // The server above runs insights(), so its suite runs too.
   plugins: [
     insightsTestSuite({
+      // The plugin's API on the database, as a server running it assembles it.
       createModel: (database) =>
         createInsightsModel(
-          createDatabasePluginApis(database, [insights()]).insights,
+          createHotUpdater({
+            database,
+            plugins: [insights()],
+            clientAccess: "public",
+          }).api.insights,
         ),
     }),
   ],
@@ -80,15 +94,84 @@ client selector and keep a simulated device's state across updates, rollbacks
 and the built-in fallback. Native download, activation and restart remain
 device end-to-end responsibilities.
 
+## Storage adapters
+
+`setupStorageAdapterTestSuite` runs the storage adapter contract that deploy,
+patch, the Console, the server and `storage prune` rely on: the canonical URI
+of each key below the base path, streamed bodies, failed uploads that leave no
+object, exact deletes, URIs of another bucket or protocol, download URLs, and
+listing. A storage adapter's specs don't need `@hot-updater/server`.
+
+```ts
+import { setupStorageAdapterTestSuite } from "@hot-updater/test-utils";
+
+import { myStorage } from "./myStorage";
+
+setupStorageAdapterTestSuite({
+  name: "myStorage",
+  createStorage: async () => ({
+    storage: myStorage({ bucket: "bundles", basePath: "ota" }),
+    basePath: "ota",
+  }),
+  operations: ["put", "get", "getDownloadUrl", "exists", "delete"],
+});
+```
+
+`createStorage` returns the adapter over an empty bucket or base path for each
+case, and the `cleanup` it may return runs after the case. `operations` lists
+what the adapter implements: the suite fails when one of them is missing and
+skips the cases of the others.
+
+With `fetchDownloadUrls: true`, the suite downloads every `http(s)` URL
+`getDownloadUrl` returns and requires the object's bytes, for a spec against a
+real bucket or emulator whose URLs the test can reach.
+
 ## Plugins and servers
 
-- `createPluginTestHarness` runs one server plugin the way `createHotUpdater`
-  does, on a memory adapter by default, and measures what each API call reads.
+- `createPluginTestHarness` runs one server plugin on `createEngine` from
+  `@hot-updater/plugin-core`, the engine `createHotUpdater` runs plugins on, on
+  a memory adapter by default, and measures what each API call reads.
 - `setupReleaseCatalogTestSuite` with `createHttpTestClient` tests a running
   server by URL. Use `createHandlerHttpTestClient` inside a Workers Vitest pool.
 - Server processes can import `createReleaseCatalogTestStorage` from
   `@hot-updater/test-utils/node` to install the suites' storage fixtures.
 
+## Client plugins
+
+`@hot-updater/test-utils/react-native` runs client plugins the way the app
+does. `setupClientPlugin(plugin, options)` and
+`setupClientPlugins(plugins, options)` set plugins up as `HotUpdater.init`
+does, on the plugin host from `@hot-updater/protocol`, the one the SDK runs,
+against an in-memory device and a server the test answers. The entry loads
+neither React Native nor Vitest, so plugin specs run in plain Node under
+Vitest or Jest when the plugin imports `defineClientPlugin` from
+`@hot-updater/protocol`; the SDK's root entry loads React Native.
+
+```ts
+import { setupClientPlugin } from "@hot-updater/test-utils/react-native";
+
+const runtime = setupClientPlugin(myPlugin(), {
+  requestHeaders: { "x-api-key": "client-key" },
+});
+
+runtime.hooks.onAppReady(launch);
+await runtime.settled();
+
+expect(runtime.requests[0]?.json()).toEqual(expectedEvent);
+expect(runtime.errors).toEqual([]);
+```
+
+`hooks` calls each hook as the SDK does, without waiting for it, and
+`settled()` waits for what the hooks started. `requests` records what plugins
+sent with `context.fetch`, and the `respond` option answers each request,
+`204 No Content` by default. `errors` holds what the SDK reports to `onError`.
+`storage` is the device's plugin storage: pass it to the next setup to start
+the plugins again on the same device, or seed one with `createTestStorage()`.
+
 See the
-[custom database adapter guide](https://hot-updater.dev/docs/database-plugins/custom-database)
-for the adapter contract and complete specs for each suite.
+[storage adapter guide](https://hot-updater.dev/docs/storage-adapters/custom-storage#test-the-adapter),
+the
+[database adapter guide](https://hot-updater.dev/docs/database-adapters/custom-database),
+and the
+[client plugin guide](https://hot-updater.dev/docs/react-native-api/client-plugins#test-the-plugin)
+for the contracts and complete specs.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { ArtifactInfo, Bundle, ReleaseCatalog } from "@hot-updater/core";
-import { DatabaseAdapter, DatabaseReadCount, PhysicalTable } from "@hot-updater/plugin-core/internal";
-import { AggregateBatching, BundleRow, ChannelRow, DeployReleasePolicy, EngineDatabase, HotUpdaterCoreApi, ReleaseRow, StoragePlugin } from "@hot-updater/plugin-core";
+import { ArtifactInfo, Bundle } from "@hot-updater/protocol";
+import { AnyHotUpdaterPlugin, BundlePatchRow, BundleRow, ChannelRow, ClientAuth, DatabaseAdapter, DeployReleasePolicy, EngineDatabase, HotUpdaterCoreApi, HotUpdaterDatabase, KeyValueStore, ModuleSchema, PhysicalTable, PluginApis, ReadMeasurement, ReleaseRow, StorageAdapter, StorageOperation } from "@hot-updater/plugin-core";
+import { BundleEventRow, InsightsModel } from "@hot-updater/plugin-insights/server";
 //#region src/httpTestClient.d.ts
 type HttpTestRequestInit = NonNullable<ConstructorParameters<typeof Request>[1]>;
 type HttpTestRequest = (path: string, init?: HttpTestRequestInit) => Promise<Response>;
@@ -128,7 +128,7 @@ type DatabaseTestSuiteOptions<TDatabase extends EngineDatabase = EngineDatabase>
    */
   readonly createHttpClient: (options: {
     readonly database: TDatabase;
-    readonly storage: readonly StoragePlugin[];
+    readonly storage: readonly StorageAdapter[];
   }) => HttpTestServer | Promise<HttpTestServer>;
   /** The suites of the server plugins the provider opts in to test. */
   readonly plugins?: readonly DatabasePluginTestSuite<TDatabase>[];
@@ -175,9 +175,44 @@ declare const conformanceExpiring: PhysicalTable;
  */
 declare const setupDatabaseAdapterConformanceSuite: (options: DatabaseAdapterConformanceOptions) => void;
 //#endregion
+//#region src/setupStorageAdapterTestSuite.d.ts
+interface StorageAdapterTestSuiteOptions {
+  readonly name: string;
+  /**
+   * Returns the adapter over an empty bucket or base path. Every case creates
+   * its own and calls `cleanup` after it.
+   */
+  readonly createStorage: () => Promise<{
+    readonly storage: StorageAdapter;
+    /**
+     * The base path the adapter stores keys below. With it, every URI `put`
+     * returns must have the key `<basePath>/<key>`.
+     */
+    readonly basePath?: string;
+    readonly cleanup?: () => Promise<void>;
+  }>;
+  /**
+   * The operations the adapter implements. The suite requires them, with
+   * `put` and `get`, and skips the cases of every other operation. Without
+   * it, the suite skips the cases of the operations the adapter lacks.
+   */
+  readonly operations?: readonly StorageOperation[];
+  /**
+   * Fetches every `http(s)` URL `getDownloadUrl` returns and requires the
+   * object's bytes. Set it when the adapter runs against a bucket or emulator
+   * whose URLs the test can reach.
+   */
+  readonly fetchDownloadUrls?: boolean;
+}
+/**
+ * The storage adapter contract that deploy, patch, the Console, the server,
+ * and `storage prune` rely on. Every official storage adapter runs it.
+ */
+declare const setupStorageAdapterTestSuite: (options: StorageAdapterTestSuiteOptions) => void;
+//#endregion
 //#region src/sqlRowsExamined.d.ts
 /**
- * Rows a SQL database examined for the reads a storage adapter made: what
+ * Rows a SQL database examined for the reads a database adapter made: what
  * read-budget suites compare with the rows the adapter read.
  */
 interface RowsExamined {
@@ -237,72 +272,17 @@ declare const mysqlRowsExamined: (query: SqlQuery) => {
 };
 //#endregion
 //#region src/setupReadBudgetTestSuite.d.ts
-/** Core's API with the client routes' reads, which the public API leaves out. */
-type ReadBudgetCore = HotUpdaterCoreApi & {
-  getReleaseCatalog(input: {
-    readonly strategy: "APP_VERSION";
-    readonly platform: "ios" | "android";
-    readonly channelKey: string;
-    readonly appVersion: string;
-  }): Promise<ReleaseCatalog | null>;
-  getArtifactInfo(targetBundleId: string, currentBundleId: string, artifactProtocolVersion: 1): Promise<ArtifactInfo | null>;
-  latestReleaseId(scopeKey: string): Promise<string | null>;
-};
-/** How core reads bundle manifests and resolves file URLs. */
-interface ReadBudgetStorage {
-  readonly readStorageText?: (storageUri: string) => Promise<string | null>;
-  readonly resolveFileUrl: (storageUri: string | null) => Promise<string | null>;
-}
-/** What `createMeasuredDatabase` returns: core and the plugins on one engine in verify mode. */
-interface ReadBudgetDatabase {
-  readonly core: ReadBudgetCore;
-  readonly api: Readonly<Record<string, unknown>>;
-  readonly clientAuth?: {
-    authenticate(headers: Headers): Promise<boolean>;
-  };
-  measureReads<T>(read: () => Promise<T>): Promise<{
-    readonly result: T;
-    readonly adapter: DatabaseReadCount;
-    readonly engine: {
-      readonly calls: number;
-      readonly rows: number;
-    };
-  }>;
-}
-/**
- * What the suite takes from `@hot-updater/server`; pass those exports, which
- * keeps test-utils free of a dependency on the server.
- */
-interface ReadBudgetServer {
-  /** `createMeasuredDatabase` from `@hot-updater/server/db`. */
-  createMeasuredDatabase(adapter: DatabaseAdapter, plugins: readonly unknown[], options: {
-    readonly now: () => number;
-    readonly storage: ReadBudgetStorage;
-  }): ReadBudgetDatabase;
-  /** `toolingTargetOf` from `@hot-updater/server/database`: core's and the plugins' tables to create. */
-  toolingTargetOf(plugins: readonly unknown[]): {
-    readonly schema: {
-      readonly tables: readonly PhysicalTable[];
-    };
-  };
-  /** `[insights(), apiKeys()]`, the plugins whose reads have budgets. */
-  readonly plugins: readonly unknown[];
-  /** `targetBaseCandidateKey` from `@hot-updater/server/db`. */
-  targetBaseCandidateKey(target: {
-    readonly channel: string;
-    readonly platform: "ios" | "android";
-    readonly fingerprintHash: string | null;
-    readonly appVersion: string | null;
-  }): string | null;
-}
 interface ReadBudgetAdapterContext {
+  /**
+   * Core's tables, those of the plugins the suite measures, and the settings
+   * table, where the retention passes keep their lease.
+   */
   readonly tables: readonly PhysicalTable[];
   /** Test-only: the adapter must fetch at most this many rows per native page. */
   readonly nativePageSize: number;
 }
 interface ReadBudgetSuiteOptions {
   readonly name: string;
-  readonly server: ReadBudgetServer;
   /** Returns an adapter over freshly created, empty tables. */
   readonly createAdapter: (context: ReadBudgetAdapterContext) => Promise<{
     readonly adapter: DatabaseAdapter;
@@ -317,44 +297,18 @@ interface ReadBudgetSuiteOptions {
   }>;
 }
 /**
- * The read-budget suite (PRD S4) on one backend: core and the built-in
- * plugins in verify mode over the backend's adapter, native pages capped at
- * two rows. Every API in the read-budget list reads exactly its budget at the
- * adapter and at the engine; with `examined`, the database examines no more
- * rows than the adapter read, within the backend's native multipliers.
+ * The read-budget suite (PRD S4) on one backend: core and the server's
+ * built-in plugins on `createMeasuredDatabase` over the backend's adapter,
+ * native pages capped at two rows. Every API in the read-budget list reads
+ * exactly its budget at the adapter and at the engine; with `examined`, the
+ * database examines no more rows than the adapter read, within the backend's
+ * native multipliers. It loads `@hot-updater/server`, an optional peer.
  */
 declare const setupReadBudgetTestSuite: (options: ReadBudgetSuiteOptions) => void;
 //#endregion
 //#region src/setupAggregateBatchingTestSuite.d.ts
-interface Module {
-  readonly id: string;
-  readonly schema: object;
-}
-/**
- * What the suite takes from `@hot-updater/server/database`; pass that
- * module, which keeps test-utils free of a dependency on the server.
- */
-interface AggregateBatchingEngine {
-  resolveSchema(modules: readonly Module[]): {
-    readonly tables: readonly PhysicalTable[];
-  };
-  readonly aggregateBatchingModule: Module;
-  createDatabaseEngine(options: {
-    readonly adapter: DatabaseAdapter;
-    readonly schema: never;
-    readonly batching?: AggregateBatching;
-    readonly retry?: {
-      readonly attempts?: number;
-    };
-  }): {
-    database(module: Module): unknown;
-    flush(): Promise<void>;
-  };
-}
 interface AggregateBatchingSuiteOptions {
   readonly name: string;
-  /** `import * as engine from "@hot-updater/server/database"`. */
-  readonly engine: AggregateBatchingEngine;
   /** Returns an adapter over an empty store; each case calls it once. */
   readonly createAdapter: () => Promise<{
     readonly adapter: DatabaseAdapter;
@@ -368,7 +322,7 @@ interface AggregateBatchingSuiteOptions {
  * writes with each transaction and a compaction merges once, and a memory
  * buffer, read back exactly as transactional writes read.
  */
-declare const setupAggregateBatchingTestSuite: ({ name, engine, createAdapter, oversizedRows }: AggregateBatchingSuiteOptions) => void;
+declare const setupAggregateBatchingTestSuite: ({ name, createAdapter, oversizedRows }: AggregateBatchingSuiteOptions) => void;
 //#endregion
 //#region src/runContentionHarness.d.ts
 /** Delays every adapter call by `ms`, like a round trip to a remote database. */
@@ -396,40 +350,48 @@ interface ContentionReport {
  */
 declare const runContentionHarness: (options: ContentionOptions) => Promise<ContentionReport>;
 //#endregion
-//#region src/createPluginTestHarness.d.ts
-interface HarnessModule {
-  readonly id: string;
-  readonly schema: object;
-  readonly namespace?: string;
+//#region src/createMeasuredDatabase.d.ts
+/** How core reads bundle manifests and resolves the file URLs of `storage://` URIs. */
+interface MeasuredDatabaseStorage {
+  readonly readStorageText?: (storageUri: string) => Promise<string | null>;
+  readonly resolveFileUrl: (storageUri: string) => Promise<string>;
 }
-interface HarnessEngine {
-  database(module: HarnessModule): unknown;
-  measureReads<T>(read: () => Promise<T>): Promise<{
-    readonly result: T;
-    readonly adapter: DatabaseReadCount;
-    readonly engine: {
-      readonly calls: number;
-      readonly rows: number;
-    };
-  }>;
+interface MeasuredDatabaseOptions {
+  /**
+   * The plugins' clock, which they read through `ctx.now`. Core's
+   * timestamps and the retention passes run on `Date.now`.
+   */
+  readonly now?: () => number;
+  /**
+   * The storage of `storage://` URIs, for reads that resolve them, such as
+   * artifact resolution; without it those reads fail.
+   */
+  readonly storage?: MeasuredDatabaseStorage;
+}
+/** Core and the plugins' APIs on `createHotUpdater`, with the database's read meter. */
+interface MeasuredDatabase<TApi = Readonly<Record<string, unknown>>> {
+  readonly core: HotUpdaterCoreApi;
+  readonly api: TApi;
+  /** The client-route policy, when a plugin provides one. */
+  readonly clientAuth?: ClientAuth;
+  /** Runs `read` and reports what it read at the adapter and at the engine. */
+  measureReads<T>(read: () => Promise<T>): Promise<ReadMeasurement<T>>;
 }
 /**
- * What the harness takes from `@hot-updater/server/database`; pass that
- * module, which keeps test-utils free of a dependency on the server.
+ * Core and the plugins over `adapter` as `createHotUpdater` runs them: what
+ * read-budget suites measure. The database is `meterReads` over
+ * `verifyAdapter(adapter)`, so every adapter call is checked against the
+ * contract and `measureReads` reports each call's reads; the adapter runs
+ * as given, without the schema fence. It loads `@hot-updater/server`, an
+ * optional peer, when called.
  */
-interface PluginTestEngine {
-  resolveSchema(modules: readonly HarnessModule[]): {
-    readonly tables: readonly PhysicalTable[];
-  };
-  createDatabaseEngine(options: {
-    readonly adapter: DatabaseAdapter;
-    readonly schema: never;
-    readonly verify?: boolean;
-  }): HarnessEngine;
-}
+declare const createMeasuredDatabase: <const TPlugins extends readonly AnyHotUpdaterPlugin[]>(adapter: DatabaseAdapter, plugins: TPlugins, options?: MeasuredDatabaseOptions) => Promise<MeasuredDatabase<PluginApis<TPlugins>>>;
+//#endregion
+//#region src/createPluginTestHarness.d.ts
 interface HarnessPlugin {
   readonly id: string;
-  readonly schema: object;
+  readonly schemaVersion: string;
+  readonly schema: ModuleSchema;
   /** `false` keeps the declared table names, as `createHotUpdater` does. */
   readonly namespace?: false;
   init(context: never): {
@@ -437,36 +399,111 @@ interface HarnessPlugin {
   };
 }
 interface PluginTestHarnessOptions {
-  /** `import * as engine from "@hot-updater/server/database"`. */
-  readonly engine: PluginTestEngine;
   /** Defaults to a fresh memory adapter. */
   readonly adapter?: DatabaseAdapter;
   /** The plugin's clock; `setNow` changes it later. */
   readonly now?: () => number;
 }
 /**
- * Runs one plugin the way `createHotUpdater` does, on a memory adapter in
- * verify mode, so tests can call its API and measure what each call reads.
+ * Runs one plugin on `createEngine`, the storage engine `createHotUpdater`
+ * runs its plugins on, so tests can call its API and measure what each call
+ * reads. Every adapter call is checked against the adapter contract
+ * (`verifyAdapter`), and `ctx.core` is empty: core's reads need a server.
+ * The engine gets the adapter without `prune`, as a store that expires rows
+ * itself would give it, so no retention pass adds to what a call reads and
+ * writes; rows stay past their retention.
  */
-declare const createPluginTestHarness: <TPlugin extends HarnessPlugin>(plugin: TPlugin, options: PluginTestHarnessOptions) => Promise<{
+declare const createPluginTestHarness: <TPlugin extends HarnessPlugin>(plugin: TPlugin, options?: PluginTestHarnessOptions) => Promise<{
   api: ReturnType<TPlugin["init"]>["api"];
   instance: ReturnType<TPlugin["init"]>;
-  /** The plugin's own database handle; cast it to its `HotUpdaterDatabase` type. */
-  db: unknown;
+  /** The plugin's own database handle. */
+  db: HotUpdaterDatabase<TPlugin["schema"]>;
   adapter: DatabaseAdapter;
-  tables: readonly PhysicalTable[];
-  /** Reads at both boundaries while `read` runs. */
-  measureReads: <T>(read: () => Promise<T>) => Promise<{
-    readonly result: T;
-    readonly adapter: DatabaseReadCount;
-    readonly engine: {
-      readonly calls: number;
-      readonly rows: number;
-    };
-  }>;
-  setNow: (now: () => number) => void;
+  /** The plugin's physical tables. */
+  tables: import("@hot-updater/plugin-core").PhysicalTable[];
+  /** Reads at the adapter and at the engine while `read` runs. */
+  measureReads: <T>(read: () => Promise<T>) => Promise<import("@hot-updater/plugin-core").ReadMeasurement<T>>;
+  setNow: (next: () => number) => void;
+}>;
+//#endregion
+//#region src/databaseTestFixtures.d.ts
+declare const createChannelRowFixture: (name?: string) => ChannelRow;
+declare const createBundleRowFixture: (suffix: string, _channel?: string) => BundleRow;
+declare const createBundlePatchRowFixture: (suffix: string, bundleId: string, baseBundleId: string, orderIndex?: number) => BundlePatchRow;
+declare const createReleaseRowFixture: (suffix: string, bundle: BundleRow, channel: ChannelRow) => ReleaseRow;
+declare const createBundleFixture: (suffix: string, _channel?: string) => Bundle;
+//#endregion
+//#region src/storeBundles.d.ts
+/**
+ * Stores bundles and their patches with no release, as a database holds an
+ * artifact that no release uses. `deploy` always adds a release, and
+ * deleting a bundle's last release deletes the bundle, so tests store such
+ * bundles through the engine. A patch's base comes before it in `bundles`.
+ */
+declare const storeBundles: (database: EngineDatabase, bundles: readonly Bundle[]) => Promise<void>;
+//#endregion
+//#region src/insights/expectInsightsIndex.d.ts
+/** Allow committed secondary indexes to catch up; query failures still fail. */
+declare const expectInsightsIndex: <T>(query: () => Promise<T>, expected: T) => Promise<void>;
+//#endregion
+//#region src/insights/fixtures.d.ts
+/** An applied update from install `suffix`, received at `receivedAtMs`. */
+declare const createBundleEventRowFixture: (suffix: string, receivedAtMs: number) => Extract<BundleEventRow, {
+  type: "UPDATE_APPLIED" | "RECOVERED";
 }>;
 //#endregion
+//#region src/insights/setupInsightsHttpTestSuite.d.ts
+/**
+ * The Insights plugin's routes on a database: a client reports an event, and
+ * the admin routes read it back. The server must run `insights()`.
+ */
+declare const setupInsightsHttpTestSuite: (options: {
+  readonly getClient: () => HttpTestClient;
+}) => void;
+//#endregion
+//#region src/insights/setupInsightsModelTestSuite.d.ts
+/**
+ * The Insights report contract on one database: pass the Insights plugin's
+ * model over it, `createInsightsModel(createHotUpdater({ database, plugins:
+ * [insights()], clientAccess: "public" }).api.insights)`, as `createDatabase`.
+ */
+declare const setupInsightsModelTestSuite: (lifecycle: DatabaseTestLifecycle<InsightsModel>) => void;
+//#endregion
+//#region src/insights/index.d.ts
+/**
+ * The Insights plugin's tests, for `setupDatabaseTestSuite`'s `plugins`: its
+ * HTTP routes on the provider's server, which must run `insights()`, and
+ * with `createModel` its report contract on the provider's database, such as
+ * `(database) => createInsightsModel(createHotUpdater({ database, plugins:
+ * [insights()], clientAccess: "public" }).api.insights)`.
+ */
+declare const insightsTestSuite: <TDatabase = EngineDatabase>(options?: {
+  readonly createModel?: (database: TDatabase) => InsightsModel;
+}) => {
+  name: string;
+  register: (context: {
+    readonly getClient: () => HttpTestClient;
+    readonly getDatabase: () => TDatabase;
+  }) => void;
+};
+//#endregion
+//#region src/kvTestStore.d.ts
+interface MemoryKeyValueStoreOptions {
+  /** Test-only: the most items one `query` page returns. */
+  readonly nativePageSize?: number;
+  readonly limits?: KeyValueStore["limits"];
+}
+/**
+ * An in-memory key-value store that behaves like DynamoDB where the adapter
+ * can tell: a write checks every condition against the state before it,
+ * refuses two ops on one item, and applies all ops or none.
+ */
+declare const createMemoryKeyValueStore: (options?: MemoryKeyValueStoreOptions) => KeyValueStore & {
+  readonly items: () => number;
+  /** Each item's expiry, as a store's native TTL would hold it, by `[pk, sk]` JSON. */
+  readonly expiries: () => ReadonlyMap<string, number>;
+};
+//#endregion
 //#region src/setupReleaseCatalogTestSuite.d.ts
 /**
  * Server conformance through HTTP only, on admin API protocol 2. The caller
@@ -494,6 +531,6 @@ declare const releaseCatalogArtifact: (bundle: BundleRow) => ArtifactInfo;
 /** Install these storage objects in the test server, independently of its DB. */
 declare const RELEASE_CATALOG_STORAGE_FIXTURES: Readonly<Record<string, string>>;
 /** Storage boundary shared by provider and separately spawned server tests. */
-declare const createReleaseCatalogTestStorage: () => StoragePlugin;
+declare const createReleaseCatalogTestStorage: () => StorageAdapter;
 //#endregion
-export { AdminApiTestClient, AggregateBatchingEngine, AggregateBatchingSuiteOptions, ContentionOptions, ContentionReport, DatabaseAdapterConformanceContext, DatabaseAdapterConformanceOptions, DatabasePluginTestSuite, type DatabaseTestLifecycle, DatabaseTestSuiteOptions, HttpTestClient, HttpTestHandlers, HttpTestRequest, HttpTestRequestInit, HttpTestServer, PluginTestEngine, PluginTestHarnessOptions, RELEASE_CATALOG_DOWNLOAD_HASH, RELEASE_CATALOG_MANIFEST_URIS, RELEASE_CATALOG_STORAGE_FIXTURES, ReadBudgetAdapterContext, ReadBudgetDatabase, ReadBudgetServer, ReadBudgetStorage, ReadBudgetSuiteOptions, RowsExamined, SqlExecutorLike, SqlQuery, SqlStatementLike, conformanceCounters, conformanceExpiring, conformanceItems, createAdminApiTestClient, createHandlerHttpTestClient, createHttpTestClient, createPluginTestHarness, createReleaseCatalogTestStorage, jsonRequest, mysqlRowsExamined, postgresRowsExamined, releaseCatalogArtifact, releaseCatalogDownloadUrl, runContentionHarness, setupAggregateBatchingTestSuite, setupBundleMethodsTestSuite, setupCoreAdminTestSuite, setupDatabaseAdapterConformanceSuite, setupDatabaseTestSuite, setupReadBudgetTestSuite, setupReleaseCatalogTestSuite, setupSemverSatisfiesTestSuite, startHttpTestServer, toDeployBundle, withAdapterLatency };
+export { AdminApiTestClient, AggregateBatchingSuiteOptions, ContentionOptions, ContentionReport, DatabaseAdapterConformanceContext, DatabaseAdapterConformanceOptions, DatabasePluginTestSuite, type DatabaseTestLifecycle, DatabaseTestSuiteOptions, HttpTestClient, HttpTestHandlers, HttpTestRequest, HttpTestRequestInit, HttpTestServer, MeasuredDatabase, MeasuredDatabaseOptions, MeasuredDatabaseStorage, MemoryKeyValueStoreOptions, PluginTestHarnessOptions, RELEASE_CATALOG_DOWNLOAD_HASH, RELEASE_CATALOG_MANIFEST_URIS, RELEASE_CATALOG_STORAGE_FIXTURES, ReadBudgetAdapterContext, ReadBudgetSuiteOptions, RowsExamined, SqlExecutorLike, SqlQuery, SqlStatementLike, StorageAdapterTestSuiteOptions, conformanceCounters, conformanceExpiring, conformanceItems, createAdminApiTestClient, createBundleEventRowFixture, createBundleFixture, createBundlePatchRowFixture, createBundleRowFixture, createChannelRowFixture, createHandlerHttpTestClient, createHttpTestClient, createMeasuredDatabase, createMemoryKeyValueStore, createPluginTestHarness, createReleaseCatalogTestStorage, createReleaseRowFixture, expectInsightsIndex, insightsTestSuite, jsonRequest, mysqlRowsExamined, postgresRowsExamined, releaseCatalogArtifact, releaseCatalogDownloadUrl, runContentionHarness, setupAggregateBatchingTestSuite, setupBundleMethodsTestSuite, setupCoreAdminTestSuite, setupDatabaseAdapterConformanceSuite, setupDatabaseTestSuite, setupInsightsHttpTestSuite, setupInsightsModelTestSuite, setupReadBudgetTestSuite, setupReleaseCatalogTestSuite, setupSemverSatisfiesTestSuite, setupStorageAdapterTestSuite, startHttpTestServer, storeBundles, toDeployBundle, withAdapterLatency };