@jskit-ai/agent-docs 0.1.282 → 0.1.284

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

@@ -8,6 +8,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
 [bundled source pattern index](pattern-index.md) is the smallest complete feature to copy.
+Code that reads or writes a table starts from [data access](data-access.md):
+the table resource and its owner feature come first, and this page shapes the
+code around them.
 
 The [typed features heuristic](heuristics/typed-features.md)
 maps keywords and lint findings to the section that fixes them. Client code
@@ -39,11 +42,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.
 
@@ -53,15 +58,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 });
@@ -69,7 +72,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() }]
 ```
 
@@ -88,7 +91,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`.
 
@@ -124,13 +128,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
@@ -268,6 +272,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](data-access.md#layer-4-locks)).
 
 Why: module state is shared by every runtime in the process and outlives
 `shutdown()`.
@@ -277,8 +289,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
@@ -303,14 +315,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?.();
 }
 ```
 
@@ -532,6 +544,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](data-access.md)
+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
@@ -559,8 +609,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.
@@ -573,13 +623,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) {
 ```
@@ -594,8 +644,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,
@@ -661,180 +711,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](data-access.md#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](data-access.md#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](data-access.md#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](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](data-access.md#layer-1-the-table-resource) has the policy's
+shape and [Layer 3](data-access.md#layer-3-many-rows-at-once)
+the batch writes.
 
 ### Routes
 
@@ -864,7 +785,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
@@ -974,7 +895,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;
@@ -1025,72 +946,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](data-access.md#tests) gives the
+one-line test.
 
 ### Test files run in parallel
 
@@ -1127,7 +986,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
@@ -1304,7 +1167,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](data-access.md#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:
@@ -1345,7 +1209,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](data-access.md#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](client-features.md#running-the-checks).
 
@@ -1424,6 +1290,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](client-features.md#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](data-access.md#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/patterns/feature-package/example/variations/customKnexRepository.js

@@ -1,40 +0,0 @@
-import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
-
-/**
- * The invoice rollup's persistence: a reviewed custom Knex repository.
- * @param {{ knex: import("@jskit-ai/database-runtime/server/types").RuntimeKnex }} dependencies
- */
-function createInvoiceRollup({ knex }) {
-  const withTransaction = createWithTransaction(knex);
-
-  async function getStatus(input, options = {}) {
-    return {
-      ok: true,
-      feature: "invoice-rollup",
-      persistence: "custom-knex",
-      tableName: "invoice_rollups",
-      hasTransaction: Boolean(options.trx),
-      input
-    };
-  }
-
-  async function execute(input, options = {}) {
-    return {
-      accepted: false,
-      feature: "invoice-rollup",
-      persistence: "custom-knex",
-      tableName: "invoice_rollups",
-      hasTransaction: Boolean(options.trx),
-      input,
-      message: "Replace this example with the reviewed domain-specific query."
-    };
-  }
-
-  return Object.freeze({
-    withTransaction,
-    getStatus,
-    execute
-  });
-}
-
-export { createInvoiceRollup };

package/reference/autogen/packages/json-rest-api-core.md

@@ -1,66 +0,0 @@
-# packages/json-rest-api-core
-
-Generated by `npm run agent-docs:build`.
-Do not edit manually.
-
-Generated inventory for `packages/json-rest-api-core`.
-Use this on demand; do not load the full index at startup.
-
-## Scope
-- Source: `packages/json-rest-api-core/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `.build/`, `.git/`, `.jscpd/`, `.jskit/`, `coverage/`, `dist/`, `docs/`, `node_modules/`, `test/`, `tests/`, `__tests__/`, `.vitepress/cache/`, `.vitepress/dist/`, `skills/jskit/references/patterns/`, `*.test.*`, `*.spec.*`, `*.vitest.*`
-
-## Sections
-
-### src
-
-### `src/server/jsonRestApiHost.js`
-Exports
-- `addResourceIfMissing(api, scopeName, resourceConfig)`
-- `buildJsonRestQueryParams(resourceType = "", query = {}, { include = undefined } = {})`
-- `createJsonRestResourceScopeOptions(resource = {}, { writeSerializers = {}, normalizeId, rowPolicy, searchSchema, queryFields } = {})`
-- `createJsonRestContext`
-- `extractJsonRestCollectionRows`
-- `queryAllJsonRestCollectionDocument`
-- `queryAllJsonRestCollectionRows`
-- `returnNullWhenJsonRestResourceMissing(run)`
-- `returnBadRequestWhenJsonRestFieldsetInvalid(run)`
-- `resolveWorkspaceScopeValue(context = null)`
-- `resolveUserScopeValue(context = null)`
-- `createJsonRestApiHost({ knex, logger })`
-Local functions
-- `cloneJsonRestResourceValue(value, { writeSerializers = {} } = {})`
-- `normalizeScopeValue(value)`
-- `normalizeJsonRestFilterValue(value)`
-- `normalizeJsonRestList(value)`
-- `resolveJsonRestCollectionRelationships(resource)`
-- `normalizeJsonRestQueryField(fieldName = "", fieldDefinition = {}, projectionDefinition = null)`
-- `isJsonRestVirtualField(fieldDefinition = null)`
-- `applyJsonRestQueryFields(scopeOptions = {}, extraQueryFields = {})`
-- `resolveJsonRestDefaultExcludedFields(resource)`
-- `applyJsonRestDefaultExclusions(scopeOptions = {}, resource = {})`
-- `workspaceScopeOwnerId(visibilityContext)`
-- `isJsonRestResourceMissingError(error = null)`
-- `isJsonRestSparseFieldError(error = null)`
-
-### `src/server/JsonRestApiProvider.js`
-Exports
-- `JsonRestApiProvider`
-
-### `src/server/jsonRestCollectionReads.js`
-Exports
-- `createJsonRestContext(context = null)`
-- `extractJsonRestCollectionRows(payload)`
-- `queryAllJsonRestCollectionDocument(resource, params, context)`
-- `queryAllJsonRestCollectionRows(resource, params, context)`
-Local functions
-- `readEveryJsonRestCollectionPage(resource, { queryParams, ...params }, context, { caller, onPage })`
-
-### `src/server/jsonRestValues.js`
-Exports
-- `isPlainJsonRestObject(value)`
-
-### `src/server/types.js`
-Exports
-- `type RuntimeJsonRestApi`
-- `type JsonRestResource`