@jskit-ai/agent-docs 0.1.282 → 0.1.284

package/guide/agent/app-extras/assistant.md

@@ -124,11 +124,16 @@ above. This section documents that existing surface's behavior and migration
 constraints, not a second engine/tool implementation.
 
 ```bash
-npm install @jskit-ai/assistant-runtime
+npm install @jskit-ai/assistant-runtime @jskit-ai/resource-runtime
 npm run db:migrate
 ```
 
-These migration instructions apply only to an application selecting the database
+The application registers `AssistantStoreFeature` (from
+`@jskit-ai/assistant-runtime/server`) in its server feature list. It owns the
+assistant's four tables as table resources and provides their repositories as
+`assistant.repositories`, which `AssistantFeature` uses; without it, or an
+`assistant.conversations` runtime, the assistant refuses to start. These
+migration instructions apply only to an application selecting the database
 integration. Its `assistant/assistant-surface` pattern composes the SQL surface;
 there is no assistant generator.
 
@@ -205,6 +210,13 @@ user change the instructions; choose it only deliberately. A malformed value
 stops the server from starting. Anyone else is refused with
 `assistant.runtime.settings.updateForbidden` (403).
 
+The settings the server returns say whether the signed-in person may change
+them (`canUpdate`, from the same check that refuses the change), and the
+settings pane follows it: people who may change them get **Save** in the app
+bar, anyone else sees the instructions read-only, without Save. The browser
+never guesses the permission, so a `settingsUpdatePermission` in server config
+needs nothing on the client.
+
 ### Existing SQL conversations
 
 The optional database integration uses the common conversation runtime for

package/guide/agent/app-extras/realtime.md

@@ -29,7 +29,44 @@ The `event_scope` audience, the default for action entity-change and CRUD
 example one written from a public route or by a job, reaches nobody and logs a
 warning; `event_scope` never widens to all users. Broadcast to every signed-in
 user only through the explicit `all_users` audience; a CRUD feature selects it
-with `defineCrudJsonApiFeature({ realtimeAudience: "all_users" })`.
+with `defineCrudFeature({ realtimeAudience: "all_users" })`.
+
+An audience entry may also reach users that only a record's owner knows, such
+as the person an invitation was sent to. It provides
+`audienceUsers({ event, options })`, which answers, or resolves to, a list of
+user ids; realtime adds each one's user room. It asks the owners' APIs (for
+example `activeMemberIds(workspaceId, options)` of `workspaces.memberships`, or
+the record owner's repository) and never the database directly. It runs once
+for the event, however many sockets receive it, and `options.context` is the
+event's own scope (its workspace, user, or user in a workspace), so the owners
+answer for that scope and not for a request's. An event written on a customer's
+or a public surface has a global scope, which reaches no room by itself: the
+framework adds the workspace the request resolved as its `workspaceId`, so the
+audience reads there and `all_workspace_users` reaches it. The payload never
+chooses the scope, since a payload may copy an input id: an `audienceUsers`
+reads with `options`, never with a workspace the payload names. An event with
+no workspace and no user reads with no context. Realtime needs no database, so
+those contexts come from `RealtimeAudienceScopeFeature`
+(`@jskit-ai/realtime/server/RealtimeAudienceScopeFeature`): an application whose
+action events declare such an audience registers it beside its other features,
+or realtime refuses to boot and names the actions. An audience that reads only
+public tables (users, workspaces, memberships, invitations) says so with
+`publicTablesOnly: true` and reads with no context; an owned table would throw
+`MissingScopeError` there. An audience given as a function of the execution is
+not known at boot, so realtime checks it when the event is published: without
+the feature, an entry that reads in the event's scope is logged as an error and
+skipped. An `audienceUsers` that fails is logged as an error and skipped too,
+and the event still reaches the audience's other rooms:
+
+```js
+realtime: {
+  event: "users.bootstrap.changed",
+  audience: {
+    preset: "event_scope",
+    audienceUsers: ({ event, options }) => invitations.recipientUserIds(event.entityId, options)
+  }
+}
+```
 
 Client features register listeners through `@jskit-ai/realtime`. Keep query
 invalidation close to the resource that owns the query keys.

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

@@ -114,10 +114,20 @@ A route name auth does not have, or a value that is neither
 or text such as `"30 seconds"` or `"1 hour"`.
 
 The address is Fastify's `request.ip`. Behind a reverse proxy every request
-comes from the proxy, so all clients would share one count: create Fastify with
-`trustProxy` set to the proxy's address (for example
-`Fastify({ trustProxy: "127.0.0.1" })`), and never to `true` when clients can
-also reach the server directly.
+comes from the proxy, so all clients would share one count. The app's
+`server.js` creates Fastify with
+`trustProxy: resolveTrustedProxies(runtimeEnv)` (from
+`@jskit-ai/kernel/server/http`), which reads one setting, `TRUSTED_PROXIES`:
+the addresses or ranges of the proxies in front of the server, comma-separated,
+in Fastify's `trustProxy` syntax (`10.0.0.5`, `10.0.0.0/24`, `fd00::/8`, or
+`loopback`, `linklocal` or `uniquelocal`), for example
+`TRUSTED_PROXIES=loopback,10.0.0.5`. Only those proxies' `X-Forwarded-For` (and
+`-Host` and `-Proto`) is believed, so each client behind them has its own count
+and a client that sends the header itself changes nothing. Without the setting
+only a proxy on the same machine (`loopback`) is believed. `true` and hop counts
+stop startup, because they believe a header any client can send. Name the
+narrowest addresses that are only your proxies: a private range shared with
+other machines lets each of them choose its address.
 
 **Per account (local auth).** After 5 failed sign-ins in a row for one email,
 that email must wait 30 seconds before its next attempt; each further failure
