@jskit-ai/agent-docs 0.1.280 → 0.1.282

package/skills/jskit/references/patterns/auth/supabase-auth/example/package.json

@@ -2,6 +2,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/auth-provider-supabase-core": "0.2.13"
+    "@jskit-ai/auth-provider-supabase-core": "0.2.15"
   }
 }

package/skills/jskit/references/patterns/connectors/calendar-cli/example/package.json

@@ -7,10 +7,10 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/connectors-core": "0.2.12",
-    "@jskit-ai/connector-google-calendar": "0.2.12",
-    "@jskit-ai/database-runtime": "0.1.260",
-    "@jskit-ai/database-runtime-mysql": "0.1.258",
+    "@jskit-ai/connectors-core": "0.2.14",
+    "@jskit-ai/connector-google-calendar": "0.2.14",
+    "@jskit-ai/database-runtime": "0.1.262",
+    "@jskit-ai/database-runtime-mysql": "0.1.260",
     "knex": "^3.1.0"
   }
 }

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/package.json

@@ -9,8 +9,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.12",
-    "@jskit-ai/resource-crud-core": "0.1.202"
+    "@jskit-ai/crud-core": "0.2.14",
+    "@jskit-ai/resource-crud-core": "0.1.204"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/database/mysql-application/PATTERN.md

@@ -61,27 +61,38 @@ metadata. Do not combine it with the PostgreSQL pattern's workflow: a MySQL
 application's workflow has no `postgres` service, `POSTGRES_*` variables, port
 `5432`, or `pg_isready` option.
 
-`example/tests/browser/database.js` is the application-owned browser preparation
-helper. It requires the exact `BROWSER_TEST_DB_NAME`, rejects the ordinary and
-disposable `TEST_DB_NAME` databases,
-retains the schema and migration ledger, applies pending migrations, then clears
-test rows and calls one explicit fixture seed transaction. The seed must restore
-any migration-owned baseline rows the app needs. Call it once before starting
-the isolated test server, never in `beforeEach`. It closes its connections without
-dropping the database. The launcher selects that database only for its own server
-and identity process, disables external effects, and proves actual server identity
-before the suite writes data. It must not edit the normal environment. Provision
-both test databases with exact grants for the application account. A disposable
-integration or migration test must never drop the browser database.
-
-Startup reports whether the schema exists, the number of migrations applied,
-and the migration, fixture-reset and seed durations. Use those measurements to
-diagnose a slow start before rerunning a browser case.
+Tests get their own databases from
+`@jskit-ai/database-runtime/server/testDatabases`. The `test` script runs
+`jskit test --databases`: each Node test file running at once gets its own
+copy of `TEST_DB_NAME` (`<name>`, `<name>_1`, ...), restored from a stored
+snapshot of the current migrations' schema and the rows they write, in
+`node_modules/.cache/jskit-test-databases/`. The snapshot is replayed once, and
+again only when a migration's name or contents or `package-lock.json` change;
+a file that migrates or drops tables leaves its copy to be restored before the
+next file takes it.
+
+`example/tests/e2e/databases.js` is the browser run's `prepare` module for
+`browserTestConfig({ prepare: "tests/e2e/databases.js" })` from
+`@jskit-ai/jskit-catalog/browser-tests`. It gives each Playwright worker's
+server its own copy of `BROWSER_TEST_DB_NAME`, restored from the same kind of
+snapshot and seeded in one transaction by the app's fixture `seed`, which
+restores any migration-owned baseline rows the app needs. Every server serves
+the production build. Both refuse the application's database (`DB_NAME`,
+`DATABASE_URL`'s, the Knex connection's), `PROD_DB_NAME` and the other test
+database and its copies. Provision `TEST_DB_NAME`, `BROWSER_TEST_DB_NAME` and
+their numbered copies with grants for the application account (a `<app>_%`
+grant covers them); a user who may create no copies runs one file or worker at
+a time. Two test runs at once need different database names. Test-only server
+settings that disable external effects (email, payments) go in
+`browserTestConfig({ env })`; a suite that writes data proves the server's
+identity first.
+
+Each preparation reports how many databases it made, whether it replayed the
+migrations for a new snapshot, and the restore and seed durations. Use those
+measurements to diagnose a slow start before rerunning a browser case.
 
 Keep fixtures small for the selected test scope. Run related cases in one suite
