@jskit-ai/agent-docs 0.1.290 → 0.1.292

package/reference/autogen/packages/workspaces-core.md

@@ -39,8 +39,6 @@ Exports
 - `createRepository({ workspaceInvites, workspaces })`
 - `normalizeInviteRecord(payload)`
 - `normalizeInviteWithWorkspace(payload = {})`
-Local functions
-- `normalizeInvitePatchPayload(payload = {})`
 
 ### `src/server/common/repositories/workspaceMembershipsRepository.js`
 Exports

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

@@ -66,6 +66,19 @@ Local functions
 - `buildCatalog({ repoRoot, packagesRoot, outputPath })`
 - `main()`
 
+### `scripts/data-access-files.mjs`
+Exports
+- `ROOT`
+- `lintIgnores({ governed, config })`
+- `sourceFiles(root)`
+Local functions
+- `skipsDirectory(name)`
+- `walk(root, directory, files)`
+- `frameworkPackages(root)`
+- `appEslint(root)`
+- `lintConfigs(root, files)`
+- `skippedPaths(files, skipped)`
+
 ### `scripts/data-access.mjs`
 Exports
 - `checkDataAccess({ projectRoot = process.cwd() } = {})`
@@ -73,7 +86,6 @@ Exports
 - `readTableResourceSources({ projectRoot = process.cwd() } = {})`
 Local functions
 - `escapeRegExp(text)`
-- `skipsDirectory(name)`
 - `blank(text)`
 - `maskStrings(code)`
 - `closingOffset(masked, start)`
@@ -98,16 +110,12 @@ Local functions
 - `readLintDisables(file, source, position)`
 - `readRuntimeCapabilities(file, { code, masked, position })`
 - `isError(setting)`
-- `appEslint(root)`
-- `checkLintConfig(root, files, baseline, report)`
+- `checkLintConfig({ configs, error }, baseline, report)`
 - `checkCapabilities(baseline, uses, report)`
 - `readBaseline(root, report)`
 - `checkBaseline(baseline, excuses, scopes, report)`
-- `walk(root, directory, files)`
-- `frameworkPackages(root)`
 - `checkTables(resources, report)`
 - `checkSystemScopes(scopes, report)`
-- `sourceFiles(root)`
 
 ### `scripts/files.mjs`
 Exports
@@ -188,9 +196,8 @@ Local functions
 ### `scripts/material3.mjs`
 Exports
 - `MATERIAL3_RULES`
-- `checkMaterial3({ projectRoot = process.cwd(), paths = [], navigationOnly = false } = {})`
+- `checkMaterial3({ projectRoot = process.cwd(), paths = [] } = {})`
 - `formatMaterial3Report(result)`
-- `formatNavigationReport(result)`
 Local functions
 - `hexPattern()`
 - `channelColour()`
@@ -201,8 +208,8 @@ Local functions
 - `isFrameworkPackage(projectRoot, directory)`
 - `walk(projectRoot, directory, files, wholeApp = false)`
 - `collectFiles(projectRoot, paths)`
-- `createReporter(file, source, { navigationOnly = false } = {})`
-- `checkCode(code, offset, { report, themed })`
+- `createReporter(file, source)`
+- `checkCode(code, offset, context)`
 - `checkScript(code, offset, context)`
 - `checkCss(css, offset, context)`
 - `checkDeclaration(declaration, context)`
@@ -386,10 +393,23 @@ Local functions
 - `seconds(ms)`
 - `readTestTimeBounds(cwd)`
 
+### `scripts/ui-components.mjs`
+Exports
+- `checkRemovedProps(tags, script, removedProps, report)`
+- `checkVuetifyByNameAttribute(tag, entry, context)`
+- `checkVuetifyByNameCode(code, offset, context)`
+- `readRemovedProps(root)`
+- `readVuetifyComponents(root)`
+Local functions
+- `readExportNames(file, names = new Set(), seen = new Set())`
+- `readComponentImports(script)`
+- `reportByName({ report, vuetifyComponents }, offset, name, how)`
+
 ### `scripts/verify-packages.mjs`
 Exports
 - `main()`
 - `validateApiSummarySurfaces(packageJson)`
+- `validateRemovedProps(packageJson)`
 - `validateCapabilityClosure(packages, { builtinCapabilities = BUILTIN_CAPABILITIES } = {})`
 - `validateMigrations(packageRecord, migrationOwners)`
 - `validateProviderExport(value, label)`

package/skills/jskit/references/data-access.md

@@ -29,9 +29,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` |
@@ -55,6 +56,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 |
@@ -152,6 +161,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
@@ -197,7 +244,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.
@@ -313,7 +427,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
@@ -487,8 +605,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
@@ -501,8 +621,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
@@ -559,6 +680,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
@@ -671,8 +831,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
@@ -702,6 +864,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.
@@ -721,11 +931,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
@@ -741,6 +971,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);
 ```
@@ -832,14 +1067,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) });
     }
@@ -948,7 +1190,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
@@ -1001,6 +1246,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](typed-features.md#optional-tokens)).
+
 ## Check and judge
 
 Before calling data work done, apply the
@@ -1024,7 +1301,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
@@ -1205,5 +1486,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/skills/jskit/references/existing-application-migration.md

@@ -208,7 +208,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/skills/jskit/references/heuristics/ui-testing.md

@@ -11,7 +11,9 @@ Use when:
 
 Rules:
 
-- Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior before the chunk is done.
+- Any chunk that adds or changes user-facing UI proves the changed behavior with an automated test before the chunk is done, at the cheapest level that can: a component's content, states and conditional display in a client component test (Vitest); only what needs a real browser (navigation, a flow across screens, layout at the standard widths, focus, the real sign-in) in Playwright.
+- Put a new browser check in the existing spec that already reaches that screen with the data it needs. Add a new spec only for a new flow, using the app's shared server, sign-in and fixture setup. A browser test that pays its own server start, sign-in or seeding to check one card, label or state is not acceptable: every run pays for it for as long as it exists. Move that check to a component test or an existing spec, and report the spec's time and the suite's time before and after.
+- Never wait out the app's own delays (request retries, debounce, polling) in real time, and never change the scenario to skip them: install Playwright's `page.clock` before the page loads and advance it with `page.clock.runFor(...)`, or use Vitest's fake timers in a component test. Change the scenario only when another test already proves the skipped path.
 - Pattern and framework UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
 - Check horizontal overflow, clipped or invisible text, duplicate navigation, and broken route placement at every standard viewport. On compact screens, also check screen tap targets under 48 px; medium and expanded layouts may use their documented denser controls.
 - Apps with `shell-web` installed should start from `tests/e2e/adaptive-shell.spec.ts` and extend it with feature-specific assertions.
@@ -186,7 +188,8 @@ browser check with a full lint, build, or test sweep; follow its verification po
 
 Do not mark the chunk done if:
 
-- the feature changed user-facing UI but no Playwright flow ran
-- the Playwright flow skipped the changed behavior itself
+- the feature changed user-facing UI but no test at the right level proves it
+- the test skipped the changed behavior itself
+- a new browser test pays its own setup to check what a component test or an existing spec could
 - a managed environment was bypassed by installing another browser
 - an authenticated flow was left untested without clearly reporting the missing session-bootstrap seam