@@ -154,23 +164,35 @@ password, in every environment, unless `AUTH_LOCAL_EMAIL_CONFIRMATION=false`.
 Registering keeps the registration waiting, with no account, profile or
 session, and answers `requiresEmailConfirmation: true`; the sign-in page then
 shows "Confirm your email", with a button to send a new link and a field for
-the link or its code. Opening the link (`/auth/login?confirmation_token=...`)
-creates the account and signs the person in. The `auth.local.user.registered`
-hook runs then, not on registering. Signing in with the right password while the registration waits
-is refused with status 403 and `auth.login.emailUnconfirmed`, and the sign-in
-page shows how to confirm; a wrong password is an ordinary failed sign-in.
+the link or its code. Confirming takes the link's code and the password the
+registration was made with (`POST /api/register/confirm` with
+`{ token, password }`): opening the link (`/auth/login?confirmation_token=...`)
+asks for that password, and right after registering the page keeps the one
+just typed. Confirming creates the account and signs the person in. The
+`auth.local.user.registered` hook runs then, not on registering. A missing or
+wrong password creates nothing and keeps the registration and its link, with
+status 400 and `auth.local.register.confirmationPasswordInvalid`. Signing in
+with the right password while the registration waits is refused with status
+403 and `auth.login.emailUnconfirmed`, and the sign-in page shows how to
+confirm; a wrong password is an ordinary failed sign-in.
 
 A link's code is random, kept only as a hash, works once and expires after a
-day. Registering the same email again, or asking for a new link, replaces it,
-so a waiting registration never keeps the email from its owner. Asking for a
-new link answers the same whether or not a registration waits.
+day. Registering the same email again replaces the waiting registration whole
+and its link, so a waiting registration never keeps the email from its owner.
+Asking for a new link replaces the link and keeps the registration, password
+included; it answers the same whether or not a registration waits, and sends
+nothing for an expired one. The link proves the email and the password proves
+the registration: whoever registers an email, before its owner or after, the
+account its link creates has the password of the person who confirms it. A
+link its owner never asked for confirms nothing with the owner's password;
+the owner registers instead.
 
 The link is emailed by the optional `auth.local.confirmation-sender`
 capability, an async function accepting `{ email, confirmationUrl }`, built
 like the recovery sender below; with it, `APP_PUBLIC_URL` is required and the
 link is never returned or logged. In development without one, the link is in
 the registration's answer (`confirmationUrl`) and the log, and the sign-in page
-shows it with a button that confirms it. In production (`NODE_ENV=production`)
+shows it with a button that confirms it with the password typed. In production (`NODE_ENV=production`)
 without one, while anyone may register, the server refuses to start, naming
 the ways out: install a sender, set `AUTH_LOCAL_EMAIL_CONFIRMATION=false`, or
 set `AUTH_LOCAL_SELF_REGISTRATION=false`. For direct library
