@jskit-ai/agent-docs 0.1.283 → 0.1.284

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

@@ -3,10 +3,10 @@
 # Sanity checks
 
 Before calling a list, a save, a test, a refactor, a screen or a deployment
-done, measure what it actually costs and does, judge whether that is sane, and
-fix the cause when it is not. This page is the JSKIT part of that: the
-pitfalls JSKIT's own packages cause, then which JSKIT call, helper or setting
-applies each check, with one line on what the check catches and why.
+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
+packages cause, then the JSKIT call, helper or setting that applies each
+check, with one line on what it catches and why.
 
 ## JSKIT's own pitfalls
 
@@ -66,36 +66,35 @@ expects the relationship id or an unselected field never gets it.
 
 ### Every row
 
-- An unpaged JSON:API query returns the first 20 rows, and a page above the
-  resource's `queryMaxLimit` (100 unless it sets one) is cut to that size,
-  both without an error; CRUD `queryDocuments()` refuses such a `limit`. A
-  read its callers treat as complete uses `queryAllJsonRestCollectionRows()`
-  or the repository's `queryEveryDocument()`, because the missing rows
-  otherwise vanish from every picker and delivery built on it
-  ([Every row](/guide/framework/typed-features#every-row)).
-- A lookup by a unique key matches at most one row, so it may read `rows[0]`
-  of a plain query.
+- 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
+  ([Reads](/guide/framework/data-access#reads-shaped-for-the-screen)).
+- A lookup by a unique key matches at most one row: `get(id)`, or a `query()`
+  of page size 1.
 
 ### Query counts and batches
 
-- Count a path's queries with `countQueries()` from
-  `@jskit-ai/database-runtime/server/testDatabases` at a few rows and at a
+- 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
-  ([Query counts at realistic
-  sizes](/guide/framework/typed-features#query-counts-at-realistic-sizes)).
+  ([Tests](/guide/framework/data-access#tests)).
 - A JSON:API read adds a few lookup and visibility queries per page and per
-  relationship field. That follows pages, so it is expected.
-- `getDocumentById()`, `queryDocuments()` or a service `get` inside a loop is
-  the usual per-row read; batch it with an id-list `searchSchema` filter or
-  `include`, grouped with `Map.groupBy()` ([Lists read related rows in
-  batches](/guide/framework/typed-features#lists-read-related-rows-in-batches)).
+  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.
+- 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()`
+  ([Reads](/guide/framework/data-access#reads-shaped-for-the-screen)).
 - A `rowPolicy` adds one correlated predicate to the query it is given, so
   its cost follows the rows read, not the subject's history. It runs on every
-  single-record read, including a write's default `returning: "full"` read
-  back, so a write that discards its result passes `returning: "minimal"` and
-  a batch of creates uses `createDocuments()`, in the owner's transaction
-  ([Bounded access
-  checks](/guide/framework/typed-features#bounded-access-checks)).
+  single-record read, including a write's default `returning: "record"` read
+  back, so a write that discards its result passes `returning: "id"` or
+  `"none"`, and a batch uses the many-row writes (`createMany()`,
+  `patchMany()`) ([Layer 1](/guide/framework/data-access#layer-1-the-table-resource)).
 
 ### Tests
 

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

@@ -13,6 +13,9 @@ what to do, why in one line, and shows good and bad code. `npm run lint`
 reports the rules a machine can see ([checks](#checks)); the others are
 checked by reading. The `server/feature-package` pattern in the
 [source pattern library](/patterns/) is the smallest complete feature to copy.
+Code that reads or writes a table starts from [data access](/guide/framework/data-access):
+the table resource and its owner feature come first, and this page shapes the
+code around them.
 
 The [typed features heuristic](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/heuristics/typed-features.md)
 maps keywords and lint findings to the section that fixes them. Client code
@@ -44,11 +47,13 @@ it reports the call as exact instead of guessing from the method name.
 ### Feature files
 
 **A `defineFeature` lives in `<Name>Feature.js`, its keys in one order, one
-per line: `id, domain, requires, optional, provides, setup, actions, boot,
-shutdown`.** A `defineProvider` lives in `<Name>Provider.js`.
+per line: `id, domain, owns, systemScope, requires, optional, provides,
+setup, actions, boot, shutdown`.** A `defineProvider` lives in `<Name>Provider.js`.
 
 - `setup` builds each provided value with a named `create<Name>` factory from
-  a module of its own, never inline.
+  a module of its own, never inline. It returns exactly the keys `provides`
+  names, or boot refuses it; a value only `actions` needs is built in
+  `actions`, which receives the requires.
 - `actions` is a method that returns `create<Name>Actions({ … })`.
 - The hooks take `capabilities`, destructured and typed.
 
@@ -58,15 +63,13 @@ Why: every feature reads the same way, top to bottom.
 // good
 const InvoicesFeature = defineFeature({
   id: "feature.invoices",
-  requires: {
-    database: "runtime.database"
-  },
+  owns: [invoiceResource],
   provides: {
     invoices: "feature.invoices"
   },
-  /** @param {{ database: import("@jskit-ai/database-runtime/server/types").RuntimeDatabase }} capabilities */
-  setup({ database }) {
-    return { invoices: createInvoices({ knex: database.knex }) };
+  /** @param {{ resources: { invoices: import("@jskit-ai/resource-runtime/server/types").ResourceHandle } }} capabilities */
+  setup({ resources }) {
+    return { invoices: createInvoices({ invoices: resources.invoices }) };
   },
   actions({ invoices }) {
     return createInvoiceActions({ invoices });
@@ -74,7 +77,7 @@ const InvoicesFeature = defineFeature({
 });
 
 // bad: the value built inline, the actions an inline array
-setup: ({ database }) => ({ invoices: { list: () => database.knex("invoices") } }),
+setup: ({ resources }) => ({ invoices: { list: (options) => resources.invoices.queryAll({}, options) } }),
 actions: ({ invoices }) => [{ id: "invoices.list", execute: () => invoices.list() }]
 ```
 
@@ -93,7 +96,8 @@ there.**
 - Hand-write a contract only for a token with several implementations (such as
   `auth.service`), in its owning package, with optional operations marked
   optional.
-- JSKIT's names: `RuntimeKnex`, `RuntimeKnexTransaction`,
+- JSKIT's names: `ResourceHandle`, `ResourceCallOptions`, `SystemContext`
+  (`@jskit-ai/resource-runtime/server/types`), `RuntimeKnex`,
   `RuntimeKnexQueryBuilder`, `RuntimeRouter`, `RuntimeLogger`, `RuntimeEnv`,
   `CrudService`, `CrudRepository`.
 
@@ -129,13 +133,13 @@ Why: the type is what turns a call into one step.
 // good
 /**
  * The invoices the feature provides.
- * @param {{ knex: import("@jskit-ai/database-runtime/server/types").RuntimeKnex }} dependencies
+ * @param {{ invoices: import("@jskit-ai/resource-runtime/server/types").ResourceHandle }} dependencies
  */
-function createInvoices({ knex }) {
+function createInvoices({ invoices }) {
 
 // bad: untyped, read from a bag in the body
 function createInvoices(dependencies) {
-  const knex = dependencies.knex;
+  const invoices = dependencies.invoices;
 ```
 
 ### Required collaborators
@@ -273,6 +277,14 @@ filled after construction.**
   saying so.
 - No late-bound closures between two tokens of one feature: the consumer
   requires the other token.
+- `boot()` and `shutdown()` receive what the feature requires, as `setup()`
+  does, and its own setup's values second, as `outputs`:
+  `boot(capabilities, { outputs })`.
+- A periodic job is such a capability; JSKIT ships no scheduler. `setup()`
+  builds the job, `boot()` starts its timer (`setInterval(runOnce,
+  everyMs).unref()`), `shutdown()` clears it and awaits a run in progress, and
+  tests call `runOnce()` itself. Every server runs the timer, so a run takes
+  its rows with `claim()` ([data access, Layer 4](/guide/framework/data-access#layer-4-locks)).
 
 Why: module state is shared by every runtime in the process and outlives
 `shutdown()`.
@@ -282,8 +294,8 @@ Why: module state is shared by every runtime in the process and outlives
 setup() {
   return { jobs: createJobQueue() };
 },
-boot({ jobs }) {
-  jobs.start();
+boot(_capabilities, { outputs }) {
+  outputs.jobs.start();
 },
 
 // bad
@@ -308,14 +320,14 @@ setup({ events }) {
   if (!config.remindersEnabled) return {};
   return { reminders: createReminders({ events }) };
 },
-shutdown({ reminders }) {
+shutdown(_capabilities, { outputs }) {
   if (!config.remindersEnabled) return;
-  return reminders.stop();
+  return outputs.reminders.stop();
 }
 
 // bad
-shutdown({ reminders }) {
-  return reminders?.stop?.();
+shutdown(_capabilities, { outputs }) {
+  return outputs.reminders?.stop?.();
 }
 ```
 
@@ -537,6 +549,44 @@ const actorId = context?.actor?.id || options.context?.user?.id || null;
 
 ## Services and repositories
 
+### Resource first
+
+**Every table has one table resource, and only its owner feature reads or
+writes it, through the handle it lists in `owns`. A repository holds the
+owner's queries on its handles (a plain CRUD feature's repository is the
+handle itself); a service calls repositories and other features' services or
+capabilities, and never builds a query or reaches another feature's table.** [Data access](/guide/framework/data-access)
+gives the five layers, from one record to reports.
+
+Why: ownership, the row policy, validation and audits run only on the
+resource's path; Knex in a repository skips all of them.
+
+```js
+// good
+
+/**
+ * The owner's repository, on its handle.
+ * @param {{ receivals: import("@jskit-ai/resource-runtime/server/types").ResourceHandle }} handles
+ */
+function createReceivalsRepository({ receivals }) {
+  /**
+   * @param {string} id
+   * @param {string} arrivedAt
+   * @param {import("@jskit-ai/resource-runtime/server/types").ResourceCallOptions} options
+   */
+  function markArrived(id, arrivedAt, options) {
+    return receivals.patch(id, { status: "arrived", arrivedAt }, options);
+  }
+
+  return Object.freeze({ markArrived });
+}
+
+// bad
+function markArrived(id, arrivedAt) {
+  return knex("receivals").where({ id }).update({ status: "arrived", arrived_at: arrivedAt });
+}
+```
+
 ### Validated input as is
 
 **A method that receives an action's validated input takes it as it is: no
@@ -564,8 +614,8 @@ async function rename(input = {}, options = {}) {
 it, destructure and use.**
 
 - An options bag whose fields are optional by contract keeps `options = {}`,
-  with no `?.` or second `|| {}` on it. Pass it on as `options`, or
-  `{ ...options, trx }` inside a transaction.
+  with no `?.` or second `|| {}` on it. Pass it on as `options`, or as the
+  `txOptions` that `withTransaction` hands its work inside a transaction.
 - A parameter or bag no caller passes is dropped and its values written in
   place. A helper's argument takes no default unless a real caller omits it,
   and a default never comes before a required parameter.
@@ -578,13 +628,13 @@ second method inside the first.
 
 ```js
 // good
-async function list(query, options = {}) {
-  return resolveRepoClient(knex, options)("invoices").where(query);
+async function list(filters, options = {}) {
+  return invoices.queryAll({ filters }, options);
 }
 
 // bad
-async function list(query = {}, options = {}) {
-  const client = options?.trx || knex;
+async function list(filters = {}, options = {}) {
+  const context = options?.context || null;
 }
 async function save(invoice, skipAudit = false) {
 ```
@@ -599,8 +649,8 @@ map shows.
 
 ```js
 // good
-function createInvoices({ knex }) {
-  async function list(query) { … }
+function createInvoices({ invoices }) {
+  async function list(filters, options) { … }
   async function send(input, options) { … }
   return Object.freeze({
     list,
@@ -666,180 +716,51 @@ helper, never by hand.**
 
 | Fact | Reader |
 | --- | --- |
-| the call's transaction, or the client to query through | `resolveTransaction(options)`, `resolveRepoClient(knex, options)` (`@jskit-ai/database-runtime/shared`) |
-| what a service hands its repository | `repositoryCallOptions(options)` (`@jskit-ai/crud-core/server/jsonApiService`), only at the repository call |
 | the signed-in user | `resolveActor(context)`, `resolveActorId(context)` |
 | a tagged result's records, or its document | `simplifyJsonApiResult(result)`, `jsonApiResultValue(result)` (`@jskit-ai/http-runtime/shared`) |
 | a collection's next-page cursor | `jsonApiNextCursor(document)` (`@jskit-ai/http-runtime/shared`) |
 | a created record's id | `resolveCrudJsonApiEntityIdFromResult(result)` (`@jskit-ai/crud-core/server/serviceEvents`) |
 | a CRUD record change's event | `buildCrudRecordChangedEvent({ namespace, operation, entityId, audience })` (`@jskit-ai/crud-core/server/serviceEvents`) |
 | the workspace a request asks for, before any action context | `requestedWorkspaceScope(request)` (`@jskit-ai/workspaces-core/server/support/workspaceRouteInput`) |
-| a context's workspace id | `resolveWorkspaceScopeValue(context)` (`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`) |
+| a context's workspace id | `resolveWorkspaceScopeValue(context)` (`@jskit-ai/resource-runtime/server`) |
 
-Why: each reader knows every place JSKIT keeps its fact (`trx` or
-`transaction`, a tagged result's wrapper), and a hand read misses one.
+A call's transaction is not a fact to read: pass `options` on, and inside a
+transaction the `txOptions` that `withTransaction` hands its work
+([Transactions](/guide/framework/data-access#transactions)).
+
+Why: each reader knows every place JSKIT keeps its fact (a tagged result's
+wrapper, the actor in a context), and a hand read misses one.
 
 ```js
 // good
-const trx = resolveTransaction(options);
+const actorId = resolveActorId(context);
 
 // bad
-const trx = options?.trx || options?.transaction || null;
+const actorId = context?.actor?.id || context?.auth?.userId || null;
 ```
 
 ### Every row
 
-**A server-side resource query that needs every row it matches reads them
-with `queryAllJsonRestCollectionRows(resource, params, context)`
-(`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`). A query without a
-page means "the first 20 rows".**
-
-- json-rest-api answers a query that names no page with the resource's
-  default page, 20 rows, and says nothing about the rest. The CRUD
-  repository's `queryDocuments(query)` without a `limit` is the same first
-  page, and one with a `limit` above its `queryMaxLimit()` (100) throws,
-  because json-rest-api would answer only 100. A CRUD read of every record
-  uses the repository's `queryEveryDocument(query, options)`, which answers
-  one JSON:API document `{ data, included }` with no `limit`, `cursor` or
-  `sort`.
-- The helper reads cursor pages of 1,000 rows (json-rest-api's server-only
-  `pageSizeLimit`; a resource whose `queryMaxLimit` is larger uses that) in id
-  order until none follows, keeping the call's transaction and context, so no
-  row is skipped or repeated. Each page pays the row policy and linkage
-  queries once, so 480 rows cost 3 statements, not 15. It sets the page and
-  sort itself; sort the rows it returns.
-- A lookup by a unique key (an id, a slug, a token hash, a unique pair such
-  as workspace and user) matches at most one row and may read `rows[0]` of a
-  plain query. A read of the newest or first few rows names its own `sort`
-  and `page`.
-- HTTP list routes keep the caller's page: their default and maximum page
-  sizes are public behaviour, not a server-side limit to raise.
-
-Why: a list read without a page looks complete until the 21st row, then
-silently drops the rest from every person picker, scope and delivery built on it.
-
-```js
-// good
-const rows = await queryAllJsonRestCollectionRows(api.resources.workspaceMemberships, {
-  queryParams: { filters: { workspace: workspaceId, status: "active" }, include: ["user"] },
-  transaction: resolveTransaction(options),
-  format: "plain"
-}, options.context);
-
-// bad: the first 20 members only
-const rows = extractJsonRestCollectionRows(await api.resources.workspaceMemberships.query({
-  queryParams: { filters: { workspace: workspaceId, status: "active" }, include: ["user"] },
-  transaction: resolveTransaction(options),
-  format: "plain"
-}, createJsonRestContext(options.context)));
-```
+**A server-side read that needs every row it matches reads them with the
+handle's `queryAll(params, options)`. A `query()` names its page size, and
+answers one page.** [Reads shaped for the screen](/guide/framework/data-access#reads-shaped-for-the-screen)
+gives the rules and examples.
 
 ### Lists read related rows in batches
 
 **A read that builds a list fetches its related rows in batches, an id-list
 query per related table, and groups them in memory, so its query count follows
-the tables and pages it reads, not the rows.**
-
-- Collect the ids from the first read, then read each related table with an
-  id-list filter: a `searchSchema` entry
-  `{ type: "array", actualField: "<column>", filterOperator: "in" }`, read
-  through `queryAllJsonRestCollectionRows()`, or the resource's `include`.
-  Group the rows by id with `Map.groupBy()`.
-- A count that grows with the rows means something runs per row:
-  `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
-  single-record read inside a loop over the list, however the loop is spelled
-  (`for`, `map` with `Promise.all`, a helper called per item), or a
-  single-record helper reused for a list.
-- Work derived from a row (hashing, preparing a form, assembling a snapshot)
-  runs once per distinct input in the call, not once per row it appears in.
-- A JSON:API read also costs a few lookup and visibility queries per page and
-  relationship field, and pages hold the resource's `queryMaxLimit` (100 rows
-  unless it sets one). That cost follows pages, so three hundred invoices take
-  a few more queries than ten, not three hundred more ([Query counts at
-  realistic sizes](#query-counts-at-realistic-sizes)).
-
-Why: each JSKIT single-record read runs its lookups and row policy too, so a
-read per row repeats all of them.
-
-```js
-// good: a read per related table, however many invoices there are
-const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
-  queryParams: { filters: { workspace: workspaceId } },
-  transaction: resolveTransaction(options),
-  format: "plain"
-}, options.context);
-const lineRows = await queryAllJsonRestCollectionRows(api.resources.invoiceLines, {
-  queryParams: { filters: { invoiceIds: invoiceRows.map((invoice) => invoice.id) } },
-  transaction: resolveTransaction(options),
-  format: "plain"
-}, options.context);
-const linesByInvoice = Map.groupBy(lineRows, (line) => line.invoiceId);
-return invoiceRows.map((invoice) => ({ ...invoice, lines: linesByInvoice.get(invoice.id) || [] }));
-
-// bad: one more query, and its lookups and row policy, for every invoice
-for (const invoice of invoiceRows) {
-  invoice.lines = await invoiceLines.queryDocuments({ invoiceId: invoice.id }, options);
-}
-```
+the tables and pages it reads, not the rows.** [Reads shaped for the
+screen](/guide/framework/data-access#reads-shaped-for-the-screen) shows how.
 
 ### Bounded access checks
 
 **A row policy costs what the rows its query reads cost, never what the
 subject's stored history costs, and a write decides access once instead of
-paying a read policy for every row it writes.**
-
-- A `rowPolicy` adds one predicate to the query it is given: a join, `EXISTS`
-  or subquery correlated with the row being read, on indexed columns. It never
-  loads everything the subject was ever linked to (every source, notice or
-  grant in their history) to build an `IN` list, and never calls another
-  owner's access check once per item of that history. The
-  [row policies heuristic](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/heuristics/row-policies.md)
-  has the policy contract and its package composition.
-- The policy runs on every single-record read, and a CRUD write includes one:
-  `createDocument()` and `patchDocumentById()` default to `returning: "full"`,
-  which reads the record back through the policy, and `patch` and `delete`
-  first look the record up through it.
-- A write path decides access once, inside its transaction. A write that does
-  not use its result passes `returning: "minimal"` or `"none"`, and a batch of
-  creates (a delivery, an import, a fan-out) goes through
-  `createDocuments(payloads, { trx, context })`, which reads nothing back
-  unless asked
-  ([writes that return less](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#writes-that-return-less)).
-  Any other batch whose per-row lookup would pay an expensive policy writes
-  through a repository method added with `decorateRepository`, on
-  `resolveRepoClient(database.knex, options)`, setting the same columns the
-  resource would, its ownership columns included.
-- Its test counts the queries of one read and one write for a subject with a
-  short history and for one with a long one ([Query counts at realistic
-  sizes](#query-counts-at-realistic-sizes)).
-
-Why: the row policy runs on every read, write read-back and lookup, so every
-request pays what it costs.
-
-```js
-// good: one predicate on the row being read
-function noticeVisibilityPolicy({ query, context, column, value, db }) {
-  const userId = resolveActorId(context);
-  if (!userId) return false;
-  query.where(column("recipientId"), value("recipientId", userId)).whereExists(
-    db("sources").select(1)
-      .whereColumn("sources.id", column("sourceId"))
-      .where("sources.status", "published")
-  );
-  return true;
-}
-
-// bad: every source the recipient was ever notified about, checked one by one
-async function noticeVisibilityPolicy({ query, context, column, value }) {
-  const sourceIds = await noticeHistory.listSourceIds(resolveActorId(context));
-  const readable = [];
-  for (const sourceId of sourceIds) {
-    if (await sources.canRead(sourceId, context)) readable.push(sourceId);
-  }
-  query.whereIn(column("sourceId"), readable.map((id) => value("sourceId", id)));
-  return true;
-}
-```
+paying a read policy for every row it writes.** [Layer
+1](/guide/framework/data-access#layer-1-the-table-resource) has the policy's
+shape and [Layer 3](/guide/framework/data-access#layer-3-many-rows-at-once)
+the batch writes.
 
 ### Routes
 
@@ -869,7 +790,7 @@ router.register("POST", "/api/invoices/:invoiceId/send", { auth: "required", met
   });
 
 // bad: the route reads storage itself
-router.register("GET", "/api/invoices", {}, async (request, reply) => reply.send(await knex("invoices")));
+router.register("GET", "/api/invoices", {}, async (request, reply) => reply.send(await invoices.queryAll({}, { context: request })));
 ```
 
 ## Errors
@@ -979,7 +900,7 @@ change with its package.
 
 ```js
 // good
-const invoices = createInvoices({ knex, mailer: { send: async () => ({ accepted: true }) } });
+const invoices = createInvoices({ invoices: resources.invoices, mailer: { send: async () => ({ accepted: true }) } });
 
 // bad: production code that exists for the double
 if (typeof mailer.send !== "function") return;
@@ -1030,72 +951,10 @@ export function resetInvoiceCacheForTests() {
 
 ### Query counts at realistic sizes
 
-**A list, batch or write path's database test counts its queries with
-`countQueries()` at a few rows and at a realistic number, and fails when the
-count grows with the rows instead of the pages.**
-
-- `countQueries(knex, work)`, from
-  `@jskit-ai/database-runtime/server/testDatabases`, runs `work` and returns
-  its `result`, the `count` of statements the Knex instance or transaction
-  sent meanwhile (a transaction's `BEGIN` and `COMMIT` included) and their
-  SQL in `queries`. Pass the Knex the path runs on: the one the test built its
-  repository or service with.
-- A route is counted through the server the test boots in its own process
-  (`createServer()`, then `app.inject()`): `countRuntimeQueries(work)`, from
-  the same module, records what the app's own `runtime.database` sends while
-  `work` runs, and leaves out the test's own Knex. A server in another process
-  is out of its reach, so the route's guard boots it in the test.
-- Pages add a few queries; rows should add none. A path that pages nothing
-  (one read, one write) compares a short and a long history.
-- When the counts differ more than the pages explain, read `queries`: the
-  statement that repeats once per row is the one to batch. Judge the
-  comparison by what the path has to read; never tune a fixed ceiling until
-  it passes.
-- When it fails, fix the reads ([Lists read related rows in
-  batches](#lists-read-related-rows-in-batches), [Bounded access
-  checks](#bounded-access-checks)).
-
-Why: JSON:API reads add queries per page and relationship field, so comparing
-two sizes separates that cost from a read per row, where one fixed number
-cannot.
-
-```js
-// good
-import { countQueries, countRuntimeQueries } from "@jskit-ai/database-runtime/server/testDatabases";
-
-test("the invoice list's queries follow its pages, not its invoices", async () => {
-  const listAt = async (count) => {
-    const workspace = await createWorkspace(knex);
-    await seedInvoices(knex, { workspace, count, linesEach: 5 });
-    return countQueries(knex, () => invoices.listWithLines(workspace, { context }));
-  };
-  const few = await listAt(10);
-  const many = await listAt(300);
-  // Thirty times the invoices may add pages; a read per invoice would add about 290 queries.
-  assert.ok(many.count <= few.count * 2,
-    `${few.count} queries for 10 invoices, ${many.count} for 300:\n${many.queries.join("\n")}`);
-});
-
-// good: the same comparison for the route, through the server this test booted
-test("GET /api/invoices reads per page, not per invoice", async () => {
-  const app = await createServer({ runtimeEnv });
-  const listAt = async (count) => {
-    const workspace = await createWorkspace(knex);
-    await seedInvoices(knex, { workspace, count, linesEach: 5 });
-    return countRuntimeQueries(() => app.inject({ url: invoicesUrl(workspace), headers: signedIn }));
-  };
-  const few = await listAt(10);
-  const many = await listAt(300);
-  assert.ok(many.count <= few.count * 2,
-    `${few.count} queries for 10 invoices, ${many.count} for 300:\n${many.queries.join("\n")}`);
-});
-
-// bad: three invoices, nothing counted, so a read per invoice passes
-test("the invoice list has its lines", async () => {
-  await seedInvoices(knex, { workspace, count: 3, linesEach: 1 });
-  assert.equal((await invoices.listWithLines(workspace, { context })).length, 3);
-});
-```
+**A list, batch or write path's database test proves with
+`expectFlatQueries()` that its statements follow the tables and pages it
+reads, not the rows.** [Tests](/guide/framework/data-access#tests) gives the
+one-line test.
 
 ### Test files run in parallel
 
@@ -1132,7 +991,11 @@ and Vitest's `maxWorkers` come from `testConcurrency()`.**
   spec file's tests run in order in one worker. With `PLAYWRIGHT_BASE_URL`, the
   tests use that managed target as its host serves it. Every run is bounded by
   a `globalTimeout` (20 minutes, or the suite's own measured bound) and ends
-  with its 10 slowest tests. With a `signIn` module, each worker's server is
+  with its 10 slowest tests. Each action and navigation is bounded too
+  (`actionTimeout` 15 s, `navigationTimeout` 30 s): a stale locator should
+  fail in seconds, not minutes, so a test waiting on something that never
+  comes fails with that action's own error. An app sets a longer bound only
+  for a measured need, never 0. With a `signIn` module, each worker's server is
   signed in once and every test of that worker starts signed in, instead of
   each test signing in. `jskit check` fails a webServer that runs the development server
   (`npm run develop`, `vite`), one webServer shared by every worker, and a
@@ -1309,7 +1172,8 @@ Why: a comment that narrates history is wrong the day after it is written.
 ### Running the checks
 
 `npm run lint` runs ESLint with `@jskit-ai/config-eslint`, and `npm run
-verify` runs `jskit check` (the package graph, navigation and [test
+verify` runs `jskit check` (the package graph, navigation, [data
+access](/guide/framework/data-access#exceptions) and [test
 runs](#test-run-rules)), lint, the tests and the build. The foundations'
 `eslint.config.mjs` already holds a new
 application's code to every check:
@@ -1350,7 +1214,9 @@ export default [
 - `formatterConfig(globs)` is the formatter.
 - `baseConfig` reports the `jskit/*` rules as warnings on any
   `**/src/server/**`, so an existing application sees them before it lists a
-  package; it lists each package as it converts it.
+  package; it lists each package as it converts it. It makes the
+  [data-access rules](/guide/framework/data-access#hard-rules) errors in all
+  code but the client's, tests, migrations and seeds.
 - `clientFeaturesConfig(globs)` holds client code to the same rules; see
   [client features](/guide/framework/client-features#running-the-checks).
 
@@ -1429,6 +1295,7 @@ if (typeof buildSerializer !== "function") {
 | `filled by <repository>; convert with its supplier` | keeps a setter that another repository's code calls |
 | `cross-repository slot <token>` | keeps a probe for a token another repository supplies |
 | `shared resource:` | keeps client module state that every instance on the page shares on purpose ([client features](/guide/framework/client-features#module-state)) |
+| `infrastructure: <what the module is>` | excuses a whole file whose job is data access itself from `jskit/no-direct-knex` or `jskit/no-transaction-reader`, one line per rule before its first line of code ([data access](/guide/framework/data-access#exceptions)) |
 
 One kind of probe gets one prefix and one wording everywhere, and a bare
 `typeof x` guard of that kind carries the same comment even where no rule

package/guide/agent/index.md

@@ -25,6 +25,8 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
 ## Framework reference
 
 - [Application operations](/guide/framework/application-operations)
+- [Data access](/guide/framework/data-access): read before any code that reads
+  or writes a database table
 - [CRUD operations](/guide/framework/crud-operations)
 - [Record form actions](/guide/framework/crud-form-actions)
 - [Typed features](/guide/framework/typed-features): read before writing any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.283",
+  "version": "0.1.284",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [
@@ -10,7 +10,7 @@
     "skills"
   ],
   "scripts": {
-    "test": "jskit test test/*.test.js"
+    "test": "jskit test test/*.test.js patterns/minimal-foundation/example/tests/server/*.test.js patterns/shell-foundation/example/tests/server/*.test.js"
   },
   "engines": {
     "node": "^22.13.0 || ^24.0.0 || ^26.0.0"
@@ -22,5 +22,8 @@
     "jskit",
     "agent",
     "docs"
-  ]
+  ],
+  "devDependencies": {
+    "@fastify/static": "^10.1.3"
+  }
 }