@jskit-ai/agent-docs 0.1.292 → 0.1.294

package/reference/autogen/tooling/config-eslint.md

@@ -219,6 +219,25 @@ Local functions
 - `typeKey(text, file, imports)`
 - `commentTypes(text)`
 
+### `plugin/rules/narrowInQuery.js`
+Exports
+- `narrowInQuery`
+Local functions
+- `literalProperty(object, key)`
+- `paramsLiteral(node)`
+- `objectLiteral(sourceCode, node)`
+- `literalNumber(object, key)`
+- `isOneMore(node)`
+- `pageBound(sourceCode, params)`
+- `builderChain(node)`
+- `limitCount(end, back)`
+- `isScopedBuilder(sourceCode, identifier)`
+- `readOf(sourceCode, call)`
+- `isRowsMember(expression)`
+- `useOf(expression)`
+- `repeatsPerItem(node, readNode)`
+- `statementLine(node)`
+
 ### `plugin/rules/noDirectKnex.js`
 Exports
 - `noDirectKnex`
@@ -248,7 +267,9 @@ Exports
 Local functions
 - `topLevelFunctions(program)`
 - `isNamedNoOp(fn)`
-- `topLevelHelpers(program, text)`
+- `inside(range, [start, end])`
+- `componentClosures(scopeManager, setupRanges)`
+- `topLevelHelpers(program, text, isComponentClosure)`
 - `comparisonRoot(file, packageDirectory)`
 - `compareCopies(left, right)`
 
@@ -370,6 +391,28 @@ Exports
 Local functions
 - `positionalCollaboratorDefaults(fn, visitorKeys)`
 
+### `plugin/rules/searchOnServer.js`
+Exports
+- `searchOnServer`
+Local functions
+- `isSearchName(name)`
+- `attribute(element, name, directive = "")`
+
+### `plugin/rules/selectionField.js`
+Exports
+- `selectionField`
+Local functions
+- `kebabName(rawName)`
+- `isWrittenList(node)`
+- `isWrittenValue(node)`
+- `computedResult(getter)`
+- `isFixedValue(node, { freezing, computing })`
+- `fixedBindings(program)`
+- `propAttribute(element, name)`
+- `bindsObject(element)`
+- `rootIdentifier(expression)`
+- `hasFixedItems(attribute, bindings)`
+
 ### `plugin/rules/sqlLiteral.js`
 Exports
 - `sqlLiteral`

package/reference/autogen/tooling/jskit-catalog.md

@@ -71,14 +71,35 @@ Exports
 - `ROOT`
 - `lintIgnores({ governed, config })`
 - `sourceFiles(root)`
+- `vueFiles(root)`
 Local functions
 - `skipsDirectory(name)`
-- `walk(root, directory, files)`
+- `walk(root, directory, files, pattern = SOURCE_FILE)`
 - `frameworkPackages(root)`
 - `appEslint(root)`
+- `configIgnoredBy(root, { eslint, ESLint })`
 - `lintConfigs(root, files)`
 - `skippedPaths(files, skipped)`
 
+### `scripts/data-access-source.mjs`
+Exports
+- `assignedVariable(masked, offset)`
+- `blank(text)`
+- `closingOffset(masked, start)`
+- `enclosingObject(masked, offset)`
+- `identifierAt(code, offset)`
+- `keyValue(code, masked, keys, key)`
+- `nextCodeOffset(text, offset)`
+- `objectArgument(masked, callOffset, matchLength)`
+- `objectAt(masked, offset)`
+- `objectKeys(masked, start, end)`
+- `readSourceFile(source)`
+- `readValue(code, masked, offset)`
+- `topLevelKeys(masked, start, end, names)`
+Local functions
+- `maskStrings(code)`
+- `constantValue(code, name)`
+
 ### `scripts/data-access.mjs`
 Exports
 - `checkDataAccess({ projectRoot = process.cwd() } = {})`
@@ -86,21 +107,14 @@ Exports
 - `readTableResourceSources({ projectRoot = process.cwd() } = {})`
 Local functions
 - `escapeRegExp(text)`
-- `blank(text)`
-- `maskStrings(code)`
-- `closingOffset(masked, start)`
-- `nextCodeOffset(text, offset)`
-- `constantValue(code, name)`
-- `readValue(code, masked, offset)`
-- `topLevelKeys(masked, start, end, names)`
-- `objectArgument(masked, callOffset, matchLength)`
-- `keyValue(code, masked, keys, key)`
-- `readSourceFile(source)`
-- `objectKeys(masked, start, end)`
-- `objectAt(masked, offset)`
 - `readSchemaFields(code, masked, keys, ownership)`
 - `readTableResources(file, { code, masked, position })`
+- `readSearchQ(masked, keys)`
 - `readCrudContracts({ code, masked })`
+- `readSearches(file, { code, masked, position })`
+- `vueScripts(source)`
+- `resourceNameFromNamespace(namespace)`
+- `checkSearchQ(resources, contracts, searches, report)`
 - `unnamedFields(resources, contracts)`
 - `ownsSystemContextName(source, masked)`
 - `readSystemScopes(file, { source, code, masked, position })`
@@ -166,6 +180,14 @@ Local functions
 - `runI18n({ subcommand, locale, projectRoot })`
 - `readCatalog()`
 
+### `scripts/manifest-capabilities.mjs`
+Exports
+- `checkManifestCapabilities({ projectRoot, manifests })`
+- `formatManifestCapabilitiesReport(result)`
+Local functions
+- `capabilityLine(contents, capabilityId = "")`
+- `kernelPlatform(manifestPath, root)`
+
 ### `scripts/material3-source.mjs`
 Exports
 - `DEFAULT_IMPORT`