@@ -203,7 +225,35 @@ upgrade wait. Waiting registrations are kept in the file store
 the `auth_local_registrations` table (run `npm run db:migrate`). A custom
 `auth.local.backend` implements the `registrations` collection. Tests that
 register and expect a session either confirm with the answer's
-`confirmationUrl` or set `AUTH_LOCAL_EMAIL_CONFIRMATION=false`.
+`confirmationUrl` and the password they registered with, or set
+`AUTH_LOCAL_EMAIL_CONFIRMATION=false`.
+
+## Local accounts from application code (database backend)
+
+Application code that works with local auth's records beside local auth, such
+as an emailed sign-in link or a job that removes old sessions, requires their
+owners' capabilities from `@jskit-ai/auth-provider-local-db-core` and never
+reads or writes the `auth_local_*` tables. Every method takes the call's
+`options` last and runs in `options.trx` when there is one. That transaction
+must be a managed one: open it with one of the application's own table
+resource handles, `handle.withTransaction(options, (txOptions) => …)`, and pass
+`txOptions` on. Their writes refuse a transaction from `knex.transaction()`, and
+a failed write fails the whole transaction even when the work catches its
+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)` |
+
+`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`,
+`AuthLocalSessions` and `AuthLocalRecovery` in
+`@jskit-ai/auth-provider-local-db-core/server/types`.
 
 ## The first account in production (local auth)
 

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

@@ -33,6 +33,14 @@ Do not create a console merely to host one ordinary settings page.
 The first-owner policy, if the product selects it, is a runtime product rule;
 it is not a hard-coded seed account.
 
+Server code that needs the console's settings, such as who owns the console,
+requires `console.settings` and reads them with `getSingleton(options)`, which
+answers `{ id, ownerUserId, settings, createdAt, updatedAt }`; it never reads
+the `console_settings` table. Its type is `ConsoleSettings` in
+`@jskit-ai/console-core/server/types`. To check the console's owner, use
+`isConsoleOwnerUserId(userId, options)` of `console.core`'s
+`services.access`.
+
 ## Verification
 
 Test authorized and forbidden direct entry, first-owner behavior, switching,

package/guide/agent/app-setup/database-layer.md

@@ -12,16 +12,17 @@ genuinely chooses a driver at runtime.
 For MySQL or MariaDB:
 
 ```bash
-npm install @jskit-ai/database-runtime-mysql
+npm install @jskit-ai/database-runtime @jskit-ai/database-runtime-mysql
 ```
 
 For PostgreSQL:
 
 ```bash