-invocation. Use the development launcher for ordinary browser checks; test the
-production build separately when needed. Fresh-schema migration proofs are
-separate from browser startup.
+invocation. Fresh-schema migration proofs are separate from browser startup.
 
 ## Variation points
 
@@ -99,11 +110,10 @@ it as `seed` to `prepareDatabaseFromApp()`.
 - Run `npm run db:migrate:status` and the application verification command.
 - Exercise one transaction and one negative connection case.
 - When a seed exists, run `db:prepare` twice and require the second run to be safe.
-- For browser preparation, run a disposable test between two starts: the second applies no
-  old migrations, stale fixture data is removed, baseline rows are restored,
-  foreign-key checks remain enabled, and the normal database is unchanged.
-  Also prove that a new pending migration is applied. Keep this as a regression
-  test when adapting the example; reject a harness that recreates the schema.
+- For the test databases, run the suite twice: the second run restores the
+  stored snapshot instead of replaying the migrations, stale rows are gone,
+  baseline rows are restored, foreign keys are enforced, and the normal
+  database is unchanged. A new migration takes a new snapshot.
 - Confirm `.github/workflows/verify.yml` parses as YAML and declares only the
   `mariadb` service. GitHub reports an unparseable workflow only as a failed
   run with "no jobs were run".

package/skills/jskit/references/patterns/database/mysql-application/example/package.json

@@ -5,9 +5,10 @@
     "db:prepare": "node ./scripts/prepare-database.js",
     "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
     "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
-    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list",
+    "test": "jskit test --databases"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.258"
+    "@jskit-ai/database-runtime-mysql": "0.1.260"
   }
 }

package/skills/jskit/references/patterns/database/mysql-application/example/tests/e2e/databases.js

@@ -0,0 +1,25 @@
+import { prepareTestDatabases } from "@jskit-ai/database-runtime/server/testDatabases";
+import knexConfig from "../../knexfile.js";
+
+// The browser run's `prepare` module: `browserTestConfig({ prepare: "tests/e2e/databases.js" })` in
+// playwright.config.mjs runs it once, before the servers start. Every Playwright worker gets its own copy of
+// BROWSER_TEST_DB_NAME (`<name>`, `<name>_1`, ...), restored from the schema snapshot of the current migrations, then
+// seeded; the normal and disposable TEST_DB_NAME databases are refused. It is also given each worker's `baseUrls`,
+// for a server setting that names its own address.
+
+/** The fixtures the specs rely on, including any migration-owned baseline rows the app needs. */
+async function seed(transaction) {
+  await transaction("fixtures").insert({ id: 1, label: "Browser fixture" });
+}
+
+export default async function prepareBrowserDatabases({ workers }) {
+  const { databases, summary } = await prepareTestDatabases({
+    knexConfig,
+    environment: process.env,
+    variable: "BROWSER_TEST_DB_NAME",
+    count: workers,
+    seed
+  });
+  console.log(`[browser-tests] ${summary}.`);
+  return databases.map((database) => ({ DB_NAME: database }));
+}

package/skills/jskit/references/patterns/database/postgres-application/PATTERN.md

@@ -53,6 +53,18 @@ dialect. `example/scripts/prepare-database.js` is the portable
 migrate-then-seed entrypoint for managed sessions and deployments.
 `example/.env.example` names the five connection values without a secret.
 
+Tests get their own databases from
+`@jskit-ai/database-runtime/server/testDatabases`. The `test` script runs
+`jskit test --databases`: each Node test file running at once gets a copy of
+`TEST_DB_NAME`, created from `<TEST_DB_NAME>_snapshot`, a database the
+migrations are replayed into once and again only when a migration changes.
+`example/tests/e2e/databases.js` is the browser run's `prepare` module for
+`browserTestConfig({ prepare: "tests/e2e/databases.js" })` from
+`@jskit-ai/jskit-catalog/browser-tests`: each Playwright worker's server gets
+its own seeded copy of `BROWSER_TEST_DB_NAME`. The database user needs
+`CREATEDB`; without it, Node test files run one at a time on the connected
+database.
+
 `example/.github/workflows/verify.yml` is a normal app-owned CI workflow with
 exactly one database service: `postgres` (`postgres:17`, `POSTGRES_*`
 variables, port `5432`, a `pg_isready` health check). Copy it whole from this

package/skills/jskit/references/patterns/database/postgres-application/example/package.json

