@jskit-ai/agent-docs 0.1.283 → 0.1.285

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,47 @@ 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, 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.
+
+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`.
 
 ## 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