@jskit-ai/agent-docs 0.1.275 → 0.1.277

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

@@ -365,6 +365,36 @@ Do not add migration receipts, sync ledgers, generator provenance, or dialect
 questionnaires. The installed graph, migration source, environment, and
 database migration table are sufficient.
 
+## Integration test databases
+
+Disposable integration and migration tests use `TEST_DB_NAME`. A test run
+prepares that schema once and restores it from a stored snapshot; it never
+rebuilds a database by replaying the whole migration history:
+
+- 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.
+- 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
+  duration, and the suite has a time budget, so slow preparation is visible
+  instead of hiding inside the next test that waits for it. A slow phase is
+  fixed, never absorbed by a longer time limit.
+
+Endpoints and batch operations get their own database tests at realistic row
+counts with a fixed query budget; see the typed features guide's
+[budgets at realistic counts](/guide/framework/typed-features#budgets-at-realistic-counts).
+
 ## Browser test preparation
 
 Keep the test schema and migration history between routine browser runs. The

package/guide/agent/app-setup/material-3-migration.md

@@ -52,8 +52,9 @@ export const theme = {
 - A colour the app really owns (a partner brand, a status of its own) goes in
   `colors` by camelCase name, such as `partner: "#0A7D3E"`. It becomes
   `partner`, `on-partner`, `partner-container` and `on-partner-container`,
-  harmonized to the seed, in both schemes. `success`, `warning` and `info` are
-  already there.
+  harmonized to the seed, in both schemes; `{ value: "#F5C518", blend: false }`
+  keeps a brand colour's own hue. `success`, `warning` and `info` are already
+  there.
 - Delete `defaultTheme: "light"`. The app now follows the device's light or
   dark setting.
 
@@ -114,6 +115,9 @@ arrow. The shell's Up arrow returns to the page the person came from, or else
 to the parent, so:
 
 - delete "Back to X" buttons, `router.back()` and `history.back()` calls;
+- rename a back button for a step or panel inside a page to what it does
+  ("Previous step") or where it goes ("Dashboard"), without the back arrow.
+  An embedded frame's own Back and Forward, such as a preview browser's, stay;
 - delete redirects from a settings or section landing page to its first child.
   A settings page is a list-detail page (`ShellListDetail`): on wide windows the
   list stays beside the open section, and on narrow ones the list is the
@@ -135,6 +139,32 @@ the content into the app bar:
 At most one action is `primary`; on compact windows the others show as icon
 buttons named by their label.
 
+A layout that draws its own top app bar instead of `ShellLayout` keeps it and
+builds the page's part from the shell's pieces, so Up, the title and the
+actions behave as in `ShellLayout`:
+
+```vue
+<script setup>
+import { ShellPageActionsTarget, ShellPageTitle, ShellUpButton, useShellAppBar } from "@jskit-ai/shell-web/client";
+
+useShellAppBar();
+</script>
+
+<template>
+  <v-app-bar>
+    <ShellUpButton />
+    <ShellPageTitle title="Workspace" />
+    <ShellPageActionsTarget />
+    <!-- the app's own controls -->
+  </v-app-bar>
+  <v-main><slot /></v-main>
+</template>
+```
+
+Delete the bar's own back button and the pages' own `h1`s: `ShellPageTitle` is
+the page's one `h1`, and `jskit check` now counts the layout as a shell layout,
+so its inner pages need parents.
+
 ## 7. CRUD screens
 
 The CRUD screens apply all of this themselves. An app that customized them

package/guide/agent/framework/material-3.md

@@ -112,7 +112,7 @@ Exactly this, and nothing more:
 | `nav/history` | `history.back()`, `history.go()`, `history.pushState()`/`replaceState()`, `router.back()`, `router.go()` |
 | `nav/window-location` | `window.location` assignments, `.href =`, `location.assign()`, `location.replace()` |
 | `nav/raw-link` | a hand-built in-app path in `to`, `href`, `router.push()`, `router.replace()` or a `to:`/`href:` object key outside a placement |
-| `nav/back-control` | any back control but the shell's Up: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
+| `nav/back-control` | any back control but the shell's Up navigating the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
 | `nav/missing-parent` | an inner page of a shell surface without a declared parent |
 | `nav/top-level-parent` | a main-navigation destination that declares a parent |
 | `nav/allow` | any `m3-check: allow nav/...` comment: nothing excuses a navigation rule |
@@ -145,6 +145,9 @@ Exactly this, and nothing more:
   `finish(recordUrl)`; the record shows, and Up goes where the record's Up went
   before. Wrong: `router.push(recordUrl)` after Save, so Up or Back reopens the
   form.
+- **Steps inside a page are named actions:** "Previous step" or the
+  destination's name, not "Back" or a back arrow. A frame's own Back
+  (`contentWindow.history`) is fine.
 
 ## Foundation
 
@@ -196,6 +199,9 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   standalone heading. A section inside a page uses a title role.
 - **Up** sits in the bar on every inner page (see Navigation and Up). On phones
   it replaces the menu icon.
+- **A layout with its own top app bar** calls `useShellAppBar()` and renders
+  `ShellUpButton`, `ShellPageTitle` and `ShellPageActionsTarget` in it;
+  `jskit check` treats it as a shell layout.
 - **Actions:** a screen's actions go in the bar inside `ShellPageActions`
   (`@jskit-ai/shell-web/client/components/ShellPageActions`), each a
   `ShellPageAction` with `icon`, `label` (also its accessible name and compact
@@ -322,7 +328,8 @@ Take the approved route first; none needs an exception:
 
 - **Brand or partner colours** are theme custom colours, used by name:
   `colors: { partner: "#0A7D3E" }` in `src/theme/index.js`, then
-  `<v-chip color="partner">`.
+  `<v-chip color="partner">`. `{ value: "#F5C518", blend: false }` keeps
+  its hue.
 - **Chart and data colours** come from the theme: `const theme = useTheme()`,
   then `["primary", "tertiary"].map((role) => theme.current.value.colors[role])`.
 - **A third-party widget** lives in one wrapper component, such as

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

@@ -724,6 +724,107 @@ const rows = extractJsonRestCollectionRows(await api.resources.workspaceMembersh
 }, createJsonRestContext(options.context)));
 ```
 
+### One read per table
+
+**A read that builds a list reads each table once for the whole list: one
+query per table with an id-list filter, the rows grouped in memory. It never
+reads one row, or runs one lookup, per item of the list.**
+
+- Collect the ids from the first read, then read each related table once with
+  an id-list filter: a `searchSchema` entry
+  `{ type: "array", actualField: "<column>", filterOperator: "in" }`, read
+  through `queryAllJsonRestCollectionRows()`, or the resource's `include`.
+  Group the rows by id with `Map.groupBy()`.
+- `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
+  single-record read inside a loop over the list is a read per row, however
+  the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
+  item). So is a single-record helper reused for a list.
+- Work derived from a row (hashing, preparing a form, assembling a snapshot)
+  runs once per distinct input in the call, not once per row it appears in.
+- The list's query count follows its tables and pages (100 rows a page unless
+  the resource sets `queryMaxLimit`), never its rows: three hundred invoices
+  and their lines take a handful of queries, not three hundred more (see
+  [Budgets at realistic counts](#budgets-at-realistic-counts)).
+
+Why: a read per row costs nothing with three test rows and seconds with a few
+hundred real ones, and every lookup and visibility check inside it repeats too.
+
+```js
+// good: one read per table, however many invoices there are
+const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
+  queryParams: { filters: { workspace: workspaceId } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const lineRows = await queryAllJsonRestCollectionRows(api.resources.invoiceLines, {
+  queryParams: { filters: { invoiceIds: invoiceRows.map((invoice) => invoice.id) } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const linesByInvoice = Map.groupBy(lineRows, (line) => line.invoiceId);
+return invoiceRows.map((invoice) => ({ ...invoice, lines: linesByInvoice.get(invoice.id) || [] }));
+
+// bad: one more query, and its lookups and row policy, for every invoice
+for (const invoice of invoiceRows) {
+  invoice.lines = await invoiceLines.queryDocuments({ invoiceId: invoice.id }, options);
+}
+```
+
+### Bounded access checks
+
+**A row policy costs what the rows its query reads cost, never what the
+subject's stored history costs, and a write decides access once instead of
+paying a read policy for every row it writes.**
+
+- A `rowPolicy` adds one predicate to the query it is given: a join, `EXISTS`
+  or subquery correlated with the row being read, on indexed columns. It never
+  loads everything the subject was ever linked to (every source, notice or
+  grant in their history) to build an `IN` list, and never calls another
+  owner's access check once per item of that history. The
+  [row policies heuristic](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/heuristics/row-policies.md)
+  has the policy contract and its package composition.
+- The policy runs on every single-record read, and a CRUD write includes one:
+  `createDocument()` and `patchDocumentById()` write with `returning: "full"`
+  and read the record back through the policy, and `patch` and `delete` first
+  look the record up through it. A write therefore pays the read policy for
+  each row it writes.
+- A write path decides access once, inside its transaction. A batch write (a
+  delivery, an import, a fan-out) whose per-row read-back would pay an
+  expensive policy writes through a repository method added with
+  `decorateRepository`, on `resolveRepoClient(database.knex, options)`,
+  setting the same columns the resource would, its ownership columns
+  included, and reading back only what it returns.
+- Its test runs one read and one write for a subject with a short history and
+  with a realistic long one, and asserts the same query count.
+
+Why: a check sized by history grows with every record the subject receives,
+so the same write that takes milliseconds in a test takes seconds a year later.
+
+```js
+// good: one predicate on the row being read
+function noticeVisibilityPolicy({ query, context, column, value, db }) {
+  const userId = resolveActorId(context);
+  if (!userId) return false;
+  query.where(column("recipientId"), value("recipientId", userId)).whereExists(
+    db("sources").select(1)
+      .whereColumn("sources.id", column("sourceId"))
+      .where("sources.status", "published")
+  );
+  return true;
+}
+
+// bad: every source the recipient was ever notified about, checked one by one
+async function noticeVisibilityPolicy({ query, context, column, value }) {
+  const sourceIds = await noticeHistory.listSourceIds(resolveActorId(context));
+  const readable = [];
+  for (const sourceId of sourceIds) {
+    if (await sources.canRead(sourceId, context)) readable.push(sourceId);
+  }
+  query.whereIn(column("sourceId"), readable.map((id) => value("sourceId", id)));
+  return true;
+}
+```
+
 ### Routes
 
 **A route does HTTP work only (status, cookies, redirects) and runs an action
@@ -910,6 +1011,112 @@ export function resetInvoiceCacheForTests() {
 }
 ```
 
+### Budgets at realistic counts
+
+**A list, batch or write path has a database test at the row counts and
+history a real workspace holds, and that test fails above a fixed query
+budget, one that a read per row or a history-sized check cannot meet.**
+
+- Seed hundreds of records and long per-person histories, not one to three
+  rows: a read per row and a history-sized policy cost nothing at three.
+- Count the queries with the test Knex instance's `query` event and assert a
+  ceiling: the count the correct implementation needs at that size, which a
+  read per row overshoots by hundreds. A path that pages nothing (one read,
+  one write) asserts the same count at a short and a long history. A query
+  count is stable in CI; also report the time the call took.
+- Meet the budget by fixing the reads ([One read per
+  table](#one-read-per-table), [Bounded access checks](#bounded-access-checks)),
+  never by shrinking the data or raising the budget.
+
+Why: without a budget at real counts, a path that does one read per row ships,
+and its first sign is a request that takes seconds in production.
+
+```js
+// good
+test("the invoice list reads each table once", async () => {
+  await seedInvoices(knex, { workspace, count: 300, linesEach: 5 });
+  let queries = 0;
+  const count = () => { queries += 1; };
+  knex.on("query", count);
+  try {
+    await invoices.listWithLines(workspace, { context });
+  } finally {
+    knex.off("query", count);
+  }
+  // A page of each table at a time; one read per invoice would add 300.
+  assert.ok(queries <= 40, `${queries} queries`);
+});
+
+// bad: three invoices and no budget, so a read per invoice passes
+test("the invoice list has its lines", async () => {
+  await seedInvoices(knex, { workspace, count: 3, linesEach: 1 });
+  assert.equal((await invoices.listWithLines(workspace, { context })).length, 3);
+});
+```
+
+### Time limits are not fixes
+
+**A slow test, suite, preparation or request is a defect to find, never a time
+limit to raise. Measure where the time goes, fix that cause, and keep the
+default limits.**
+
+- Raising `--test-timeout`, a test's `{ timeout }`, Playwright's `timeout`,
+  `test.setTimeout()` or an `expect` timeout, adding retries, or calling a
+  request in a loop until it answers hides the cause and lets it grow.
+- Read the preparation phases' durations and the query counts first; the
+  cause is usually a read per row, a history-sized policy, or a database
+  prepared by replaying migrations ([Test databases are prepared
+  once](#test-databases-are-prepared-once)).
+- A longer limit is right only for work that is long by nature, such as a
+  fixture of deliberate size, and the test names that work.
+- A time limit still bounds every run, so a hang ends; it is not a speed
+  setting.
+
+Why: a raised limit absorbs today's slowness and every later one, until a run
+takes hours and nobody knows which change made it slow.
+
+```js
+// good: the slow step was found and fixed, so the default limit holds
+test("delivers a batch of notices", async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+
+// bad
+test("delivers a batch of notices", { timeout: 600_000 }, async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+```
+
+### Test databases are prepared once
+
+**A test run prepares each database once, from a stored snapshot of its
+schema, migration ledger and seed rows checked by a digest of their sources,
+and never replays the whole migration history inside the run.**
+
+- The snapshot is rebuilt only when the digest of the migration and seed
+  sources changes, once and outside the timed tests; every disposable
+  database, and every database a test migrated up or down, is restored from
+  it.
+- 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 the suite
+  has a time budget, so slow preparation shows instead of hiding inside the
+  next test that waits for it.
+- The database layer guide's [integration test
+  databases](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#integration-test-databases)
+  gives the snapshot's contents per engine.
+
+Why: the migration history only grows, so a run that replays it whenever a
+schema changed gets slower with every migration the application adds.
+
+```js
+// good: the application's test support restores the snapshot its digest names
+before(async () => restoreTestDatabase(knex, await testDatabaseSnapshot()));
+
+// bad: every file replays every migration
+before(() => knex.migrate.latest());
+```
+
 ## Files and layout
 
 ### Size limits

package/package.json

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

package/patterns/minimal-foundation/example/package.json

@@ -35,7 +35,7 @@
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
     "@jskit-ai/kernel": "0.2.10",
-    "@jskit-ai/material-web": "0.1.0",
+    "@jskit-ai/material-web": "0.1.1",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.29",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/package.json

@@ -35,7 +35,7 @@
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
     "@jskit-ai/kernel": "0.2.10",
-    "@jskit-ai/material-web": "0.1.0",
+    "@jskit-ai/material-web": "0.1.1",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -45,13 +45,13 @@
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
     "@jskit-ai/http-runtime": "0.2.10",
-    "@jskit-ai/shell-web": "0.2.11",
+    "@jskit-ai/shell-web": "0.2.12",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.29",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/reference/autogen/PATTERN_INDEX.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.277`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.277`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
 
 - Id: `assistant/assistant-surface`
 - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/assistant-runtime@0.2.24`
+- Owner: `@jskit-ai/assistant-runtime@0.2.25`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/assistant/assistant-surface/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/assistant/assistant-surface/example/)
 - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -59,7 +59,7 @@ Compose JSKIT authentication routes, views, profile controls, and public surface
 
 - Id: `auth/auth-surface`
 - Keywords: `account`, `auth`, `login`, `logout`, `password`, `placement`, `profile`, `reset`, `surface`
-- Owner: `@jskit-ai/auth-web@0.2.13`
+- Owner: `@jskit-ai/auth-web@0.2.14`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/auth/auth-surface/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/auth/auth-surface/example/)
 - Requires: `@jskit-ai/auth-core`, `@jskit-ai/auth-web`, `@jskit-ai/shell-web`
@@ -70,7 +70,7 @@ Let people sign in with the accounts they already have in an accounts hub or ano
 
 - Id: `auth/oidc-sign-in`
 - Keywords: `accounts hub`, `auth`, `authentication`, `back-channel logout`, `dynamic client registration`, `issuer`, `master login`, `oidc`, `openid connect`, `single sign-on`, `sso`
-- Owner: `@jskit-ai/auth-provider-oidc-core@0.2.15`
+- Owner: `@jskit-ai/auth-provider-oidc-core@0.2.16`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/auth/oidc-sign-in/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/auth/oidc-sign-in/example/)
 - Requires: `@jskit-ai/auth-provider-oidc-core`, `@jskit-ai/auth-web`
@@ -246,7 +246,7 @@ Add a protected administration surface, settings shell, and semantic navigation
 
 - Id: `console/console-surface`
 - Keywords: `admin`, `console`, `navigation`, `owner`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/console-web@0.1.235`
+- Owner: `@jskit-ai/console-web@0.1.236`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/console/console-surface/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/console/console-surface/example/)
 - Requires: `@jskit-ai/console-core`, `@jskit-ai/console-web`, `@jskit-ai/shell-web`
@@ -257,7 +257,7 @@ Build a routed CRUD user interface as thin application pages over JSKIT's shared
 
 - Id: `crud/crud-screen-set`
 - Keywords: `actions`, `add`, `crud`, `delete`, `edit`, `filters`, `list`, `material`, `routes`, `view`, `vue`
-- Owner: `@jskit-ai/http-web@0.2.16`
+- Owner: `@jskit-ai/http-web@0.2.17`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/crud/crud-screen-set/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/crud/crud-screen-set/example/)
 - Requires: `@jskit-ai/http-web`, `@jskit-ai/resource-crud-core`
@@ -312,7 +312,7 @@ Wrap a JSKIT web application in a Capacitor Android shell using native Capacitor
 
 - Id: `mobile/android-application`
 - Keywords: `android`, `capacitor`, `device`, `mobile`, `native`, `shell`, `webview`
-- Owner: `@jskit-ai/mobile-capacitor@0.2.11`
+- Owner: `@jskit-ai/mobile-capacitor@0.2.12`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/mobile/android-application/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/mobile/android-application/example/)
 - Requires: `@capacitor/android`, `@capacitor/app`, `@capacitor/cli`, `@jskit-ai/mobile-capacitor`
@@ -323,7 +323,7 @@ Add JSKIT realtime events with an optional Redis backplane and an explicit shell
 
 - Id: `realtime/realtime-application`
 - Keywords: `realtime`, `redis`, `socket.io`, `sockets`, `status`, `websocket`
-- Owner: `@jskit-ai/realtime@0.2.14`
+- Owner: `@jskit-ai/realtime@0.2.15`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/realtime/realtime-application/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/realtime/realtime-application/example/)
 - Requires: `@jskit-ai/realtime`, `@jskit-ai/shell-web`
@@ -334,7 +334,7 @@ Compose application-owned Google Publisher Tag delivery with the generic rewarde
 
 - Id: `rewards/google-rewarded`
 - Keywords: `ads`, `google`, `publisher tag`, `rewarded`, `unlock`
-- Owner: `@jskit-ai/rewarded-web@0.2.13`
+- Owner: `@jskit-ai/rewarded-web@0.2.14`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/rewards/google-rewarded/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/rewards/google-rewarded/example/)
 - Requires: `@jskit-ai/rewarded-web`
@@ -345,7 +345,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.277`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`
@@ -356,7 +356,7 @@ Compose the JSKIT responsive shell, semantic placements, settings navigation, an
 
 - Id: `shell/application-shell`
 - Keywords: `adaptive`, `app`, `layout`, `navigation`, `placement`, `responsive`, `settings`, `shell`
-- Owner: `@jskit-ai/shell-web@0.2.11`
+- Owner: `@jskit-ai/shell-web@0.2.12`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/shell/application-shell/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/shell/application-shell/example/)
 - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -367,7 +367,7 @@ Add product routes and shell extensions through file routing, semantic placement
 
 - Id: `ui/page-and-placement`
 - Keywords: `component`, `navigation`, `outlet`, `page`, `placement`, `routes`, `section`, `shell`, `subpages`, `vue`
-- Owner: `@jskit-ai/shell-web@0.2.11`
+- Owner: `@jskit-ai/shell-web@0.2.12`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/ui/page-and-placement/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/ui/page-and-placement/example/)
 - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -378,7 +378,7 @@ Compose an account settings route and profile, preference, notification, and sig
 
 - Id: `users/account-settings`
 - Keywords: `account`, `link provider`, `notifications`, `oauth`, `preferences`, `profile`, `settings`, `sign-in methods`, `user`, `vue`
-- Owner: `@jskit-ai/users-web@0.2.18`
+- Owner: `@jskit-ai/users-web@0.2.19`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/users/account-settings/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/users/account-settings/example/)
 - Requires: `@jskit-ai/shell-web`, `@jskit-ai/users-core`, `@jskit-ai/users-web`
@@ -411,7 +411,7 @@ Compose workspace selection, invitation, member administration, settings, and re
 
 - Id: `workspaces/workspace-surfaces`
 - Keywords: `admin`, `invite`, `member`, `navigation`, `settings`, `surface`, `switcher`, `workspace`
-- Owner: `@jskit-ai/workspaces-web@0.2.18`
+- Owner: `@jskit-ai/workspaces-web@0.2.19`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/workspaces/workspace-surfaces/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/workspaces/workspace-surfaces/example/)
 - Requires: `@jskit-ai/shell-web`, `@jskit-ai/workspaces-core`, `@jskit-ai/workspaces-web`

package/reference/autogen/packages/material-web.md

@@ -21,7 +21,7 @@ Local functions
 - `kebabCase(name)`
 - `channels(argb)`
 - `customColorRoleNames(name)`
-- `addCustomColorRoles(roles, seedArgb, dark, name, argb)`
+- `addCustomColorRoles(roles, seedArgb, dark, name, argb, blend = true)`
 - `schemeColors(scheme, seedArgb, dark, appColors)`
 - `vuetifyTheme(seedArgb, dark, appColors)`
 - `normalizeAppColors(colors, schemeRoles)`

package/reference/autogen/packages/shell-web.md

@@ -82,7 +82,6 @@ Exports
 - None
 Local functions
 - `updateScrolled()`
-- `goUp()`
 
 ### `src/client/components/ShellListDetail.vue`
 Exports
@@ -123,6 +122,14 @@ Local functions
 Exports
 - None
 
+### `src/client/components/ShellPageActionsTarget.vue`
+Exports
+- None
+
+### `src/client/components/ShellPageTitle.vue`
+Exports
+- None
+
 ### `src/client/components/ShellRouteTransition.vue`
 Exports
 - None
@@ -135,12 +142,22 @@ Exports
 Exports
 - None
 
+### `src/client/components/ShellUpButton.vue`
+Exports
+- None
+Local functions
+- `goUp()`
+
 ### `src/client/composables/shellLayoutDrawerPreference.js`
 Exports
 - `SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY`
 - `readDrawerDefaultOpenPreference({ storage = pageStorage() } = {})`
 - `writeDrawerDefaultOpenPreference(open, { storage = pageStorage() } = {})`
 
+### `src/client/composables/useShellAppBar.js`
+Exports
+- `useShellAppBar()`
+
 ### `src/client/composables/useShellDrawer.js`
 Exports
 - `useShellDrawer({ props, modalLayout, viewportWidth, navigationToggle, layoutState })`
@@ -278,6 +295,10 @@ Exports
 - `ShellPageActions`
 - `ShellPageAction`
 - `ShellListDetail`
+- `ShellUpButton`
+- `ShellPageTitle`
+- `ShellPageActionsTarget`
+- `useShellAppBar`
 - `useShellLayoutState`
 - `useShellPageTitle`
 - `useShellWindowSizeClass`
@@ -640,6 +661,10 @@ Local functions
 - `createSurfacePlacements(surface)`
 - `refuseBlockedRecord(to)`
 
+### `fixtures/adaptive-shell/src/OwnBarLayout.vue`
+Exports
+- None
+
 ### `fixtures/adaptive-shell/src/RecordListPage.vue`
 Exports
 - None
@@ -660,6 +685,10 @@ Exports
 Exports
 - None
 
+### `fixtures/adaptive-shell/src/StudioPage.vue`
+Exports
+- None
+
 ### `fixtures/adaptive-shell/src/theme/index.js`
 Exports
 - `theme`

package/reference/autogen/tooling/jskit-catalog.md

@@ -124,7 +124,7 @@ Local functions
 ### `scripts/navigation.mjs`
 Exports
 - `NAVIGATION_RULES`
-- `checkBackControl(tag, report)`
+- `checkBackControl(tag, report, script = "")`
 - `checkLinkAttribute(tag, entry, report)`
 - `checkNavigationCode(code, offset, report)`
 - `checkPageParents({ root, appFiles, pageFiles, report })`
@@ -134,6 +134,10 @@ Exports
 Local functions
 - `compact(text)`
 - `isPlacementLink(code, offset)`
+- `definitionOf(script, name)`
+- `statementFrom(text, start)`
+- `navigatesApp(code, script, seen = new Set())`
+- `navigatesFromControl(tag, script)`
 - `attribute(tag, name)`
 - `visibleText(inner)`
 - `isBackTag(tag)`
@@ -149,6 +153,8 @@ Local functions
 - `surfaceOf(route, surfaces)`
 - `routeDeclarations(source)`
 - `readPage(file, source)`
+- `createShellBarReader(appFiles, read)`
+- `localComponent(file, specifier, known)`
 - `pageKey(file)`
 
 ### `scripts/pattern-assets.mjs`

package/skills/jskit/SKILL.md

@@ -121,3 +121,9 @@ Run focused tests for a slice and the application's `npm run verify` for a
 whole changeset. Use the current-state owners in application operations and
 Playwright for affected UI. There is no current JSKIT Doctor command; ignore
 old CLI authoring-history diagnoses. Never expose environment values.
+
+Tests and requests take the time their work needs, no more: a list reads each
+table once, a row policy is bounded by the rows it reads, list and batch paths
+have a query budget tested at realistic row counts, and test databases restore
+a stored snapshot instead of replaying migrations. Find why a check is slow;
+never raise its time limit. Typed features' repository and Tests rules say how.

package/skills/jskit/references/heuristics/INDEX.md

@@ -42,9 +42,9 @@ How to use it:
   - [server-search.md](./server-search.md)
 - `actualField`, `storage.writeSerializer`, `storage.virtual`, computed field, virtual field, projection, `createCrudResourceRuntime`, datetime write serialization, temporalPrecision, json-rest-schema dates
   - [crud-repository-mapping.md](./crud-repository-mapping.md)
-- row policy, permission filtering, visibility before pagination, recursive CTE, descendants, package cycle, `RowPolicyPlugin`
+- row policy, permission filtering, visibility before pagination, recursive CTE, descendants, package cycle, `RowPolicyPlugin`, row policy cost, slow writes through a policy, access check per history item
   - [row-policies.md](./row-policies.md)
-- typed features, server feature, provider, service, repository, collaborator, `typeof`, `= null`, `setProvider`, `register`, `input || {}`, `payload = {}`, `async execute`, `Object.freeze`, `requires`, `optional`, `types.js`, `RuntimeKnex`, `silentLogger`, `create<Name>Actions`, `ActionSpecifications`, request context, `api.resources.x.query`, every row, list stops at 20 rows, `queryAllJsonRestCollectionRows`, `jskit/*` lint findings, `readable-check: allow`, `optional operation:`, `process.env`, `AppError` code, `Object.assign(new Error`, `idempotency`, `…ForTests` export, file or function size
+- typed features, server feature, provider, service, repository, collaborator, `typeof`, `= null`, `setProvider`, `register`, `input || {}`, `payload = {}`, `async execute`, `Object.freeze`, `requires`, `optional`, `types.js`, `RuntimeKnex`, `silentLogger`, `create<Name>Actions`, `ActionSpecifications`, request context, `api.resources.x.query`, every row, list stops at 20 rows, `queryAllJsonRestCollectionRows`, `jskit/*` lint findings, `readable-check: allow`, `optional operation:`, `process.env`, `AppError` code, `Object.assign(new Error`, `idempotency`, `…ForTests` export, file or function size, read per row, N+1 queries, slow endpoint, query budget, realistic row counts, slow tests, raised timeout, `migrate.latest()` in tests, test database snapshot
   - [typed-features.md](./typed-features.md)
 - client features, composable, `use<Name>`, Vue component, client provider, props, emits, `inject`, `provide`, `ref`, `reactive`, `watch`, `addEventListener`, `setInterval`, module state, `Object.freeze` on a composable, `?.()` in a template, `jskit/typed-inject`, `jskit/collaborator-props`, `jskit/fixed-result-shape`, `jskit/released-listeners`, `jskit/no-module-state`, `jskit/no-frozen-vue-state`, `clientFeaturesConfig`, `shared resource:`
   - [client-features.md](./client-features.md)

package/skills/jskit/references/heuristics/row-policies.md

@@ -8,6 +8,7 @@ Use when:
 - filtering after pagination produces empty or incomplete pages
 - another package grants access to a resource but a reverse dependency would create a cycle
 - the user mentions `RowPolicyPlugin`, recursive CTEs, descendants, or permission-filtered counts
+- reads or writes of a resource with a policy get slower as records or a person's history grow
 
 Read first:
 
@@ -36,6 +37,13 @@ Package composition:
 - the owner seals the contributions and builds the policy during `boot()`
 - do not use module-global mutable registries
 
+Cost:
+
+- a policy's cost follows the rows its query reads: add a join, `EXISTS` or subquery correlated with the row through `column()` and `value()`, on indexed columns
+- never load the subject's whole history (every source, notice or grant they were ever linked to) to build an `IN` list, and never call another owner's access check per item of it; another package's grant is a predicate contribution
+- the policy runs on every single-record read, including the read-back after `createDocument()` and `patchDocumentById()` (`returning: "full"`) and the lookup before `patch` and `delete`, so a write pays it once per row it writes
+- a write decides access once, inside its transaction; a batch write that would pay an expensive read-back per row follows the typed features guide's [Bounded access checks](../typed-features.md#bounded-access-checks)
+
 Child-resource rules:
 
 - a self-referencing relationship targets the same resource and receives the same row policy
@@ -50,6 +58,7 @@ Testing:
 - assert hidden direct records behave as not found
 - assert children and includes do not leak records
 - assert package and provider dependencies stay one-way
+- run one read and one write for a subject with a short history and with a realistic long one (hundreds of linked rows), and assert the same query count
 
 AnyAPI boundary:
 
@@ -65,3 +74,4 @@ Avoid:
 - adding a default policy file to every CRUD
 - returning a Knex builder or promise from a synchronous grouped contribution
 - swallowing a policy error and retrying without mandatory visibility
+- a policy that reads the subject's history or calls an access check per history item

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

@@ -65,6 +65,10 @@ ends with the same link.
   - [One reader per fact](../typed-features.md#one-reader-per-fact)
 - `api.resources.x.query(…)` with no `page` for a list, `queryDocuments(query)` with no `limit` in a service, a list that stops at 20 rows
   - [Every row](../typed-features.md#every-row)
+- `await getDocumentById(…)`, `queryDocuments(…)` or a service `get` inside a loop or a `Promise.all` over a list, a single-record helper reused for a list, N+1 queries, a slow list endpoint
+  - [One read per table](../typed-features.md#one-read-per-table)
+- a `rowPolicy` that loads a person's whole history or calls an access check per item, `createDocument` per row of a batch, a write that gets slower as history grows
+  - [Bounded access checks](../typed-features.md#bounded-access-checks)
 - a route that queries storage, `boot*.js` holding routes
   - [Routes](../typed-features.md#routes)
 - `new AppError(status, message)` with no code, `new NotFoundError("…")`, one code for two sentences (`jskit/app-error-code`)
@@ -81,6 +85,12 @@ ends with the same link.
   - [Tests are not callers](../typed-features.md#tests-are-not-callers)
 - `…ForTests`, `__reset…`, `testOnly…` exports (`jskit/no-test-only-export`)
   - [No test-only exports](../typed-features.md#no-test-only-exports)
+- a list, batch or write test with one to three rows, no query count, a slow endpoint first seen with real data
+  - [Budgets at realistic counts](../typed-features.md#budgets-at-realistic-counts)
+- a raised `{ timeout }`, `test.setTimeout()`, `--test-timeout` or Playwright `timeout`, retries or a request loop that absorbs slowness, a slow suite
+  - [Time limits are not fixes](../typed-features.md#time-limits-are-not-fixes)
+- `knex.migrate.latest()` in each test file, a template database rebuilt by migrating, test preparation slower than its tests
+  - [Test databases are prepared once](../typed-features.md#test-databases-are-prepared-once)
 - a file over 750 lines, a function over 600 (`max-lines`, `max-lines-per-function`), a data module
   - [Size limits](../typed-features.md#size-limits), [Data modules](../typed-features.md#data-modules)
 - two properties on one line in `Object.freeze({ … })` or a token map (`jskit/one-property-per-line`)
@@ -100,3 +110,5 @@ Avoid:
 - module-level registries
 - refusals without their own code
 - excusing a finding without a reason in its `readable-check: allow` comment
+- a read per row of a list, or an access check sized by stored history
+- raising a time limit instead of finding why a check is slow

package/skills/jskit/references/heuristics/ui-testing.md

@@ -65,11 +65,15 @@ in the regression: one test's teardown must not erase another test's migrations.
 
 Do not drop/recreate the database, replay completed migrations, build every
 module fixture, or run a production frontend build for each focused check.
-Choose small fixture sets for the selected suite. Fresh-schema migration tests
-and production-artifact tests are separate operations. Measure migration,
-fixture, and server startup time before retrying a slow launch or raising its
-deadline. When a host supplies a managed target, use its scoped suite command so
-one startup serves the whole batch and cleanup restores normal Preview.
+Choose small fixture sets for the selected suite; realistic row counts belong
+in the database tests that hold each endpoint's query budget. Fresh-schema
+migration tests and production-artifact tests are separate operations. Measure
+migration, fixture, and server startup time and fix the slow phase; never retry
+a slow launch, or raise its deadline or a spec's timeout, to absorb it. A page
+that needs a longer timeout to load is a slow endpoint to fix (typed features'
+Time limits are not fixes). When a host supplies a managed target, use its
+scoped suite command so one startup serves the whole batch and cleanup
+restores normal Preview.
 
 ## Keep browser evidence focused
 

package/skills/jskit/references/material-3.md

@@ -107,7 +107,7 @@ Exactly this, and nothing more:
 | `nav/history` | `history.back()`, `history.go()`, `history.pushState()`/`replaceState()`, `router.back()`, `router.go()` |
 | `nav/window-location` | `window.location` assignments, `.href =`, `location.assign()`, `location.replace()` |
 | `nav/raw-link` | a hand-built in-app path in `to`, `href`, `router.push()`, `router.replace()` or a `to:`/`href:` object key outside a placement |
-| `nav/back-control` | any back control but the shell's Up: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
+| `nav/back-control` | any back control but the shell's Up navigating the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
 | `nav/missing-parent` | an inner page of a shell surface without a declared parent |
 | `nav/top-level-parent` | a main-navigation destination that declares a parent |
 | `nav/allow` | any `m3-check: allow nav/...` comment: nothing excuses a navigation rule |
@@ -140,6 +140,9 @@ Exactly this, and nothing more:
   `finish(recordUrl)`; the record shows, and Up goes where the record's Up went
   before. Wrong: `router.push(recordUrl)` after Save, so Up or Back reopens the
   form.
+- **Steps inside a page are named actions:** "Previous step" or the
+  destination's name, not "Back" or a back arrow. A frame's own Back
+  (`contentWindow.history`) is fine.
 
 ## Foundation
 
@@ -191,6 +194,9 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   standalone heading. A section inside a page uses a title role.
 - **Up** sits in the bar on every inner page (see Navigation and Up). On phones
   it replaces the menu icon.
+- **A layout with its own top app bar** calls `useShellAppBar()` and renders
+  `ShellUpButton`, `ShellPageTitle` and `ShellPageActionsTarget` in it;
+  `jskit check` treats it as a shell layout.
 - **Actions:** a screen's actions go in the bar inside `ShellPageActions`
   (`@jskit-ai/shell-web/client/components/ShellPageActions`), each a
   `ShellPageAction` with `icon`, `label` (also its accessible name and compact
@@ -317,7 +323,8 @@ Take the approved route first; none needs an exception:
 
 - **Brand or partner colours** are theme custom colours, used by name:
   `colors: { partner: "#0A7D3E" }` in `src/theme/index.js`, then
-  `<v-chip color="partner">`.
+  `<v-chip color="partner">`. `{ value: "#F5C518", blend: false }` keeps
+  its hue.
 - **Chart and data colours** come from the theme: `const theme = useTheme()`,
   then `["primary", "tertiary"].map((role) => theme.current.value.colors[role])`.
 - **A third-party widget** lives in one wrapper component, such as

package/skills/jskit/references/pattern-index.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.277`
 - Read: [PATTERN.md](patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.277`
 - Read: [PATTERN.md](patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
 
 - Id: `assistant/assistant-surface`
 - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/assistant-runtime@0.2.24`
+- Owner: `@jskit-ai/assistant-runtime@0.2.25`
 - Read: [PATTERN.md](patterns/assistant/assistant-surface/PATTERN.md)
 - Examples: [example/](patterns/assistant/assistant-surface/example/)
 - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -59,7 +59,7 @@ Compose JSKIT authentication routes, views, profile controls, and public surface
 
 - Id: `auth/auth-surface`
 - Keywords: `account`, `auth`, `login`, `logout`, `password`, `placement`, `profile`, `reset`, `surface`
-- Owner: `@jskit-ai/auth-web@0.2.13`
+- Owner: `@jskit-ai/auth-web@0.2.14`
 - Read: [PATTERN.md](patterns/auth/auth-surface/PATTERN.md)
 - Examples: [example/](patterns/auth/auth-surface/example/)
 - Requires: `@jskit-ai/auth-core`, `@jskit-ai/auth-web`, `@jskit-ai/shell-web`
@@ -70,7 +70,7 @@ Let people sign in with the accounts they already have in an accounts hub or ano
 
 - Id: `auth/oidc-sign-in`
 - Keywords: `accounts hub`, `auth`, `authentication`, `back-channel logout`, `dynamic client registration`, `issuer`, `master login`, `oidc`, `openid connect`, `single sign-on`, `sso`
-- Owner: `@jskit-ai/auth-provider-oidc-core@0.2.15`
+- Owner: `@jskit-ai/auth-provider-oidc-core@0.2.16`
 - Read: [PATTERN.md](patterns/auth/oidc-sign-in/PATTERN.md)
 - Examples: [example/](patterns/auth/oidc-sign-in/example/)
 - Requires: `@jskit-ai/auth-provider-oidc-core`, `@jskit-ai/auth-web`
@@ -246,7 +246,7 @@ Add a protected administration surface, settings shell, and semantic navigation
 
 - Id: `console/console-surface`
 - Keywords: `admin`, `console`, `navigation`, `owner`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/console-web@0.1.235`
+- Owner: `@jskit-ai/console-web@0.1.236`
 - Read: [PATTERN.md](patterns/console/console-surface/PATTERN.md)
 - Examples: [example/](patterns/console/console-surface/example/)
 - Requires: `@jskit-ai/console-core`, `@jskit-ai/console-web`, `@jskit-ai/shell-web`
@@ -257,7 +257,7 @@ Build a routed CRUD user interface as thin application pages over JSKIT's shared
 
 - Id: `crud/crud-screen-set`
 - Keywords: `actions`, `add`, `crud`, `delete`, `edit`, `filters`, `list`, `material`, `routes`, `view`, `vue`
-- Owner: `@jskit-ai/http-web@0.2.16`
+- Owner: `@jskit-ai/http-web@0.2.17`
 - Read: [PATTERN.md](patterns/crud/crud-screen-set/PATTERN.md)
 - Examples: [example/](patterns/crud/crud-screen-set/example/)
 - Requires: `@jskit-ai/http-web`, `@jskit-ai/resource-crud-core`
@@ -312,7 +312,7 @@ Wrap a JSKIT web application in a Capacitor Android shell using native Capacitor
 
 - Id: `mobile/android-application`
 - Keywords: `android`, `capacitor`, `device`, `mobile`, `native`, `shell`, `webview`
-- Owner: `@jskit-ai/mobile-capacitor@0.2.11`
+- Owner: `@jskit-ai/mobile-capacitor@0.2.12`
 - Read: [PATTERN.md](patterns/mobile/android-application/PATTERN.md)
 - Examples: [example/](patterns/mobile/android-application/example/)
 - Requires: `@capacitor/android`, `@capacitor/app`, `@capacitor/cli`, `@jskit-ai/mobile-capacitor`
@@ -323,7 +323,7 @@ Add JSKIT realtime events with an optional Redis backplane and an explicit shell
 
 - Id: `realtime/realtime-application`
 - Keywords: `realtime`, `redis`, `socket.io`, `sockets`, `status`, `websocket`
-- Owner: `@jskit-ai/realtime@0.2.14`
+- Owner: `@jskit-ai/realtime@0.2.15`
 - Read: [PATTERN.md](patterns/realtime/realtime-application/PATTERN.md)
 - Examples: [example/](patterns/realtime/realtime-application/example/)
 - Requires: `@jskit-ai/realtime`, `@jskit-ai/shell-web`
@@ -334,7 +334,7 @@ Compose application-owned Google Publisher Tag delivery with the generic rewarde
 
 - Id: `rewards/google-rewarded`
 - Keywords: `ads`, `google`, `publisher tag`, `rewarded`, `unlock`
-- Owner: `@jskit-ai/rewarded-web@0.2.13`
+- Owner: `@jskit-ai/rewarded-web@0.2.14`
 - Read: [PATTERN.md](patterns/rewards/google-rewarded/PATTERN.md)
 - Examples: [example/](patterns/rewards/google-rewarded/example/)
 - Requires: `@jskit-ai/rewarded-web`
@@ -345,7 +345,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.277`
 - Read: [PATTERN.md](patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`
@@ -356,7 +356,7 @@ Compose the JSKIT responsive shell, semantic placements, settings navigation, an
 
 - Id: `shell/application-shell`
 - Keywords: `adaptive`, `app`, `layout`, `navigation`, `placement`, `responsive`, `settings`, `shell`
-- Owner: `@jskit-ai/shell-web@0.2.11`
+- Owner: `@jskit-ai/shell-web@0.2.12`
 - Read: [PATTERN.md](patterns/shell/application-shell/PATTERN.md)
 - Examples: [example/](patterns/shell/application-shell/example/)
 - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -367,7 +367,7 @@ Add product routes and shell extensions through file routing, semantic placement
 
 - Id: `ui/page-and-placement`
 - Keywords: `component`, `navigation`, `outlet`, `page`, `placement`, `routes`, `section`, `shell`, `subpages`, `vue`
-- Owner: `@jskit-ai/shell-web@0.2.11`
+- Owner: `@jskit-ai/shell-web@0.2.12`
 - Read: [PATTERN.md](patterns/ui/page-and-placement/PATTERN.md)
 - Examples: [example/](patterns/ui/page-and-placement/example/)
 - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -378,7 +378,7 @@ Compose an account settings route and profile, preference, notification, and sig
 
 - Id: `users/account-settings`
 - Keywords: `account`, `link provider`, `notifications`, `oauth`, `preferences`, `profile`, `settings`, `sign-in methods`, `user`, `vue`
-- Owner: `@jskit-ai/users-web@0.2.18`
+- Owner: `@jskit-ai/users-web@0.2.19`
 - Read: [PATTERN.md](patterns/users/account-settings/PATTERN.md)
 - Examples: [example/](patterns/users/account-settings/example/)
 - Requires: `@jskit-ai/shell-web`, `@jskit-ai/users-core`, `@jskit-ai/users-web`
@@ -411,7 +411,7 @@ Compose workspace selection, invitation, member administration, settings, and re
 
 - Id: `workspaces/workspace-surfaces`
 - Keywords: `admin`, `invite`, `member`, `navigation`, `settings`, `surface`, `switcher`, `workspace`
-- Owner: `@jskit-ai/workspaces-web@0.2.18`
+- Owner: `@jskit-ai/workspaces-web@0.2.19`
 - Read: [PATTERN.md](patterns/workspaces/workspace-surfaces/PATTERN.md)
 - Examples: [example/](patterns/workspaces/workspace-surfaces/example/)
 - Requires: `@jskit-ai/shell-web`, `@jskit-ai/workspaces-core`, `@jskit-ai/workspaces-web`

package/skills/jskit/references/patterns/app/minimal-foundation/example/package.json

@@ -35,7 +35,7 @@
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
     "@jskit-ai/kernel": "0.2.10",
-    "@jskit-ai/material-web": "0.1.0",
+    "@jskit-ai/material-web": "0.1.1",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.29",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/skills/jskit/references/patterns/app/shell-foundation/example/package.json

@@ -35,7 +35,7 @@
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
     "@jskit-ai/kernel": "0.2.10",
-    "@jskit-ai/material-web": "0.1.0",
+    "@jskit-ai/material-web": "0.1.1",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -45,13 +45,13 @@
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
     "@jskit-ai/http-runtime": "0.2.10",
-    "@jskit-ai/shell-web": "0.2.11",
+    "@jskit-ai/shell-web": "0.2.12",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.29",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/skills/jskit/references/patterns/auth/oidc-sign-in/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/auth-provider-oidc-core": "0.2.15",
-    "@jskit-ai/auth-web": "0.2.13"
+    "@jskit-ai/auth-provider-oidc-core": "0.2.16",
+    "@jskit-ai/auth-web": "0.2.14"
   }
 }

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.14",
-    "@jskit-ai/shell-web": "0.2.11"
+    "@jskit-ai/realtime": "0.2.15",
+    "@jskit-ai/shell-web": "0.2.12"
   }
 }

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

@@ -719,6 +719,107 @@ const rows = extractJsonRestCollectionRows(await api.resources.workspaceMembersh
 }, createJsonRestContext(options.context)));
 ```
 
+### One read per table
+
+**A read that builds a list reads each table once for the whole list: one
+query per table with an id-list filter, the rows grouped in memory. It never
+reads one row, or runs one lookup, per item of the list.**
+
+- Collect the ids from the first read, then read each related table once with
+  an id-list filter: a `searchSchema` entry
+  `{ type: "array", actualField: "<column>", filterOperator: "in" }`, read
+  through `queryAllJsonRestCollectionRows()`, or the resource's `include`.
+  Group the rows by id with `Map.groupBy()`.
+- `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
+  single-record read inside a loop over the list is a read per row, however
+  the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
+  item). So is a single-record helper reused for a list.
+- Work derived from a row (hashing, preparing a form, assembling a snapshot)
+  runs once per distinct input in the call, not once per row it appears in.
+- The list's query count follows its tables and pages (100 rows a page unless
+  the resource sets `queryMaxLimit`), never its rows: three hundred invoices
+  and their lines take a handful of queries, not three hundred more (see
+  [Budgets at realistic counts](#budgets-at-realistic-counts)).
+
+Why: a read per row costs nothing with three test rows and seconds with a few
+hundred real ones, and every lookup and visibility check inside it repeats too.
+
+```js
+// good: one read per table, however many invoices there are
+const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
+  queryParams: { filters: { workspace: workspaceId } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const lineRows = await queryAllJsonRestCollectionRows(api.resources.invoiceLines, {
+  queryParams: { filters: { invoiceIds: invoiceRows.map((invoice) => invoice.id) } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const linesByInvoice = Map.groupBy(lineRows, (line) => line.invoiceId);
+return invoiceRows.map((invoice) => ({ ...invoice, lines: linesByInvoice.get(invoice.id) || [] }));
+
+// bad: one more query, and its lookups and row policy, for every invoice
+for (const invoice of invoiceRows) {
+  invoice.lines = await invoiceLines.queryDocuments({ invoiceId: invoice.id }, options);
+}
+```
+
+### Bounded access checks
+
+**A row policy costs what the rows its query reads cost, never what the
+subject's stored history costs, and a write decides access once instead of
+paying a read policy for every row it writes.**
+
+- A `rowPolicy` adds one predicate to the query it is given: a join, `EXISTS`
+  or subquery correlated with the row being read, on indexed columns. It never
+  loads everything the subject was ever linked to (every source, notice or
+  grant in their history) to build an `IN` list, and never calls another
+  owner's access check once per item of that history. The
+  [row policies heuristic](heuristics/row-policies.md)
+  has the policy contract and its package composition.
+- The policy runs on every single-record read, and a CRUD write includes one:
+  `createDocument()` and `patchDocumentById()` write with `returning: "full"`
+  and read the record back through the policy, and `patch` and `delete` first
+  look the record up through it. A write therefore pays the read policy for
+  each row it writes.
+- A write path decides access once, inside its transaction. A batch write (a
+  delivery, an import, a fan-out) whose per-row read-back would pay an
+  expensive policy writes through a repository method added with
+  `decorateRepository`, on `resolveRepoClient(database.knex, options)`,
+  setting the same columns the resource would, its ownership columns
+  included, and reading back only what it returns.
+- Its test runs one read and one write for a subject with a short history and
+  with a realistic long one, and asserts the same query count.
+
+Why: a check sized by history grows with every record the subject receives,
+so the same write that takes milliseconds in a test takes seconds a year later.
+
+```js
+// good: one predicate on the row being read
+function noticeVisibilityPolicy({ query, context, column, value, db }) {
+  const userId = resolveActorId(context);
+  if (!userId) return false;
+  query.where(column("recipientId"), value("recipientId", userId)).whereExists(
+    db("sources").select(1)
+      .whereColumn("sources.id", column("sourceId"))
+      .where("sources.status", "published")
+  );
+  return true;
+}
+
+// bad: every source the recipient was ever notified about, checked one by one
+async function noticeVisibilityPolicy({ query, context, column, value }) {
+  const sourceIds = await noticeHistory.listSourceIds(resolveActorId(context));
+  const readable = [];
+  for (const sourceId of sourceIds) {
+    if (await sources.canRead(sourceId, context)) readable.push(sourceId);
+  }
+  query.whereIn(column("sourceId"), readable.map((id) => value("sourceId", id)));
+  return true;
+}
+```
+
 ### Routes
 
 **A route does HTTP work only (status, cookies, redirects) and runs an action
@@ -905,6 +1006,112 @@ export function resetInvoiceCacheForTests() {
 }
 ```
 
+### Budgets at realistic counts
+
+**A list, batch or write path has a database test at the row counts and
+history a real workspace holds, and that test fails above a fixed query
+budget, one that a read per row or a history-sized check cannot meet.**
+
+- Seed hundreds of records and long per-person histories, not one to three
+  rows: a read per row and a history-sized policy cost nothing at three.
+- Count the queries with the test Knex instance's `query` event and assert a
+  ceiling: the count the correct implementation needs at that size, which a
+  read per row overshoots by hundreds. A path that pages nothing (one read,
+  one write) asserts the same count at a short and a long history. A query
+  count is stable in CI; also report the time the call took.
+- Meet the budget by fixing the reads ([One read per
+  table](#one-read-per-table), [Bounded access checks](#bounded-access-checks)),
+  never by shrinking the data or raising the budget.
+
+Why: without a budget at real counts, a path that does one read per row ships,
+and its first sign is a request that takes seconds in production.
+
+```js
+// good
+test("the invoice list reads each table once", async () => {
+  await seedInvoices(knex, { workspace, count: 300, linesEach: 5 });
+  let queries = 0;
+  const count = () => { queries += 1; };
+  knex.on("query", count);
+  try {
+    await invoices.listWithLines(workspace, { context });
+  } finally {
+    knex.off("query", count);
+  }
+  // A page of each table at a time; one read per invoice would add 300.
+  assert.ok(queries <= 40, `${queries} queries`);
+});
+
+// bad: three invoices and no budget, so a read per invoice passes
+test("the invoice list has its lines", async () => {
+  await seedInvoices(knex, { workspace, count: 3, linesEach: 1 });
+  assert.equal((await invoices.listWithLines(workspace, { context })).length, 3);
+});
+```
+
+### Time limits are not fixes
+
+**A slow test, suite, preparation or request is a defect to find, never a time
+limit to raise. Measure where the time goes, fix that cause, and keep the
+default limits.**
+
+- Raising `--test-timeout`, a test's `{ timeout }`, Playwright's `timeout`,
+  `test.setTimeout()` or an `expect` timeout, adding retries, or calling a
+  request in a loop until it answers hides the cause and lets it grow.
+- Read the preparation phases' durations and the query counts first; the
+  cause is usually a read per row, a history-sized policy, or a database
+  prepared by replaying migrations ([Test databases are prepared
+  once](#test-databases-are-prepared-once)).
+- A longer limit is right only for work that is long by nature, such as a
+  fixture of deliberate size, and the test names that work.
+- A time limit still bounds every run, so a hang ends; it is not a speed
+  setting.
+
+Why: a raised limit absorbs today's slowness and every later one, until a run
+takes hours and nobody knows which change made it slow.
+
+```js
+// good: the slow step was found and fixed, so the default limit holds
+test("delivers a batch of notices", async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+
+// bad
+test("delivers a batch of notices", { timeout: 600_000 }, async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+```
+
+### Test databases are prepared once
+
+**A test run prepares each database once, from a stored snapshot of its
+schema, migration ledger and seed rows checked by a digest of their sources,
+and never replays the whole migration history inside the run.**
+
+- The snapshot is rebuilt only when the digest of the migration and seed
+  sources changes, once and outside the timed tests; every disposable
+  database, and every database a test migrated up or down, is restored from
+  it.
+- 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 the suite
+  has a time budget, so slow preparation shows instead of hiding inside the
+  next test that waits for it.
+- The database layer guide's [integration test
+  databases](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#integration-test-databases)
+  gives the snapshot's contents per engine.
+
+Why: the migration history only grows, so a run that replays it whenever a
+schema changed gets slower with every migration the application adds.
+
+```js
+// good: the application's test support restores the snapshot its digest names
+before(async () => restoreTestDatabase(knex, await testDatabaseSnapshot()));
+
+// bad: every file replays every migration
+before(() => knex.migrate.latest());
+```
+
 ## Files and layout
 
 ### Size limits