@jskit-ai/agent-docs 0.1.284 → 0.1.285

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

@@ -70,7 +70,10 @@ Local functions
 Exports
 - `checkDataAccess({ projectRoot = process.cwd() } = {})`
 - `formatDataAccessReport(result)`
+- `readTableResourceSources({ projectRoot = process.cwd() } = {})`
 Local functions
+- `escapeRegExp(text)`
+- `skipsDirectory(name)`
 - `blank(text)`
 - `maskStrings(code)`
 - `closingOffset(masked, start)`
@@ -90,14 +93,21 @@ Local functions
 - `ownsSystemContextName(source, masked)`
 - `readSystemScopes(file, { source, code, masked, position })`
 - `readInfrastructureExcuses(file, source)`
+- `isDataAccessRule(rule)`
+- `blockComments(source)`
 - `readLintDisables(file, source, position)`
 - `readRuntimeCapabilities(file, { code, masked, position })`
+- `isError(setting)`
+- `appEslint(root)`
+- `checkLintConfig(root, files, baseline, report)`
+- `checkCapabilities(baseline, uses, report)`
 - `readBaseline(root, report)`
 - `checkBaseline(baseline, excuses, scopes, report)`
 - `walk(root, directory, files)`
 - `frameworkPackages(root)`
 - `checkTables(resources, report)`
 - `checkSystemScopes(scopes, report)`
+- `sourceFiles(root)`
 
 ### `scripts/files.mjs`
 Exports
@@ -312,6 +322,7 @@ Local functions
 - `alignLockManifestRecord(lockRecord, manifest, localPackageNames)`
 - `preparePackageLockForInstall(projectRoot, manifests, packageLockPath)`
 - `findImports(root, packageIds)`
+- `installedPackageMigrations(root)`
 
 ### `scripts/test-budget.mjs`
 Exports
@@ -334,9 +345,12 @@ Local functions
 ### `scripts/test-databases.mjs`
 Exports
 - `DATABASES_OPTION`
+- `foreignKeyCheckFor(cwd)`
 - `testDatabaseRunFor(count, cwd = process.cwd())`
 Local functions
 - `withOwnEnvironment(load)`
+- `exportedTableResources(namespace, isTableResource)`
+- `keyText({ tableName, columns, referencedTableName, referencedColumns })`
 
 ### `scripts/test-file-stop.mjs`
 Exports

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

@@ -84,6 +84,8 @@ Local functions
 - `git(repoRoot, args)`
 - `commitAll(repoRoot, message)`
 - `releaseCommitMessage(entries)`
+- `catalogPins(record, entry)`
+- `waitUntilServedAsLatest(pins, inspection, { attempts = Number(process.env.JSKIT_RELEASE_SERVE_ATTEMPTS || 20), delayMs = Number(process.env.JSKIT_RELEASE_RETRY_DELAY_MS || 30_000) } = {})`
 - `publishRelease(records, { cwd: repoRoot, registry })`
 - `publishCommand(options)`
 - `forgetPinnedLockEntries(repoRoot, names)`

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

@@ -41,6 +41,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
@@ -66,7 +67,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`. |
@@ -141,6 +142,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
@@ -191,6 +202,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](existing-application-migration.md#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
@@ -200,6 +242,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
@@ -208,12 +259,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
@@ -252,8 +312,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
@@ -511,6 +571,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`.
@@ -572,34 +642,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") })
@@ -661,6 +740,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
@@ -684,13 +816,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
@@ -709,8 +843,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.
@@ -718,6 +853,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](typed-features.md#owned-state).
@@ -784,11 +929,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
@@ -886,6 +1040,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
@@ -963,19 +1125,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
@@ -1019,8 +1185,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/skills/jskit/references/existing-application-migration.md

@@ -267,6 +267,35 @@ one table at a time:
 Keep each move behaviour-preserving
 ([refactors](sanity-checks.md#refactors)).
 
+A table keyed by several columns, or by its owner's id, gets an integer `id`
+first ([Layer 1](data-access.md#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/skills/jskit/references/heuristics/crud-authoring.md

@@ -54,7 +54,10 @@ The `crud/crud-contract` and `database/table-resource` patterns list what each e
 
 Normal CRUD tables use one non-null single-column primary key. Foreign keys are
 single-column and target compatible keys. Composite unique indexes may enforce
-business rules but do not become framework identities.
+business rules but do not become framework identities: a table keyed by several
+columns, or by its owner's id, gets an integer `id` and keeps that key as a
+unique index, read with a filter and written with an upsert
+([Layer 1](../data-access.md#layer-1-the-table-resource)).
 
 ## Schema evolution