-npm install @jskit-ai/database-runtime-postgres
+npm install @jskit-ai/database-runtime @jskit-ai/database-runtime-postgres
 ```
 
-Each driver brings `@jskit-ai/database-runtime` and the appropriate Knex
+The application declares `@jskit-ai/database-runtime` itself: each driver takes
+it as a peer, so the application holds its one copy, and brings its own Knex
 driver through ordinary npm dependencies. There is no JSKIT install wizard.
 
 ## Connection environment
@@ -47,7 +48,7 @@ credentials. JSKIT never guesses or commits them.
 
 The running database provider registers a `database` health check that runs
 `select 1` within two seconds. The foundations' `GET /api/health` answers `503`
-while it fails; see [Health endpoint](./initial-scaffolding.md#health-endpoint).
+while it fails; see [Health endpoint](/guide/app-setup/initial-scaffolding#health-endpoint).
 
 ## Migration configuration
 
@@ -162,7 +163,7 @@ pending migrations in this order, using the default `migrationsDirectory`:
 2. Application `migrations/`.
 3. The `constraints/` subdirectory of each discovered package migration
    directory that has one, in the same order.
-4. Application `migrations/constraints/`.
+4. Application `migrations/constraints/`, when it exists.
 
 Knex sorts filenames within each directory, not across the whole graph; see
 its [`sortDirsSeparately` option](https://knexjs.org/guide/migrations.html#migration-api).
@@ -257,10 +258,10 @@ database allocation, credentials, lifetime, and environment injection.
 
 ## Resource services and custom operations
 
-Conventional persisted resources use `defineCrudResource()` and
-`defineCrudJsonApiFeature()` so the framework owns repeated repository,
-service, action, permission, JSON API, and route mechanics. This does not make
-product CRUD behavior fixed.
+Conventional persisted resources use `defineTableResource()`,
+`defineCrudContract()` and `defineCrudFeature()` so the framework owns
+repeated table ownership, service, action, permission, JSON API, and route
+mechanics. This does not make product CRUD behavior fixed.
 
 - `decorateRepository` adds resource-specific queries, locks, or writes.
 - `decorateService` overrides a standard method or adds domain methods such as
@@ -268,108 +269,27 @@ product CRUD behavior fixed.
 - `operationLifecycle` surrounds a standard operation with `before`, `execute`,
   `after`, and mutation-only `afterCommit` phases. Create, update, and delete
   phases before commit share one repository transaction, and `execute` receives
-  `standard(nextInput)` for retaining the normal framework write.
+  `standard(nextInput)` for retaining the normal framework write. A deadlock
+  runs that transaction again, so `before`, `execute` and `after` can run twice
+  and touch only the database; an outside effect (an email, an HTTP call) goes
+  in `afterCommit`, which runs once after commit, or in an outbox row.
 - Named `actions` expose non-CRUD service methods through normal input,
   permission, event, and optional HTTP route contracts.
 
-Repositories own database access. Services and lifecycle hooks orchestrate
-repositories. External delivery belongs after commit; when it must be durable,
+The feature that owns a table reads and writes it through the handles its
+`owns` entry gives its repository; services, hooks and other features call
+that repository or the owner's API, never the table. External delivery belongs after commit; when it must be durable,
 write an outbox record inside the transaction and deliver it separately.
 A separate Feature is warranted when an operation belongs to another domain,
 not merely because a useful resource has behavior beyond list and save. Write
 it as a [typed feature](/guide/framework/typed-features).
 
-## Writes that return less
+## Writes, versions, locks and deadlocks
 
-A CRUD repository's `createDocument(payload, options)` and
-`patchDocumentById(id, patch, options)` return the full document by default:
-the write is followed by a get through the resource's row policy and its
-lookups, about four queries and a policy run per linked type. Server code that
-does not use the result passes `returning: "minimal"`, which answers
-`{ data: { type, id } }`, or `"none"`, which answers `undefined`; a missing or
-out-of-scope record still patches to `null`. `createDocuments(payloads,
-{ trx, context, returning })` creates several records in order in one
-transaction, the caller's `trx` or one it owns, so they are all created or
-none; its `returning` is `"minimal"` unless the caller asks for `"full"`, and
-its results follow the payloads. Each record is still validated and inserted
-by itself: a batch saves the read-backs and the transactions, not the inserts.
-
-## Optimistic locking
-
-A CRUD resource whose records carry a version number names it with
-`lockVersionField`, an integer schema field over a non-null integer column
-with a starting value, such as `0`:
-
-```js
-defineCrudResource({
-  namespace: "contracts",
-  tableName: "contracts",
-  autofilter: "workspace",
-  lockVersionField: "lockVersion",
-  schema: {
-    // ...
-    lockVersion: { type: "integer", min: 0, readOnly: true, column: "lock_version" }
-  }
-});
-```
-
-The CRUD repository's
-`patchDocumentIfLockVersion(recordId, expectedLockVersion, patch, { trx, context })`
-then applies `patch` only while the record still holds `expectedLockVersion`, a
-non-negative integer, and adds one to the lock version in the same
-transaction: the caller's `trx`, or one it owns. It returns the patched document, which carries the new lock
-version, or `null` when the record does not exist or is outside the caller's
-scope. A record whose lock version has moved on rejects with a 409 coded
-`crud.document.lockVersionConflict` ("This record changed. Reload and try
-again."), and nothing is written. The patch leaves the lock field out; an app
-that wants its own wording for the conflict catches that code. A resource
-without `lockVersionField` cannot call it, and `defineCrudResource()` rejects
-a `lockVersionField` that names no integer schema field.
-
-## Row locks
-
-A check-then-write that must not race another request (is the drier empty?
-then load it) reads the record with
-`getDocumentById(recordId, query, { trx, context, forUpdate: true })` inside
-`withTransaction`. It locks the record's row in that transaction before
-reading it, so another `forUpdate` read or a write of the record waits until
-the transaction ends, and the read sees the latest version on PostgreSQL; on
-MySQL and MariaDB it does when the lock is the transaction's first read of
-that row. Without a transaction `forUpdate` throws, and a value other than
-`true` or `false` throws too. SQLite runs one transaction at a time on its
-single connection, so there is no row lock to take. The CRUD service's
-`getDocumentById` passes `forUpdate` through.
-
-## Deadlock retries
-
-When the database aborts a transaction as a deadlock victim (MySQL and MariaDB
-`ER_LOCK_DEADLOCK`, errno 1213; PostgreSQL `40P01`), it rolls the whole
-transaction back, so JSKIT runs the whole transaction callback again, up to
-three more times with a short random pause. The person sees one successful
-request instead of a 500. This applies to `runInTransaction()` and
-`createWithTransaction()` from `@jskit-ai/database-runtime/shared`, to
-`transactionManager.inTransaction()`, to the seed transaction, to every JSON
-REST repository's `withTransaction()` (CRUD, users and workspaces), and to a
-CRUD `createDocument`, `patchDocumentById`, `patchDocumentIfLockVersion` or
-`deleteDocumentById` given no `trx`, which owns its own transaction. A lock wait timeout (errno 1205) is not
-retried.
-
-Only the outermost transaction retries. A call given an existing `trx`, or a
-`runInTransaction()` on a transaction, which opens a savepoint, fails at once
-and leaves the retry to the transaction that owns it.
-
-A retried callback must be safe to run again: keep HTTP calls, email, file
-uploads and other external effects out of it, before or after the transaction
-or in an outbox, as above. CRUD lifecycle `before`, `execute` and `after`
-phases are inside the transaction; `afterCommit` is not. A transaction whose
-callback cannot be repeated passes `{ retries: 0 }`:
-`runInTransaction(knex, work, { retries: 0 })`.
-
-Application code that opens transactions directly uses the same behavior through
-`runInTransaction(knex, work)` instead of `knex.transaction(work)`, or wraps any
-other transaction opener in `retryDeadlocks(() => open(work))`. `isDeadlockError(error)`
-follows `error.cause` and is false for an error that reports
-`transactionOutcome: "committed"`, because that transaction must not run again.
+Writes that skip their read-back (`returning`), optimistic locking
+(`lockVersionField`), row locks and deadlock retries belong to the table
+resource's handle: see [Data access](/guide/framework/data-access), Layers 1
+and 4 and [Transactions](/guide/framework/data-access#transactions).
 
 ## Verification
 
@@ -456,7 +376,7 @@ Endpoints and batch operations get their own database tests at realistic row
 counts that compare their query counts, counted with `countQueries()` from
 `@jskit-ai/database-runtime/server/testDatabases`, or `countRuntimeQueries()`
 for a route of the server the test boots; see the typed features guide's
-[query counts at realistic sizes](/guide/framework/typed-features#query-counts-at-realistic-sizes).
+[data access tests](/guide/framework/data-access#tests).
 
 ## Browser test preparation
 

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

@@ -101,31 +101,33 @@ application's normal verification script, and Playwright.
 
 ## 3. Choose the narrowest server seam that owns each behavior
 
-Conventional resources use `defineCrudResource()` and
-`defineCrudJsonApiFeature()` so JSKIT owns the repeated repository, service,
-permission, action, JSON API, and route mechanics. Extend that contract instead
+Conventional resources use `defineTableResource()`, `defineCrudContract()`
+and `defineCrudFeature()` so JSKIT owns the repeated repository,
+service, permission, action, JSON API, and route mechanics. Extend that contract instead
 of copying it.
 
 | Product need | Normal owner |
 | --- | --- |
 | Behavior before, around, or after one standard CRUD operation | `operationLifecycle` |
 | A resource-specific domain method or override | `decorateService` |
-| A resource-specific query, lock, or persistence operation | `decorateRepository` |
+| A resource-specific query, lock, or many-row write | `decorateRepository`, on the table's handle |
 | A named non-CRUD command on the resource | a named CRUD `action` backed by the service |
 | A separate aggregate, workflow, or capability domain | `defineFeature()` with named actions |
-| Persistence that the high-level resource APIs cannot express | an explicit custom repository owned by that Feature |
+| A report the handle cannot express | one `scopedQuery()` repository method, under `// Knex: <kind> - <reason>` ([data access](/guide/framework/data-access#layer-5-reports-the-resource-cannot-express)) |
 
 For mutations, lifecycle phases before commit share one repository
 transaction. An `execute` hook that only normalizes input calls
-`standard(nextInput)` rather than reimplementing the write. Repositories own
-database access; services and hooks orchestrate repositories. External work
+`standard(nextInput)` rather than reimplementing the write. The feature that
+owns a table reads and writes it through the handles its `owns` entry gives
+its repository; services, hooks and other features call that repository or
+the owner's API, never the table. External work
 runs after commit, or a durable outbox record is written inside the transaction
 and delivered separately.
 
 Give commands product names such as `confirm`, `publish`, or `cancel`, with
 explicit input, permissions, routes where needed, audit behavior, events, and
 tests. Do not hide unrelated workflows behind a generic `execute(anything)`
-action, and do not create a custom repository merely because SQL is familiar.
+action, and do not write Knex merely because SQL is familiar.
 
 ### Reuse response serializers
 
@@ -148,9 +150,11 @@ upgrading JSKIT and declaring the directly used
 ```js
 import Fastify from "fastify";
 import SerializerSelector from "@fastify/fast-json-stringify-compiler";
-import { createCachedResponseSerializerFactory } from "@jskit-ai/kernel/server/http";
+import { createCachedResponseSerializerFactory, resolveTrustedProxies } from "@jskit-ai/kernel/server/http";
 
 const app = Fastify({
+  // TRUSTED_PROXIES: the proxies whose X-Forwarded-For is believed (loopback without it).
+  trustProxy: resolveTrustedProxies(runtimeEnv),
   schemaController: {
     compilersFactory: {
       buildSerializer: createCachedResponseSerializerFactory(SerializerSelector())
@@ -160,84 +164,113 @@ const app = Fastify({
 ```
 
 Keep the application's other Fastify options, including serializer options and
