@jskit-ai/agent-docs 0.1.280 → 0.1.281

package/guide/agent/app-extras/assistant-conversation.md

@@ -196,7 +196,11 @@ storage or infer authorization from browser fields. Authentication may be async;
 return a context object or throw an application error. A missing context is denied.
 Apply the application's normal session, Origin/CSRF and socket-handshake rules
 there. The returned trusted fields extend the action context; the runtime's own
-`authorize` still controls each conversation operation and subscription.
+`authorize` still controls each conversation operation and subscription. A
+subscriber is authorized again for every event it hears, except a streamed delta
+(an in-progress message), which reuses an authorization under a second old: a
+reply's hundreds of deltas cost about one check a second, and a revoked subscriber
+stops hearing the turn within a second.
 
 The helper assembles `AssistantFeature`, the HTTP/action/bootstrap/event providers
 and one realtime provider. It closes that hosting on Fastify `preClose`. The

package/guide/agent/app-extras/realtime.md

@@ -62,12 +62,18 @@ When `auth.service.authenticateRequest()` is present, each publish reauthenticat
 every socket that could receive it before sending, and every socket is rechecked
 every 30 seconds. A socket could receive a publish when the audience is
 `all_clients` or `broadcast`, when it is already in a target room, or, when an
-audience contributor is registered, when a target room is a user or workspace
-room it could join on revalidation. Other sockets are not checked for that
-publish. Sockets whose authentication requests are identical, such as tabs of
+audience contributor is registered and a target room is a user or workspace
+room, when its actor's contributed rooms include a target room or it has not
+signed in yet. A socket joins only its own actor's contributed rooms, so a
+publish to `workspace:7` checks that workspace's members' sockets, not every
+connected one. To decide, the publish resolves the contributed rooms of every
+signed-in socket's actor in one call to each contributor, whatever the number
+of sockets. Other sockets are not checked for that publish; the 30-second check
+reaches them. Sockets whose authentication requests are identical, such as tabs of
 one browser, share one `authenticateRequest()` call within a publish or a
-30-second pass, and sockets of one actor share one lookup of their contributed
-rooms; nothing is reused from one publish or pass to the next. Revoked,
+30-second pass, and the sockets a publish or pass checks reuse that one lookup
+of their contributed rooms; nothing is reused from one publish or pass to the
+next. Redis peers select the sockets they check the same way. Revoked,
 expired, or changed actors are disconnected by the first publish that could
 reach them or the next 30-second check. Authentication lookup errors fail
 closed.
@@ -91,14 +97,18 @@ a connected socket is disconnected. The local and OIDC providers never need
 this: their checks do not rotate tokens.
 
 Packages that know which scopes an actor belongs to contribute them through
-`runtime.realtime.registerAudienceContributor({ id, resolveActorScopes })` during
-setup. `resolveActorScopes(actorId)` returns event scopes (`{ kind: "user", id }`,
+`runtime.realtime.registerAudienceContributor({ id, resolveActorsScopes })` during
+setup. `resolveActorsScopes(actorIds)` answers for many actors at once, so read
+them in one query rather than one per actor: it returns, or resolves to, a `Map`
+from actor id to that actor's event scopes (`{ kind: "user", id }`,
 `{ kind: "workspace", id }` or `{ kind: "workspace_user", workspaceId, userId }`);
-realtime turns each into the same room an `event_scope` audience targets. Sockets
+an actor it leaves out has none. A single actor is asked as a list of one.
+Realtime turns each scope into the same room an `event_scope` audience targets. Sockets
 join those rooms on connection and, on every revalidation, leave the contributed
 rooms the actor no longer belongs to; rooms joined by anything else are left
-alone. `@jskit-ai/workspaces-core` contributes the actor's active workspace
-memberships this way when realtime is installed.
+alone. `@jskit-ai/workspaces-core` contributes the actors' active workspace
+memberships this way when realtime is installed, with
+`listActiveWorkspaceIdsByUserIds()`: one memberships query per 1,000 actors.
 
 The authentication request includes parsed cookies, the `Host`, `Origin` and
 `X-Forwarded-Proto` headers when present, and the socket address and TLS state.

package/guide/agent/app-setup/authentication.md

@@ -66,6 +66,23 @@ Protected server operations declare an auth policy; they do not trust a hidden
 button or a page-local session check. Other packages extend auth through the
 public extension capability rather than replacing the auth service.
 
