@jskit-ai/agent-docs 0.1.283 → 0.1.285

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

package/guide/agent/app-setup/multi-homing.md

@@ -110,14 +110,25 @@ The package migrations create and own these tables:
 | `workspace_invites` | `workspace_id`, `email`, `role_sid`, `status`, `token_hash`, `invited_by_user_id`, `expires_at`, `accepted_at`, `revoked_at` |
 
 Application records that belong to a workspace use a non-null `workspace_id`
-foreign key to `workspaces.id`. Read and change these tables through the
-`workspaces.core` repositories and services, not directly.
+foreign key to `workspaces.id`. Read and change these tables through their
+owners' capabilities (`workspaces`, `workspaces.memberships` and
+`workspaces.core`, below), not directly.
 
 ## Server composition
 
 Use `workspaces/workspace-server` for role vocabulary, creation policy,
 invitations, settings, and app-owned invitation email rendering.
 
+Two server settings are required, and the server refuses to start without
+them: whether new workspaces accept invitations, and how long an invitation
+lasts.
+
+```js
+// config/server.js
+config.workspaceSettings = { defaults: { invitesEnabled: true } };
+config.workspaceMembers = { defaults: { inviteExpiresInMs: 7 * 24 * 60 * 60 * 1000 } };
+```
+
 Workspace scope must reach repository queries. Parsing a workspace slug or
 hiding an admin link is not authorization. Membership and role checks happen
 before an operation discloses records or record existence.
@@ -125,14 +136,12 @@ before an operation discloses records or record existence.
 ### Workspace-scoped features and routes
 
 For a standard CRUD resource owned by a workspace, give its table the
-`workspace_id` column, set the resource's `autofilter: "workspace"`, and bind
-`defineCrudJsonApiFeature()` with `ownershipFilter: "workspace"` and `scope:
-WORKSPACE_CRUD_SCOPE` (from `@jskit-ai/workspaces-core/server/support/workspaceCrud`)
-on a workspace surface. JSKIT then filters `workspaceId` by the workspace in the
-route. A repository method you add reads the workspace id with
-`resolveWorkspaceScopeValue(options.context)`
-(`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`), which throws when the
-context names two workspaces.
+`workspace_id` column, set its table resource's `ownership: "workspace"`, and bind
+`defineCrudFeature()` with `scope: WORKSPACE_CRUD_SCOPE` (from
+`@jskit-ai/workspaces-core/server/support/workspaceCrud`) on a workspace
+surface. JSKIT then filters `workspaceId` by the workspace in the route. A
+repository method you add passes the call's `options` on to the table's handle,
+which scopes every read and write to the context's workspace.
 `workspace_user` also filters by the signed-in user. See the CRUD operations
 guide.
 
@@ -175,9 +184,29 @@ capability provides:
 | `workspaces.services.members` | Members, roles and invitations |
 | `workspaces.services.pendingInvitations` | Invitation resolution, redemption and acceptance participants |
 | `workspaces.services.settings` | Workspace settings |
-| `workspaces.repositories.workspaces`, `.workspaceMemberships`, `.workspaceSettings`, `.workspaceInvites` | Repository access inside the application's own transactions |
+| `workspaces.repositories.workspaceSettings`, `.workspaceInvites` | Settings and invitation records inside the application's own transactions |
 | `workspaces.tenancyProfile` | The resolved tenancy mode and workspace policy |
 
+The workspaces and their memberships are their own capabilities, for code that
+reads or changes them inside its own transactions, typed `Workspaces` and
+`WorkspacesMemberships` in `@jskit-ai/workspaces-core/server/types`. Every
+method takes the call's `options` last and joins the transaction of the
+`txOptions` it is given.
+
+| Capability | Methods |
+| --- | --- |
+| `workspaces` | `findById(id, options)`, `findBySlug(slug, options)` (a deleted workspace is not found, though its slug stays taken), `listSlugsIn`, `findPersonalByOwnerUserId`, `listForUserId(userId, options)`, `insert`, `updateById`, `lock(workspaceId, options)` |
+| `workspaces.memberships` | `findByWorkspaceIdAndUserId`, `ensureOwnerMembership`, `upsertMembership(workspaceId, userId, patch, options)`, `addMember({ workspaceId, userId, roleSid }, options)`, `activeMemberIds(workspaceId, options)`, `listActiveByWorkspaceId`, `findActiveByWorkspaceIdAndUserId`, `listActiveWorkspaceIdsByUserId`, `listActiveWorkspaceIdsByUserIds` |
+
+`addMember` makes the user an active member with the role (`member` when none
+is given), adding the membership or reactivating it. `activeMemberIds` answers
+the active members' user ids at the same cost however many members there
+are, without including their profiles. `lock` takes
+the workspace's row lock until the caller's transaction ends, so work that must
+not interleave for one workspace takes turns; it runs only inside a
+transaction, given its `txOptions`, and answers `{ id }`, or `null` when there
+is no such workspace.
+
 To check one person's membership, for example a notification recipient, call
 `workspaces.services.members.getMember(workspace, userId, options)`. It answers
 that member's `listMembers` entry, or `null` for a removed or unknown member,