-validator configuration. This setup wraps the native default serializer builder;
+validator configuration, but replace an application's own `trustProxy` setting
+with `resolveTrustedProxies(runtimeEnv)` (`runtimeEnv` is the environment the
+server starts with, `process.env` if it has no other), and its environment
+variable with `TRUSTED_PROXIES`; see
+[sign-in protection](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/authentication#sign-in-protection)
+for the setting. This setup wraps the native default serializer builder;
 retain any deliberately chosen custom compiler instead of replacing or wrapping
 it. Native route-level compiler overrides continue to apply. Update the lockfile
 through the application's normal installation flow and restart the backend to
 activate the new setup. Updating packages or starter examples alone does not
 change an existing application's startup source.
 
-### JSON REST v2 integration
+### Data access on table resources (json-rest-api 3)
 
-Applications using `@jskit-ai/json-rest-api-core` require Node.js 24 or newer.
+Applications using `@jskit-ai/resource-runtime` require Node.js 24 or newer.
 JSKIT's repository and application default is Node.js 26. Upgrade dependencies,
-custom resource calls, and hooks together; rebuild native database dependencies
-after changing Node.
-
-The standard `defineCrudJsonApiFeature()` API keeps `queryDocuments`,
-`getDocumentById`, `createDocument`, `patchDocumentById`, and
-`deleteDocumentById`, with `{ trx, context }` repository/service options.
-Read, create, and patch services still return tagged JSON:API documents.
-Application-owned hosts use `JsonRestApi` from `json-rest-api`; the JSKIT host
-already owns that setup.
-
-For direct resource calls, replace `inputRecord` with exactly one of `data`
-(plain values) or `document` (a JSON:API document). `format` selects output
-independently: `"plain"` or `"jsonapi"`. Replace `simplified` and
-`returnFullRecord` with `format` and `returning: "full" | "minimal" | "none"`.
-The JSKIT host defaults to plain output and full write responses; standard
-document repositories explicitly request JSON:API output and full create/patch
-responses. A plain collection is still `{ data: [...], meta?, links? }`; use
-`extractJsonRestCollectionRows()` when a custom repository needs its rows.
-A query without a page returns only the resource's first 20 rows; a
-server-side read that needs every row uses `queryAllJsonRestCollectionRows()`
-([every row](/guide/framework/typed-features#every-row)).
+resource calls and hooks together; rebuild native database dependencies after
+changing Node.
 
-```js
-await jsonRestApi.resources.books.patch({
-  id: recordId,
-  data: { title: "Revised title" },
-  format: "jsonapi",
-  returning: "full",
-  transaction: trx
-}, createJsonRestContext(context));
-```
+Every table has one table resource and one owner feature, and every read and
+write goes through that table's handle
+([data access](/guide/framework/data-access)). Rename as you go:
 
-Keep the target ID outside the patch data. Direct plain writes use the
-belongs-to relationship name and ID, such as `author: authorId`; the standard
-repository maps a resource field's declared `as` alias. Do not send both names.
-
-Resource hooks share the mutable context supplied as the second argument
-within one operation. The normalized hook field remains
-`context.inputRecord.data`; only the public input argument changed.
-`createJsonRestContext()` clones the JSKIT execution context and its
-`visibilityContext` and `scopeValues`, allowing frozen caller contexts; other
-nested objects remain shared references. Permission hooks use
-`context.originalContext ?? context` for operation-wide caches; enrichment
-hooks use `context.parentContext`. Built-in nested operations get separate
-contexts with shallow inheritance. For an application-initiated child call,
-choose the application properties to share in a fresh context and pass
-`transaction` explicitly; reusing or blindly spreading an active operation
-context carries its working state into the child.
-
-The standard repository's `withTransaction(work)` delegates to
-`jsonRestApi.transaction(work)`. Its callback and mutation lifecycle phases
-receive the actual callable Knex transaction: custom repository SQL can use
-`await trx("audit_entries").insert(...)`, while resource calls receive it as
-`transaction`. Await every participant before returning. The helper owns
-commit, rollback, and completion hooks. Raw `knex.transaction()` handles cannot
-own resource writes, and calling `transaction()` again starts an independent
-unit; forward the existing handle to compose work.
+| Before | Now |
+| --- | --- |
+| `defineCrudResource()` | `defineTableResource()` plus `defineCrudContract()` |
+| `defineCrudJsonApiFeature()`, `createCrudResourceRuntime()` | `defineCrudFeature({ crud })` |
+| the CRUD runtime's `listByIds()`, `listByForeignIds()` | `queryAll({ filters: { [key]: ids } })` on a filter declared `{ type: "array", filterOperator: "in" }`; a page's children with `createHooksToCollectChildren()` |
+| the CRUD runtime's lookup hydration | `include` on the CRUD list or view |
+| the CRUD runtime's `virtualFields` | `queryFields` in the `owns` entry, or `decorateService` for a value SQL cannot compute |
+| the CRUD runtime's `createdAt`/`updatedAt` stamping | every handle write stamps them; only a system context sets its own |
+| the CRUD runtime's output validation | the table resource's schema, whose types json-rest-api reads each field as |
+| `defineCrudFeature`'s `ownershipFilter`, `searchSchema` | `visibility`; an `owns` entry |
+| a lifecycle hook's `trx`; a decorator's or CRUD capability's `resource` | `options`; `crud` |
+| `decorateRepository`'s `database`, `http`, `jsonRestApi` | its `repository` and `resources`, each owned table's handle |
+| `@jskit-ai/crud-core/server/fieldAccess`, `/server/lookups` | removed (nothing called them); restrict fields in the CRUD contract and its `decorateService` |
+| `runtime.json-rest-api`, `addResourceIfMissing()`, `createJsonRestResourceScopeOptions()` | `defineFeature({ owns })`; a row policy, search schema or query fields go in the `owns` entry |
+| `queryDocuments()`, `getDocumentById()` | `query({ page: { size } })`, `get(id)` |
+| `queryAllJsonRestCollectionRows()`, `queryEveryDocument()` | `queryAll(params)` |
+| `createDocument()`, `createDocuments()` | `create()`, `createMany()` |
+| `patchDocumentById()`, `patchDocumentIfLockVersion()` | `patch(id, changes, options)`, `patch(id, changes, { ...options, lockVersion })` |
+| `deleteDocumentById()` | `delete(id)` |
+| `getDocumentById(…, { forUpdate: true })`, `applyForUpdate()`, `lockScopedRecordId()` | `lock(id)` inside `withTransaction` |
+| `runInTransaction()`, `createWithTransaction()`, `joinOrOpenTransaction()`, `resolveTransaction()`, `resolveQueryOptions()`, `resolveRepoClient()` | `withTransaction(options, (txOptions) => …)` |
+| `returning: "full" \| "minimal"` | `returning: "record" \| "id"` (`"none"` is unchanged) |
+| a hand-built `visibilityContext` or scope values, `applyVisibility()`, `applyVisibilityOwners()` | the caller's context, or `systemContext(reason).forWorkspace(id)` |
+| a field's `default:` | `defaultTo:` (`default` is refused, since json-rest-api never read it) |
+| a `createdAt` or `updatedAt` default of now | nothing: drop it, since every handle write stamps them |
+| a CRUD contract that showed every column | a contract shows only its `fields`, so list every field the API showed |
+| reading every row | `queryAll`, which refuses above 10,000 rows, so page with `query()` |
+| an app's own wrappers around old calls | the handle method they wrapped, then delete the wrapper |
+
+Handles answer records, `{ id, ...fields }`, with a belongs-to field as the
+related id; the CRUD service alone answers JSON:API documents. Every call takes
+`options` last: the caller's context, and inside a transaction the `txOptions`
+`withTransaction` handed its work. A call without a context throws on a table
+that is not public.
+
+json-rest-api 3 changes what a failed write means: any failed write inside a
+managed transaction fails the whole transaction. "Insert, catch the duplicate,
+then read" inside a transaction no longer works; use
+`createMany(rows, { ...options, onConflict: { keys, action: "ignore" } })` and then read,
+or read first. A `get`, `patch`, `delete` or `lock` of a missing or hidden
+record throws json-rest-api's not-found error (a 404); with `missing: "skip"`
+it answers `null`, without failing the caller's transaction. Upsert rows carry no
+`id`, never repeat their conflict keys, and name the ownership field among
+those keys; only a table with no owners and no row policy may key the upsert on
+the id alone, `onConflict: { keys: ["id"] }`, with an id on every row. `patchWhere` and `deleteWhere` need filters, or `all: true`.
 
 Preserve `error.transactionOutcome` and its cause when translating failures:
 `none` means no transaction was acquired or accepted, `pending` leaves
 completion to the owner, `rolledBack` confirms rollback, `committed` confirms
 commit, and `unknown` means the outcome is unresolved. These describe database
-transaction evidence, not external effects. A failed JSKIT mutation
-`afterCommit` hook raises `RestApiWriteError` with outcome `committed` and does
-not undo the write. Do not turn pending, committed, or unknown write failures
-into successful missing-record results, or automatically replay a committed
-or unresolved write.
+transaction evidence, not external effects. A failed `afterCommit` hook raises
+`RestApiWriteError` with outcome `committed` and does not undo the write. Do
+not turn pending, committed, or unknown write failures into successful
+missing-record results, or automatically replay a committed or unresolved
+write.
+
+### Moving hand-written SQL behind resources
+
+An application with Knex in its repositories moves it behind table resources
+one table at a time:
+
+1. **Inventory.** List every statement that reads or writes a table: the
+   repository methods, raw queries, migrations' seed data, jobs and scripts.
+   `jskit check` and the data-access lint rules (`jskit/no-direct-knex`,
+   `jskit/no-hand-scope`) find most of them.
+2. **One owner per table.** Pick the feature that owns each table and give the
+   table one table resource with its `ownership`. Two features writing one
+   table means one of them asks the other.
+3. **Owner APIs.** Code outside the owner calls the owner's service or
+   repository capability. JSKIT's own tables already work this way: users
+   (`users.profiles`, `users.settings`), workspaces, local sign-in and console
+   settings.
+4. **Map each statement to a layer**
+   ([data access](/guide/framework/data-access)): one record or page →
+   Layer 1; screens over HTTP → Layer 2; a loop of writes → a many-row write;
+   a `forUpdate` read → a lock; totals and reports → `aggregate`, a window
+   include, or one `scopedQuery()` method; work over every workspace → a job
+   with `systemScope`.
+5. **Two tests per path.** `expectScoped` proves the path never reads or
+   changes a second owner's rows; `expectFlatQueries` proves its statements do
+   not grow with its rows. Both come from `@jskit-ai/resource-runtime/test`.
+
+Keep each move behaviour-preserving
+([refactors](/guide/framework/sanity-checks#refactors)).
 
 ### Workspace invitation transaction compatibility (workspaces-core 0.1.198)