@jskit-ai/agent-docs 0.1.290 → 0.1.291

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

@@ -213,7 +213,7 @@ write goes through that table's handle
 | a field's `default:` | `defaultTo:` (`default` is refused, since json-rest-api never read it) |
 | a `createdAt` or `updatedAt` default of now | nothing: drop it, since every handle write stamps them |
 | a CRUD contract that showed every column | a contract shows only its `fields`, so list every field the API showed |
-| reading every row | `queryAll`, which refuses above 10,000 rows, so page with `query()` |
+| reading every row | `queryAll`, which refuses above 10,000 rows in a request; a job over more reads `queryPages()` a page at a time |
 | an app's own wrappers around old calls | the handle method they wrapped, then delete the wrapper |
 
 Handles answer records, `{ id, ...fields }`, with a belongs-to field as the

package/guide/agent/framework/data-access.md

@@ -35,8 +35,9 @@ through its handle's calls, and every call takes the call's `options` last:
 | --- | --- |
 | `query({ filters, sort, page, include }, options)` | one page: `{ records, page }` |
 | `queryAll({ filters, sort, include }, options)` | every matching row, for jobs, id lists and one parent's rows |
+| `queryPages({ filters, sort, include }, options)` | every matching row, a page at a time, for work over many rows |
 | `get(id, params, options)` | one record |
-| `aggregate({ measures, groupBy, filters, sort }, options)` | totals, grouped by fields or date buckets |
+| `aggregate({ measures, groupBy, filters, sort, page }, options)` | totals, grouped by fields or date buckets |
 | `create(data, options)`, `findOrCreate({ id, ...data }, options)` | one record; a keyed one, created once |
 | `patch(id, changes, options)`, `delete(id, options)` | one record |
 | `createMany(rows, options)` | many records, or an upsert with `onConflict` |