+## When the app profile is synchronized
+
+With users-core, every signed-in identity has an app profile (a `users` row),
+and synchronizing it also ensures the user's settings and runs the profile-sync
+lifecycle, where workspaces-core provisions the personal workspace. The
+providers synchronize in full at sign-in, registration, account changes and
+each session refresh (local auth: when the 15-minute access token has expired).
+An ordinary request checks its session as always, then reads the
+profile once: it synchronizes in full only when the profile is missing or its
+email or display name no longer matches the identity the request carries.
+
+So a name or email changed at the provider shows at the next request, while a
+personal workspace, owner membership or settings row deleted while the person
+is signed in comes back at their next sign-in or session refresh, not at their
+next request. Authorization never rests on those rows: sign-out and revoked
+sessions take effect at the next request.
+
 ## Sign-in protection
 
 Two limits slow down password guessing, and both are on by default.
@@ -420,7 +437,9 @@ For direct localhost Playwright tests, enable the development auth bypass only
 in the server process and use `loginAsExistingUser()` from
 `@jskit-ai/auth-web/test/playwright`. The Node-side helper sends the private
 `x-jskit-dev-auth-secret`; never pass that secret through browser code, URLs, or
-client environment.
+client environment. Under `browserTestConfig()`, a `signIn` module signs each
+worker in once with `loginRequestAsExistingUser()` instead of each test
+signing in ([Upgrading JSKIT](/guide/app-setup/upgrading-jskit#sign-each-browser-worker-in-once)).
 
 A managed host instead supplies authenticated state through
 `PLAYWRIGHT_STORAGE_STATE` and the app-owned Playwright config. Treat the

package/guide/agent/app-setup/database-layer.md

@@ -398,21 +398,53 @@ database migration table are sufficient.
 
 Disposable integration and migration tests use `TEST_DB_NAME`, never the
 application's `DB_NAME`. A test run prepares that schema once and restores it
-from a stored snapshot:
-
-- The snapshot holds the schema as the engine reports it (each table's
-  `SHOW CREATE TABLE` on MySQL and MariaDB, `pg_dump --schema-only` on
-  PostgreSQL), the migration ledger rows and the seed rows. Its key is a digest
-  of the migration files that the application's `migrations/` and its installed
-  packages supply, and of the seed source.
-- When that digest changes, the harness migrates one database once, outside
-  the timed tests, and stores a new snapshot. Otherwise it restores the stored
-  one. On PostgreSQL, `CREATE DATABASE <name> TEMPLATE <prepared>` copies a
-  prepared database that has no open connections.
-- A test that runs migrations up or down, or otherwise changes the schema,
-  leaves its database dirty. The harness restores the snapshot before another
-  test uses that database, instead of running `migrate.latest()` over the
-  whole history.
+from a stored snapshot. `jskit test --databases` (the database patterns' `test`
+script) does this with `@jskit-ai/database-runtime/server/testDatabases`, from
+the application's `knexfile.js`:
+
+- Each test file running at once gets a database of its own for as long as it
+  runs, as both `DB_NAME` and `TEST_DB_NAME`: `TEST_DB_NAME` itself, then
+  copies named `<TEST_DB_NAME>_1`, `_2`, ... up to the machine's test budget,
+  as many as the database user may create. With no usable `TEST_DB_NAME`
+  (unset, the connected database itself, or one the database user may not
+  prepare), the files run one at a time on the connected database. A copy
+  named like the application's database or `PROD_DB_NAME`, or a server that
+  cannot be reached, fails the run instead.
+- The snapshot holds the schema as the engine reports it and the rows the
+  migrations wrote, including the migration ledger. On MySQL and MariaDB it is
+  each table's `SHOW CREATE TABLE` and rows, in
+  `node_modules/.cache/jskit-test-databases/`; on PostgreSQL it is the database
+  `<TEST_DB_NAME>_snapshot`, which `CREATE DATABASE <name> TEMPLATE <snapshot>`
+  copies while nothing is connected to it (the user needs `CREATEDB`), file by
+  file (`STRATEGY FILE_COPY`) from PostgreSQL 15. Its key
+  is a digest of the dialect, of the name and contents of every migration file
+  that the application's `migrations/` and its installed packages supply, and
+  of `package-lock.json`, since an upgraded package can change a helper its
+  migrations import. MySQL test databases hold tables only: a schema with
+  views, triggers, routines or events is refused.
+- Each test file gets the environment `jskit test` was given, plus its
+  database's connection (`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`); the
+  rest of the `.env` that `knexfile.js` loads is read for the databases only.
+  The run's settings, connection password included, are in a file only the
+  user can read; the runner's environment names only its directory.
+- When that digest changes, the harness replays the migrations into the
+  designated database once, outside the timed tests, and stores a new
+  snapshot. Otherwise it restores the stored one.
+- A schema the migrations alone do not build, such as migrations that start
+  from a baseline schema file, or reference rows every test reads, comes from
+  the application's own build: `knexfile.js` also exports
+  `testDatabaseSchema = { files, build }`, and a browser `prepare` module passes
+  the same `schema` to `prepareTestDatabases()`. `build(knex)` runs in the empty
+  designated database instead of `knex.migrate.latest()` (the baseline, then
+  `knex.migrate.latest()`), and `files` lists every file it reads, its own
+  module included, relative to the application root: their contents join the
+  digest, so changing one takes a new snapshot.
+- A test that runs migrations up or down, or otherwise changes the tables,
+  leaves its database dirty: its tables or migration ledger differ from the
+  snapshot's. The harness restores the snapshot before another test file uses
+  that database, instead of running `migrate.latest()` over the whole history.
+- A browser run's seed is not part of the snapshot: it runs in each restored
+  database, in one transaction ([Browser test preparation](#browser-test-preparation)).
 - Only the fresh-schema check in [Verification](#verification) replays the
   whole history, as its own step.
 - The harness reports each phase (digest, restore or rebuild, seed) with its
@@ -421,27 +453,39 @@ from a stored snapshot:
   fixed, never absorbed by a longer time limit.
 
 Endpoints and batch operations get their own database tests at realistic row
-counts that compare their query counts; see the typed features guide's
+counts that compare their query counts, counted with `countQueries()` from
+`@jskit-ai/database-runtime/server/testDatabases`, or `countRuntimeQueries()`
+for a route of the server the test boots; see the typed features guide's
 [query counts at realistic sizes](/guide/framework/typed-features#query-counts-at-realistic-sizes).
 
 ## Browser test preparation
 
-Keep the test schema and migration history between routine browser runs. The
-MySQL application pattern includes `example/tests/browser/database.js`: it
-validates the exact `BROWSER_TEST_DB_NAME`, applies pending migrations, clears test rows,
-and runs one explicit fixture seed. Restore migration-owned baseline rows in
-that seed. Prove repeat preparation, stale-data removal, pending migrations, and
-isolation from the normal database before adopting the launcher. Give disposable
-integration and migration tests their own `TEST_DB_NAME`; require the two names
-to differ and provision exact grants for each. Run disposable cleanup between
-two browser preparations in the regression test to prove it cannot erase the
-reusable schema. Startup reports applied migration counts and phase durations
-so a cold rebuild is visible to the caller.
+A browser run gives every Playwright worker its own server and its own copy of
+`BROWSER_TEST_DB_NAME`. The database patterns' `example/tests/e2e/databases.js`
+is the `prepare` module of `browserTestConfig({ prepare: "tests/e2e/databases.js" })`
+from `@jskit-ai/jskit-catalog/browser-tests`: it calls `prepareTestDatabases()`
+with `variable: "BROWSER_TEST_DB_NAME"`, the worker count and the app's fixture
+seed, and returns each worker's `DB_NAME`. The worker's own process gets the
+same environment as its server, so a test that opens the database itself (with
+the app's `knexfile.js`) reaches that worker's copy. The copies (`<name>`, `<name>_1`,
+...) are restored from the same stored snapshot as the Node test databases
+([Integration test databases](#integration-test-databases)), then seeded in one
+transaction each, so stale rows never survive a run and the migrations are
+replayed only when one changes. It refuses the application's database,
+`PROD_DB_NAME`, `TEST_DB_NAME` and their copies.
+
+Give disposable integration and migration tests their own `TEST_DB_NAME`;
+the two names, and their copies, must differ, and the application account
+needs grants for each (a `<app>_%` grant covers the copies). Each preparation
+reports how many databases it made, whether it replayed the migrations for a
+new snapshot, and its restore and seed durations, so a cold rebuild is visible
+to the caller.
 
 Run related checks in one suite invocation and prepare only their required
-fixtures. The application foundations use the development launcher for ordinary
-browser checks; fresh-schema migration proofs and production builds are separate.
-A managed suite uses the host's server URL and identity, starts no second server,
-and restores normal Preview after the batch. Database isolation alone does not
+fixtures. A local browser run serves the production build, never the
+development launcher; fresh-schema migration proofs are separate. A managed
+suite (`PLAYWRIGHT_BASE_URL`) uses the host's server URL and identity, as the
+host serves it, starts no second server, and restores normal Preview after the
+batch. Database isolation alone does not
 disable email, payments or other external effects: configure those test controls
 and verify the actual server identity before destructive requests.

package/guide/agent/app-setup/existing-application-migration.md

@@ -133,7 +133,13 @@ The foundation servers reuse compiled response serializers for identical JSON
 schemas through `createCachedResponseSerializerFactory` from
 `@jskit-ai/kernel/server/http`. This reduces duplicate startup compilation and
 retained memory in applications with many routes. Each Fastify compiler context
-keeps its own cache; request data and response payloads are not cached.
+keeps its own cache; request data and response payloads are not cached. A
+serializer is compiled when a response first uses it, in every environment, so
+startup compiles none. Startup still checks every response schema as
+fast-json-stringify would before building it: an invalid schema or a `$ref`
+that does not resolve stops the server. A problem fast-json-stringify only
+finds while generating a serializer fails the first response that uses it, so
+keep a test that calls each route.
 
 Existing applications adopt the same setup in their own `server.js` after
 upgrading JSKIT and declaring the directly used

package/guide/agent/app-setup/multi-homing.md

@@ -56,8 +56,12 @@ config.tenancyPolicy = {
 ```
 
 Provisioning runs in the users profile-sync lifecycle after registration and
-sign-in. The first run creates the personal workspace, its owner membership and
-its settings; later runs reuse it. The default name is the user's display name,
+sign-in, at each session refresh, and on a request whose identity's email or
+display name changed. The first run creates the personal workspace, its owner
+membership and its settings; later runs reuse it. An ordinary request only reads
+the existing profile, so a personal workspace, owner membership or settings row
+deleted while the person is signed in comes back at their next sign-in or
+session refresh, not at their next request. The default name is the user's display name,
 or email, followed by "'s Workspace". To choose another, provide the
 `workspaces.personal-workspace-name` capability from an application feature. It
 receives the synchronized profile (`id`, `displayName`, `email`, `username`), and

package/guide/agent/app-setup/upgrading-jskit.md

@@ -191,6 +191,81 @@ An application adopts it once, at the upgrade that brings `jskit test`:
 4. The whole suite passes with the budget, and its time before and after is
    recorded.
 
+## Move browser and database tests onto the JSKIT harness
+
+The release that brings `browserTestConfig()` and `jskit test --databases`
+makes JSKIT own the fast test harness. Plain `jskit check` fails a Playwright
+webServer on the development server (`test/playwright-dev-server`), one
+webServer every worker shares (`test/playwright-isolation`), and a config
+without a `globalTimeout` (`test/playwright-global-timeout`). At that repin, an
+application:
+
+1. Deletes its own copies of the harness: a local test-budget helper
+   (`testConcurrency()` in its own scripts), a launcher that starts a server
+   per worker, a cached production-build step, worker port and database-name
+   helpers, a Node test runner wrapper that hands each file a database, and
+   its schema-snapshot code. It imports `testConcurrency()` from
+   `@jskit-ai/jskit-catalog/test-budget` wherever it still needs the number.
+2. Replaces `playwright.config.*` with
+   `defineConfig(browserTestConfig({ testDir: "./tests/e2e", prepare: "tests/e2e/databases.js" }))`
+   from `@jskit-ai/jskit-catalog/browser-tests`, with `server`, `build`, `env`
+   or `port` only where its own differ from `node ./bin/server.js`,
+   `npm run build` and 4173, and `globalTimeout` only for a suite measured to
+   need more than 20 minutes. Settings a config adds (projects, a globalSetup
+   that proves the server's identity, `timezoneId`) spread over the result:
+   `defineConfig({ ...base, projects, use: { ...base.use, timezoneId } })`. A
+   second local Playwright config and any `npm run develop` or `vite`
+   webServer go.
+3. Copies its database pattern's `example/tests/e2e/databases.js` and moves
+   its browser fixture seed into its `seed`; each worker's server then gets a
+   seeded copy of `BROWSER_TEST_DB_NAME`. Server settings for tests only (a
+   simulated email or payment driver) go in `browserTestConfig({ env })`.
+4. Runs Node tests with `"test": "jskit test --databases"`, with
+   `TEST_DB_NAME` distinct from `DB_NAME`, `BROWSER_TEST_DB_NAME` and
+   `PROD_DB_NAME`, and a database user that may create its numbered copies
+   (`CREATEDB` on PostgreSQL). Test files read `DB_NAME`/`TEST_DB_NAME` as
+   given rather than naming the test database themselves, and no longer
+   create, migrate or drop it: the run hands each file a restored copy.
+5. Proves it with a timed full run: `npm test` and `npx playwright test`, every
+   test passing, the time of each before and after recorded, and the slowest
+   tests the run lists read.
+
+## Cache built assets for good
+
+The foundations' `server.js` serves each content-hashed file under
+`dist/assets/` with `Cache-Control: public, max-age=31536000, immutable`, so a
+page load no longer revalidates every script and stylesheet the build made;
+`index.html` and unhashed files are still revalidated on every load. An
+application copies `HASHED_ASSET`, `HASHED_ASSET_CACHE` and the
+`reply.sendFile()` choice from its foundation's `example/server.js` into its
+own `server.js`, with the browser test "built assets are kept for good and the
+page itself is revalidated" from `example/tests/e2e/startup.spec.ts`. A spec
+that mocks requests with `page.route()` turns Playwright's HTTP cache off, so
+it still fetches every asset on each navigation.
+
+## Sign each browser worker in once
+
+A suite whose tests sign in one by one, such as a helper that calls
+`loginAsExistingUser()` at the start of each test, signs each worker's server
+in once instead, with `browserTestConfig({ signIn: "tests/e2e/sign-in.js" })`:
+
+```js
+// tests/e2e/sign-in.js: `env` is the worker server's environment.
+import { loginRequestAsExistingUser } from "@jskit-ai/auth-web/test/playwright";
+
+export default ({ request, env }) =>
+  loginRequestAsExistingUser(request, { email: "owner@example.com", secret: env.AUTH_DEV_BYPASS_SECRET });
+```
+
+The servers' launcher runs it once per server, after the servers start. Each
+test of that worker then starts from the signed-in storage state, which the
+worker's process also finds in `PLAYWRIGHT_STORAGE_STATE`, as on a managed
+target, so a helper that skips signing in under `PLAYWRIGHT_STORAGE_STATE`
+skips it locally too. A test that must start signed out uses
+`test.use({ storageState: { cookies: [], origins: [] } })`; a test that signs
+out or ends other sessions signs in on its own first, so the worker's shared
+session lives on. A login state the host supplies is used as it is.
+
 ## Application migration
 
 The updater changes package manifests and the lockfile only. It does not

package/guide/agent/framework/client-features.md

@@ -237,7 +237,7 @@ const ConversationClientProvider = defineProvider({
   },
   /** @param {{ components: import("@jskit-ai/kernel/client/types").ClientComponents }} capabilities */
   setup({ components }) {
-    components.register("conversation.web.settings.element", ConversationSettingsElement);
+    components.register("conversation.web.status.widget", ConversationStatusWidget);
   }
 });
 
@@ -246,6 +246,40 @@ const components = new Map();
 export function registerComponent(id, component) { components.set(id, component); }
 ```
 
+### Provider subpaths
+
+**Export each client provider by a subpath of its own. The provider's file
+imports only what every page needs, such as a widget the shell always shows; a
+screen that only some routes show is imported by those routes.**
+
+Why: every page of every app loads the client providers, and what they import,
+before it shows anything. The client bootstrap imports a provider through the
+subpath export that names its file, so the screens `./client` re-exports, and
+their libraries, load only with the routes that show them. A provider without a
+subpath, or a `./client` that declares `routeComponents` or `clientRoutes` or
+uses `export *`, brings all of `./client` to every page.
+
+```json
+// good: package.json
+"exports": {
+  "./client": "./src/client/index.js",
+  "./client/providers/ConversationClientProvider": "./src/client/providers/ConversationClientProvider.js"
+}
+
+// bad: package.json, no subpath for the provider, so every page loads all of ./client
+"exports": {
+  "./client": "./src/client/index.js"
+}
+```
+
+```js
+// good: the provider's file imports the widget every page shows
+import ConversationStatusWidget from "../components/ConversationStatusWidget.vue";
+
+// bad: the provider's file imports a screen that only its route shows
+import ConversationSettingsScreen from "../components/ConversationSettingsScreen.vue";
+```
+
 ### Injected values
 
 **`inject()` takes the owner's exported key, never a literal. A required value

package/guide/agent/framework/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](/guide/framework/typed-features#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/guide/agent/framework/typed-features.md

@@ -1030,12 +1030,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)).
@@ -1046,17 +1061,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) => {
@@ -1067,7 +1072,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
@@ -1101,37 +1121,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
@@ -1145,8 +1191,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());
@@ -1346,8 +1392,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.280",
+  "version": "0.1.281",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/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.12",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {