@jskit-ai/agent-docs 0.1.284 → 0.1.285

package/guide/agent/app-setup/authentication.md

@@ -244,14 +244,26 @@ error.
 | Capability | Methods |
 | --- | --- |
 | `auth.local.accounts` | `create(account, options)`, `findById(userId, options)`, `findByEmail(email, options)`, `updatePassword(userId, passwordRecord, options)`, `updateProfile(userId, { displayName }, options)`, `markEmailVerified(userId, options)` |
-| `auth.local.sessions` | `create(session, options)`, `update(sessionId, { purpose, expiresAt }, options)`, `revoke(sessionId, options)`, `revokeForUser(userId, { ...options, exceptSessionId })`, `deleteExpired(now, options)` |
-| `auth.local.recovery` | `create(token, options)`, `findByTokenHash(tokenHash, options)`, `consume(tokenId, options)`, `consumeForUser(userId, options)` |
+| `auth.local.sessions` | `create(session, options)`, `update(sessionId, { purpose, expiresAt }, { ...options, onlyIf })`, `revoke(sessionId, options)`, `revokeForUser(userId, { ...options, exceptSessionId })`, `deleteExpired(now, options)` |
+| `auth.local.recovery` | `create(token, options)`, `findByTokenHash(tokenHash, options)`, `consume(tokenId, options)`, `consumeForUser(userId, { ...options, idPrefix })` |
 
 `markEmailVerified` records that the account proved it owns its email address,
 for example by using an emailed link, in the `email_verified_at` column (run
 `npm run db:migrate`); the first proof is kept, and the account answers it as
 `emailVerifiedAt` (empty until then). `deleteExpired` deletes the sessions that
-expired by `now` and answers how many. Their types are `AuthLocalAccounts`,
+expired by `now` and answers how many.
+
+A recovery token's kind is the start of its id: local sign-in's password resets
+are `rec_…`, and an app's own kind (a sign-in link, say) takes a prefix of its
+own, such as `magic_…`. `consumeForUser` consumes the user's open tokens of the
+kind `idPrefix` names and no others, so a new sign-in link leaves an open
+password reset usable, and a completed reset leaves sign-in links open.
+`update` with `onlyIf` (`userId`, `purpose`, `revokedAt`) changes the session
+only while it still has those values, compared in the UPDATE itself, and
+answers null, writing nothing, when it does not: promote a sign-in link's
+session with
+`update(sessionId, { purpose: "normal", expiresAt }, { ...options, onlyIf: { userId, purpose: "recovery", revokedAt: null } })`
+and treat null as a refused link. Their types are `AuthLocalAccounts`,
 `AuthLocalSessions` and `AuthLocalRecovery` in
 `@jskit-ai/auth-provider-local-db-core/server/types`.
 

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

@@ -272,6 +272,35 @@ one table at a time:
 Keep each move behaviour-preserving
 ([refactors](/guide/framework/sanity-checks#refactors)).
 
+A table keyed by several columns, or by its owner's id, gets an integer `id`
+first ([Layer 1](/guide/framework/data-access#layer-1-the-table-resource)).
+One new migration does it on MySQL, MariaDB and PostgreSQL: the key becomes a
+unique index before the primary key goes, so a foreign key on its first column
+keeps an index, and adding the `id` numbers the existing rows. `down` undoes it
+in reverse.
+
+```js
+const KEY = ["workspace_id", "day"];
+
+export async function up(knex) {
+  await knex.schema.alterTable("day_slots", (table) => table.unique(KEY, { indexName: "day_slots_key" }));
+  await knex.schema.alterTable("day_slots", (table) => table.dropPrimary());
+  await knex.schema.alterTable("day_slots", (table) => table.increments("id"));
+}
+
+export async function down(knex) {
+  await knex.schema.alterTable("day_slots", (table) => table.dropColumn("id"));
+  await knex.schema.alterTable("day_slots", (table) => table.primary(KEY));
+  await knex.schema.alterTable("day_slots", (table) => table.dropUnique(KEY, "day_slots_key"));
+}
+```
+
+MySQL and MariaDB commit each statement on its own, so a run that fails
+part-way resumes as the [partial-failure
+rules](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#directory-order-comes-before-filenames)
+say. Code that wrote by the old key now upserts on it, with the ownership
+column among the keys.
+
 ### Workspace invitation transaction compatibility (workspaces-core 0.1.198)
 
 Invitation creation, acceptance and refusal now own their managed transactions:

package/guide/agent/app-setup/upgrading-jskit.md

@@ -81,6 +81,15 @@ installation, or validation fails, it restores the previous manifests,
 lockfile, and installed tree before reporting the failure. Resolve the reported
 registry or real peer problem and rerun `npm run jskit:update`.
 
+When the install brings package migrations the application has not had, the
+updater lists each one (`<package>: <file>`) and says to run
+`npm run db:migrate`. Run it, on every database the application uses, before
+the new version serves requests: a package's new version reads what its
+migration creates, so until then those reads fail, such as every local sign-in
+with an unknown `email_verified_at` column. Read each package's CHANGELOG
+**Upgrading** section too, for the changes the application itself must make,
+such as a feature to register.
+
 ## Separately composed packages
 
 Pass each additional manifest explicitly to both commands:

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

@@ -46,6 +46,7 @@ through its handle's calls, and every call takes the call's `options` last:
 | `lockOrCreate({ id, ...initial }, options, work)` | a keyed record locked, created first when missing, for `work` |
 | `claim({ filters, sort, take }, txOptions)` | the next rows no other worker holds |
 | `withTransaction(options, work)` | one transaction; `work` gets its `txOptions` |
+| `changeHorizon(options)` | PostgreSQL's snapshot horizon, where a read of what changed since starts ([What changed since](#what-changed-since)) |
 | `scopedQuery(params, options)` | a read-only builder for a report ([Layer 5](#layer-5-reports-the-resource-cannot-express)) |
 
 ```js
@@ -71,7 +72,7 @@ function totalsByMonth(options) {
 | owner API | The capability through which a table's owner lets other features read and write its records, such as `users.profiles`. |
 | CRUD contract | The optional HTTP and screen surface on a table resource: `defineCrudContract()`. |
 | CRUD feature | The feature `defineCrudFeature()` builds from a CRUD contract: its repository, service, actions, routes and screens. |
-| ownership | Who owns a row, required in every table resource: `public`, `workspace`, `user`, `workspace_user`, or `workspace_or_shared` (a workspace's own rows, or rows shared with every workspace when the owner is empty). |
+| ownership | Who owns a row, required in every table resource: `public`, `workspace`, `user`, `workspace_user`, `workspace_or_shared` (a workspace's own rows, or rows shared with every workspace when the owner is empty), or `system` (rows of no workspace or user, which only the owning feature's system context reaches). |
 | row policy | A server-only rule narrowing which rows a context sees, applied to every statement, joins, includes and locks included. |
 | scoped query | The read-only Knex builder `scopedQuery()` returns, with ownership and the row policy already applied. |
 | system scope | Why a feature works across every workspace and user, declared with `systemScope`. |
@@ -146,6 +147,16 @@ function createReceivalsRepository({ receivals }) {
 }
 ```
 
+A field's type says what its column holds, not the column's SQL type. A
+whole-number column that is not an id (a counter, a byte count, a position),
+BIGINT included, is `type: "integer"`. Every handle read answers it as a
+number on MySQL, MariaDB and PostgreSQL alike, although both drivers read
+BIGINT as text. A column that holds another row's id is `type: "id"` and
+reads as text, as ids do. Past 2^53 − 1 a JavaScript number cannot hold a
+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 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
@@ -196,6 +207,37 @@ otherwise, naming both.
 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.
 
+A handle finds every row by one `id`. A table whose rows another key
+identifies (a workspace and a day, or one row per user keyed by the user's id)
+still gets an integer `id` primary key, and keeps that key as a unique index
+on exactly the columns its upsert names, the ownership column among them. The
+code reads by the key with a filter and writes by it with an upsert,
+`onConflict: { keys: ["workspaceId", "day"] }`
+([Layer 3](#layer-3-many-rows-at-once)). The [port
+guide](/guide/app-setup/existing-application-migration#moving-hand-written-sql-behind-resources)
+has the migration for a table that exists already.
+
+A route that reads or writes without an action (a provider's callback, a
+download it streams) takes its options from `await request.callOptions()`: the
+context the same request's action would get, its user, workspace and route
+scope resolved by the same contributors. No action's permission runs, so the
+route's own `auth` and `permission` are its gate. Never build a request's
+context by hand.
+
+A `workspace_or_shared` table's shared rows (no workspace) belong to every
+workspace, so no request or job writes one: a create stamps the caller's
+workspace, a patch or delete of a shared row is refused, and many-row writes
+and locks leave shared rows out. When a request may change one (a permission
+says so, or the row is the person's own), the owner reads the row in the
+request's own context, which proves the caller reaches it, decides in code
+whether this caller may change it, and only then writes it in a system
+context, `systemContext(reason)` itself (one `forUser` or its kin derived is
+not a system context), naming the empty owner: `create({ ...fields,
+workspaceId: null }, …)`, or `patchWhere({ id: [id], workspaceId: null },
+changes, …)` and `deleteWhere` with the same filters, which never reach a
+workspace's row. `{ ...txOptions, context: systemContext(reason) }` joins
+the request's transaction.
+
 A read answers every field unless `fields` names the ones it needs (a
 belongs-to field by its own key, such as `customerId`, or its relationship);
 the locks (`lock`, `lockMany`, `lockWhere` and `claim`) take it in their
@@ -205,6 +247,15 @@ visible, so a hot path names its fields. A collection relation with
 `hydrateOnList: false` or `hydrateOnView: false` loads its rows on that kind of
 read only when the read includes it.
 
+`foreignKeys` declares the table's real database foreign keys, in json-rest-api's
+shape: `foreignKeys: [{ columns: ["customerId"], referencedTableName: "customers" }]`,
+`columns` naming schema fields and `referencedColumns` the other table's columns
+when they are not its `id`. json-rest-api relies on a declared key to skip work,
+so a declaration the database lacks changes results: before any test runs,
+`jskit test --databases` compares every declaration with the test database's keys,
+fails on one the database lacks and lists the keys of your tables that nothing
+declares.
+
 A `hidden: true` field (an ownership id, a bearer token, a storage key) never
 reaches a request: no CRUD route or JSON:API document (`format: "jsonapi"`)
 carries it, even when `fields` names it. The owner's own code reads one by
@@ -213,12 +264,21 @@ options)` or `{ ...txOptions, fields }` for a lock, which costs one more
 statement per 1,000 records, scoped as the read is; a read without `fields`
 never answers it. It may be an id, string, integer, number or boolean, and
 naming any other kind refuses the read. The repository a CRUD feature gives
-other features, and its own actions, refuses a read naming a hidden field, and
-any `scopedQuery()` (its builder carries every column), and every method it
-holds, `decorateRepository`'s included, answers without the hidden fields of the
-tables its owner owns, unless the call runs in a system context. So the owner
-checks a token in a method `decorateRepository` adds, with the handle it
-receives, and answers only the outcome. Never unhide a field to read it, and
+other features, and its own actions, refuses any call whose `fields` names a
+hidden field, whatever the method (`decorateRepository`'s included), and any
+`scopedQuery()` or answered builder other than a `joinSource()`'s (either can
+select every column), and every method it holds answers without the hidden
+fields of the tables its owner owns, unless the call runs in a system context.
+It tells hidden fields by name, so a feature whose tables hide a field in one
+and show it in another fails to start: hide it in both, or rename one. So the
+owner checks a token in a method `decorateRepository` adds, with the handle it
+receives, and answers only the outcome. Work in another feature that needs the
+value itself (a key it signs with, an address it sends to) calls a method the
+owner's `decorateService` adds: that receives the repository before the guard,
+so it reads the field, named in `fields`, in the caller's own context, with no
+system context. A test of such a path asserts the value the other feature uses,
+not only that the call succeeded: a hidden field left out of a record reads as
+`undefined`, not as an error. Never unhide a field to read it, and
 never read it with `scopedQuery`.
 
 `create` and `patch` answer the written record by default, read back through
@@ -257,8 +317,8 @@ who the call runs for as `caller`: `{ kind: "user", userId }` for a signed-in
 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 was derived for (below), so never read a missing actor as an
-anonymous request.
+person it works for ([below](#background-work)), so never read a missing actor
+as an anonymous request.
 
 ```js
 // good: one predicate on the row being read
@@ -516,6 +576,16 @@ no record behind. On its own it runs work once, so work may call a provider:
 two first uses of one id at once can collide on the insert, and the loser runs
 again before its work starts.
 
+Every lock takes `FOR UPDATE`, as `patchWhere` does for the rows it selects,
+which also keeps out another transaction's insert of a row that references the
+locked one (a foreign key's check). Where work locks a parent only to change
+its own fields while children may be added meanwhile (a balance others post
+entries to), pass `lockMode: "noKeyUpdate"` to `lock`, `lockMany`,
+`lockWhere`, `claim`, `lockOrCreate` or `patchWhere`: on PostgreSQL it
+is `FOR NO KEY UPDATE`, which still keeps every other lock and write of the row
+out but lets those inserts through; MySQL, MariaDB and SQLite lock as for the
+default `"update"`. Any other value throws a `TypeError` before anything runs.
+
 A record that a person edits from a form it read earlier carries a version
 number: the table resource names it with `lockVersionField`, an integer field
 over a non-null integer column with `defaultTo: 0`.
@@ -577,34 +647,43 @@ async function activeDays(memberIds, options) {
     resource in the code describes.
 - `column()` names columns; `raw` takes one expression as a string literal,
   with its values as bindings.
-- The builder only reads, and only its own table is scoped. A `.join()` of a
-  table by name, or a table named inside `raw()`, reads that table's rows past
-  its owner and row policy. Nothing at run time stops it: `jskit/no-direct-knex`
-  and `jskit/sql-literal` flag it, and `expectScoped` catches it only when the
-  test seeds another owner's rows the join matches. Join another table only as
-  that table's scoped subquery.
-- When a report needs another owner's rows side by side, that owner adds a
-  method answering its scoped rows as a subquery with its own column names,
-  and the report joins it in one statement. The method answers
-  `{ query, column }` from its `scopedQuery({ alias }, options)`, with
-  `column(field)` naming its columns under that alias, wrapped, since a
-  builder is thenable and an async function would run it. The report shapes
-  that builder (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 feature that requires both. A join source carries
-  every column, hidden ones too, so an owner answers one only to a feature
-  that may read them.
+- Its rows are the driver's, with no field types applied: a BIGINT column
+  (ids and counters alike) and a `COUNT` read as text on MySQL and MariaDB
+  (the runtime's `bigNumberStrings`) and on PostgreSQL (int8). The method
+  turns the counts and totals it answers into numbers, such as `Number(days)`
+  for `activeDays` above.
+- The builder only reads, and only its own table is scoped. A `.join()` or
+  `.from()` of a table by name, or a table named inside `raw()`, reads that
+  table's rows past its owner and row policy, and so does a subquery callback
+  (`whereIn("id", (sub) => sub.from(...))`), whose builder is Knex's own. Nothing
+  at run time stops it: `jskit/no-direct-knex` and `jskit/sql-literal` flag it
+  (a name as text, an alias object such as `{ p: "projects" }`, a variable
+  whose name says table or name, a const holding one, either branch of a `?:`
+  or `??`, any `fromRaw()` or `joinRaw()`, and in a subquery callback any
+  variable but a scoped subquery or one destructured from a call, such as
+  `const { query } = await lots.scopedQuery(...)`), and `expectScoped` catches it
+  only when the test seeds another owner's rows the join matches. Join another
+  table only as that table's scoped subquery.
+- When a report needs another owner's rows side by side, it joins that
+  table's join source in one statement. `joinSource({ alias, filters },
+  options)` on the owner's handle, or on the repository a CRUD feature gives
+  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, never a hidden one, and `column(field)` naming each
+  under the alias. 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 feature that
+  requires both. Never hand-build a join source on `scopedQuery()`: its
+  builder carries every column, so a CRUD feature's repository refuses
+  `scopedQuery()`, and any method answering a builder other than a
+  `joinSource()`'s, outside a system context. A report that needs another
+  owner's hidden value asks that owner for a method answering what it needs.
 
   ```js
-  // billing's owner API: its scoped invoices as a join source, with their column names
-  async function invoiceSource(alias, options) {
-    const { query } = await invoices.scopedQuery({ alias }, options);
-    return { query, column: (field) => invoices.column(field, alias) };
-  }
-
   // Knex: report - open tasks and billed totals per project, joined on billing's scoped invoices
   async function projectSummary(options) {
-    const source = await billing.invoiceSource("i", options);
+    const source = await billing.joinSource({ alias: "i" }, options);
     const billed = source.query
       .select({ projectId: source.column("projectId") })
       .sum({ billed: source.column("amount") })
@@ -666,6 +745,59 @@ const { records: firstPage } = await subscriptions.query({ filters: { newsletter
 
 Bad: a list read 100-row pages in a loop for each of 40 related sets.
 
+## What changed since
+
+A page that catches up on a chat, a watch that acts on changes and a sync to
+another system each read what changed since they last read. "Past the highest
+id seen" misses a row whose id was taken before its transaction committed, and
+every change to an older row; "`updatedAt` after the last read" misses a
+transaction that committed after a later one. On PostgreSQL a change stamp and
+the change horizon miss neither:
+
+- The table stamps each row with the transaction that last wrote it, an `xid8`
+  column a trigger sets on every insert and update, whatever the write sent,
+  with an index that starts with the ownership columns:
+
+  ```js
+  // migrations/20261108120000_messages_changed.cjs
+  exports.up = async function up(knex) {
+    await knex.raw("alter table messages add column changed xid8 not null default pg_current_xact_id()");
+    await knex.raw("create function messages_changed() returns trigger language plpgsql as $$ begin new.changed := pg_current_xact_id(); return new; end $$");
+    await knex.raw("create trigger messages_changed before insert or update on messages for each row execute function messages_changed()");
+    await knex.raw("create index messages_changed_ix on messages (workspace_id, changed)");
+  };
+  ```
+- The table resource reads it as an `xid8` field, which nothing writes, and
+  filters on it:
+
+  ```js
+  schema: { /* ... */ changed: { type: "xid8", nullable: true } },
+  searchSchema: {
+    changedSince: { type: "xid8", actualField: "changed", filterOperator: ">=" },
+    changedBefore: { type: "xid8", actualField: "changed", filterOperator: "<" }
+  }
+  ```
+- The reader takes `changeHorizon(options)` before it reads and answers it as
+  the next cursor. Every transaction below the horizon had finished, so the
+  next read, `changedSince: cursor`, finds everything this read could not see.
+  A row can come twice, so the reader merges by id. A job that keeps its cursor
+  in a row reads the window `{ changedSince: cursor, changedBefore: horizon }`
+  and stores the horizon as the new cursor in the same transaction.
+
+```js
+async function catchUp(conversationId, since, options) {
+  const cursor = await messages.changeHorizon(options);
+  const changed = await messages.queryAll({ filters: { conversationId, changedSince: since } }, options);
+  return { messages: changed, cursor };
+}
+```
+
+The horizon is the server's: a long transaction anywhere holds it back, so a
+read repeats more rows, never misses one. MySQL, MariaDB and SQLite stamp no
+row with its transaction: `changeHorizon` throws `UnsupportedDatabaseError`
+there, and an `xid8` field is refused. A reader there takes the rows to handle
+with `claim()`, marking each done in the same transaction.
+
 ## Background work
 
 Work over the whole population runs as a background job, never inside one
@@ -689,13 +821,15 @@ const SettlementFeature = defineFeature({
   `actions.execute({ actionId, input, context })` keeps the context's kind:
   inside it, a handle call still reads as the system context or job.
 - Work a job does for one person (a request it carries out later) passes
-  `{ actorId }` last: `forWorkspace(id, { actorId: requestedBy })`. It is for
-  attribution only: audit fields read it with `resolveAuditActorId(context)`
-  (the signed-in user, else the person a job acts for) and the row policy as
-  `caller.actorId`. It never changes which rows the job reaches and signs no
-  one in: `resolveActorId` and every `authenticated` check still see no one.
-  Write audit fields with `resolveAuditActorId`, and decide access with
-  `resolveActorId`.
+  `{ actorId }` last: `forWorkspace(id, { actorId: requestedBy })`. It says
+  whom the work is for and never sets the scope, which stays the workspace or
+  user the job was derived for, and it signs no one in: `resolveActorId` and
+  every `authenticated` check still see no one. Audit fields read it with
+  `resolveAuditActorId(context)`. A row policy is told it as `caller.actorId`,
+  and one that holds people to their own rows reads it as it reads a
+  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,
   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
@@ -714,8 +848,9 @@ const SettlementFeature = defineFeature({
   ["workspaceId", "email"] }, { context })`, as a system context may do through
   another feature's CRUD repository too (see [Layer
   1](#layer-1-the-table-resource)). Never unhide it for the job.
-- A request uses its own context. The only exception is a console report
-  behind a console permission, with bounded output.
+- A request uses its own context. The exceptions are a console report
+  behind a console permission, with bounded output, and the write of a shared
+  row it has proved it reaches ([Layer 1](#layer-1-the-table-resource)).
 - `jskit check` lists every system scope and every `systemContext` call with
   its reason, read from the string literal at the call: a reason kept in a
   constant reads as none.
@@ -723,6 +858,16 @@ const SettlementFeature = defineFeature({
   from the request or from `forWorkspace`, `forUser` and `forWorkspaceUser`:
   lint refuses `createSystemContext` and hand-written `scopeValues`, and a
   context naming two workspaces or two users throws.
+- A table only the feature's own background work reads and writes, whose rows
+  belong to no workspace or user (an agent's runs, a server's leases, a queue
+  keyed by something other than an owner), takes ownership `system`. Every call
+  then needs the owner's `systemContext(reason)`: a request's context, a
+  `forWorkspace`, `forUser` or `forWorkspaceUser` job and no context at all
+  throw `SystemContextRequiredError` before any statement, since on such a
+  table they would reach every workspace's rows. Requests
+  reach the rows only through the owner's own methods, which decide what each
+  caller may see, and `defineCrudFeature` refuses a `system` table. A table
+  whose rows do belong to a workspace or user names that ownership instead.
 - A job that runs on a schedule is a feature whose `boot()` starts a timer and
   whose `shutdown()` stops it; JSKIT ships no scheduler. See
   [typed features, Owned state](/guide/framework/typed-features#owned-state).
@@ -789,11 +934,20 @@ Ask the owner: its service, or for a JSKIT table its owner API, with the same
 (`users.profiles`, `users.settings`), workspaces (`workspaces`,
 `workspaces.memberships`), local sign-in (`auth.local.accounts`,
 `auth.local.sessions`, `auth.local.recovery`) and the console
-(`console.settings`). A realtime audience reaches its users the same way: its
+(`console.settings`). Local sign-in's owner APIs work in its system context,
+so `jskit check` wants a reviewed reason for each module that requires one
+(see [Hard rules](#hard-rules)). A realtime audience reaches its users the same way: its
 `audienceUsers({ event, options })` asks the owners and answers user ids, in the
 event's scope: for a customer's or a public surface's event, the workspace the
 request resolved, never one its payload names (see [Realtime](/guide/app-extras/realtime)).
 
+Code that names people by id (a conversation's members, a group's
+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.
+
 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
 (users-core's `userProfileTableResource`) and served through the owner with
@@ -891,6 +1045,14 @@ test booted (`countRuntimeQueries(work)` from
 nothing never passes: "The path sent no statement at any size" means pass
 `knex`, or the path never reached the database.
 
+A package's own data test that creates its tables in the test takes its Knex
+from `createPackageTestKnex(t, { environment: process.env })` (from
+`@jskit-ai/resource-runtime/test`): an in-memory SQLite database, or on a
+`DB_CLIENT=pg` run a schema of the test's own in `TEST_DB_NAME`, dropped after
+it. The same file then proves its locks, many-row writes and upserts on
+PostgreSQL too; compare counts with `Number()` (PostgreSQL answers them as
+strings) and ids with `String()`.
+
 `createTestResourceRuntime({ knex })` gives a test the resource runtime its
 features own their tables through: `runtime.own(featureId, [resource])`
 answers the handles, and `runtime.declareSystemScope(featureId, reason)` the
@@ -968,19 +1130,23 @@ async function signUp(email, password) {
 
 ## Hard rules
 
-These are always wrong, and lint reports them as errors in all code but the
-client's, wherever it sits; tests, migrations and seeds are outside them.
-`eslint-disable` cannot turn them off.
+These are always wrong, and lint reports them as errors in all code but a
+package's client (`src/client`), the app's own `src/` included, since server
+code sits there too. Tests, migrations and seeds (a `test/`, `migrations/` or
+`seeds/` folder at the root of the app or of a package, or a `seed*` script in
+its `scripts/`, `bin/` or root) are outside them; such a folder deeper in
+server code is server code. Neither `eslint-disable`, an inline
+`/* eslint ... */` config nor the app's ESLint config can turn them off.
 
 ### Lint rules
 
 | Rule | Reports | Section |
 | --- | --- | --- |
 | `jskit/no-direct-knex` | a table reached by name with Knex, a `.knex` read or `knex` destructured, a transaction opened by hand | [The resource is the only door](#the-resource-is-the-only-door) |
-| `jskit/no-transaction-reader` | `options.trx`, `trx \|\| knex`, a `trx = knex` default, `trx` destructured from options | [Transactions](#transactions) |
+| `jskit/no-transaction-reader` | `options.trx`, `trx \|\| knex`, a `trx = knex` default, `trx` destructured from options, any key but `context` and `trx` read from the `txOptions` work receives | [Transactions](#transactions) |
 | `jskit/no-hand-scope` | a hand-written `where` on `workspace_id` or `workspaceId` | [Layer 1: the table resource](#layer-1-the-table-resource) |
 | `jskit/sql-literal` | raw SQL built from strings or templates instead of one literal with bindings | [Layer 5: reports the resource cannot express](#layer-5-reports-the-resource-cannot-express) |
-| `jskit/no-hand-context` | a system context made with `createSystemContext`, a context's `scopeValues` written by hand | [Background work](#background-work) |
+| `jskit/no-hand-context` | a system context made with `createSystemContext` or `declareSystemScope`, a context's `scopeValues` written by hand | [Background work](#background-work) |
 | `jskit/knex-reason` | a `scopedQuery()` report outside a named repository method under `// Knex: <kind> - <reason>` | [Layer 5: reports the resource cannot express](#layer-5-reports-the-resource-cannot-express) |
 
 ### Exceptions
@@ -1024,8 +1190,18 @@ it. Check and judge, for each file:
 - an infrastructure exception or a feature's system scope that the app's
   checked-in `jskit-data-access.json` does not list, so each new one is
   reviewed: `{ "infrastructure": [{ "file", "rule" }], "systemScopes":
-  [{ "feature", "systemScope" }] }`;
-- a module that requires `runtime.database` or `runtime.resources` without
-  the infrastructure exception: features own their tables with `owns`;
-- an `eslint-disable` that names a data-access rule, or no rule, outside
-  client code.
+  [{ "feature", "systemScope" }, { "file", "capability", "systemScope" }] }`;
+- a module that requires a capability handing out rows past their owners:
+  `runtime.database` or `runtime.resources` without the infrastructure
+  exception (features own their tables with `owns`), and
+  `realtime.audience-scope`, `auth.local.accounts`, `auth.local.sessions`,
+  `auth.local.recovery`, `connectors.store`, `assistant.repositories` or
+  `payments.store` until `systemScopes` lists that file and capability with
+  its reason, in any spelling the kernel resolves (`Runtime.Resources`); a
+  feature's own id counts only where it provides that capability;
+- an `eslint-disable` that names a data-access rule, or no rule, or an inline
+  `/* 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.

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

@@ -772,7 +772,9 @@ for anything that reads or writes the domain.**
 - One handler shape: a named async function that sends what
   `request.executeAction({ actionId: ACTION_X, input })` returns.
 - A route that bypasses actions (a provider's callback) gets its own named
-  registrar. Summaries are sentences.
+  registrar and reads with `await request.callOptions()`
+  ([data access](/guide/framework/data-access#layer-1-the-table-resource)).
+  Summaries are sentences.
 - A route that repetition can abuse (sign-in, codes, sending email) declares
   `rateLimit: { max, timeWindow }`, which the kernel enforces per client
   address and refuses with 429, `kernel.http.rateLimited` and `Retry-After`.
@@ -1216,7 +1218,7 @@ export default [
   `**/src/server/**`, so an existing application sees them before it lists a
   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.
+  code but a package's `src/client`, tests, migrations and seeds.
 - `clientFeaturesConfig(globs)` holds client code to the same rules; see
   [client features](/guide/framework/client-features#running-the-checks).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.284",
+  "version": "0.1.285",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.14",
+    "@jskit-ai/kernel": "0.2.15",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

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

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.14",
+    "@jskit-ai/kernel": "0.2.15",
     "@jskit-ai/material-web": "0.1.3",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
@@ -44,13 +44,13 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.14",
+    "@jskit-ai/http-runtime": "0.2.15",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.247",
-    "@jskit-ai/jskit-catalog": "0.2.36",
+    "@jskit-ai/config-eslint": "0.1.248",
+    "@jskit-ai/jskit-catalog": "0.2.37",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.14",
+    "@jskit-ai/kernel": "0.2.15",
     "@jskit-ai/material-web": "0.1.3",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
@@ -44,14 +44,14 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.14",
-    "@jskit-ai/shell-web": "0.2.17",
+    "@jskit-ai/http-runtime": "0.2.15",
+    "@jskit-ai/shell-web": "0.2.18",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.247",
-    "@jskit-ai/jskit-catalog": "0.2.36",
+    "@jskit-ai/config-eslint": "0.1.248",
+    "@jskit-ai/jskit-catalog": "0.2.37",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.14"
+    "@jskit-ai/kernel": "0.2.15"
   },
   "jskit": {
     "kind": "runtime",

package/reference/autogen/KERNEL_MAP.md

@@ -373,6 +373,7 @@ Exports
 ### `capabilities/defineProvider.js`
 Exports
 - `ARCHITECTURE_ID_PATTERN`
+- `capabilityKey(value)`
 - `defineProvider({ id, requires = {}, optional = {}, provides = {}, hints = {}, setup, boot = null, shutdown = null } = {})`
 - `normalizeArchitectureId(value, label)`
 - `type ProviderDefinition`