@jskit-ai/agent-docs 0.1.290 → 0.1.292

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

@@ -34,9 +34,10 @@ through its handle's calls, and every call takes the call's `options` last:
 | Call | Does |
 | --- | --- |
 | `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 |
+| `queryAll({ filters, sort, include, take }, options)` | every matching row, or the first `take`, 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,74 @@ 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 filter that asks whether a row has, or lacks, another owner's rows
+(projects with an open task, projects with no task) reads that owner's join
+source. The `owns` entry's `searchSchema` names each join source by an alias,
+with a function answering its owner from the feature's `requires` or its own
+handles (`owned`), and `applyFilter` gets `joinSource(alias)`: that owner's
+`{ query, column }` for the caller's scope, as a report's join source
+([Layer 5](#layer-5-reports-the-resource-cannot-express)), which it ties to
+the row with `whereColumn` inside `whereExists` or `whereNotExists`:
+
+```js
+// the projects feature's owns entry; the feature requires the tasks owner as `tasks`
+{
+  resource: projectResource,
+  searchSchema: {
+    hasOpenTask: {
+      type: "boolean",
+      joinSources: { k: ({ requires }) => requires.tasks },
+      applyFilter(query, wanted, { column, joinSource }) {
+        const task = joinSource("k");
+        const openTasks = task.query
+          .select(task.column("id"))
+          .whereColumn(task.column("projectId"), column("id"))
+          .where(task.column("status"), "open");
+        if (wanted) {
+          query.whereExists(openTasks);
+        } else {
+          query.whereNotExists(openTasks);
+        }
+      }
+    }
+  }
+}
+```
+
+The handle builds the join sources a read's filters use just before the read,
+in the call's own context and transaction, so `query`, `queryAll`,
+`queryPages`, `aggregate` and `joinSource` take the filter in their one
+statement, and the other owner's ownership, row policy and hidden fields
+decide which of its rows count (`column()` refuses a hidden field). A filter
+that prefers one match and falls back on another when no row of the table has
+the first (the projects named like the term, or, when none is, those with a
+task in that status) names the feature's own handle for its own table,
+`({ owned }) => owned.projects`. Only a read through a handle builds join
+sources. `own()` refuses, at startup, `joinSources` that is not a record of
+functions under aliases, such a filter with `oneOf` or without `applyFilter`,
+and `joinSources` in the table resource's own `searchSchema`, which names no
+feature to answer it.
+
+An app switches to such a filter where a search resolves another owner's
+matches first: a repository that reads the other owner's ids (an id report on
+its `scopedQuery()`, or that owner's `queryAll` matched in memory) and then
+filters `id` by the list, or a filter that was a `whereRaw` with `EXISTS
+(SELECT ... FROM ...)`, which `jskit/sql-literal` refuses. The filter moves
+into the `owns` entry with the other owner as a join source, the code that
+resolved ids goes, and the read is one statement however many rows match,
+where the id list grew with the matches.
 
 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 +432,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 +610,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
@@ -506,8 +626,9 @@ waiter with errno 1020 ("Record has changed since last read"), which a write
 that owns its transaction runs again. For one row,
 `patch(id, changes, { ...options, onlyIf: { status: "open" } })` does the same.
 A filter on another table (a search field whose `actualField` reaches a
-related table) is refused on MySQL and MariaDB (`RestApiValidationError`, rule
-`selection_cross_table`), even when it matches no row. A search entry's own
+related table, or one that reads a join source) is refused on MySQL and
+MariaDB (`RestApiValidationError`, rule `selection_cross_table`), even when it
+matches no row; `lockWhere` and `claim` refuse it the same way. A search entry's own
 `applyFilter` that reads another table through a subquery is not detected, and
 is no compare-and-set there either. Filter on the row's own columns instead, for example
 on the link after locking its targets with `lockMany` in the same transaction
@@ -564,6 +685,45 @@ 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 the rows it locks, with the fields `fields` names. Its
+`include` names belongs-to relationships (`include: ["customer"]`, or
+`"batch.yard"` a level further): after its own rows, the lock locks the
+records they name through each related table's own handle (its scope, its row
+policy, its hidden fields), in id order, each related table once however many
+rows name it, and nests them as a read's include does; a link to a record the
+caller may not see reads as in a read, its belongs-to field null. Those are locks too, so on MySQL and MariaDB
+they find a record committed after the transaction's first plain read, which a
+plain read misses. They come after the rows, a child before the parent it
+names, so a path that locks the parent first and then its children (to add one)
+takes the other order: the database ends a deadlock between the two by failing
+one transaction, which `withTransaction` runs again, and a path that runs
+often keeps one order on both sides. A collection (`include: ["lines"]`) is
+refused before any statement: lock a parent's children with their own
+table's `lockWhere` in the same transaction.
+
+Every other read after the lock is a plain read. 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, through the lock's
+`include` or a lock of its own, 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 +836,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 +869,54 @@ 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)). Nor
+  does a question that only narrows a plain read's rows (has an open task, has
+  no task): a search filter that reads the other owner's join source answers
+  it in that read, with its page, sort and includes as usual (Layer 1).
+
+  ```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") });
+  }
+  ```
+
+- A report in a feature that owns none of its tables (a console's, over
+  several owners) roots at the main owner's `joinSource()` instead of a
+  `scopedQuery()`, and ties the other owners' join sources to it the same way,
+  in one statement, every owner's scope and row policy applied.
+
+  ```js
+  // Knex: report - the caller's projects with no task the caller sees, for a console that owns neither table
+  async function idleProjects(options) {
+    const project = await projects.joinSource({ alias: "p" }, options);
+    const task = await tasks.joinSource({ alias: "k" }, options);
+    return project.query
+      .whereNotExists(task.query.select(task.column("id")).whereColumn(task.column("projectId"), project.column("id")))
+      .select({ name: project.column("name") });
+  }
+  ```
+
+- An app switches a report it kept as a raw-SQL exception (another owner's
+  table joined by name, or a subquery in `raw()`, in a file under an
+  infrastructure exception, see [Exceptions](#exceptions)) to these: the
+  report's feature requires each owner whose rows it reads, puts each owner's
+  join source where the table stood (`whereExists`, `whereNotExists`, or
+  joined grouped for counts and sums), roots at its own table's
+  `scopedQuery()` or at the main owner's `joinSource()`, and the file drops
+  its `readable-check: allow` lines and its `jskit-data-access.json` entry.
+  When an owner is a JSKIT package, its owner API answers `joinSource`
+  ([Tables you don't own](#tables-you-dont-own)).
 - 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 +936,31 @@ 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.
+  `queryAll({ ..., take: 500 })` answers only the first 500 rows in its sort
+  order and reads no row past them, the last page no larger than the rows still
+  wanted. `take` is then the read's bound, so a request may name more than the
+  request row limit and never gets `RESOURCE_ROW_LIMIT`: name the bound the
+  work can hold, never one from the request unchecked.
+- 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 +976,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 +1072,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 +1195,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 +1251,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 +1306,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 +1491,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>