@jskit-ai/agent-docs 0.1.292 → 0.1.294

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

@@ -103,10 +103,13 @@ audience contributor is registered and a target room is a user or workspace
 room, when its actor's contributed rooms include a target room or it has not
 signed in yet. A socket joins only its own actor's contributed rooms, so a
 publish to `workspace:7` checks that workspace's members' sockets, not every
-connected one. To decide, the publish resolves the contributed rooms of every
-signed-in socket's actor in one call to each contributor, whatever the number
-of sockets. Other sockets are not checked for that publish; the 30-second check
-reaches them. Sockets whose authentication requests are identical, such as tabs of
+connected one. To decide, the publish asks each contributor once about the
+actors of every signed-in socket outside the target rooms, whatever their
+number, naming only the target rooms' scopes, so a contributor reads only
+those (a publish to `workspace:7` reads workspace 7's memberships among them,
+and a publish to user rooms reads no memberships); meanwhile it looks up the
+contributed rooms of the actors already inside, for their checks. Other
+sockets are not checked for that publish; the 30-second check reaches them. Sockets whose authentication requests are identical, such as tabs of
 one browser, share one `authenticateRequest()` call within a publish or a
 30-second pass, and the sockets a publish or pass checks reuse that one lookup
 of their contributed rooms; nothing is reused from one publish or pass to the
@@ -140,12 +143,19 @@ them in one query rather than one per actor: it returns, or resolves to, a `Map`
 from actor id to that actor's event scopes (`{ kind: "user", id }`,
 `{ kind: "workspace", id }` or `{ kind: "workspace_user", workspaceId, userId }`);
 an actor it leaves out has none. A single actor is asked as a list of one.
+A publish asking whether actors outside its rooms belong to them calls
+`resolveActorsScopes(actorIds, { scopes })` with those rooms' scopes: the
+contributor may read only those scopes, and realtime keeps only them of its
+answer, so a contributor that ignores `scopes` still answers correctly.
 Realtime turns each scope into the same room an `event_scope` audience targets. Sockets
 join those rooms on connection and, on every revalidation, leave the contributed
 rooms the actor no longer belongs to; rooms joined by anything else are left
 alone. `@jskit-ai/workspaces-core` contributes the actors' active workspace
 memberships this way when realtime is installed, with
 `listActiveWorkspaceIdsByUserIds()`: one memberships query per 1,000 actors.
+Asked about some scopes, it reads only the memberships of the workspaces they
+name, with `listActiveWorkspaceIdsByUserIdsAmong()`, and none when they name
+no workspace.
 
 The authentication request includes parsed cookies, the `Host`, `Origin` and
 `X-Forwarded-Proto` headers when present, and the socket address and TLS state.

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

@@ -161,8 +161,15 @@ The login page shows either refusal, translated, with the wait.
 
 Local auth confirms the email address of each account it registers by
 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