@@ -60,6 +61,14 @@ function totalsByMonth(options) {
 }
 ```
 
+A grouped `aggregate` answers its groups from one statement, at most
+`pageLimits().request` of them (the resource's `queryMaxLimit`). When there
+are more it throws a 400 coded `RESOURCE_GROUP_LIMIT` instead of answering
+part of them. Narrow the filters, or read the groups in pages, `page: { size,
+number }` with `number` from 1, until a page answers fewer than `size` rows.
+Page numbers are offsets, so read every page before work that changes what
+the filters match.
+
 ## Words
 
 | Word | Meaning |
@@ -157,6 +166,44 @@ whole number exactly, so json-rest-api answers those digits as text rather
 than a rounded number. A value that can grow that large gets a decimal field
 (`precision` and `scale`), whose digits stay text.
 
+A `type: "blob"` field holds bytes the process reads and writes whole, so it
+names `maxBytes`, the most bytes a value holds, and its column holds that much
+too: MySQL's and MariaDB's `BLOB` holds 64 KiB and `MEDIUMBLOB` 16 MiB, while
+PostgreSQL's `bytea` and SQLite's `BLOB` hold more than any limit you would
+name. A blob takes no `search`, `indexed`, `unique`, `sortable`, `defaultTo` or
+`belongsTo`. A write takes a Buffer or a Uint8Array of at most `maxBytes`, or
+null, and refuses anything else with a validation error on the field (422)
+before any statement, a transaction's or a lock's included. A read leaves a
+blob out unless its `fields` names it, and answers it as a Buffer, holding at
+most 16 MiB of the blobs it names, or one record's: `get(id, { fields:
+["image"] }, options)` and `lock()` read one record's; a page of `query()` and
+the ids of `lockMany()` are refused past the records whose `maxBytes` fit 16
+MiB, and each page of `queryPages()` holds no more. `queryAll()`, `lockWhere()`
+and `claim()` read every matching row at once, so they refuse to name a blob,
+and no read names an included table's blob, since an include holds any number
+of records: read it through that table's handle. A join source carries no
+blob. JSON holds no binary, so a JSON:API read and a CRUD contract refuse a
+blob, and a route of its own serves one as the response body. A file people upload (a photo, a
+document) goes to storage through `runtime.uploads` and the table keeps its
+key; a blob is for the few bytes the record itself needs, such as a thumbnail
+or a signature.
+
+```js
+const signatureResource = defineTableResource({
+  name: "signatures",
+  tableName: "signatures",
+  ownership: "workspace",
+  schema: {
+    signedBy: { type: "string", required: true },
+    // MEDIUMBLOB on MySQL and MariaDB
+    image: { type: "blob", maxBytes: 256 * 1024, required: true }
+  }
+});
+
+// One signature's image, read where a route answers it.
+const imageOf = async (id, options) => (await signatures.get(id, { fields: ["image"] }, options)).image;
+```
+
 A package whose features own tables or declare `systemScope` lists
 `runtime.resources` in its descriptor's `capabilities.requires`, or boot
 refuses it; the feature never requires it itself, since it receives its
@@ -202,7 +249,17 @@ A filter on another table's field (`searchSchema: { supplierName: { type:
 "string", actualField: "suppliers.name" } }`) needs that field declared
 `indexed: true` on its own table resource, with a database index on its column,
 even when the join is on the other table's id; `own()` refuses it at startup
-otherwise, naming both.
+otherwise, naming both. That `indexed: true` is the other table's owner letting
+filters search the field. The filter reads that table as the table's own read
+in the caller's scope: its ownership, its owner's row policy and the policies
+contributed to it decide which of its rows can match, in `query`, `queryAll`,
+`queryPages` and `aggregate` alike, and each row matches once, through a
+has-many path too (suppliers filtered by their items' names). `own()` also
+refuses two filters no scope guards: one that reads a `system` table from a
+table that is not `system`, since a request would read it, and one on a field
+the other table hides, which would tell a caller which rows hold a value it
+may not read. For either, the other table's owner answers the ids it matches
+through its owner API, and the filter takes the list: `filters: { supplierIds }`.
 
 A table keyed by a `uuid` or `string` primary key takes its ids as text; an
 `owns` entry's `normalizeId` is only for an id written some other way.
@@ -318,7 +375,11 @@ request, `{ kind: "anonymous" }` for one by no one, and `{ kind: "system" }` or
 `{ kind: "job" }` (a context `forWorkspace` and its kin derived), each with its
 `reason`, for background work. A job names a user only as `actorId`, the
 person it works for ([below](#background-work)), so never read a missing actor
-as an anonymous request.
+as an anonymous request. The owner's policy also receives the capabilities its
+feature requires (and its optional ones), by local name, as `requires`, the
+same ones its setup receives: a policy that needs another feature's answer
+declares that feature's capability in `requires` and reads `requires.<name>`.
+It runs on every read, so what it asks there must be cheap.
 
 ```js
 // good: one predicate on the row being read
@@ -492,8 +553,10 @@ Every filter takes `id`, one id or a list, so `patchWhere({ id: ids },
 changes, options)` and `deleteWhere({ id: ids }, options)` change a known
 list. Each checks every row against the resource first, reads which of the
 rows the caller may touch, then writes each chunk with one statement, in one
-transaction. Audits and change events run once for the batch, so the
-statements are the same for 10 rows as for 200. `patchWhere` and
+transaction. A chunk is 500 rows unless the call passes `chunkSize`, which is
+at least 100: a smaller chunk would send a statement every few rows, as a loop
+does, and is refused before any statement. Audits and change events run once
+for the batch, so the statements are the same for 10 rows as for 200. `patchWhere` and
 `deleteWhere` check the scope and filters on each row once they hold its lock,
 so a row gone meanwhile, or changed so that it no longer matches, is skipped,
 and they take no `missing`. That makes them a compare-and-set on their filters
@@ -564,6 +627,31 @@ or a counter row taken with `lock(id)`. Every lock needs a transaction; SQLite
 runs one transaction at a time, so there is no row lock to take. Take locks in
 one order on every path, a parent before its children.
 
