@jskit-ai/agent-docs 0.1.278 → 0.1.280

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

@@ -438,6 +438,9 @@ record declares `mode: "patch"`; a command never does.**
 
 - Patch mode skips `required`, so a service keeps its guard for a field a
   patch input lists as required.
+- An input field lists its allowed values with `enum`; the kernel refuses
+  `oneOf` on an input field at startup, because json-rest-schema checks no
+  `oneOf` and the field would accept any value.
 
 Why: a command whose required field is never enforced reaches the service
 without it.
@@ -639,7 +642,7 @@ way (is this user an operator) is a member of its owner's capability.**
 - A helper two packages of an application use lives in its shared package,
   never inside one of them.
 
-Why: copies drift, and the next reader cannot tell which one is right.
+Why: the kernel's helpers fix one meaning of empty, and a copy brings its own.
 
 ```js
 // good
@@ -668,7 +671,8 @@ helper, never by hand.**
 | the workspace a request asks for, before any action context | `requestedWorkspaceScope(request)` (`@jskit-ai/workspaces-core/server/support/workspaceRouteInput`) |
 | a context's workspace id | `resolveWorkspaceScopeValue(context)` (`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`) |
 
-Why: each hand-written copy treats a missing value its own way.
+Why: each reader knows every place JSKIT keeps its fact (`trx` or
+`transaction`, a tagged result's wrapper), and a hand read misses one.
 
 ```js
 // good
@@ -688,11 +692,17 @@ page means "the first 20 rows".**
 - json-rest-api answers a query that names no page with the resource's
   default page, 20 rows, and says nothing about the rest. The CRUD
   repository's `queryDocuments(query)` without a `limit` is the same first
-  page.
-- The helper reads cursor pages of the resource's maximum size
-  (`queryMaxLimit`, 100 unless the resource sets it) in id order until none
-  follows, keeping the call's transaction and context, so no row is skipped
-  or repeated. It sets the page and sort itself; sort the rows it returns.
+  page, and one with a `limit` above its `queryMaxLimit()` (100) throws,
+  because json-rest-api would answer only 100. A CRUD read of every record
+  uses the repository's `queryEveryDocument(query, options)`, which answers
+  one JSON:API document `{ data, included }` with no `limit`, `cursor` or
+  `sort`.
+- The helper reads cursor pages of 1,000 rows (json-rest-api's server-only
+  `pageSizeLimit`; a resource whose `queryMaxLimit` is larger uses that) in id
+  order until none follows, keeping the call's transaction and context, so no
+  row is skipped or repeated. Each page pays the row policy and linkage
+  queries once, so 480 rows cost 3 statements, not 15. It sets the page and
+  sort itself; sort the rows it returns.
 - A lookup by a unique key (an id, a slug, a token hash, a unique pair such
   as workspace and user) matches at most one row and may read `rows[0]` of a
   plain query. A read of the newest or first few rows names its own `sort`
