@jskit-ai/agent-docs 0.1.282 → 0.1.284

package/skills/jskit/references/patterns/server/feature-package/example/variations/invoiceResource.js

@@ -0,0 +1,15 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+
+/** The invoices table: its fields, and the workspace that owns each row. Shared with the client. */
+const invoiceResource = defineTableResource({
+  name: "invoices",
+  tableName: "invoices",
+  ownership: "workspace",
+  schema: {
+    status: { type: "string", required: true, search: true },
+    amount: { type: "number", required: true },
+    issuedAt: { type: "dateTime", required: true }
+  }
+});
+
+export { invoiceResource };

package/skills/jskit/references/patterns/server/feature-package/example/variations/invoiceRollupActions.js

@@ -1,6 +1,6 @@
 import { emptyInputValidator } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 
-const ACTION_GET_ROLLUP_STATUS = "invoices.rollup.status.read";
+const ACTION_READ_MONTHLY_TOTALS = "invoices.rollup.monthly-totals.read";
 
 /** The fields every invoice rollup query shares, spread first into each definition: they run on the admin surface. */
 const ROLLUP_QUERY = Object.freeze({
@@ -15,12 +15,12 @@ function createInvoiceRollupActions({ invoiceRollup }) {
   return Object.freeze([
     Object.freeze({
       ...ROLLUP_QUERY,
-      id: ACTION_GET_ROLLUP_STATUS,
+      id: ACTION_READ_MONTHLY_TOTALS,
       input: emptyInputValidator,
       output: null,
-      execute: (input, context) => invoiceRollup.getStatus(input, { context })
+      execute: (input, context) => invoiceRollup.totalsByMonth(input, { context })
     })
   ]);
 }
 
-export { ACTION_GET_ROLLUP_STATUS, createInvoiceRollupActions };
+export { ACTION_READ_MONTHLY_TOTALS, createInvoiceRollupActions };

package/skills/jskit/references/patterns/server/feature-package/example/variations/ownedTableRepository.js

@@ -0,0 +1,27 @@
+/**
+ * The invoice rollup's persistence: the queries of the invoices table its
+ * feature owns, on that table's handle. The handle adds the workspace to every
+ * statement, so no query names it.
+ * @param {{ invoices: import("@jskit-ai/resource-runtime/server/types").ResourceHandle }} dependencies
+ */
+function createInvoiceRollup({ invoices }) {
+  /**
+   * How many invoices of each status the workspace issued each month, and their total.
+   * @param {Record<string, never>} input
+   * @param {import("@jskit-ai/resource-runtime/server/types").ResourceCallOptions} options
+   */
+  function totalsByMonth(input, options) {
+    return invoices.aggregate({
+      groupBy: ["status", { field: "issuedAt", bucket: "month", as: "month" }],
+      measures: { invoices: { count: "*" }, amount: { sum: "amount" } },
+      sort: ["month"]
+    }, options);
+  }
+
+  return Object.freeze({
+    withTransaction: invoices.withTransaction,
+    totalsByMonth
+  });
+}
+
+export { createInvoiceRollup };

package/skills/jskit/references/patterns/server/feature-package/example/variations/types.js

@@ -2,6 +2,6 @@
 // capabilities, for features that require them.
 
 /** @typedef {ReturnType<typeof import("./orchestratorService.js").createAvailabilityEngine>} AvailabilityEngine */
-/** @typedef {ReturnType<typeof import("./customKnexRepository.js").createInvoiceRollup>} InvoiceRollup */
+/** @typedef {ReturnType<typeof import("./ownedTableRepository.js").createInvoiceRollup>} InvoiceRollup */
 
 export {};

package/skills/jskit/references/patterns/users/user-administration-server/PATTERN.md

@@ -22,21 +22,66 @@ credentials, or an application that needs no administrative user listing.
 
 Choose global versus workspace scope, visible and editable fields, permission
 policy, route surface, filters, and whether account deletion is part of the
-product. Do not expose password/session data through the resource.
+product. Do not expose password, session or sign-in identity data through the
+CRUD contract.
 
 ## Framework APIs
 
 Use `@jskit-ai/users-core` for profile persistence and policies,
-`defineCrudJsonApiFeature()` from `@jskit-ai/crud-core` for standard mechanics,
-and the resource contracts from `@jskit-ai/resource-crud-core`.
+`defineCrudFeature()` from `@jskit-ai/crud-core` for standard mechanics,
+and `defineCrudContract()` from `@jskit-ai/resource-crud-core`.
+
+users-core is the `users` table's one owner, so an administration feature does
+not own it: `defineCrudFeature({ crud: userCrud, ownerRepository: "users.profiles", ... })`
+serves the CRUD contract through users-core's repository. The workspace
+variant also names `visibility: "workspace"`: its routes are a workspace's,
+so they resolve the caller's workspace and check its `crud.users.*`
+permissions. The `users` table is public, every user's, so the variant also
+narrows the repository to the workspace's members with `decorateRepository`
+(`src/server/workspaceMembersOnly.js`): a list reads only the active members
+from `workspaces.memberships`' `activeMemberIds`, and anyone else is a missing
+record, so a workspace admin never learns who else has an account. The narrowed
+repository answers only `query`, `get` and `pageLimits`: users.profiles' other
+methods (`findByEmail`, `countUsers`, the writes) read or write every user, so
+they never pass through it.
+
+The `users` table has one table resource, users-core's `userProfileTableResource`
+(`@jskit-ai/users-core/shared/resources/userProfileResource`). An
+administration package never defines a second one; `jskit check` fails a table
+with two. It builds its CRUD contract on that resource,
+`defineCrudContract(userProfileTableResource, { namespace, operations, fields })`,
+which chooses the operations, their namespace and the fields each returns; a
+field it does not name, such as the sign-in identity, is never shown. The
+list searches with the resource's `q` filter: every word in the display name,
+email or username.
+
+Other code that reads or writes the users' records (a decorated service, a
+hook, a job) requires their owners' capabilities, never the `users` or
+`user_settings` tables:
+
+- `users.profiles`: `findById`, `findByEmail`, `findByIdentity`,
+  `listByEmails(emails, options)` (one read), `upsert`,
+  `createWithSettings({ profile, settings }, options)` (the profile and its
+  settings in one transaction; settings start from the defaults),
+  `createWithId(profile, options)` (a profile keeping an earlier table's id),
+  `createManyIgnoringExisting(profiles, options)` (a re-runnable bulk import,
+  system context only), `changeUsername(userId, username, options)` and
+  `countUsers({ excludeIds, createdSince, authProvider }, options)`.
+- `users.settings`: `findByUserId`, `ensureForUserId` and the settings updates.
+
+Their types are `UsersProfiles` and `UsersSettings` in
+`@jskit-ai/users-core/server/types`. Every method takes `options` last and
+joins the caller's transaction: inside `withTransaction(options, async
+(txOptions) => …)`, pass `txOptions` to every call.
 
 ## Invariants
 
 - The public user id is the resource identity.
 - Workspace operations are scoped before repository access.
 - Permission checks happen before records or record existence are disclosed.
-- Shared profile persistence remains owned by `@jskit-ai/users-core`.
-- The resource is the field contract; the feature projects its repository,
+- Shared profile persistence remains owned by `@jskit-ai/users-core`, and so
+  does the `users` table's one table resource.
+- The CRUD contract is the field contract; the feature projects its repository,
   service, actions, and routes without app-local ceremony.
 - Each package exports the type of the capability it provides:
   `src/server/types.js` declares `AppUsers` (for `app.users`) or
@@ -54,9 +99,12 @@ and the resource contracts from `@jskit-ai/resource-crud-core`.
 
 `example/packages/users/` is a global administration package.
 `example/packages/users-workspace/` demonstrates the workspace route/action
-boundary, with workspaces-core's `WORKSPACE_CRUD_SCOPE`, while reusing the same
-service contract. Each package's
-`src/server/types.js` declares the type of the capability it provides. Copy only the composition
+boundary, with workspaces-core's `WORKSPACE_CRUD_SCOPE`, and lists only the
+workspace's members through the same service contract. Each package's `src/shared/userCrud.js` builds its CRUD
+contract on users-core's `userProfileTableResource`, its `package.json` requires
+`users.profiles` (users-core, which owns the table, must be installed), and its
+`src/server/types.js` declares the type of the capability it provides; the
+workspace variant also requires `workspaces.memberships`. Copy only the composition
 that matches the product and adapt it as ordinary application source.
 
 ## Variation points
@@ -71,9 +119,10 @@ isolation, missing records, null/cleared fields, filtering, and pagination.
 
 ## Avoid
 
-- copying authentication credential tables into the user resource
+- a second table resource on `users` or `user_settings`
+- copying authentication credential tables into the CRUD contract
 - trusting route scope without repository scope
-- adding app-local mechanics already provided by `defineCrudJsonApiFeature()`
+- adding app-local mechanics already provided by `defineCrudFeature()`
 - generator metadata or field questionnaires
 - probing a collaborator, defaulting one to `null`, `{}` or a no-op, setters
   that fill a slot after construction, and module-level registries

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/package.json

@@ -10,8 +10,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.14",
-    "@jskit-ai/resource-crud-core": "0.1.204"
+    "@jskit-ai/crud-core": "0.2.15",
+    "@jskit-ai/resource-crud-core": "0.1.205",
+    "@jskit-ai/users-core": "0.2.16"
   },
   "jskit": {
     "kind": "runtime",
@@ -20,10 +21,10 @@
         "app.users"
       ],
       "requires": [
+        "crud.contracts",
         "runtime.http",
-        "runtime.json-rest-api",
         "runtime.actions",
-        "runtime.database"
+        "users.profiles"
       ]
     },
     "runtime": {

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/server/UsersFeature.js

@@ -1,12 +1,14 @@
-import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
-import { resource } from "../shared/userResource.js";
+import { defineCrudFeature } from "@jskit-ai/crud-core/server/defineCrudFeature";
+import { userCrud } from "../shared/userCrud.js";
 
-const UsersFeature = defineCrudJsonApiFeature({
-  resource,
+// users-core owns the users table; this feature serves the administration
+// CRUD contract through its owner's repository.
+const UsersFeature = defineCrudFeature({
+  crud: userCrud,
+  ownerRepository: "users.profiles",
   id: "app.users",
   capability: "app.users",
   surface: "home",
-  ownershipFilter: "public",
   relativePath: "/users"
 });
 

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/shared/index.js

@@ -1 +1 @@
-export { resource } from "./userResource.js";
+export { userCrud } from "./userCrud.js";

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/shared/userCrud.js

@@ -0,0 +1,21 @@
+import { defineCrudContract } from "@jskit-ai/resource-crud-core/shared/crudContract";
+import { userProfileTableResource } from "@jskit-ai/users-core/shared/resources/userProfileResource";
+
+// The users list and view. The users table has one table resource, users-core's
+// userProfileTableResource; this contract chooses the operations and the fields they
+// return, and the list searches with the resource's q (display name, email and
+// username). It shows only the fields it names, so the sign-in identity and the
+// avatar's storage stay out of administration.
+const userCrud = defineCrudContract(userProfileTableResource, {
+  namespace: "users",
+  operations: ["list", "view"],
+  fields: {
+    displayName: { output: "optional" },
+    email: { output: "optional" },
+    username: { output: "optional" },
+    createdAt: { output: "required" },
+    updatedAt: { output: "required" }
+  }
+});
+
+export { userCrud };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/package.json

@@ -10,9 +10,14 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.14",
-    "@jskit-ai/resource-crud-core": "0.1.204",
-    "@jskit-ai/workspaces-core": "0.2.15"
+    "@jskit-ai/crud-core": "0.2.15",
+    "@jskit-ai/resource-crud-core": "0.1.205",
+    "@jskit-ai/users-core": "0.2.16",
+    "@jskit-ai/workspaces-core": "0.2.16"
+  },
+  "peerDependencies": {
+    "@jskit-ai/kernel": "0.2.14",
+    "@jskit-ai/resource-runtime": "0.2.12"
   },
   "jskit": {
     "kind": "runtime",
@@ -21,10 +26,11 @@
         "app.users-workspace"
       ],
       "requires": [
+        "crud.contracts",
         "runtime.http",
-        "runtime.json-rest-api",
         "runtime.actions",
-        "runtime.database"
+        "users.profiles",
+        "workspaces.memberships"
       ]
     },
     "runtime": {

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/server/UsersWorkspaceFeature.js

@@ -1,13 +1,22 @@
-import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
+import { defineCrudFeature } from "@jskit-ai/crud-core/server/defineCrudFeature";
 import { WORKSPACE_CRUD_SCOPE } from "@jskit-ai/workspaces-core/server/support/workspaceCrud";
-import { resource } from "../shared/userResource.js";
+import { userCrud } from "../shared/userCrud.js";
+import { workspaceMembersOnly } from "./workspaceMembersOnly.js";
 
-const UsersWorkspaceFeature = defineCrudJsonApiFeature({
-  resource,
+// users-core owns the users table; this feature serves the administration
+// CRUD contract on a workspace's admin surface through its owner's
+// repository. The routes are a workspace's, so they resolve the caller's
+// workspace and check its crud.users.* permissions, and the repository is
+// narrowed to that workspace's members: the users table is every user's.
+const UsersWorkspaceFeature = defineCrudFeature({
+  crud: userCrud,
+  ownerRepository: "users.profiles",
+  requires: { memberships: "workspaces.memberships" },
+  decorateRepository: ({ repository, memberships }) => workspaceMembersOnly(repository, memberships),
+  visibility: "workspace",
   id: "app.users-workspace",
   capability: "app.users-workspace",
   surface: "admin",
-  ownershipFilter: "workspace",
   relativePath: "/users",
   scope: WORKSPACE_CRUD_SCOPE
 });

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/server/workspaceMembersOnly.js

@@ -0,0 +1,52 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { passedOn, resolveWorkspaceScopeValue } from "@jskit-ai/resource-runtime/server";
+
+/**
+ * users-core's users repository narrowed to the caller's workspace: a list reads only the workspace's active members,
+ * and anyone else is a missing record, so a workspace admin never learns who else has an account. The users table is
+ * public, so its handle alone would list every user; the narrowing reads the workspace's memberships first. It answers
+ * only the reads it narrows (query and get, with pageLimits): the rest of users.profiles, such as findByEmail or
+ * countUsers, never passes through this feature's repository, so nothing reaches users past the narrowing through it.
+ * @param {import("@jskit-ai/crud-core/server/types").CrudRepository} repository
+ * @param {import("@jskit-ai/workspaces-core/server/types").WorkspaceMembershipsRepository} memberships
+ */
+function workspaceMembersOnly(repository, memberships) {
+  // The caller's workspace's active members; none when the context names no workspace. The memberships get only the
+  // context and transaction: the list's own settings (its format, missing) are for the users read.
+  function memberIds(options) {
+    return memberships.activeMemberIds(resolveWorkspaceScopeValue(options.context), passedOn(options));
+  }
+
+  /**
+   * One page of the workspace's members the params select.
+   * @param {Record<string, any>} params
+   * @param {{ context?: object }} options
+   */
+  async function query(params, options) {
+    const members = await memberIds(options);
+    const requested = params.filters?.id;
+    // An empty list matches no row: a workspace with no members lists nobody.
+    const id = requested === undefined ? members : [requested].flat().map(String).filter((memberId) => members.includes(memberId));
+    return repository.query({ ...params, filters: { ...params.filters, id } }, options);
+  }
+
+  /**
+   * A member of the workspace, or a missing record for anyone else.
+   * @param {unknown} id
+   * @param {Record<string, any>} params
+   * @param {{ context?: object, missing?: "skip" }} options
+   */
+  async function get(id, params, options) {
+    if ((await memberIds(options)).includes(String(id))) {
+      return repository.get(id, params, options);
+    }
+    if (options.missing === "skip") {
+      return null;
+    }
+    throw new AppError(404, "Document not found.", { code: "crud.document.notFound" });
+  }
+
+  return Object.freeze({ query, get, pageLimits: repository.pageLimits });
+}
+
+export { workspaceMembersOnly };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/shared/index.js

@@ -1 +1 @@
-export { resource } from "./userResource.js";
+export { userCrud } from "./userCrud.js";

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/shared/userCrud.js

@@ -0,0 +1,21 @@
+import { defineCrudContract } from "@jskit-ai/resource-crud-core/shared/crudContract";
+import { userProfileTableResource } from "@jskit-ai/users-core/shared/resources/userProfileResource";
+
+// The users list and view. The users table has one table resource, users-core's
+// userProfileTableResource; this contract chooses the operations and the fields they
+// return, and the list searches with the resource's q (display name, email and
+// username). It shows only the fields it names, so the sign-in identity and the
+// avatar's storage stay out of administration.
+const userCrud = defineCrudContract(userProfileTableResource, {
+  namespace: "users",
+  operations: ["list", "view"],
+  fields: {
+    displayName: { output: "optional" },
+    email: { output: "optional" },
+    username: { output: "optional" },
+    createdAt: { output: "required" },
+    updatedAt: { output: "required" }
+  }
+});
+
+export { userCrud };

package/skills/jskit/references/patterns/workspaces/workspace-server/PATTERN.md

@@ -66,20 +66,20 @@ catalogue entries. Updating labels requires no database migration.
 Provide one function as the optional `workspaces.invite-acceptance-participant`
 capability, from a small application feature that requires only what its writes
 need (it cannot require `workspaces.core`, which receives it). The built-in
-`workspace.invite.redeem` action invokes `fn({ invite, user }, { trx, context })`
+`workspace.invite.redeem` action invokes `fn({ invite, user }, txOptions)`
 after validating the recipient, state and expiry and activating membership in the
-uncommitted transaction. Forward `trx` to every application owner and propagate
-failures. JSKIT marks accepted and commits after the function succeeds. Keep
+uncommitted transaction. Pass `txOptions` to every application owner's calls and
+propagate failures. JSKIT marks accepted and commits after the function succeeds. Keep
 external effects out of it. Without the capability, acceptance activates the
 membership only. Allow ordinary invitations; reject stale, revoked, conflicting
 or unexpectedly missing application associations.
 
-Use `members.prepareInvite(workspace, actor,
-payload, { trx, context })` in `repositories.workspaceInvites.withTransaction`
-or the same JSON REST API's managed `transaction`. It returns
+Call `members.prepareInvite(workspace, actor, payload, txOptions)` inside
+`repositories.workspaceInvites.withTransaction(options, async (txOptions) => …)`
+or another resource handle's `withTransaction`. It returns
 `{ createdInviteId, inviteTokenPreview }` without delivery. Lock the workspace
-with `repositories.workspaceInvites.lockWorkspaceForInvitations(workspace.id,
-{ trx })` before application draft/receipt rows, and save the exact invitation
+with `lock(workspace.id, txOptions)` of the `workspaces` capability before
+application draft/receipt rows, and save the exact invitation
 association and retry receipt before commit. Failure restores the previous
 pending invitation. Keep access drafts separate: preparation creates a real token.
 
@@ -92,7 +92,7 @@ failure. A provider may accept a message before failing; the application owns
 receipts and retries. Keep tokens/URLs out of logs and use controlled mailers in tests.
 
 `createInvite`, acceptance and refusal own their managed transactions and
-reject a borrowed `options.trx`. Use preparation followed by delivery after commit for
+refuse a call made inside one (`withTransaction({ ...options, outermost: true }, work)`). Use preparation followed by delivery after commit for
 transactional creation; put related acceptance writes in the participant. Revocation may join
 a managed transaction. Raw Knex/savepoint transactions cannot own resource
 writes. Invitation mutations lock workspace then invitation rows, revalidate

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/PATTERN.md

@@ -54,6 +54,22 @@ the **Your workspaces** page at `src/pages/home/workspaces/index.vue`, member
 and settings routes, not-found state, app-owned invitation widgets, and the
 components that an application's client provider registers.
 
+`example/src/surfaces/<surface>/` and `example/src/pages/admin/` are each
+surface's own pages; the app puts them under the surface's `pagesRoot`. With
+`pagesRoot: "w/[workspaceSlug]"` for `app` and `"w/[workspaceSlug]/admin"` for
+`admin`:
+
+| Example file | App file |
+| --- | --- |
+| `src/surfaces/app/root.vue` | `src/pages/w/[workspaceSlug].vue` |
+| `src/surfaces/app/index.vue` | `src/pages/w/[workspaceSlug]/index.vue` |
+| `src/surfaces/admin/root.vue` | `src/pages/w/[workspaceSlug]/admin.vue` |
+| `src/surfaces/admin/index.vue` | `src/pages/w/[workspaceSlug]/admin/index.vue` |
+| `src/pages/admin/...` | `src/pages/w/[workspaceSlug]/admin/...` |
+
+The surface definitions and access policies they need are in the human
+guide's **Workspace tenancy → Surfaces and where `/` lands**.
+
 ## Variation points
 
 Change surfaces, routes, section owners, labels, icons, placement order,

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/pages/home/workspaces/index.vue

@@ -4,4 +4,6 @@
 
 <script setup>
 import WorkspacesClientElement from "@jskit-ai/workspaces-web/client/components/WorkspacesClientElement";
+
+definePage({ meta: { jskit: { parent: "/" } } });
 </script>

package/skills/jskit/references/sanity-checks.md

@@ -3,10 +3,10 @@
 # Sanity checks
 
 Before calling a list, a save, a test, a refactor, a screen or a deployment
-done, measure what it actually costs and does, judge whether that is sane, and
-fix the cause when it is not. This page is the JSKIT part of that: the
-pitfalls JSKIT's own packages cause, then which JSKIT call, helper or setting
-applies each check, with one line on what the check catches and why.
+done, measure what it costs and does, judge whether that is sane, and fix the
+cause when it is not. This page holds JSKIT's part: the pitfalls JSKIT's own
+packages cause, then the JSKIT call, helper or setting that applies each
+check, with one line on what it catches and why.
 
 ## JSKIT's own pitfalls
 
@@ -66,36 +66,35 @@ expects the relationship id or an unselected field never gets it.
 
 ### Every row
 
-- An unpaged JSON:API query returns the first 20 rows, and a page above the
-  resource's `queryMaxLimit` (100 unless it sets one) is cut to that size,
-  both without an error; CRUD `queryDocuments()` refuses such a `limit`. A
-  read its callers treat as complete uses `queryAllJsonRestCollectionRows()`
-  or the repository's `queryEveryDocument()`, because the missing rows
-  otherwise vanish from every picker and delivery built on it
-  ([Every row](typed-features.md#every-row)).
-- A lookup by a unique key matches at most one row, so it may read `rows[0]`
-  of a plain query.
+- A handle's `query()` answers one page and refuses a missing or oversized
+  `page.size`, because json-rest-api would otherwise cut the list without an
+  error. A read its callers treat as complete uses `queryAll()`, because the
+  missing rows otherwise vanish from every picker and delivery built on it
+  ([Reads](data-access.md#reads-shaped-for-the-screen)).
+- A lookup by a unique key matches at most one row: `get(id)`, or a `query()`
+  of page size 1.
 
 ### Query counts and batches
 
-- Count a path's queries with `countQueries()` from
-  `@jskit-ai/database-runtime/server/testDatabases` at a few rows and at a
+- Count a path's queries with `expectFlatQueries()` from
+  `@jskit-ai/resource-runtime/test`, or `countQueries()` from
+  `@jskit-ai/database-runtime/server/testDatabases`, at a few rows and at a
   realistic number; the count should follow tables and pages, not rows
-  ([Query counts at realistic
-  sizes](typed-features.md#query-counts-at-realistic-sizes)).
+  ([Tests](data-access.md#tests)).
 - A JSON:API read adds a few lookup and visibility queries per page and per
-  relationship field. That follows pages, so it is expected.
-- `getDocumentById()`, `queryDocuments()` or a service `get` inside a loop is
-  the usual per-row read; batch it with an id-list `searchSchema` filter or
-  `include`, grouped with `Map.groupBy()` ([Lists read related rows in
-  batches](typed-features.md#lists-read-related-rows-in-batches)).
+  relationship field, and json-rest-api reads each relationship's related ids
+  in one statement however many rows the page has. Both follow pages, not
+  rows, so `expectFlatQueries` passes them.
+- A handle's `get()` or `query()`, or a service `get`, inside a loop is the
+  usual per-row read; batch it with an id-list filter through `queryAll()` or
+  `include`, grouped with `Map.groupBy()`
+  ([Reads](data-access.md#reads-shaped-for-the-screen)).
 - A `rowPolicy` adds one correlated predicate to the query it is given, so
   its cost follows the rows read, not the subject's history. It runs on every
-  single-record read, including a write's default `returning: "full"` read
-  back, so a write that discards its result passes `returning: "minimal"` and
-  a batch of creates uses `createDocuments()`, in the owner's transaction
-  ([Bounded access
-  checks](typed-features.md#bounded-access-checks)).
+  single-record read, including a write's default `returning: "record"` read
+  back, so a write that discards its result passes `returning: "id"` or
+  `"none"`, and a batch uses the many-row writes (`createMany()`,
+  `patchMany()`) ([Layer 1](data-access.md#layer-1-the-table-resource)).
 
 ### Tests
 
@@ -113,7 +112,7 @@ expects the relationship id or an unselected field never gets it.
   duration, so slow preparation shows ([Test databases are prepared
   once](typed-features.md#test-databases-are-prepared-once),
   [integration test
-  databases](/guide/app-setup/database-layer#integration-test-databases)).
+  databases](database-layer.md#integration-test-databases)).
 
 ### Inputs and access