+A lock answers only the rows it locks, with the fields `fields` names, and
+refuses `include` before any statement. Read the locked rows' related records
+after the lock, in the same transaction: `queryAll({ filters: { id: ids },
+include }, txOptions)`, or the related table's read by id list. On PostgreSQL
+every statement sees what had committed when it began, so that read is current.
+On MySQL and MariaDB a plain read inside a transaction sees the snapshot of the
+transaction's first plain read, and a lock that waited does not move it. So
+take the lock before any plain read in the transaction: the reads after it then
+see what the lock's previous holder committed. A related row the work decides
+on (is this seat already booked?) is locked itself, or read after a lock
+that every writer of it takes first.
+
+```js
+// good: the lock is the transaction's first read, so the bookings read after it are current
+const reserve = (seatId, options) => seats.withTransaction(options, async (txOptions) => {
+  await seats.lock(seatId, { ...txOptions, fields: ["status"] });
+  const taken = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
+  return taken.length > 0 ? null : bookings.create({ seatId }, { ...txOptions, returning: "id" });
+});
+
+// bad: the read before the lock fixed the snapshot, so a booking committed while the lock waited is missed
+const free = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
+await seats.lock(seatId, txOptions);
+```
+
 On MySQL and MariaDB a locking read locks every row it examines, so two rules
 apply there. Lock ids taken from your own scoped reads, never a list straight
 from a request: every id listed is locked, a hidden one too, before it is left