@@ -225,8 +254,8 @@ workspace routes, `workspaces-web` switches Vuetify to the `workspace-light` or
 colours. Other routes use the application's themes.
 
 New workspaces start from JSKIT's blue palette unless `config/server.js` sets
-the application's own. Missing fields keep JSKIT's values; an invalid colour
-stops the server at startup:
+the application's own beside the required `invitesEnabled`. Missing colours
+keep JSKIT's values; an invalid colour stops the server at startup:
 
 ```js
 // config/server.js
@@ -301,11 +330,11 @@ authorization and role checks. Do not pass arbitrary HTTP input as options.
 
 | Capability method | Contract |
 | --- | --- |
-| `workspaces.repositories.workspaceInvites.withTransaction(work)` | Delegates to the same JSON REST API's managed `transaction(work)`; awaits commit and completion hooks before resolving. Runs `work` again when the database aborts it as a deadlock victim (see [Database layer](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#deadlock-retries)). |
-| `workspaces.repositories.workspaceInvites.lockWorkspaceForInvitations(workspaceId, { trx })` | Locks the workspace before application receipt/draft rows when composing preparation. Requires an active transaction. |
-| `workspaces.services.members.prepareInvite(workspace, actor, payload, options)` | Requires a managed `options.trx`. Validates the invitation role, replaces pending invitations for that workspace/email, and returns `{ createdInviteId, inviteTokenPreview }`. Never sends. |
-| `workspaces.services.members.sendInvite(workspace, actor, prepared, options)` | Requires no `options.trx`. Reloads the committed pending invitation and workspace display data, validates expiry and token correspondence, and sends that invitation without replacement. |
-| `workspaces.services.members.createInvite(workspace, actor, payload, options)` | Owns preparation and commit, then calls `sendInvite`, and answers with `sendInvite`'s result as JSON:API data (`returnJsonApiData`, read it from `.value`), as the invite action sends it. Rejects `options.trx`. |
+| `workspaces.repositories.workspaceInvites.withTransaction(options, (txOptions) => …)` | The invitations handle's `withTransaction`: joins the caller's transaction or opens one and hands `work` the `txOptions` to pass on; awaits commit and completion hooks before resolving. Runs `work` again when the database aborts it as a deadlock victim (see [data access](https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access#transactions)). `{ ...options, outermost: true }` refuses a call that already runs inside one. |
+| `workspaces.lock(workspaceId, txOptions)` (capability `workspaces`) | Locks the workspace before application receipt/draft rows when composing preparation. Requires an active transaction. |
+| `workspaces.services.members.prepareInvite(workspace, actor, payload, txOptions)` | Runs only inside a transaction, given its `txOptions`. Validates the invitation role, replaces pending invitations for that workspace/email, and returns `{ createdInviteId, inviteTokenPreview }`. Never sends. |
+| `workspaces.services.members.sendInvite(workspace, actor, prepared, options)` | Refuses to run inside a transaction: it delivers after the preparation's transaction commits. Reloads the committed pending invitation and workspace display data, validates expiry and token correspondence, and sends that invitation without replacement. |
+| `workspaces.services.members.createInvite(workspace, actor, payload, options)` | Owns preparation and commit, then calls `sendInvite`, and answers with `sendInvite`'s result as JSON:API data (`returnJsonApiData`, read it from `.value`), as the invite action sends it. Refuses to run inside a transaction. |
 | `workspaces.invite-acceptance-participant` (optional capability) | One application function receiving `({ invite, user }, options)` inside the acceptance transaction. Without it, acceptance activates the membership only. |
 
 `sendInvite` accepts `{ createdInviteId, inviteTokenPreview }` from preparation or
@@ -344,21 +373,20 @@ setup: ({ reviewedPeople, people, scopes, audit }) => ({
 })
 
 // Inside an authorized application command, in a feature that requires
-// workspaces: "workspaces.core":
+// workspaces: "workspaces.core" and workspaceRecords: "workspaces":
 const { members } = workspaces.services;
 const invites = workspaces.repositories.workspaceInvites;
-const prepared = await invites.withTransaction(async (trx) => {
-  const options = { trx, context };
+const prepared = await invites.withTransaction({ context }, async (txOptions) => {
   // Match acceptance's order: workspace, then application draft/receipt rows.
-  await invites.lockWorkspaceForInvitations(workspace.id, options);
-  const reviewed = await reviewedPeople.lockAuthorizedDraft(draftId, workspace.id, actor, options);
-  const receipt = await reviewedPeople.findMatchingReceipt(reviewed, requestId, options);
+  await workspaceRecords.lock(workspace.id, txOptions);
+  const reviewed = await reviewedPeople.lockAuthorizedDraft(draftId, workspace.id, actor, txOptions);
+  const receipt = await reviewedPeople.findMatchingReceipt(reviewed, requestId, txOptions);
   if (receipt) return { createdInviteId: receipt.inviteId };
   const created = await members.prepareInvite(workspace, actor, {
     email: reviewed.email,
     roleSid: reviewed.roleSid
-  }, options);
-  await reviewedPeople.associateInvitationAndSaveReceipt(reviewed, requestId, created.createdInviteId, options);
+  }, txOptions);
+  await reviewedPeople.associateInvitationAndSaveReceipt(reviewed, requestId, created.createdInviteId, txOptions);
   return { createdInviteId: created.createdInviteId };
 });
 
@@ -401,8 +429,8 @@ exactly once. Revocation after sending starts cannot recall a message.
 Register one callback during feature setup to call the required application
 services. Non-functions throw `TypeError`; duplicate registration throws, and
 registration closes when acceptance/refusal first begins. The callback's invite,
-user and options are shallow frozen. JSKIT owns the transaction and passes its
-`trx` and request `context` to the callback.
+user and options are shallow frozen. JSKIT owns the transaction and passes the
+callback the `txOptions` that carry it and the request's `context`.
 
 Acceptance checks authentication, recipient email, pending state and expiry under
 workspace/invitation locks. Before calling the participant, it activates membership
@@ -420,8 +448,8 @@ callback must not commit, roll back, create transactions/savepoints or perform
 external effects. Participant and later invitation-status failures roll back
 membership (including its previous role/status), person/training links, scopes,
 audit and accepted status. Invalid invitations and refusals do not call the
-participant. Acceptance/refusal reject borrowed `options.trx`; revocation can
-join a managed transaction or create one.
+participant. Acceptance and refusal refuse to run inside the caller's
+transaction; revocation can join one or open its own.
 
 Acceptance/refusal return 401 for unauthenticated access, 403 for a recipient
 email mismatch and 404 for a missing or handled invitation. A matching recipient's
@@ -435,7 +463,7 @@ Preserve `error.transactionOutcome` and `error.cause`: `rolledBack` confirms
 rollback, `committed` can accompany a failed completion hook, and `unknown`
 requires resolving the outcome before retrying. Errors after commit cannot undo
 persistence. See
-[managed transaction guidance](./existing-application-migration.md#json-rest-v2-integration).
+[managed transaction guidance](./existing-application-migration.md#data-access-on-table-resources-json-rest-api-3).
 
 Invitation mutations lock workspace before invitation rows. A losing acceptance,
 refusal, revocation or replacement cannot overwrite accepted/revoked state.
@@ -494,7 +522,41 @@ Workspace surfaces put the slug in their pages root, such as
 `w/[workspaceSlug]/admin` for administration. Keep the default surface
 (`surfaceDefaultId`, usually `home`) free of a workspace requirement: `/`,
 invitation links and other unscoped pages belong to it. With
-`webRootAllowed: "no"`, `/` opens that surface's root.
+`webRootAllowed: "no"`, `/` opens that surface's root. The foundation
+defines `home` and its `public` access policy, and the `auth/auth-surface`
+pattern the `auth` surface; the workspace surfaces add a policy and two
+definitions:
+
+```js
+// config/surfaceAccessPolicies.js
+surfaceAccessPolicies.workspace_member = { requireAuth: true, requireWorkspaceMembership: true };
+
+// config/public.js
+config.surfaceDefinitions.app = {
+  id: "app",
+  label: "App",
+  pagesRoot: "w/[workspaceSlug]",
+  requiresAuth: true,
+  requiresWorkspace: true,
+  accessPolicyId: "workspace_member"
+};
+config.surfaceDefinitions.admin = {
+  id: "admin",
+  label: "Admin",
+  pagesRoot: "w/[workspaceSlug]/admin",
+  requiresAuth: true,
+  requiresWorkspace: true,
+  accessPolicyId: "workspace_member"
+};
+```
+
+An access policy takes `requireAuth`, `requireWorkspaceMembership`,
+`requireAnyPermissions` and `requireAllPermissions` (permission lists), and
+`requireFlagsAny` and `requireFlagsAll` (flags the server's bootstrap sets in
+`surfaceAccess`). Without `requireAuth` or `requireWorkspaceMembership` it
+takes the surface's `requiresAuth` or `requiresWorkspace`. The browser applies
+the whole policy; the server reads only `requireWorkspaceMembership: false`
+from it, and a route's own `auth` and `permission` authorize it there.
 
 `workspaces-web` remembers the last workspace each person opened in this
 browser. The **Your workspaces** page, `WorkspacesClientElement` from

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

@@ -58,7 +58,7 @@ questions and must not be copied into committed source.
 ## Build the first product operation
 
 Use the narrow relevant pattern and public APIs. For database CRUD, author an
-immutable migration and a normal shared resource contract; use framework APIs
+immutable migration, its table resource and, for screens, a CRUD contract; use framework APIs
 for standard mechanics and app code for product-specific behavior. Do not
 invoke a source generator or reconstruct one as prompt options.
 

package/guide/agent/app-setup/run-an-accounts-hub.md

@@ -9,7 +9,7 @@ hub shows its sign-in page, the app receives an ID token, and the app keeps its
 own session.
 
 ```bash