package/skills/jskit/references/client-features.md

@@ -384,6 +384,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
@@ -491,6 +514,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
@@ -558,6 +608,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) |
 
@@ -578,10 +630,11 @@ Simplicity, effect order and presenting scripts are checked by reading.
 Client exceptions use the
 [typed features exceptions](typed-features.md#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/skills/jskit/references/crud-operations.md

@@ -250,6 +250,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/skills/jskit/references/data-access.md

@@ -60,7 +60,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.
 
@@ -710,12 +712,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);
 ```
 
@@ -926,7 +928,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
@@ -982,6 +988,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
@@ -1077,10 +1143,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/skills/jskit/references/heuristics/INDEX.md

@@ -38,7 +38,7 @@ How to use it:
   - [ui-contract.md](./ui-contract.md)
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - [filters.md](./filters.md)
-- `searchSchema`, `search: true`, `applyFilter`, server search, query validators, backend filters, internal JSON REST filters
+- `searchSchema`, `search: true`, `applyFilter`, server search, query validators, backend filters, internal JSON REST filters, picker search, `q`, filtering rows in code, `jskit/narrow-in-query`, `jskit/search-on-server`, `data/search-q`, `crud.query.undeclaredKeys`
   - [server-search.md](./server-search.md)
 - `actualField`, `storage.column`, `storage.writeSerializer`, `storage.virtual`, `queryFields`, computed field, virtual field, projection, `defaultTo`, datetime write serialization, temporalPrecision, json-rest-schema dates
   - [table-resource-fields.md](./table-resource-fields.md)

package/skills/jskit/references/heuristics/data-access.md

@@ -13,6 +13,7 @@ Pick the layer ([Data access](../data-access.md)):
 - Two requests could change the same rows: `lockMany` inside `withTransaction`, rows in id order.
 - Work inside `withTransaction`: `txOptions` is only `{ context, trx }`, so a key the work needs, the app's own included, comes from the method's `options`, and a write on the method's own table gets `{ ...options, ...txOptions }` so the caller's `returning`, `missing` or `format` reaches it.
 - A change only while a row still holds a value (open to booked, once): `patch` with `onlyIf`, or `patchWhere` with that value in its filters (a compare-and-set on every database, so of two concurrent writers one wins); a filter on a related table is refused on MySQL and MariaDB (`selection_cross_table`), so filter on the row's own columns, after locking the related rows with `lockMany`, or use `claim`.
+- Only some of the rows, one row, whether one exists: in the read (a searchSchema filter, `take: 1` or a page of size 1), never `.filter()`, `.find()`, `.some()`, `.slice()` or `.length` over the rows it answered ([Narrow in the query](../data-access.md#narrow-in-the-query)).
 - Counts, sums, buckets: `aggregate`; newest per group: a window include; anything else: one `scopedQuery()` method under `// Knex: <kind> - <reason>`.
 - Every workspace or user at once: a job with `systemScope`, finding its units with an `aggregate` grouped by the ownership field and looping over them, never rows.
 - A table another feature owns: its service or owner API, never its table. A report that joins it joins the `{ query, column }` its owner API answers from `scopedQuery({ alias })`, as a subquery: one statement, both scopes kept.

package/skills/jskit/references/heuristics/filters.md

@@ -132,6 +132,20 @@ Use `useCrudListFilterLookups(...)` when:
 - the UI needs remote autocomplete search
 - chips should show readable labels instead of raw ids
 
+A lookup filter's options are one server page, searched on the server as the
+person types (`setSearch`, sent as `q`):
+- the page keeps the server's order while more rows remain (`hasMore`), and is
+  sorted by label only once every row is loaded; `loadMore()` (or
+  `loadMoreLookup(key)`) reads the next page, so never present the first page
+  as the complete list
+- a selected value past the loaded page (from the URL or a bookmark) is read by
+  id, every such value in one request, so its chip shows its label
+- the options load when something shows them (the open filter sheet's
+  control, or a search), not with every list page
+- a lookup narrowed by another value (only active suppliers, only one
+  region's) passes it in `requestQueryParams[filterKey]`, which the lookup's
+  list must accept as a filter
+
 Use built-in `presence` when:
 - a filter means null vs not-null, such as assigned vs unassigned storage
 - the UI wants custom labels like "Assigned" / "Unassigned" but the transport contract can stay `present` / `missing`

package/skills/jskit/references/heuristics/server-search.md

@@ -243,6 +243,8 @@ owns: [{ resource: contactResource, rowPolicy: ownContactsOrShared }]
 - Put visibility in the owner's row policy, never in a search key or route query validation.
 - Do not expose a query key publicly just because the service maps to it internally.
 - Do not rely on route validators alone; a public key still needs a matching backend search definition.
+- A CRUD list refuses a query key its route does not declare with a 400 (`crud.query.undeclaredKeys`), so an undeclared filter fails loudly instead of answering every row.
+- Never narrow the rows a read answered in code, and never search a list's loaded page in the browser: the filter goes in the read, and a picker or Search box sends `q` ([Narrow in the query](../data-access.md#narrow-in-the-query); `jskit/narrow-in-query`, `jskit/search-on-server`, and `jskit check`'s `data/search-q` for a lookup or list screen whose resource has no `searchSchema.q`).
 
 ## Quick Rule Of Thumb
 

package/skills/jskit/references/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