@@ -676,8 +764,10 @@ async function activeDays(memberIds, options) {
   other features, answers `{ query, column }`: the caller's scoped rows under
   that alias (ownership, the row policy and the filters applied) with the
   columns a read answers and the ownership fields (`workspaceId`, `userId`),
-  hidden or not, as join keys; never another hidden column. `column(field)`
-  names each under the alias. The builder comes wrapped, since a builder is
+  hidden or not, as join keys; never another hidden column, and never a blob,
+  so a report's `select("k.*")` holds no unbounded bytes. `column(field)`
+  names each under the alias. A report on the owner's own `scopedQuery()`
+  names the columns it selects, never a blob's. The builder comes wrapped, since a builder is
   thenable and an async function would run it. The report shapes it (select,
   group), names it with `.as()` and joins it, so every owner's scope and row
   policy stay applied. The report lives with the main table's owner, or in a
@@ -707,6 +797,25 @@ async function activeDays(memberIds, options) {
   }
   ```
 
+- A report that asks which of its rows have, or lack, another owner's rows
+  puts that owner's join source in `whereExists` or `whereNotExists`, tied to
+  its own row with `whereColumn`; one that counts them joins the source grouped,
+  as `projectSummary` does. Rows matched by a related row's value ("items
+  whose supplier is named Acme") need no report: a cross-table search filter
+  answers them in a plain read ([Layer 1](#layer-1-the-table-resource)).
+
+  ```js
+  // Knex: report - the caller's projects with no task the caller sees
+  async function idleProjects(options) {
+    const task = await tasks.joinSource({ alias: "k" }, options);
+    const { query } = await projects.scopedQuery({ alias: "p" }, options);
+    const projectId = projects.column("id", "p");
+    return query
+      .whereNotExists(task.query.select(task.column("id")).whereColumn(task.column("projectId"), projectId))
+      .select({ id: projectId, name: projects.column("name", "p") });
+  }
+  ```
+
 - When each owner can answer on its own (keys in, grouped totals out), the
   report is a feature of its own that calls each owner's method and merges the
   answers in memory: one statement per owner, never a call per row.
@@ -726,11 +835,26 @@ async function activeDays(memberIds, options) {
   another field) or `include`, grouped in memory. Never a query per row, however
   the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
   item).
-- `queryAll` reads every matching row, in cursor pages that skip and repeat
-  none. Use it for id lists, one parent's rows and jobs: a read its callers
+- `queryAll` reads every matching row, in cursor pages that each start after
+  the sort values of the page before, so no row is skipped or read twice
+  unless a write moves a row's sort value (the id, by default) past the page
+  while the read runs. Use it for id lists, one parent's rows and jobs: a read its callers
   treat as complete, which a `query` would silently cut at one page. In a
-  request it stops past the request row limit (10,000 rows) with a 400 coded
-  `RESOURCE_ROW_LIMIT`.
+  request it stops past the request row limit (`pageLimits().requestRows`,
+  10,000 rows) with a 400 coded `RESOURCE_ROW_LIMIT`, and never answers part
+  of the rows. A job reads without that limit and holds every row in memory.
+- Work over many rows reads `queryPages` and handles one page at a time:
+  `for await (const records of handle.queryPages(params, options))`. Each
+  page is one statement of up to `pageLimits().server` rows (fewer when its
+  fields name blobs, so it holds at most 16 MiB of them), plus the reads of
+  its includes and of the hidden fields it names, and starts after the sort
+  values of the last row of the page before. So the work may change what the
+  filters match as it goes, and no row still to come is skipped or read twice,
+  as long as it leaves the sort fields' values alone (the id, by default): a
+  row whose sort value moves past the page is read again or not at all. In a
+  request it throws at the same row limit, before the page that passes it.
+  `expectFlatQueries` allows each later page's own statements, as it allows
+  a many-row write's later chunks; work the path does for each page counts.
 
 ```js
 // good: one page of invoices, then all of that page's lines in one read
@@ -746,6 +870,11 @@ for (const invoice of records) {
 // good: a delivery job reads every active subscriber
 const subscribers = await subscriptions.queryAll({ filters: { newsletterId, status: "active" } }, options);
 
+// good: a job over a table of any size marks each page as it reads it
+for await (const records of reminders.queryPages({ filters: { status: "due" } }, txOptions)) {
+  await reminders.patchWhere({ id: records.map((reminder) => reminder.id) }, { status: "sent" }, txOptions);
+}
+
 // bad: the first page only, whatever its size
 const { records: firstPage } = await subscriptions.query({ filters: { newsletterId, status: "active" }, page: { size: 20 } }, options);
 ```
@@ -837,14 +966,21 @@ const SettlementFeature = defineFeature({
   request's `caller.userId`, so a job for a person sees what that person may
   see, and a job for no one its whole scope. Work on one person's rows only
   takes their scope (`forUser`, `forWorkspaceUser`) or filters its reads.
-- A job finds its units with one `aggregate` grouped by the ownership field,
+- A job finds its units with an `aggregate` grouped by the ownership field,
   which a system context may group by (and count distinct) even when the table
-  hides it, then runs each unit scoped to it. A request's aggregate still
-  refuses a hidden field:
+  hides it, then runs each unit scoped to it. It reads the units in pages, all
+  of them before the first runs, since settling a unit changes what the
+  filters match. A request's aggregate still refuses a hidden field:
 
   ```js
   async function settleDue(options) {
-    const due = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" } }, options);
+    const size = cohorts.pageLimits().request;
+    const due = [];
+    for (let number = 1; ; number += 1) {
+      const page = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" }, page: { size, number } }, options);
+      due.push(...page);
+      if (page.length < size) break;
+    }
     for (const { workspaceId } of due) {
       await settleWorkspace({ context: systemContext("settle finished weekly leagues for every user").forWorkspace(workspaceId) });
     }
@@ -953,7 +1089,10 @@ participants) reads them with `users.profiles.listByIds(ids, options)`: every
 profile in one call, however many ids, never `query` pages of 100 walked by
 hand or one `findById` per person. `users.settings.listByUserIds(ids, options)`
 does the same for their settings, and `workspaces.listByIds(ids, options)` for
-workspaces.
+workspaces. A report that reads people, their settings, workspaces or
+memberships beside its own rows joins `joinSource({ alias, filters },
+options)` of `users.profiles`, `users.settings`, `workspaces` or
+`workspaces.memberships` ([Layer 5](#layer-5-reports-the-resource-cannot-express)).
 
 An app that had a table resource of its own over a JSKIT table (such as
 `users`) deletes it: its CRUD contract is built on the package's table resource
@@ -1006,6 +1145,38 @@ named with no value, such as `lockVersion: record.lockVersion` on a field
 called `version`, is refused (`options.lockVersion is undefined`), never run
 without it.
 
+### Capability cycles
+
+A capability cycle is a ring of requires: feature A requires a capability that
+feature B provides while B, directly or through others, requires one that A
+provides. An `optional` require closes a ring as a required one does. The
+kernel sets features up in the order their requires give, so it cannot start a
+ring: boot fails before any setup, naming it,
+`Provider capability cycle detected: children -> parents -> children.`
+`startTestFeatures` orders features the same way, so a feature test meets the
+ring before the server does. The same ring between packages, each listing the
+other in its `package.json` dependencies (as importing the other's shared
+table resource needs), fails as
+`Package dependency cycle detected: @local/jobs -> @local/checklists -> @local/jobs`.
+
+Data access makes them easy to write: a parent's owner reads its children
+through their owners while each child's owner checks or advances the parent.
+Keep every require pointing one way:
+
+- The table nearest the root requires none of the owners below it. It provides
+  a small owner API, and the owners below require that.
+- Work that reads several owners together (a parent with its children, a
+  report across them) is a feature of its own that requires each of them, as
+  above and in [Layer 5](#layer-5-reports-the-resource-cannot-express).
+- A package imports another package's shared table resource only when that
+  package does not depend on it back. When two packages need each other's
+  definitions, move those table resources into a package of their own that
+  holds only shared definitions and depends on neither.
+- Never break a ring with a value handed over later (a setter, a capability
+  looked up at call time): a call's destination then depends on what ran
+  before. A setter kept until the split carries typed features' `cycle:`
+  exception ([Optional tokens](/guide/framework/typed-features#optional-tokens)).
+
 ## Check and judge
 
 Before calling data work done, apply the
@@ -1029,7 +1200,11 @@ test("allocation is flat", () => expectFlatQueries({ environment: process.env, k
 `expectFlatQueries` (from `@jskit-ai/resource-runtime/test`) seeds each size,
 counts the statements the path sends, and fails when a larger size sends more,
 with the counts and the statements repeated most; the later chunks a many-row
-write reports are allowed. `expectScoped` runs the path as owner A before and
+write reports, and the statements of each later page `queryPages()` reads, are
+allowed. It counts only the path's own statements, those
+`run` and the async work it starts send, so another test or a background loop
+using the same Knex meanwhile changes nothing; work a loop started earlier does
+on the path's behalf is not counted either. `expectScoped` runs the path as owner A before and
 after seeding owner B and fails when the answer changes, so it catches a report
 that sums, counts or joins B's rows, not only one that returns them; it also
 fails when the path changed or removed a row of B's. The path runs twice, so it
@@ -1210,5 +1385,11 @@ it. Check and judge, for each file:
   `/* eslint ... */` config that sets one, outside client code;
 - an app file that the app's ESLint config lints without every data-access
   rule as an error (`"jskit/no-direct-knex": "off"`, `dataAccessConfig(files,
-  "off")`), or server code (`src/server`, `src/shared`, `server/`) that it
-  ignores, until `infrastructure` lists that file and rule.
+  "off")`), or server code that it ignores, until `infrastructure` lists
+  that file and rule. Server code is what the base config lints, at the app's
+  root or a package's: its files (`server.js`), `src/` (an app's whole `src/`,
+  `src/jobs/` with it), `server/`, `scripts/`, `bin/` and `config/`.
+
+It reads none of what the app's ESLint config ignores outside server code,
+such as a vendored copy of old code kept beside the app, since no lint reads
+it either, and lists each directory and file it skipped.

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

@@ -184,9 +184,9 @@ Exactly this, and nothing more:
   `createVuetify(createMaterialVuetifyOptions(theme))` with
   `createMaterialVuetifyOptions` from `@jskit-ai/material-web/client`, importing
   `@jskit-ai/material-web/client/material.css`. JSKIT generates the light and
-  dark schemes from the seed at startup (Material Color Utilities
-  `SchemeTonalSpot`, every role in kebab-case such as `surface-container-low`,
-  plus success, warning and info with their containers), with
+  dark schemes from the seed at startup (every role in kebab-case such as
+  `surface-container-low`, plus success, warning and info with their
+  containers), with
   `defaultTheme: "system"` so the person's light, dark or system preference
   applies. The `md3` blueprint and JSKIT's Material 3 Vuetify defaults live in
   material-web; an app keeps no defaults file and never hand-picks a colour. The
@@ -210,6 +210,12 @@ Exactly this, and nothing more:
   Symbols has no brand marks (Google, GitHub, a payment network): a brand's
   logo is the brand's own artwork, a content image or SVG used as its owner
   publishes it, not an icon alias.
+- **Components:** a Vuetify component chosen at run time is imported and
+  passed: `import { VDialog } from "vuetify/components"`, then `:is="VDialog"`
+  or `h(VDialog)`. A JSKIT app registers none globally, so one named as a
+  string (`resolveComponent("v-dialog")`, `is="v-dialog"`) renders nothing
+  (`ui/vuetify-by-name`). A prop a JSKIT package lists as removed (its
+  `jskit.metadata.ui.removedProps` and CHANGELOG) fails `ui/removed-prop`.
 
 ## Exact sizes
 
@@ -260,14 +266,9 @@ dialog, chip or FAB.
   file, such as a CSV export), `disabled`, `loading` or `color` (`error` for a
   destructive one); attributes such as `target` reach its button. On compact
   widths the bar shows the single `primary` action (a form's Save) and puts
-  every other action in its "More actions" menu, where `overflow` actions
-  always are. The bar's own items (top-right placements such as tools, a
-  notification bell and the account avatar) stay while they fit beside the
-  whole title; those that don't follow the actions into the menu, farthest
-  from the corner first, and the item nearest the corner stays unless the
-  `primary` action takes its place. An item keeps running while it is in the
-  menu, closed or open, so its live count, its panel or a floating button it
-  shows elsewhere on the page stay. Medium and wider bars show them all.
+  the other actions, and the top-right items that don't fit beside the title,
+  in its "More actions" menu, where `overflow` actions always are; medium and
+  wider bars show them all.
 - **Window size classes:** compact under 600 (navigation bar), medium 600–839
   (navigation rail), expanded 840–1199 and large from 1200 (drawer), read from
   `useShellWindowSizeClass()`
@@ -280,12 +281,17 @@ dialog, chip or FAB.
   starter registers it as `local.main.ui.section-tab-link-item`), and the page
   draws one tab row, `display: flex; overflow-x: auto` over a 1dp
   `outline-variant` bottom border. `ShellTabLinkItem` is the navigation bar's
-  destination; placed in a page it draws a section tab.
+  destination; placed in a page it draws a section tab. material.css draws an
+  app's own `v-bottom-navigation` the same way, keeping its colour props.
 
 ## Colour
 
 - Use semantic roles through Vuetify props, classes and
   `rgb(var(--v-theme-<role>))`; never a raw colour value in a component.
+- Text in an `on-*` role uses its class or a `color` prop
+  (`class="text-on-surface-variant"`, `<v-icon color="on-surface-variant">`);
+  an app colour's is `class="on-partner"`, which `bg-partner` already sets.
+  Never lower text emphasis with an opacity or `text-medium-emphasis`.
 - Status chips use `color="success"` (or `warning`, `info`, `error`) or the
   container roles (`success-container` with `on-success-container`), and each
   status meaning has its own hue. Never communicate status, selection, validation, or permission through
@@ -318,9 +324,11 @@ dialog, chip or FAB.
   actions in the bar's overflow menu, never in the content; the record's
   next workflow step is the one filled button, shown in context rather than a
   row of mostly disabled actions.
-- **Form:** the bar's close (X) cancels and Save is its filled action. Fields
-  use `hideDetails: "auto"`. Nothing moves under a finger: a multi-select chip
-  field keeps its input width when it loses focus. A pick-one-of-N choice is a
+- **Form:** the bar's close (X) cancels and Save is its filled action. A
+  field keeps its message line (no `hide-details`, no margin under it), so an
+  error appears in place; a field outside a form (search, filter) sets
+  `hide-details`. Nothing moves under a finger: a multi-select
+  chip field keeps its input width when it loses focus. A pick-one-of-N choice is a
   segmented button (`v-btn-toggle`, drawn by JSKIT, with 12dp segment sides as
   in any `v-btn-group`) with `role="radiogroup"` and
   `role="radio"`/`aria-checked` buttons.
@@ -354,11 +362,9 @@ dialog, chip or FAB.
   field. A user-triggered command uses JSKIT's shared action
   feedback/snackbar path. Never insert a transient command-error alert above
   page content where it shifts the working layout.
-- A snackbar never covers the FAB or the actions it reports on. `ShellErrorHost`
-  centres it above the navigation bar on compact windows and starts it at the
-  content's start edge, at most half its width, on wider ones. A FAB takes
-  layout room (`<v-fab app layout>`, as `ShellPrimaryAction`'s does), so the
-  snackbar shows above it.
+- A snackbar never covers the FAB or the actions it reports on: `ShellErrorHost`
+  places it, and a FAB takes layout room (`<v-fab app layout>`, as
+  `ShellPrimaryAction`'s does), so the snackbar shows above it.
 
 ## Adaptive layout
 
@@ -374,16 +380,14 @@ Two commands read application source (no server, no browser) and print each
 finding with its file, line, rule and the section of this page:
 
 ```bash
-npx jskit check                          # in every app's verify: fails on any nav/* rule
-npx jskit check m3                       # the whole app: src/ and packages/
+npx jskit check                          # in every app's verify: fails on any nav/*, m3/* or ui/* finding
+npx jskit check m3                       # these rules alone, the whole app: src/ and packages/
 npx jskit check m3 src/pages/home/books  # a section
 npx jskit check m3 $(git diff --name-only --diff-filter=d main)  # changed files
 ```
 
-Plain `jskit check` fails on the [navigation rules](#forbidden-in-app-code).
-`jskit check m3` lists those and the visual rules below. The visual rules are a
-report until every JSKIT app has been converted to them; the JSKIT release after
-that makes plain `jskit check`, and so every app's verify, fail on them too:
+Both fail on the [navigation rules](#forbidden-in-app-code) and on these;
+nothing excuses a `ui/*` finding:
 
 | Rule | Finds |
 |---|---|
@@ -393,12 +397,12 @@ that makes plain `jskit check`, and so every app's verify, fail on them too:
 | `m3/outlined-card` | `variant="outlined"` or `border` on a card or sheet |
 | `m3/mdi-icon` | `mdi-*` icon strings and `@mdi/js` imports |
 | `m3/fixed-button-height` | `height`/`min-height` on buttons, in props, styles or CSS |
+| `ui/vuetify-by-name` | a Vuetify component named as a string for Vue to resolve |
+| `ui/removed-prop` | a prop the installed JSKIT package lists as removed from that component |
 
 Tests, fixtures, server code and migrations are not checked. A clean check is
-necessary, not sufficient: it cannot see layout, spacing or contrast. A
-[UI pass](./ui-pass.md) is the guard for those, because it looks at every
-affected screen at three widths in light and dark; an editor that runs one
-automatically after each plan keeps that guard on every change.
+necessary, not sufficient: layout, spacing and contrast need a
+[UI pass](./ui-pass.md), every affected screen at three widths in light and dark.
 
 ### Exceptions
 
@@ -407,16 +411,13 @@ 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">`. A hex string is harmonized toward the seed; a
-  colour that must keep its hue is `{ value: "#F5C518", blend: false }`
-  (Material Theme Builder's Blend switched off), with the same four roles.
+  colour that must keep its hue is `{ value: "#F5C518", blend: false }`, with
+  the same four roles.
 - **Content colours**, colours that are content rather than UI, keep one
-  value in both schemes: an identity palette a person picks and the server
-  stores, avatar and illustration artwork, brand marks (a language's
-  file-type tint), fixed chart series, QR codes, colours written into
-  exported files. They are named exports of plain hex values in
-  `src/theme/palettes.js`, used as they are, never for UI chrome (a theme
-  colour is toned per scheme, so it can't keep an identity the same).
-  Components read them through bindings:
+  value in both schemes: an identity palette a person picks, artwork, brand
+  marks, fixed chart series, QR codes, colours in exported files. They are
+  named exports of plain hex values in `src/theme/palettes.js`, used as they
+  are, never for UI chrome. Components read them through bindings:
 
   ```vue
   <script setup>

package/guide/agent/framework/sanity-checks.md

@@ -4,9 +4,9 @@
 
 Before calling a list, a save, a test, a refactor, a screen or a deployment
 done, measure what it costs and does, judge whether that is sane, and fix the
-cause when it is not. This page holds JSKIT's part: the pitfalls JSKIT's own
+cause when it is not. This page holds JSKIT's part: the pitfalls its own
 packages cause, then the JSKIT call, helper or setting that applies each
-check, with one line on what it catches and why.
+check, and what it catches.
 
 ## JSKIT's own pitfalls
 
@@ -67,10 +67,14 @@ expects the relationship id or an unselected field never gets it.
 ### Every row
 
 - A handle's `query()` answers one page and refuses a missing or oversized
-  `page.size`, because json-rest-api would otherwise cut the list without an
-  error. A read its callers treat as complete uses `queryAll()`, because the
-  missing rows otherwise vanish from every picker and delivery built on it
+  `page.size`, where json-rest-api would cut the list silently. A read its
+  callers treat as complete uses `queryAll()`, or the missing rows vanish from
+  every picker and delivery built on it
   ([Reads](/guide/framework/data-access#reads-shaped-for-the-screen)).
+- A grouped `aggregate()` answers every group or throws
+  `RESOURCE_GROUP_LIMIT`; past `pageLimits().request` groups, page it with
+  `page: { size, number }`
+  ([The handle's calls](/guide/framework/data-access#the-handle-s-calls)).
 - A lookup by a unique key matches at most one row: `get(id)`, or a `query()`
   of page size 1.
 
@@ -79,12 +83,11 @@ expects the relationship id or an unselected field never gets it.
 - Count a path's queries with `expectFlatQueries()` from
   `@jskit-ai/resource-runtime/test`, or `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
+  realistic number; it should follow tables and pages, not rows
   ([Tests](/guide/framework/data-access#tests)).
 - A JSON:API read adds a few lookup and visibility queries per page and per
-  relationship field, and json-rest-api reads each relationship's related ids
-  in one statement however many rows the page has. Both follow pages, not
-  rows, so `expectFlatQueries` passes them.
+  relationship field, and one statement per relationship for its related ids.
+  Both follow pages, not rows, so `expectFlatQueries` passes them.
 - A handle's `get()` or `query()`, or a service `get`, inside a loop is the
   usual per-row read; batch it with an id-list filter through `queryAll()` or
   `include`, grouped with `Map.groupBy()`
@@ -108,8 +111,8 @@ expects the relationship id or an unselected field never gets it.
   `DB_NAME`, because tests write and delete rows and would destroy the
   developer's data. A skip for want of a test database is a failure.
 - Test databases restore a stored snapshot checked by a digest of the
-  migration and seed sources, and the harness reports each preparation phase's
-  duration, so slow preparation shows ([Test databases are prepared
+  migration and seed sources, and the harness times each preparation phase,
+  so slow preparation shows ([Test databases are prepared
   once](/guide/framework/typed-features#test-databases-are-prepared-once),
   [integration test
   databases](/guide/app-setup/database-layer#integration-test-databases)).
@@ -135,7 +138,7 @@ Before changing a JSKIT feature, list where its behaviour lives, with the test
 that covers each item, and walk the list again after: routes, actions and
 their input schemas, row policies, CRUD fields, lookups and hooks, placements
 and navigation meta, messages and their codes, events, jobs and migrations.
-These are the places a consolidation drops behaviour without a failing build.
+A consolidation drops behaviour there without a failing build.
 
 ### Changes others depend on
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.290",
+  "version": "0.1.291",
   "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.16",
+    "@jskit-ai/kernel": "0.2.17",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

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

@@ -34,8 +34,8 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.16",
-    "@jskit-ai/material-web": "0.1.4",
+    "@jskit-ai/kernel": "0.2.17",
+    "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -44,13 +44,13 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.16",
+    "@jskit-ai/http-runtime": "0.2.17",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.248",
-    "@jskit-ai/jskit-catalog": "0.2.42",
+    "@jskit-ai/jskit-catalog": "0.2.43",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -34,8 +34,8 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.16",
-    "@jskit-ai/material-web": "0.1.4",
+    "@jskit-ai/kernel": "0.2.17",
+    "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -44,14 +44,14 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.16",
-    "@jskit-ai/shell-web": "0.2.20",
+    "@jskit-ai/http-runtime": "0.2.17",
+    "@jskit-ai/shell-web": "0.2.21",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.248",
-    "@jskit-ai/jskit-catalog": "0.2.42",
+    "@jskit-ai/jskit-catalog": "0.2.43",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",