-npm install @jskit-ai/oidc-issuer-core @jskit-ai/database-runtime-mysql
+npm install @jskit-ai/oidc-issuer-core @jskit-ai/database-runtime @jskit-ai/database-runtime-mysql
 ```
 
 Start from the "JSKIT · Accounts hub" template (seed-jskit branch

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

@@ -62,7 +62,10 @@ npm run jskit:update
 ```
 
 The updater rejects unknown JSKIT packages and private JSKIT overrides during
-preflight, before changing any manifest.
+preflight, before changing any manifest. It removes a package a release retired
+(`@jskit-ai/json-rest-api-core`, replaced by `@jskit-ai/resource-runtime`) and
+says what replaced it; while the application's code still imports a retired
+package, it refuses and names the import to use instead.
 
 `jskit:update` reads the latest published catalog, discovers the root manifest
 and npm workspaces, and preflights every declared `@jskit-ai/*` package. It then
@@ -78,6 +81,15 @@ installation, or validation fails, it restores the previous manifests,
 lockfile, and installed tree before reporting the failure. Resolve the reported
 registry or real peer problem and rerun `npm run jskit:update`.
 
+When the install brings package migrations the application has not had, the
+updater lists each one (`<package>: <file>`) and says to run
+`npm run db:migrate`. Run it, on every database the application uses, before
+the new version serves requests: a package's new version reads what its
+migration creates, so until then those reads fail, such as every local sign-in
+with an unknown `email_verified_at` column. Read each package's CHANGELOG
+**Upgrading** section too, for the changes the application itself must make,
+such as a feature to register.
+
 ## Separately composed packages
 
 Pass each additional manifest explicitly to both commands:
@@ -210,8 +222,10 @@ application:
    `defineConfig(browserTestConfig({ testDir: "./tests/e2e", prepare: "tests/e2e/databases.js" }))`
    from `@jskit-ai/jskit-catalog/browser-tests`, with `server`, `build`, `env`
    or `port` only where its own differ from `node ./bin/server.js`,
-   `npm run build` and 4173, and `globalTimeout` only for a suite measured to
-   need more than 20 minutes. Settings a config adds (projects, a globalSetup
+   `npm run build` and 4173, `globalTimeout` only for a suite measured to
+   need more than 20 minutes, and `actionTimeout` or `navigationTimeout` only
+   for an action or page measured to need more than 15 or 30 seconds (a stale
+   locator should fail in seconds, not minutes). Settings a config adds (projects, a globalSetup
    that proves the server's identity, `timezoneId`) spread over the result:
    `defineConfig({ ...base, projects, use: { ...base.use, timezoneId } })`. A
    second local Playwright config and any `npm run develop` or `vite`

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

@@ -44,11 +44,14 @@ in-page banner that moves the form.
 
 Use `users/user-administration-server` only when the product needs global or
 workspace-scoped administration beyond self-service settings. It demonstrates
-an app-owned feature package built with `defineCrudJsonApiFeature()` while
-keeping profile persistence in `users-core`.
-
-Do not expose password hashes, provider credentials, or session data through a
-user resource. Apply permission and workspace scope before repository access so
+an app-owned feature package built with `defineCrudFeature()` on a CRUD
+contract over users-core's `userProfileTableResource`, while keeping profile
+persistence, and the `users` table's one table resource, in `users-core`: the
+feature names `ownerRepository: "users.profiles"` and serves the table through
+users-core's repository instead of owning it.
+
+Do not expose password hashes, provider credentials, or session data through
+the CRUD contract. Apply permission and workspace scope before repository access so
 record existence is not leaked.
 
 ## Verification

package/guide/agent/framework/application-operations.md

@@ -101,7 +101,7 @@ normal order is:
 
 1. confirm the product resource, ownership, operations, and fields
 2. author a migration as normal application source
-3. author the shared resource contract through `resource-crud-core`
+3. define the table resource (`defineTableResource`) and, for screens, its CRUD contract (`defineCrudContract`)
 4. use framework APIs for standard repository/service/action/route mechanics
 5. author product-specific screens from the relevant UI pattern
 6. run migrations and direct verification