@@ -719,33 +729,35 @@ const rows = extractJsonRestCollectionRows(await api.resources.workspaceMembersh
 }, createJsonRestContext(options.context)));
 ```
 
-### One read per table
+### Lists read related rows in batches
 
-**A read that builds a list reads each table once for the whole list: one
-query per table with an id-list filter, the rows grouped in memory. It never
-reads one row, or runs one lookup, per item of the list.**
+**A read that builds a list fetches its related rows in batches, an id-list
+query per related table, and groups them in memory, so its query count follows
+the tables and pages it reads, not the rows.**
 
-- Collect the ids from the first read, then read each related table once with
-  an id-list filter: a `searchSchema` entry
+- Collect the ids from the first read, then read each related table with an
+  id-list filter: a `searchSchema` entry
   `{ type: "array", actualField: "<column>", filterOperator: "in" }`, read
   through `queryAllJsonRestCollectionRows()`, or the resource's `include`.
   Group the rows by id with `Map.groupBy()`.
-- `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
-  single-record read inside a loop over the list is a read per row, however
-  the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
-  item). So is a single-record helper reused for a list.
+- A count that grows with the rows means something runs per row:
+  `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
+  single-record read inside a loop over the list, however the loop is spelled
+  (`for`, `map` with `Promise.all`, a helper called per item), or a
+  single-record helper reused for a list.
 - Work derived from a row (hashing, preparing a form, assembling a snapshot)
   runs once per distinct input in the call, not once per row it appears in.
-- The list's query count follows its tables and pages (100 rows a page unless
-  the resource sets `queryMaxLimit`), never its rows: three hundred invoices
-  and their lines take a handful of queries, not three hundred more (see
-  [Budgets at realistic counts](#budgets-at-realistic-counts)).
+- A JSON:API read also costs a few lookup and visibility queries per page and
+  relationship field, and pages hold the resource's `queryMaxLimit` (100 rows
+  unless it sets one). That cost follows pages, so three hundred invoices take
+  a few more queries than ten, not three hundred more ([Query counts at
+  realistic sizes](#query-counts-at-realistic-sizes)).
 
-Why: a read per row costs nothing with three test rows and seconds with a few
-hundred real ones, and every lookup and visibility check inside it repeats too.
+Why: each JSKIT single-record read runs its lookups and row policy too, so a
+read per row repeats all of them.
 
 ```js
-// good: one read per table, however many invoices there are
+// good: a read per related table, however many invoices there are
 const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
   queryParams: { filters: { workspace: workspaceId } },
   transaction: resolveTransaction(options),
@@ -779,21 +791,25 @@ paying a read policy for every row it writes.**
   [row policies heuristic](heuristics/row-policies.md)
   has the policy contract and its package composition.
 - The policy runs on every single-record read, and a CRUD write includes one:
-  `createDocument()` and `patchDocumentById()` write with `returning: "full"`
-  and read the record back through the policy, and `patch` and `delete` first
-  look the record up through it. A write therefore pays the read policy for
-  each row it writes.
-- A write path decides access once, inside its transaction. A batch write (a
-  delivery, an import, a fan-out) whose per-row read-back would pay an
-  expensive policy writes through a repository method added with
-  `decorateRepository`, on `resolveRepoClient(database.knex, options)`,
-  setting the same columns the resource would, its ownership columns
-  included, and reading back only what it returns.
-- Its test runs one read and one write for a subject with a short history and
-  with a realistic long one, and asserts the same query count.
-
-Why: a check sized by history grows with every record the subject receives,
-so the same write that takes milliseconds in a test takes seconds a year later.
+  `createDocument()` and `patchDocumentById()` default to `returning: "full"`,
+  which reads the record back through the policy, and `patch` and `delete`
+  first look the record up through it.
+- A write path decides access once, inside its transaction. A write that does
+  not use its result passes `returning: "minimal"` or `"none"`, and a batch of
+  creates (a delivery, an import, a fan-out) goes through
+  `createDocuments(payloads, { trx, context })`, which reads nothing back
+  unless asked
+  ([writes that return less](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#writes-that-return-less)).
+  Any other batch whose per-row lookup would pay an expensive policy writes
+  through a repository method added with `decorateRepository`, on
+  `resolveRepoClient(database.knex, options)`, setting the same columns the
+  resource would, its ownership columns included.
+- Its test counts the queries of one read and one write for a subject with a
+  short history and for one with a long one ([Query counts at realistic
+  sizes](#query-counts-at-realistic-sizes)).
+
+Why: the row policy runs on every read, write read-back and lookup, so every
+request pays what it costs.
 
 ```js
 // good: one predicate on the row being read
@@ -930,7 +946,8 @@ carries on.**
   (`response.body.cancel()`), for queue tails whose error reaches the queued
   caller, and for client best effort, each with a short comment saying so.
 
-Why: `() => {}` hides a wiring `TypeError` along with the failure.
+Why: a collaborator call's failure can be a wiring `TypeError`, and
+`() => {}` hides it with the rest.
 
 ```js
 // good
@@ -952,8 +969,8 @@ frame.**
 - Complete a double with the method the code calls, returning its neutral
   value; never shape production code around a double.
 
-Why: a double that mirrors internals pins them, so the test breaks on a
-refactor and passes on a real bug.
+Why: an owner's seams are its contract; its id formats and stream frames
+change with its package.
 
 ```js
 // good
@@ -972,8 +989,8 @@ double.**
 - One named clock per factory (`now = Date.now`) is a platform default, not a
   test seam.
 
-Why: a seam kept for tests is a shape no real caller uses, and a reader
-cannot tell it apart from one that matters.
+Why: a factory's parameters are its contract with the features that call it,
+and a test is not one of them.
 
 ```js
 // good
@@ -992,8 +1009,8 @@ through the feature, and pure helpers through `__testables`.**
 - `__testables` holds pure helpers only, never one that touches a
   collaborator or reads request facts.
 
-Why: a test-only export widens the module's API and invites production
-callers.
+Why: `__testables` is the one way a test reaches inside a module, so every
+other export is production API.
 
 ```js
 // good
@@ -1006,87 +1023,105 @@ export function resetInvoiceCacheForTests() {
 }
 ```
 
-### Budgets at realistic counts
+### Query counts at realistic sizes
 
-**A list, batch or write path has a database test at the row counts and
-history a real workspace holds, and that test fails above a fixed query
-budget, one that a read per row or a history-sized check cannot meet.**
+**A list, batch or write path's database test counts its queries with the
+test Knex instance's `query` event at a few rows and at a realistic number,
+and fails when the count grows with the rows instead of the pages.**
 
-- Seed hundreds of records and long per-person histories, not one to three
-  rows: a read per row and a history-sized policy cost nothing at three.
-- Count the queries with the test Knex instance's `query` event and assert a
-  ceiling: the count the correct implementation needs at that size, which a
-  read per row overshoots by hundreds. A path that pages nothing (one read,
-  one write) asserts the same count at a short and a long history. A query
-  count is stable in CI; also report the time the call took.
-- Meet the budget by fixing the reads ([One read per
-  table](#one-read-per-table), [Bounded access checks](#bounded-access-checks)),
-  never by shrinking the data or raising the budget.
+- Pages add a few queries; rows should add none. A path that pages nothing
+  (one read, one write) compares a short and a long history.
+- When it fails, fix the reads ([Lists read related rows in
+  batches](#lists-read-related-rows-in-batches), [Bounded access
+  checks](#bounded-access-checks)).
 
-Why: without a budget at real counts, a path that does one read per row ships,
-and its first sign is a request that takes seconds in production.
+Why: JSON:API reads add queries per page and relationship field, so comparing
+two sizes separates that cost from a read per row, where one fixed number
+cannot.
 
 ```js
 // good
-test("the invoice list reads each table once", async () => {
-  await seedInvoices(knex, { workspace, count: 300, linesEach: 5 });
+async function countQueries(knex, work) {
   let queries = 0;
   const count = () => { queries += 1; };
   knex.on("query", count);
   try {
-    await invoices.listWithLines(workspace, { context });
+    await work();
   } finally {
     knex.off("query", count);
   }
-  // A page of each table at a time; one read per invoice would add 300.
-  assert.ok(queries <= 40, `${queries} queries`);
+  return queries;
+}
+
+test("the invoice list's queries follow its pages, not its invoices", async () => {
+  const listAt = async (count) => {
+    const workspace = await createWorkspace(knex);
+    await seedInvoices(knex, { workspace, count, linesEach: 5 });
+    return countQueries(knex, () => invoices.listWithLines(workspace, { context }));
+  };
+  const few = await listAt(10);
+  const many = await listAt(300);
+  // Thirty times the invoices may add pages; a read per invoice would add about 290 queries.
+  assert.ok(many <= few * 2, `${few} queries for 10 invoices, ${many} for 300`);
 });
 
-// bad: three invoices and no budget, so a read per invoice passes
+// bad: three invoices, nothing counted, so a read per invoice passes
 test("the invoice list has its lines", async () => {
   await seedInvoices(knex, { workspace, count: 3, linesEach: 1 });
   assert.equal((await invoices.listWithLines(workspace, { context })).length, 3);
 });
 ```
 
-### Time limits are not fixes
-
-**A slow test, suite, preparation or request is a defect to find, never a time
-limit to raise. Measure where the time goes, fix that cause, and keep the
-default limits.**
-
-- Raising `--test-timeout`, a test's `{ timeout }`, Playwright's `timeout`,
-  `test.setTimeout()` or an `expect` timeout, adding retries, or calling a
-  request in a loop until it answers hides the cause and lets it grow.
-- Read the preparation phases' durations and the query counts first; the
-  cause is usually a read per row, a history-sized policy, or a database
-  prepared by replaying migrations ([Test databases are prepared
-  once](#test-databases-are-prepared-once)).
-- A longer limit is right only for work that is long by nature, such as a
-  fixture of deliberate size, and the test names that work.
-- A time limit still bounds every run, so a hang ends; it is not a speed
-  setting.
-
-Why: a raised limit absorbs today's slowness and every later one, until a run
-takes hours and nobody knows which change made it slow.
+### Test files run in parallel
+
+**A test suite runs its files in parallel, as many at a time as the machine's
+test budget allows: never one file at a time, and never more than the machine
+can take. Node's test runner runs through `jskit test`; Playwright's `workers`
+and Vitest's `maxWorkers` come from `testConcurrency()`.**
+
+- The budget is `V64_TEST_CONCURRENCY` when it is a positive whole number (a
+  test runner that hands out slots exports it for each run), otherwise half of
+  the machine's CPUs, rounded down and at least 1: a 2-vCPU VPS runs one file
+  at a time, an 8-thread machine four.
+- `jskit test` (from `@jskit-ai/jskit-catalog`) passes its arguments to
+  `node --test` and sets `--test-concurrency` to the budget.
+  `testConcurrency()` from `@jskit-ai/jskit-catalog/test-budget` returns the
+  same number for a config.
+- No script passes a fixed concurrency or worker count. `jskit check` fails a
+  package script that runs `node --test` directly or passes one, and a
+  Playwright or Vitest config those scripts use whose workers do not come from
+  `testConcurrency()` ([test-run rules](#test-run-rules)).
+- Each file isolates what it shares: a port the system picks (`listen(0)`), a
+  directory from `mkdtemp`, its own database or schema with a name no other
+  file uses, its own Vite `cacheDir` for each dev server it starts (Vite
+  replaces a shared dependency cache under servers still reading it), and no
+  writes into the source tree. Files that collide are isolated, never
+  serialised. A Playwright spec works on its own records, so
+  specs can share one server.
+- A file that truly cannot run beside others, because it holds a resource of
+  the whole machine, says why on its first line,
+  `// jskit-test: alone - <reason>`. `jskit test` runs it after the others,
+  one such file at a time, and fails on a marker without a reason or below the
+  first line.
+
+Why: `jskit test` and `testConcurrency()` read one budget, so every runner
+uses the machine without starving the other runs on it.
 
 ```js
-// good: the slow step was found and fixed, so the default limit holds
-test("delivers a batch of notices", async () => {
-  await deliveries.processBatch(workspace, { context });
-});
+// good: package.json "test": "jskit test", and playwright.config.mjs
+import { testConcurrency } from "@jskit-ai/jskit-catalog/test-budget";
 
-// bad
-test("delivers a batch of notices", { timeout: 600_000 }, async () => {
-  await deliveries.processBatch(workspace, { context });
-});
+export default defineConfig({ workers: testConcurrency() });
+
+// bad: "test": "node --test --test-concurrency=1", and
+export default defineConfig({ workers: 1 });
 ```
 
 ### Test databases are prepared once
 
-**A test run prepares each database once, from a stored snapshot of its
-schema, migration ledger and seed rows checked by a digest of their sources,
-and never replays the whole migration history inside the run.**
+**A test run prepares each database once and restores it from a stored
+snapshot of the schema, migration ledger and seed rows, checked by a digest of
+their sources.**
 
 - The snapshot is rebuilt only when the digest of the migration and seed
   sources changes, once and outside the timed tests; every disposable
@@ -1094,15 +1129,15 @@ and never replays the whole migration history inside the run.**
   it.
 - The full migration history runs once, in its own fresh-schema check
   ([database verification](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#verification)).
-- The harness reports each preparation phase and its duration, and the suite
-  has a time budget, so slow preparation shows instead of hiding inside the
+- The harness reports each preparation phase and its duration, and those
+  durations are read, so slow preparation shows instead of hiding inside the
   next test that waits for it.
 - The database layer guide's [integration test
   databases](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#integration-test-databases)
   gives the snapshot's contents per engine.
 
-Why: the migration history only grows, so a run that replays it whenever a
-schema changed gets slower with every migration the application adds.
+Why: an application's migrations include those of every installed package, so
+replaying them costs more with each package as well as each migration.
 
 ```js
 // good: the application's test support restores the snapshot its digest names
@@ -1120,6 +1155,10 @@ before(() => knex.migrate.latest());
 code: server, shared, client (`.vue` and `.js`) and scripts. One concern per
 factory.**
 
+- The limit is an outer bound, not a size to aim for: a file near it usually
+  holds more than one concern. Split it by concern; never trim lines or join
+  statements to fit.
+
 Why: a reader holds one concern at a time; a 2,000-line closure holds ten.
 
 ```text
@@ -1219,8 +1258,9 @@ Why: a comment that narrates history is wrong the day after it is written.
 ### Running the checks
 
 `npm run lint` runs ESLint with `@jskit-ai/config-eslint`, and `npm run
-verify` runs `jskit check` (the package graph), lint, the tests and the
-build. The foundations' `eslint.config.mjs` already holds a new
+verify` runs `jskit check` (the package graph, navigation and [test
+runs](#test-run-rules)), lint, the tests and the build. The foundations'
+`eslint.config.mjs` already holds a new
 application's code to every check:
 
 ```js
@@ -1292,6 +1332,19 @@ Every finding ends with a link to the section of this page that explains it.
 | `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) |
 | `max-lines`, `max-lines-per-function` | files over 750 lines, functions over 600 | [Size limits](#size-limits) |
 
+### Test-run rules
+
+`jskit check` reports these in every package script, and in the Playwright
+and Vitest configs those scripts use. No comment excuses them; a test file
+that must run alone says so on its own first line instead.
+
+| Rule | Reports | Section |
+| --- | --- | --- |
+| `test/node-test` | a script that runs `node --test` directly instead of `jskit test` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/fixed-concurrency` | `--test-concurrency` in a script | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-workers` | `--workers` or `-j` passed to `playwright test`, or its config without `workers: testConcurrency()` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/vitest-workers` | `--maxWorkers`, `--minWorkers` or `--no-file-parallelism` passed to Vitest, or its config without `maxWorkers: testConcurrency()` or with `fileParallelism: false` | [Test files run in parallel](#test-files-run-in-parallel) |
+
 The rules see shapes, not intent. Feature files, owned state beyond
 registries, shutdown, loggers, shared action fields, strict inputs, the action
 policy, request context, validated input, one reader per fact, routes,

package/skills/jskit/references/ui-operations.md

@@ -31,7 +31,9 @@ Cancel, Close, and a wizard's Previous step; keep existing unsaved-change
 guards.
 
 `createShellRouter()` owns scroll position (`shell/application-shell`
-pattern); never reset scroll in page components.
+pattern); never reset scroll in page components. An app's own scroll behaviour
+is its `scrollBehavior` option, never a `createRouter` wrapper's (that throws);
+a hash target opens below its `scroll-margin-top`.
 
 ## Application-owned files