+Two registrations whose email is already proven sign in at once instead: one
+through an invitation that a feature's invitation context resolver (such as
+workspace invites) resolves, still pending, for the registering email (letter
+case aside) and before its `expiresAt`, since its link reached that address;
+and the first account a production server's setup code admits (see below). An
+invitation passed through as given, with no resolver installed, or whose
+context names no email, proves nothing. Any other registration keeps 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. Confirming takes the link's code and the password the
 registration was made with (`POST /api/register/confirm` with
@@ -174,7 +181,9 @@ 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.
+confirm; a wrong password is an ordinary failed sign-in. The refusal holds
+even after `AUTH_LOCAL_EMAIL_CONFIRMATION=false`, which offers no
+confirming: the person registers again.
 
 A link's code is random, kept only as a hash, works once and expires after a
 day. Registering the same email again replaces the waiting registration whole
@@ -210,9 +219,10 @@ Confirmation guards self-registration. An app whose accounts are only invited,
 or created through the first account, sets `AUTH_LOCAL_SELF_REGISTRATION=false`
 and needs no confirmation sender: an invitation counts when a feature's
 invitation context resolver (such as workspace invites) resolves it for that
-email, and the first account is admitted by its setup code. In production
-without a sender, those registrations sign in at once; with one, they confirm
-as usual. An app that refused the register routes itself, with a 404 hook,
+email, and the first account is admitted by its setup code. Those
+registrations sign in at once, with or without a sender, except an invitation
+whose resolver names no email, which confirms when a sender is installed. An
+app that refused the register routes itself, with a 404 hook,
 can drop the hook for this setting. The sign-in page then shows its Register
 tab only to an invited person (an `invitationToken` in its address) and, while
 the app has no account, to the first one: local auth reports
@@ -289,8 +299,9 @@ field (capability `features.firstAccountSetupCode`), and the register body
 takes `setupCode`; letter case, spaces and dashes do not matter. A missing code
 is refused with 403 `auth.local.setup.codeRequired`, a wrong one with 403
 `auth.local.setup.codeInvalid`. An OAuth sign-in cannot create that first
-account. The registration then follows the ordinary rules, email confirmation
-included, and confirming it signs the owner in. The code admits registrations
+account. The registration then follows the ordinary rules, except that it
+needs no email confirmation: only the operator can read the code, so it signs
+the owner in at once. The code admits registrations
 until an account exists; then it stops working and its file is deleted, and
 registration needs no code again. Restarting before then makes a new code and
 the old one stops working: the latest log line and the file always agree, and

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

@@ -196,12 +196,21 @@ method takes the call's `options` last and joins the transaction of the
 | 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` |
+| `workspaces.memberships` | `findByWorkspaceIdAndUserId`, `ensureOwnerMembership`, `upsertMembership(workspaceId, userId, patch, options)`, `addMember({ workspaceId, userId, roleSid }, options)`, `activeMemberIds(workspaceId, options)`, `listActiveByWorkspaceId`, `findActiveByWorkspaceIdAndUserId`, `listActiveWorkspaceIdsByUserId`, `listActiveWorkspaceIdsByUserIds`, `listActiveWorkspaceIdsByUserIdsAmong(userIds, workspaceIds, options)`, `joinSource({ alias, filters }, options)` |
 
 `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
+every active member's user id, without their profiles: it reads all of the
+workspace's active memberships, so its cost grows with the workspace, and so
+do `listActiveByWorkspaceId`'s and
+`workspaces.services.members.listMembers(workspace, options)`'s. Use them where
+the work needs every member, such as a job, a delivery's recipients or a
+realtime audience. A screen or list reads a page instead:
+`workspaces.services.members.listMembersPage(workspace, { cursor, limit }, options)`
+answers one page of active members by display name (`limit`, 20 when none)
+with the `nextCursor` that asks for the next, null on the last, and an app's
+own list of members pages them in SQL with one report over the memberships'
+`joinSource`. `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
@@ -336,6 +345,7 @@ authorization and role checks. Do not pass arbitrary HTTP input as options.
 | `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. |
+| `workspaces.workspace-created-participant` (optional capability) | One application function receiving `({ workspace, owner }, options)` inside a new workspace's creation transaction. Without it, creation writes the workspace, its owner's membership and its settings only. |
 
 `sendInvite` accepts `{ createdInviteId, inviteTokenPreview }` from preparation or
 only `{ createdInviteId }` for a later attempt. The latter uses JSKIT's existing
@@ -471,6 +481,24 @@ Replacement can create a new pending invitation after acceptance while retaining
 the accepted invitation. Keep callbacks short: invitation changes in one workspace
 serialize. Deadlocks/serialization failures propagate without replaying callbacks.
 
+### Workspace creation participation
+
+Provide the optional `workspaces.workspace-created-participant` capability the
+same way, from a small application feature, to write application records for
+every new workspace in the same transaction. Both creation paths call
+`fn({ workspace, owner }, txOptions)`: the `workspace.workspaces.create` action
+(`createWorkspaceForAuthenticatedUser`) and a personal workspace's provisioning
+(`ensurePersonalWorkspaceForUser`, which joins its caller's transaction, such as
+a first sign-in's profile sync). It runs after the workspace, its owner's
+membership and its settings are written, so it can read them with `txOptions`.
+`workspace` and `owner` are shallow frozen. Pass `txOptions` to every write and
+let failures propagate: a failure rolls back the whole creation, workspace,
+membership, settings and the participant's own writes, and the caller receives
+the failure itself (an `AppError` answers as that refusal). Keep external effects
+out of it. An existing personal workspace is not created again and does not call
+it, and a create that loses its slug to the same owner's identical create answers
+that workspace without calling it a second time.
+
 ### Compatibility and verification
 
 Since `@jskit-ai/workspaces-core@0.1.198`, transactional `createInvite` callers

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

@@ -178,6 +178,10 @@ The check fails when:
 - installed package versions or root/workspace declarations disagree with the lockfile.
 - a package script runs tests outside the machine's test budget (`test/*`, see
   [Test files run in parallel](/guide/framework/typed-features#test-files-run-in-parallel)).
+- an application package's manifest (`jskit.capabilities`) misses a capability
+  its features provide or require, or provides one none of them does
+  (`manifest/capabilities`, see
+  [Package manifest](/guide/framework/typed-features#package-manifest)).
 
 Shared client owners such as the kernel, HTTP runtime, shell, auth web runtime,
 realtime runtime, and assistant runtime use exact peer dependencies where they

package/guide/agent/framework/client-features.md

@@ -389,6 +389,29 @@ const emit = defineEmits(["close"]);
 emit("closed");
 ```
 
+### Selection fields
+
+**A select, autocomplete or combobox whose options load from the server, or
+whose value is a record id, is `SelectField` from
+`@jskit-ai/http-web/client/components/SelectField`, with `loading` bound while
+the options load.** A raw `v-select`, `v-autocomplete` or `v-combobox` takes
+fixed options only: a list written out in the template, a top-level `const`
+holding one (as written, frozen, or `computed()` over one written out), or an
+import from a `shared` module. The model's name decides nothing.
+
+Why: Vuetify titles a value missing from `items` with the value itself, so a
+stored id such as `53` shows until the options arrive; `SelectField` hides it
+while `loading` is true.
+
+```vue
+<!-- good -->
+<SelectField v-model="form.serviceId" :items="services.items" :loading="services.loading" />
+<v-select v-model="form.size" :items="SIZE_OPTIONS" />
+
+<!-- bad: a stored id shows while the services load -->
+<v-select v-model="form.serviceId" :items="services.items" />
+```
+
 ### Presenting scripts
 
 **A component's `<script>` presents: props, emits, element refs, display
@@ -496,6 +519,33 @@ let attachmentClientSequence = 0;
 let pendingDraft = "";
 ```
 
+### Search on the server
+
+**A search over a list's records runs on the server: the list's search
+(`useList({ search: { enabled: true } })`) sends what the person types as `q`,
+and the table resource defines `searchSchema.q`. An autocomplete over a list's
+items or a lookup's options takes `no-filter` and sends the typed text with
+`@update:search` (a lookup's `setLookupSearch`).**
+
+Why: a list holds the page it loaded, so a search over its items misses every
+row past that page.
+
+```vue
+<!-- good: the server searches every record -->
+<SelectField v-model="formState.serviceId" searchable no-filter
+  :search="resolveLookupSearch('serviceId')"
+  @update:search="setLookupSearch('serviceId', $event)"
+  :items="resolveLookupItems('serviceId', { selectedValue: formState.serviceId })" />
+
+<!-- bad: Vuetify searches only the options already loaded -->
+<v-autocomplete v-model="serviceId" :items="services.items" />
+```
+
+```js
+// bad: a search over the page the list loaded
+const visible = computed(() => list.items.filter((service) => service.name.includes(search.value)));
+```
+
 ## Helpers and sizes
 
 ### One helper per package
@@ -563,6 +613,8 @@ client-only rules below. The server's action and error rules do not apply.
 | `jskit/no-frozen-vue-state` | `Object.freeze` over refs, computeds or reactive state | [Fixed result shape](#fixed-result-shape) |
 | `jskit/released-listeners` | a listener, interval, observer or subscription the file starts and never releases | [Released listeners](#released-listeners) |
 | `jskit/no-module-state` | a module-level `let`, `ref()` or `reactive()` | [Module state](#module-state) |
+| `jskit/selection-field` | a `v-select`, `v-autocomplete` or `v-combobox` whose items are not fixed, and a `SelectField` whose items are not fixed that binds no `loading` | [Selection fields](#selection-fields) |
+| `jskit/search-on-server` | a `computed()` that filters a list composable's items by a search ref; an autocomplete over a list's items or a lookup's options without `no-filter` or an `update:search` handler | [Search on the server](#search-on-the-server) |
 | `vue/require-prop-types`, `vue/require-default-prop`, `vue/require-valid-default-prop`, `vue/no-required-prop-with-default` | a prop without a type, optional without a default, or both | [Collaborator props](#collaborator-props) |
 | `vue/require-explicit-emits` | an emitted event the component does not declare | [Declared emits](#declared-emits) |
 
@@ -583,10 +635,11 @@ Simplicity, effect order and presenting scripts are checked by reading.
 Client exceptions use the
 [typed features exceptions](/guide/framework/typed-features#exceptions): a
 comment on the line before the finding, naming the rule or the finding, with a
-reason prefix. Client code adds three placements:
+reason prefix. Client code adds four placements:
 
 | Placement | The exception |
 | --- | --- |
 | `// readable-check: allow module-state - shared resource: <what the page shares>` | module state every instance on the page shares on purpose |
 | `<!-- readable-check: allow optional-call - optional operation: <what lacks it> -->` above an element | that element's bindings call an optional operation |
+| `<!-- readable-check: allow selection-field - data: <where the options come from> -->` above an element | a selection whose options are in memory and whose value is no record id |
 | `// readable-check: allow method-probe - input validation: <the shapes>` above a function | the probes of a function whose one job is normalizing an external value of several shapes |

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

@@ -256,6 +256,13 @@ mapping in the resource; do not add page-local filtering or duplicate request
 code. The full Books source example maps `q` to title, author and notes; narrow
 it when adapting the example to fewer fields.
 
+Every CRUD list also takes `id`, one record id or a list of them
+(`filter[id]` on the JSON:API transport), and answers only those of its rows,
+in the caller's scope. A picker whose selected values are not on the page it
+loaded reads them this way, all in one request, instead of showing their raw
+ids or reading pages until it finds them; `useCrudListFilterLookups()` does it
+for a lookup filter's chips and options.
+
 The browser page's route query and internal CRUD query use plain `q`. The
 JSON:API HTTP transport uses `filter[q]`. Shared CRUD clients encode and decode
 this automatically. Raw HTTP/API tests must send the transport key themselves:

package/guide/agent/framework/data-access.md

@@ -65,7 +65,9 @@ A grouped `aggregate` answers its groups from one statement, at most
 `pageLimits().request` of them (the resource's `queryMaxLimit`). When there
 are more it throws a 400 coded `RESOURCE_GROUP_LIMIT` instead of answering
 part of them. Narrow the filters, or read the groups in pages, `page: { size,
-number }` with `number` from 1, until a page answers fewer than `size` rows.
+number }` with `number` from 1. A page answers as a `query` page does, `{ rows,
+page: { size, number, hasMore, next } }`, never a bare array that could pass
+for every group: read the next while `page.hasMore`.
 Page numbers are offsets, so read every page before work that changes what
 the filters match.
 
@@ -715,12 +717,12 @@ takes first.
 // good: the lock is the transaction's first read, so the bookings read after it are current
 const reserve = (seatId, options) => seats.withTransaction(options, async (txOptions) => {
   await seats.lock(seatId, { ...txOptions, fields: ["status"] });
-  const taken = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
-  return taken.length > 0 ? null : bookings.create({ seatId }, { ...txOptions, returning: "id" });
+  const [taken] = await bookings.queryAll({ filters: { seatIds: [seatId] }, take: 1 }, txOptions);
+  return taken ? null : bookings.create({ seatId }, { ...txOptions, returning: "id" });
 });
 
 // bad: the read before the lock fixed the snapshot, so a booking committed while the lock waited is missed
-const free = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
+const [booked] = await bookings.queryAll({ filters: { seatIds: [seatId] }, take: 1 }, txOptions);
 await seats.lock(seatId, txOptions);
 ```
 
@@ -931,7 +933,11 @@ async function activeDays(memberIds, options) {
   `page.number` reads with OFFSET, which slows as the rows grow, so anything
   that grows pages with `page.after`. Each page is one statement, with no
   count: never walk pages to reach one.
-- A screen list never uses `queryAll`.
+- A screen list never uses `queryAll`, and neither does a picker: it reads
+  one page searched on the server as the person types (`q`), narrowed in the
+  query by what it depends on (the parent record, `active`), and reads its
+  selected values past that page by id. Reading every row for a dropdown, or
+  narrowing a page in code, either grows with the table or misses rows.
 - Related rows come by id list (`filters: { id: ids }`, or an `in` filter on
   another field) or `include`, grouped in memory. Never a query per row, however
   the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
@@ -987,6 +993,66 @@ const { records: firstPage } = await subscriptions.query({ filters: { newsletter
 
 Bad: a list read 100-row pages in a loop for each of 40 related sets.
 
+## Narrow in the query
+
+A read asks the store for exactly the rows the code uses. The filter, sort,
+limit, existence check and count go in the read, never in code over the rows
+it answered: a read of every row then narrowed is slow, and a page or a `take`
+then narrowed is also wrong, since the row wanted can sit past it.
+
+- Filter with the resource's searchSchema: a field
+  (`filters: { status: "open" }`), an id list (`filters: { id: ids }`, or an
+  `in` filter on another field), or `q` for typed text, whose `oneOf` names the
+  fields it searches.
+- One row: a unique filter with `take: 1` or `page: { size: 1 }`, which also
+  answers whether one exists. A count: `aggregate()`.
+- Never filter, find, slice or count the rows a read answered, nor skip some
+  in a loop. Mapping them and grouping them by a key (`Map.groupBy`) narrow
+  nothing, and neither does code that needs every row it read: rows handed on
+  whole (returned, passed, stored, mapped or walked in full) with a subset
+  derived beside them, and rows matched against other items in a loop or a
+  callback (an in-memory join, one read instead of one per item).
+- A lookup field's picker and a list's Search box send what the person types
+  as `q` to the server, which searches every row; `useList` does with
+  `search: { enabled: true }`. The table resource defines `searchSchema.q`.
+  Never search the page a list loaded in the browser: it misses every row past
+  it.
+- A CRUD list refuses a query key it does not take with a 400
+  (`crud.query.undeclaredKeys`). A list filter is declared in the feature's
+  `listFilterQueryValidator` and the resource's searchSchema.
+- Prove a capped read with a test that seeds past the cap and makes the row
+  the cap leaves out (the oldest, for a newest-first read) the one that
+  matches: the read that asks for it finds it; a read narrowed in code does
+  not.
+
+```js
+// good: the store answers one module's sections
+const { records } = await sections.query({ filters: { moduleId }, sort: ["-createdAt"], page: { size: 50 } }, options);
+
+// bad: the newest 200 sections of every module, then one module's kept in code
+const { records: recent } = await sections.query({ sort: ["-createdAt"], page: { size: 200 } }, options);
+const moduleSections = recent.filter((section) => section.moduleId === moduleId);
+
+// good: one row says who holds a unique username
+const [holder] = await profiles.queryAll({ filters: { usernames: [username] }, take: 1 }, options);
+```
+
+`jskit/narrow-in-query` reports `.filter()`, `.find()`, `.some()`,
+`.every()`, `.slice()`, a lone `.length` and a loop that skips rows with
+`continue` over the rows a read answered in the same function, unless the
+code also uses those rows whole, runs the narrowing once per item of
+something else, read at most one row, or slices a read that asked for one row
+more than it keeps (`limit(size + 1)`) to learn whether more follow.
+`jskit/search-on-server` reports a client search over a list's loaded items.
+`jskit check` fails a lookup field or a CRUD list screen whose app table
+resource has no `searchSchema.q`, on the resource or its owns entry
+(`data/search-q`). Other code that needs every row a read answers says why on
+the line above the read or the narrowing:
+
+```js
+// readable-check: allow narrow-in-query - every row: a conversation holds at most keep + 1 summaries, since each save deletes the older ones
+```
+
 ## What changed since
 
 A page that catches up on a chat, a watch that acts on changes and a sync to
@@ -1082,10 +1148,10 @@ const SettlementFeature = defineFeature({
   async function settleDue(options) {
     const size = cohorts.pageLimits().request;
     const due = [];
-    for (let number = 1; ; number += 1) {
-      const page = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" }, page: { size, number } }, options);
-      due.push(...page);
-      if (page.length < size) break;
+    for (let number = 1; number; ) {
+      const { rows, page } = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" }, page: { size, number } }, options);
+      due.push(...rows);
+      number = page.next;
     }
     for (const { workspaceId } of due) {
       await settleWorkspace({ context: systemContext("settle finished weekly leagues for every user").forWorkspace(workspaceId) });

package/guide/agent/framework/sanity-checks.md

@@ -67,13 +67,13 @@ expects the relationship id or an unselected field never gets it.
 ### Every row
 
 - A handle's `query()` answers one page and refuses a missing or oversized
-  `page.size`, where json-rest-api would cut the list silently. A read its
-  callers treat as complete uses `queryAll()`, or the missing rows vanish from
-  every picker and delivery built on it
+  `page.size`, where json-rest-api would cut the list silently. A delivery
+  reaching every row uses `queryAll()`; a picker reads a page searched with
+  `q` and its selected values by `id`
   ([Reads](/guide/framework/data-access#reads-shaped-for-the-screen)).
 - A grouped `aggregate()` answers every group or throws
   `RESOURCE_GROUP_LIMIT`; past `pageLimits().request` groups, page it with
-  `page: { size, number }`
+  `page: { size, number }` (answers `{ rows, page }`)
   ([The handle's calls](/guide/framework/data-access#the-handle-s-calls)).
 - A lookup by a unique key matches at most one row: `get(id)`, or a `query()`
   of page size 1.

package/guide/agent/framework/typed-features.md

@@ -81,6 +81,31 @@ setup: ({ resources }) => ({ invoices: { list: (options) => resources.invoices.q
 actions: ({ invoices }) => [{ id: "invoices.list", execute: () => invoices.list() }]
 ```
 
+### Package manifest
+
+**A package's manifest, `jskit.capabilities` in its `package.json`, lists
+exactly what its features provide, and every capability they require beyond
+the kernel's own (`runtime.actions`, `runtime.events`, `runtime.http`,
+`runtime.bootstrap`) and those the package provides itself.** Optional
+capabilities are not required. A requirement no feature has stays only when
+the package needs it at install time, such as the database its migrations
+need.
+
+Why: start-up resolves every package's requirements from the manifests, and
+refuses a manifest that disagrees with the package's features. Plain
+`jskit check` loads each application package's features (the server providers
+`jskit.runtime.server.providers` declares) and reports the drift before that
+(`manifest/capabilities`), each capability to add or remove; it lists the
+requirements no feature has for review.
+
+```jsonc
+// good: BooksFeature provides app.books and requires crud.contracts and runtime.actions
+"capabilities": { "provides": ["app.books"], "requires": ["crud.contracts"] }
+
+// bad: app.books missing from provides, crud.contracts from requires
+"capabilities": { "provides": ["app.book"], "requires": [] }
+```
+
 ### Capability types
 
 **Each provided token has one `@typedef` in its package's `src/server/types.js`,
@@ -627,9 +652,9 @@ Why: a value with two defaults has two meanings, and a mode flag hides a
 second method inside the first.
 
 ```js
-// good
-async function list(filters, options = {}) {
-  return invoices.queryAll({ filters }, options);
+// good: one page, as a list shows it
+async function list(filters, page, options = {}) {
+  return invoices.query({ filters, page }, options);
 }
 
 // bad
@@ -696,6 +721,11 @@ way (is this user an operator) is a member of its owner's capability.**
   meaning of 0 and false before replacing a copy.
 - A helper two packages of an application use lives in its shared package,
   never inside one of them.
+- A component's closure over its own state is not a helper: a function of at
+  most two statements in `<script setup>` whose every outside name is a
+  binding `<script setup>` declares (not an import or a global). Two pages
+  that reload their own resources the same way keep their own `reload()`;
+  sharing it would take a module that receives each page's state.
 
 Why: the kernel's helpers fix one meaning of empty, and a copy brings its own.
 
@@ -746,6 +776,13 @@ handle's `queryAll(params, options)`. A `query()` names its page size, and
 answers one page.** [Reads shaped for the screen](/guide/framework/data-access#reads-shaped-for-the-screen)
 gives the rules and examples.
 
+### Narrow in the query
+
+**A read asks for exactly the rows the code uses: its filter, sort, limit,
+existence check and count go in the read, never in code over the rows it
+answered.** [Narrow in the query](/guide/framework/data-access#narrow-in-the-query)
+gives the rules and examples.
+
 ### Lists read related rows in batches
 
 **A read that builds a list fetches its related rows in batches, an id-list
@@ -1175,8 +1212,9 @@ Why: a comment that narrates history is wrong the day after it is written.
 
 `npm run lint` runs ESLint with `@jskit-ai/config-eslint`, and `npm run
 verify` runs `jskit check` (the package graph, navigation, [data
-access](/guide/framework/data-access#exceptions) and [test
-runs](#test-run-rules)), lint, the tests and the build. The foundations'
+access](/guide/framework/data-access#exceptions), [test
+runs](#test-run-rules) and [package manifests](#package-manifest)), lint, the
+tests and the build. The foundations'
 `eslint.config.mjs` already holds a new
 application's code to every check:
 
@@ -1246,6 +1284,7 @@ Every finding ends with a link to the section of this page that explains it.
 | `jskit/app-error-code` | an `AppError`, `DomainError`, `ConflictError` or `NotFoundError` (or a subclass the module declares) without its own code, and one code naming two sentences in a module | [Refusals carry their own code](#refusals-carry-their-own-code) |
 | `jskit/no-patched-error` | `Object.assign(new Error(…), { statusCode })`, or an error builder's result given its status afterwards | [One construction per error](#one-construction-per-error) |
 | `jskit/no-test-only-export` | an export whose name says only tests use it (`…ForTests`, `__reset…`; `__testables` aside) | [No test-only exports](#no-test-only-exports) |
+| `jskit/narrow-in-query` | `.filter()`, `.find()`, `.some()`, `.every()`, `.slice()`, a lone `.length` or a loop that skips with `continue`, over the rows a read in the same function answered and uses no other way | [Narrow in the query](#narrow-in-the-query) |
 | `jskit/one-property-per-line` | two properties on one line in a returned `Object.freeze({ … })` or a `requires` / `optional` / `provides` map (`eslint --fix` splits them) | [Formatter](#formatter) |
 | `jskit/jsdoc-description-inside` | a `//` description directly above a `/** */` block | [Comments](#comments) |
 | `jskit/allow-comment-form` | a `readable-check: allow` reason without a prefix from the table below, or one that cites tests or the state of a project | [Exceptions](#exceptions) |
@@ -1297,6 +1336,7 @@ if (typeof buildSerializer !== "function") {
 | `filled by <repository>; convert with its supplier` | keeps a setter that another repository's code calls |
 | `cross-repository slot <token>` | keeps a probe for a token another repository supplies |
 | `shared resource:` | keeps client module state that every instance on the page shares on purpose ([client features](/guide/framework/client-features#module-state)) |
+| `every row: <why>` | code needs every row a read answers and narrows them for its own use, such as a read the data itself keeps small (a conversation's few summaries) whose oldest ones it deletes (`jskit/narrow-in-query`) |
 | `infrastructure: <what the module is>` | excuses a whole file whose job is data access itself from `jskit/no-direct-knex` or `jskit/no-transaction-reader`, one line per rule before its first line of code ([data access](/guide/framework/data-access#exceptions)) |
 
 One kind of probe gets one prefix and one wording everywhere, and a bare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.292",
+  "version": "0.1.294",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,8 +5,8 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.17",
-    "json-rest-schema": "^1.0.17"
+    "@jskit-ai/kernel": "0.2.18",
+    "json-rest-schema": "^1.0.20"
   },
   "exports": {
     "./server/actions": "./src/server/bookingEngineActions.js",

package/patterns/minimal-foundation/example/AGENTS.md

@@ -74,7 +74,11 @@ Selection fields never show a stored id as text. A select, autocomplete or
 combobox whose options load from the server, or whose value is a record id,
 uses `SelectField` from `@jskit-ai/http-web/client/components/SelectField` with
 `loading` while the options load, not a raw `v-select`, `v-autocomplete` or
-`v-combobox`.
+`v-combobox`. The lint rule `jskit/selection-field` reports a raw one whose
+items are not fixed (a list written out, a top-level `const` holding one, or an
+import from a `shared` module) and a `SelectField` over loaded items without
+`loading`; a justified case says why in
+`<!-- readable-check: allow selection-field - data: <reason> -->` above it.
 
 Copied pattern source is ordinary application source. Do not add generator
 provenance, receipts, completion ledgers, or tooling-operation history. Keep

package/patterns/minimal-foundation/example/package.json

@@ -34,23 +34,23 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.17",
+    "@jskit-ai/kernel": "0.2.18",
     "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
-    "json-rest-schema": "^1.0.17",
+    "json-rest-schema": "^1.0.20",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.17",
+    "@jskit-ai/http-runtime": "0.2.18",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.248",
-    "@jskit-ai/jskit-catalog": "0.2.44",
+    "@jskit-ai/config-eslint": "0.1.250",
+    "@jskit-ai/jskit-catalog": "0.2.46",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/AGENTS.md

@@ -74,7 +74,11 @@ Selection fields never show a stored id as text. A select, autocomplete or
 combobox whose options load from the server, or whose value is a record id,
 uses `SelectField` from `@jskit-ai/http-web/client/components/SelectField` with
 `loading` while the options load, not a raw `v-select`, `v-autocomplete` or
-`v-combobox`.
+`v-combobox`. The lint rule `jskit/selection-field` reports a raw one whose
+items are not fixed (a list written out, a top-level `const` holding one, or an
+import from a `shared` module) and a `SelectField` over loaded items without
+`loading`; a justified case says why in
+`<!-- readable-check: allow selection-field - data: <reason> -->` above it.
 
 Copied pattern source is ordinary application source. Do not add generator
 provenance, receipts, completion ledgers, or tooling-operation history. Keep

package/patterns/shell-foundation/example/package.json

@@ -34,24 +34,24 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.17",
+    "@jskit-ai/kernel": "0.2.18",
     "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
-    "json-rest-schema": "^1.0.17",
+    "json-rest-schema": "^1.0.20",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.17",
-    "@jskit-ai/shell-web": "0.2.21",
+    "@jskit-ai/http-runtime": "0.2.18",
+    "@jskit-ai/shell-web": "0.2.23",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.248",
-    "@jskit-ai/jskit-catalog": "0.2.44",
+    "@jskit-ai/config-eslint": "0.1.250",
+    "@jskit-ai/jskit-catalog": "0.2.46",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.17"
+    "@jskit-ai/kernel": "0.2.18"
   },
   "jskit": {
     "kind": "runtime",