@@ -5,9 +5,10 @@
     "db:prepare": "node ./scripts/prepare-database.js",
     "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
     "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
-    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list",
+    "test": "jskit test --databases"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-postgres": "0.1.257"
+    "@jskit-ai/database-runtime-postgres": "0.1.259"
   }
 }

package/skills/jskit/references/patterns/database/postgres-application/example/tests/e2e/databases.js

@@ -0,0 +1,25 @@
+import { prepareTestDatabases } from "@jskit-ai/database-runtime/server/testDatabases";
+import knexConfig from "../../knexfile.js";
+
+// The browser run's `prepare` module: `browserTestConfig({ prepare: "tests/e2e/databases.js" })` in
+// playwright.config.mjs runs it once, before the servers start. Every Playwright worker gets its own copy of
+// BROWSER_TEST_DB_NAME (`<name>`, `<name>_1`, ...), created from the snapshot database of the current migrations with
+// CREATE DATABASE ... TEMPLATE, then seeded; the normal and disposable TEST_DB_NAME databases are refused. The database
+// user needs CREATEDB.
+
+/** The fixtures the specs rely on, including any migration-owned baseline rows the app needs. */
+async function seed(transaction) {
+  await transaction("fixtures").insert({ id: 1, label: "Browser fixture" });
+}
+
+export default async function prepareBrowserDatabases({ workers }) {
+  const { databases, summary } = await prepareTestDatabases({
+    knexConfig,
+    environment: process.env,
+    variable: "BROWSER_TEST_DB_NAME",
+    count: workers,
+    seed
+  });
+  console.log(`[browser-tests] ${summary}.`);
+  return databases.map((database) => ({ DB_NAME: database }));
+}

package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.2.17",
-    "@jskit-ai/shell-web": "0.2.14"
+    "@jskit-ai/realtime": "0.2.19",
+    "@jskit-ai/shell-web": "0.2.16"
   }
 }

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.11",
+    "@jskit-ai/kernel": "0.2.13",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/package.json

@@ -10,8 +10,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.12",
-    "@jskit-ai/resource-crud-core": "0.1.202"
+    "@jskit-ai/crud-core": "0.2.14",
+    "@jskit-ai/resource-crud-core": "0.1.204"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/package.json

@@ -10,9 +10,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.12",
-    "@jskit-ai/resource-crud-core": "0.1.202",
-    "@jskit-ai/workspaces-core": "0.2.13"
+    "@jskit-ai/crud-core": "0.2.14",
+    "@jskit-ai/resource-crud-core": "0.1.204",
+    "@jskit-ai/workspaces-core": "0.2.15"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/sanity-checks.md

@@ -78,9 +78,10 @@ expects the relationship id or an unselected field never gets it.
 
 ### Query counts and batches
 
-- Count a path's queries with the test Knex instance's `query` event at a few
-  rows and at a realistic number; the count should follow tables and pages,
-  not rows ([Query counts at realistic
+- Count a path's queries with `countQueries()` from
+  `@jskit-ai/database-runtime/server/testDatabases` at a few rows and at a
+  realistic number; the count should follow tables and pages, not rows
+  ([Query counts at realistic
   sizes](typed-features.md#query-counts-at-realistic-sizes)).
 - A JSON:API read adds a few lookup and visibility queries per page and per
   relationship field. That follows pages, so it is expected.

package/skills/jskit/references/typed-features.md

@@ -1025,12 +1025,27 @@ export function resetInvoiceCacheForTests() {
 
 ### Query counts at realistic sizes
 
-**A list, batch or write path's database test counts its queries with the
-test Knex instance's `query` event at a few rows and at a realistic number,
-and fails when the count grows with the rows instead of the pages.**
-
+**A list, batch or write path's database test counts its queries with
+`countQueries()` at a few rows and at a realistic number, and fails when the
+count grows with the rows instead of the pages.**
+
+- `countQueries(knex, work)`, from
+  `@jskit-ai/database-runtime/server/testDatabases`, runs `work` and returns
+  its `result`, the `count` of statements the Knex instance or transaction
+  sent meanwhile (a transaction's `BEGIN` and `COMMIT` included) and their
+  SQL in `queries`. Pass the Knex the path runs on: the one the test built its
+  repository or service with.
+- A route is counted through the server the test boots in its own process
+  (`createServer()`, then `app.inject()`): `countRuntimeQueries(work)`, from
+  the same module, records what the app's own `runtime.database` sends while
+  `work` runs, and leaves out the test's own Knex. A server in another process
+  is out of its reach, so the route's guard boots it in the test.
 - Pages add a few queries; rows should add none. A path that pages nothing
   (one read, one write) compares a short and a long history.
+- When the counts differ more than the pages explain, read `queries`: the
+  statement that repeats once per row is the one to batch. Judge the
+  comparison by what the path has to read; never tune a fixed ceiling until
+  it passes.
 - When it fails, fix the reads ([Lists read related rows in
   batches](#lists-read-related-rows-in-batches), [Bounded access
   checks](#bounded-access-checks)).
@@ -1041,17 +1056,7 @@ cannot.
 
 ```js
 // good
-async function countQueries(knex, work) {
-  let queries = 0;
-  const count = () => { queries += 1; };
-  knex.on("query", count);
-  try {
-    await work();
-  } finally {
-    knex.off("query", count);
-  }
-  return queries;
-}
+import { countQueries, countRuntimeQueries } from "@jskit-ai/database-runtime/server/testDatabases";
 
 test("the invoice list's queries follow its pages, not its invoices", async () => {
   const listAt = async (count) => {
@@ -1062,7 +1067,22 @@ test("the invoice list's queries follow its pages, not its invoices", async () =
   const few = await listAt(10);
   const many = await listAt(300);
   // Thirty times the invoices may add pages; a read per invoice would add about 290 queries.
-  assert.ok(many <= few * 2, `${few} queries for 10 invoices, ${many} for 300`);
+  assert.ok(many.count <= few.count * 2,
+    `${few.count} queries for 10 invoices, ${many.count} for 300:\n${many.queries.join("\n")}`);
+});
+
+// good: the same comparison for the route, through the server this test booted
+test("GET /api/invoices reads per page, not per invoice", async () => {
+  const app = await createServer({ runtimeEnv });
+  const listAt = async (count) => {
+    const workspace = await createWorkspace(knex);
+    await seedInvoices(knex, { workspace, count, linesEach: 5 });
+    return countRuntimeQueries(() => app.inject({ url: invoicesUrl(workspace), headers: signedIn }));
+  };
+  const few = await listAt(10);
+  const many = await listAt(300);
+  assert.ok(many.count <= few.count * 2,
+    `${few.count} queries for 10 invoices, ${many.count} for 300:\n${many.queries.join("\n")}`);
 });
 
 // bad: three invoices, nothing counted, so a read per invoice passes
@@ -1096,37 +1116,63 @@ and Vitest's `maxWorkers` come from `testConcurrency()`.**
   file uses, its own Vite `cacheDir` for each dev server it starts (Vite
   replaces a shared dependency cache under servers still reading it), and no
   writes into the source tree. Files that collide are isolated, never
-  serialised. A Playwright spec works on its own records, so
-  specs can share one server.
+  serialised. A database test file gets its own copy of `TEST_DB_NAME` from
+  `jskit test --databases`
+  ([integration test databases](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#integration-test-databases)).
+- An application's `playwright.config.mjs` is
+  `defineConfig(browserTestConfig({ testDir: "./tests/e2e" }))` from
+  `@jskit-ai/jskit-catalog/browser-tests`. It builds the production frontend
+  once (reused while its sources are unchanged) and gives each worker its own
+  server, port and, through its `prepare` module, its own seeded database; a
+  spec file's tests run in order in one worker. With `PLAYWRIGHT_BASE_URL`, the
+  tests use that managed target as its host serves it. Every run is bounded by
+  a `globalTimeout` (20 minutes, or the suite's own measured bound) and ends
+  with its 10 slowest tests. With a `signIn` module, each worker's server is
+  signed in once and every test of that worker starts signed in, instead of
+  each test signing in. `jskit check` fails a webServer that runs the development server
+  (`npm run develop`, `vite`), one webServer shared by every worker, and a
+  config without a `globalTimeout`.
 - A file that truly cannot run beside others, because it holds a resource of
   the whole machine, says why on its first line,
   `// jskit-test: alone - <reason>`. `jskit test` runs it after the others,
   one such file at a time, and fails on a marker without a reason or below the
   first line.
+- `jskit test` ends with its 10 slowest test files and tests, records each
+  file's time in `node_modules/.cache/jskit-test/file-times.json`, and fails
+  when a file takes more than 10 minutes or the whole command more than 45:
+  bounds only a clearly broken suite reaches, such as a file waiting out its
+  timeouts. A suite whose measured work needs more sets `runMs`, `fileMs` or a
+  file's own bound in `test-time-bounds.json`, with the measurement in the
+  commit that raises it; a file that got slow is fixed instead. A file still
+  running at twice its bound, or sooner at ten times the time it last finished
+  in (at least two minutes), is stopped and fails the run by name, so the other
+  files still finish and report: look for what it leaves open (a server, child
+  process, timer or socket) or a test without a timeout. A file with its own
+  bound is stopped at twice that bound.
 
 Why: `jskit test` and `testConcurrency()` read one budget, so every runner
 uses the machine without starving the other runs on it.
 
 ```js
 // good: package.json "test": "jskit test", and playwright.config.mjs
-import { testConcurrency } from "@jskit-ai/jskit-catalog/test-budget";
+import { browserTestConfig } from "@jskit-ai/jskit-catalog/browser-tests";
 
-export default defineConfig({ workers: testConcurrency() });
+export default defineConfig(browserTestConfig({ testDir: "./tests/e2e" }));
 
 // bad: "test": "node --test --test-concurrency=1", and
-export default defineConfig({ workers: 1 });
+export default defineConfig({ workers: 1, webServer: { command: "npm run develop" } });
 ```
 
 ### Test databases are prepared once
 
 **A test run prepares each database once and restores it from a stored
-snapshot of the schema, migration ledger and seed rows, checked by a digest of
-their sources.**
+snapshot of the schema and the rows the migrations write, migration ledger
+included, checked by a digest of the migrations.**
 
-- The snapshot is rebuilt only when the digest of the migration and seed
-  sources changes, once and outside the timed tests; every disposable
+- The snapshot is rebuilt only when the digest of the migrations' names and
+  contents changes, once and outside the timed tests; every disposable
   database, and every database a test migrated up or down, is restored from
-  it.
+  it. A browser run's fixture seed runs after each restore.
 - The full migration history runs once, in its own fresh-schema check
   ([database verification](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#verification)).
 - The harness reports each preparation phase and its duration, and those
@@ -1140,8 +1186,8 @@ Why: an application's migrations include those of every installed package, so
 replaying them costs more with each package as well as each migration.
 
 ```js
-// good: the application's test support restores the snapshot its digest names
-before(async () => restoreTestDatabase(knex, await testDatabaseSnapshot()));
+// good: package.json "test": "jskit test --databases"; each file gets a restored copy of TEST_DB_NAME
+const { databases } = await prepareTestDatabases({ knexConfig, environment: process.env, count: workers, seed });
 
 // bad: every file replays every migration
 before(() => knex.migrate.latest());
@@ -1341,8 +1387,11 @@ that must run alone says so on its own first line instead.
 | Rule | Reports | Section |
 | --- | --- | --- |
 | `test/node-test` | a script that runs `node --test` directly instead of `jskit test` | [Test files run in parallel](#test-files-run-in-parallel) |
-| `test/fixed-concurrency` | `--test-concurrency` in a script | [Test files run in parallel](#test-files-run-in-parallel) |
-| `test/playwright-workers` | `--workers` or `-j` passed to `playwright test`, or its config without `workers: testConcurrency()` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/fixed-concurrency` | `--test-concurrency` in a script, or a script that pins `V64_TEST_CONCURRENCY` or `PLAYWRIGHT_WORKERS` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-workers` | `--workers` or `-j` passed to `playwright test`, its config without `workers: testConcurrency()` or `browserTestConfig()`, or with `workers` set over `browserTestConfig()`'s | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-dev-server` | a Playwright webServer command that runs the development server (`npm run develop`, `npm run dev`, `bin/develop.js`, `vite`, `vite dev`) | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-isolation` | a Playwright webServer every worker shares, without `browserTestConfig()` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-global-timeout` | a Playwright config without a `globalTimeout` (or `browserTestConfig()`), or with `globalTimeout: 0` | [Test files run in parallel](#test-files-run-in-parallel) |
 | `test/vitest-workers` | `--maxWorkers`, `--minWorkers` or `--no-file-parallelism` passed to Vitest, or its config without `maxWorkers: testConcurrency()` or with `fileParallelism: false` | [Test files run in parallel](#test-files-run-in-parallel) |
 
 The rules see shapes, not intent. Feature files, owned state beyond

package/skills/jskit/references/patterns/database/mysql-application/example/tests/browser/database.js

@@ -1,68 +0,0 @@
-import knex from "knex";
-
-// Application-owned test setup. Schema migration tests use a separate fresh database.
-async function prepareBrowserTestDatabase({ knexConfig, environment = process.env, seed }) {
-  const started = performance.now();
-  if (environment.NODE_ENV === "production") throw new Error("Browser tests cannot prepare a production runtime.");
-  if (typeof seed !== "function") throw new TypeError("An explicit browser fixture seed is required.");
-  if (knexConfig?.client !== "mysql2" || !knexConfig.connection || typeof knexConfig.connection !== "object") {
-    throw new Error("Browser preparation requires a resolved MySQL Knex configuration.");
-  }
-  const database = String(environment.BROWSER_TEST_DB_NAME || "").trim();
-  if (!/^[a-zA-Z0-9_]{1,64}$/.test(database)) throw new Error("BROWSER_TEST_DB_NAME must name the exact browser database.");
-  const protectedNames = [knexConfig.connection.database, environment.DB_NAME, environment.TEST_DB_NAME];
-  if (environment.DATABASE_URL) {
-    try { protectedNames.push(decodeURIComponent(new URL(environment.DATABASE_URL).pathname.slice(1))); }
-    catch { throw new Error("DATABASE_URL must be a valid database URL."); }
-  }
-  if (!knexConfig.connection.database || protectedNames.some(name => String(name || "").trim().toLowerCase() === database.toLowerCase())) {
-    throw new Error("BROWSER_TEST_DB_NAME must differ from the application and disposable TEST_DB_NAME databases.");
-  }
-  const adminConnection = { ...knexConfig.connection };
-  delete adminConnection.database;
-  const admin = knex({ ...knexConfig, connection: adminConnection, pool: { min: 0, max: 1 } });
-  let schemaExisted;
-  try {
-    const [[row]] = await admin.raw("SELECT COUNT(*) AS count FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ?", [database]);
-    schemaExisted = Number(row.count) === 1;
-    await admin.raw("CREATE DATABASE IF NOT EXISTS ??", [database]);
-  }
-  finally { await admin.destroy(); }
-  console.info(`Browser database ${database}: ${schemaExisted ? "existing schema" : "new schema"}.`);
-  const db = knex({ ...knexConfig, connection: { ...knexConfig.connection, database } });
-  try {
-    const migrationStarted = performance.now();
-    const [, migrations] = await db.migrate.latest();
-    const migrationMs = Math.round(performance.now() - migrationStarted);
-    console.info(`Browser migrations: ${migrations.length} applied in ${migrationMs}ms.`);
-    const resetStarted = performance.now();
-    let resetTables = 0;
-    const connection = await db.client.acquireConnection();
-    try {
-      const [[actual]] = await db.raw("SELECT DATABASE() AS databaseName").connection(connection);
-      if (actual.databaseName !== database) throw new Error("Browser reset requires the exact BROWSER_TEST_DB_NAME connection.");
-      const [tables] = await db.raw(
-        "SELECT TABLE_NAME AS name FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'", [database]
-      ).connection(connection);
-      const ledger = knexConfig.migrations?.tableName || "knex_migrations";
-      await db.raw("SET FOREIGN_KEY_CHECKS = 0").connection(connection);
-      try {
-        for (const { name } of tables) {
-          if (name === ledger || name === `${ledger}_lock`) continue;
-          await db.raw("TRUNCATE TABLE ??", [name]).connection(connection);
-          resetTables += 1;
-        }
-      } finally { await db.raw("SET FOREIGN_KEY_CHECKS = 1").connection(connection); }
-    } finally { await db.client.releaseConnection(connection); }
-    const resetMs = Math.round(performance.now() - resetStarted);
-    console.info(`Browser fixture reset: ${resetTables} tables in ${resetMs}ms.`);
-    const seedStarted = performance.now();
-    await db.transaction(seed);
-    const seedMs = Math.round(performance.now() - seedStarted);
-    const totalMs = Math.round(performance.now() - started);
-    console.info(`Browser fixture seed: ${seedMs}ms; database preparation total: ${totalMs}ms.`);
-    return { database, migrations, schemaExisted, timings: { migrationMs, resetMs, seedMs, totalMs } };
-  } finally { await db.destroy(); }
-}
-
-export { prepareBrowserTestDatabase };