@jskit-ai/agent-docs 0.1.275 → 0.1.276

package/guide/agent/app-setup/database-layer.md

@@ -365,6 +365,36 @@ Do not add migration receipts, sync ledgers, generator provenance, or dialect
 questionnaires. The installed graph, migration source, environment, and
 database migration table are sufficient.
 
+## Integration test databases
+
+Disposable integration and migration tests use `TEST_DB_NAME`. A test run
+prepares that schema once and restores it from a stored snapshot; it never
+rebuilds a database by replaying the whole migration history:
+
+- The snapshot holds the schema as the engine reports it (each table's
+  `SHOW CREATE TABLE` on MySQL and MariaDB, `pg_dump --schema-only` on
+  PostgreSQL), the migration ledger rows and the seed rows. Its key is a digest
+  of the migration files that the application's `migrations/` and its installed
+  packages supply, and of the seed source.
+- When that digest changes, the harness migrates one database once, outside
+  the timed tests, and stores a new snapshot. Otherwise it restores the stored
+  one. On PostgreSQL, `CREATE DATABASE <name> TEMPLATE <prepared>` copies a
+  prepared database that has no open connections.
+- A test that runs migrations up or down, or otherwise changes the schema,
+  leaves its database dirty. The harness restores the snapshot before another
+  test uses that database, instead of running `migrate.latest()` over the
+  whole history.
+- Only the fresh-schema check in [Verification](#verification) replays the
+  whole history, as its own step.
+- The harness reports each phase (digest, restore or rebuild, seed) with its
+  duration, and the suite has a time budget, so slow preparation is visible
+  instead of hiding inside the next test that waits for it. A slow phase is
+  fixed, never absorbed by a longer time limit.
+
+Endpoints and batch operations get their own database tests at realistic row
+counts with a fixed query budget; see the typed features guide's
+[budgets at realistic counts](/guide/framework/typed-features#budgets-at-realistic-counts).
+
 ## Browser test preparation
 
 Keep the test schema and migration history between routine browser runs. The

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

@@ -724,6 +724,107 @@ const rows = extractJsonRestCollectionRows(await api.resources.workspaceMembersh
 }, createJsonRestContext(options.context)));
 ```
 
+### One read per table
+
+**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.**
+
+- Collect the ids from the first read, then read each related table once 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.
+- 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)).
+
+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.
+
+```js
+// good: one read per table, however many invoices there are
+const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
+  queryParams: { filters: { workspace: workspaceId } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const lineRows = await queryAllJsonRestCollectionRows(api.resources.invoiceLines, {
+  queryParams: { filters: { invoiceIds: invoiceRows.map((invoice) => invoice.id) } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const linesByInvoice = Map.groupBy(lineRows, (line) => line.invoiceId);
+return invoiceRows.map((invoice) => ({ ...invoice, lines: linesByInvoice.get(invoice.id) || [] }));
+
+// bad: one more query, and its lookups and row policy, for every invoice
+for (const invoice of invoiceRows) {
+  invoice.lines = await invoiceLines.queryDocuments({ invoiceId: invoice.id }, options);
+}
+```
+
+### Bounded access checks
+
+**A row policy costs what the rows its query reads cost, never what the
+subject's stored history costs, and a write decides access once instead of
+paying a read policy for every row it writes.**
+
+- A `rowPolicy` adds one predicate to the query it is given: a join, `EXISTS`
+  or subquery correlated with the row being read, on indexed columns. It never
+  loads everything the subject was ever linked to (every source, notice or
+  grant in their history) to build an `IN` list, and never calls another
+  owner's access check once per item of that history. The
+  [row policies heuristic](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/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.
+
+```js
+// good: one predicate on the row being read
+function noticeVisibilityPolicy({ query, context, column, value, db }) {
+  const userId = resolveActorId(context);
+  if (!userId) return false;
+  query.where(column("recipientId"), value("recipientId", userId)).whereExists(
+    db("sources").select(1)
+      .whereColumn("sources.id", column("sourceId"))
+      .where("sources.status", "published")
+  );
+  return true;
+}
+
+// bad: every source the recipient was ever notified about, checked one by one
+async function noticeVisibilityPolicy({ query, context, column, value }) {
+  const sourceIds = await noticeHistory.listSourceIds(resolveActorId(context));
+  const readable = [];
+  for (const sourceId of sourceIds) {
+    if (await sources.canRead(sourceId, context)) readable.push(sourceId);
+  }
+  query.whereIn(column("sourceId"), readable.map((id) => value("sourceId", id)));
+  return true;
+}
+```
+
 ### Routes
 
 **A route does HTTP work only (status, cookies, redirects) and runs an action
@@ -910,6 +1011,112 @@ export function resetInvoiceCacheForTests() {
 }
 ```
 
+### Budgets at realistic counts
+
+**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.**
+
+- 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.
+
+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.
+
+```js
+// good
+test("the invoice list reads each table once", async () => {
+  await seedInvoices(knex, { workspace, count: 300, linesEach: 5 });
+  let queries = 0;
+  const count = () => { queries += 1; };
+  knex.on("query", count);
+  try {
+    await invoices.listWithLines(workspace, { context });
+  } 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`);
+});
+
+// bad: three invoices and no budget, 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.
+
+```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 });
+});
+
+// bad
+test("delivers a batch of notices", { timeout: 600_000 }, async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+```
+
+### 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.**
+
+- The snapshot is rebuilt only when the digest of the migration and seed
+  sources changes, once and outside the timed tests; every disposable
+  database, and every database a test migrated up or down, is restored from
+  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
+  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.
+
+```js
+// good: the application's test support restores the snapshot its digest names
+before(async () => restoreTestDatabase(knex, await testDatabaseSnapshot()));
+
+// bad: every file replays every migration
+before(() => knex.migrate.latest());
+```
+
 ## Files and layout
 
 ### Size limits

package/package.json

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

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

@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.28",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.28",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/reference/autogen/PATTERN_INDEX.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.276`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.276`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -345,7 +345,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.276`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`

package/skills/jskit/SKILL.md

@@ -121,3 +121,9 @@ Run focused tests for a slice and the application's `npm run verify` for a
 whole changeset. Use the current-state owners in application operations and
 Playwright for affected UI. There is no current JSKIT Doctor command; ignore
 old CLI authoring-history diagnoses. Never expose environment values.
+
+Tests and requests take the time their work needs, no more: a list reads each
+table once, a row policy is bounded by the rows it reads, list and batch paths
+have a query budget tested at realistic row counts, and test databases restore
+a stored snapshot instead of replaying migrations. Find why a check is slow;
+never raise its time limit. Typed features' repository and Tests rules say how.

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

@@ -42,9 +42,9 @@ How to use it:
   - [server-search.md](./server-search.md)
 - `actualField`, `storage.writeSerializer`, `storage.virtual`, computed field, virtual field, projection, `createCrudResourceRuntime`, datetime write serialization, temporalPrecision, json-rest-schema dates
   - [crud-repository-mapping.md](./crud-repository-mapping.md)
-- row policy, permission filtering, visibility before pagination, recursive CTE, descendants, package cycle, `RowPolicyPlugin`
+- row policy, permission filtering, visibility before pagination, recursive CTE, descendants, package cycle, `RowPolicyPlugin`, row policy cost, slow writes through a policy, access check per history item
   - [row-policies.md](./row-policies.md)
-- typed features, server feature, provider, service, repository, collaborator, `typeof`, `= null`, `setProvider`, `register`, `input || {}`, `payload = {}`, `async execute`, `Object.freeze`, `requires`, `optional`, `types.js`, `RuntimeKnex`, `silentLogger`, `create<Name>Actions`, `ActionSpecifications`, request context, `api.resources.x.query`, every row, list stops at 20 rows, `queryAllJsonRestCollectionRows`, `jskit/*` lint findings, `readable-check: allow`, `optional operation:`, `process.env`, `AppError` code, `Object.assign(new Error`, `idempotency`, `…ForTests` export, file or function size
+- typed features, server feature, provider, service, repository, collaborator, `typeof`, `= null`, `setProvider`, `register`, `input || {}`, `payload = {}`, `async execute`, `Object.freeze`, `requires`, `optional`, `types.js`, `RuntimeKnex`, `silentLogger`, `create<Name>Actions`, `ActionSpecifications`, request context, `api.resources.x.query`, every row, list stops at 20 rows, `queryAllJsonRestCollectionRows`, `jskit/*` lint findings, `readable-check: allow`, `optional operation:`, `process.env`, `AppError` code, `Object.assign(new Error`, `idempotency`, `…ForTests` export, file or function size, read per row, N+1 queries, slow endpoint, query budget, realistic row counts, slow tests, raised timeout, `migrate.latest()` in tests, test database snapshot
   - [typed-features.md](./typed-features.md)
 - client features, composable, `use<Name>`, Vue component, client provider, props, emits, `inject`, `provide`, `ref`, `reactive`, `watch`, `addEventListener`, `setInterval`, module state, `Object.freeze` on a composable, `?.()` in a template, `jskit/typed-inject`, `jskit/collaborator-props`, `jskit/fixed-result-shape`, `jskit/released-listeners`, `jskit/no-module-state`, `jskit/no-frozen-vue-state`, `clientFeaturesConfig`, `shared resource:`
   - [client-features.md](./client-features.md)

package/skills/jskit/references/heuristics/row-policies.md

@@ -8,6 +8,7 @@ Use when:
 - filtering after pagination produces empty or incomplete pages
 - another package grants access to a resource but a reverse dependency would create a cycle
 - the user mentions `RowPolicyPlugin`, recursive CTEs, descendants, or permission-filtered counts
+- reads or writes of a resource with a policy get slower as records or a person's history grow
 
 Read first:
 
@@ -36,6 +37,13 @@ Package composition:
 - the owner seals the contributions and builds the policy during `boot()`
 - do not use module-global mutable registries
 
+Cost:
+
+- a policy's cost follows the rows its query reads: add a join, `EXISTS` or subquery correlated with the row through `column()` and `value()`, on indexed columns
+- never load the subject's whole history (every source, notice or grant they were ever linked to) to build an `IN` list, and never call another owner's access check per item of it; another package's grant is a predicate contribution
+- the policy runs on every single-record read, including the read-back after `createDocument()` and `patchDocumentById()` (`returning: "full"`) and the lookup before `patch` and `delete`, so a write pays it once per row it writes
+- a write decides access once, inside its transaction; a batch write that would pay an expensive read-back per row follows the typed features guide's [Bounded access checks](../typed-features.md#bounded-access-checks)
+
 Child-resource rules:
 
 - a self-referencing relationship targets the same resource and receives the same row policy
@@ -50,6 +58,7 @@ Testing:
 - assert hidden direct records behave as not found
 - assert children and includes do not leak records
 - assert package and provider dependencies stay one-way
+- run one read and one write for a subject with a short history and with a realistic long one (hundreds of linked rows), and assert the same query count
 
 AnyAPI boundary:
 
@@ -65,3 +74,4 @@ Avoid:
 - adding a default policy file to every CRUD
 - returning a Knex builder or promise from a synchronous grouped contribution
 - swallowing a policy error and retrying without mandatory visibility
+- a policy that reads the subject's history or calls an access check per history item

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

@@ -65,6 +65,10 @@ ends with the same link.
   - [One reader per fact](../typed-features.md#one-reader-per-fact)
 - `api.resources.x.query(…)` with no `page` for a list, `queryDocuments(query)` with no `limit` in a service, a list that stops at 20 rows
   - [Every row](../typed-features.md#every-row)
+- `await getDocumentById(…)`, `queryDocuments(…)` or a service `get` inside a loop or a `Promise.all` over a list, a single-record helper reused for a list, N+1 queries, a slow list endpoint
+  - [One read per table](../typed-features.md#one-read-per-table)
+- a `rowPolicy` that loads a person's whole history or calls an access check per item, `createDocument` per row of a batch, a write that gets slower as history grows
+  - [Bounded access checks](../typed-features.md#bounded-access-checks)
 - a route that queries storage, `boot*.js` holding routes
   - [Routes](../typed-features.md#routes)
 - `new AppError(status, message)` with no code, `new NotFoundError("…")`, one code for two sentences (`jskit/app-error-code`)
@@ -81,6 +85,12 @@ ends with the same link.
   - [Tests are not callers](../typed-features.md#tests-are-not-callers)
 - `…ForTests`, `__reset…`, `testOnly…` exports (`jskit/no-test-only-export`)
   - [No test-only exports](../typed-features.md#no-test-only-exports)
+- a list, batch or write test with one to three rows, no query count, a slow endpoint first seen with real data
+  - [Budgets at realistic counts](../typed-features.md#budgets-at-realistic-counts)
+- a raised `{ timeout }`, `test.setTimeout()`, `--test-timeout` or Playwright `timeout`, retries or a request loop that absorbs slowness, a slow suite
+  - [Time limits are not fixes](../typed-features.md#time-limits-are-not-fixes)
+- `knex.migrate.latest()` in each test file, a template database rebuilt by migrating, test preparation slower than its tests
+  - [Test databases are prepared once](../typed-features.md#test-databases-are-prepared-once)
 - a file over 750 lines, a function over 600 (`max-lines`, `max-lines-per-function`), a data module
   - [Size limits](../typed-features.md#size-limits), [Data modules](../typed-features.md#data-modules)
 - two properties on one line in `Object.freeze({ … })` or a token map (`jskit/one-property-per-line`)
@@ -100,3 +110,5 @@ Avoid:
 - module-level registries
 - refusals without their own code
 - excusing a finding without a reason in its `readable-check: allow` comment
+- a read per row of a list, or an access check sized by stored history
+- raising a time limit instead of finding why a check is slow

package/skills/jskit/references/heuristics/ui-testing.md

@@ -65,11 +65,15 @@ in the regression: one test's teardown must not erase another test's migrations.
 
 Do not drop/recreate the database, replay completed migrations, build every
 module fixture, or run a production frontend build for each focused check.
-Choose small fixture sets for the selected suite. Fresh-schema migration tests
-and production-artifact tests are separate operations. Measure migration,
-fixture, and server startup time before retrying a slow launch or raising its
-deadline. When a host supplies a managed target, use its scoped suite command so
-one startup serves the whole batch and cleanup restores normal Preview.
+Choose small fixture sets for the selected suite; realistic row counts belong
+in the database tests that hold each endpoint's query budget. Fresh-schema
+migration tests and production-artifact tests are separate operations. Measure
+migration, fixture, and server startup time and fix the slow phase; never retry
+a slow launch, or raise its deadline or a spec's timeout, to absorb it. A page
+that needs a longer timeout to load is a slow endpoint to fix (typed features'
+Time limits are not fixes). When a host supplies a managed target, use its
+scoped suite command so one startup serves the whole batch and cleanup
+restores normal Preview.
 
 ## Keep browser evidence focused
 

package/skills/jskit/references/pattern-index.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.276`
 - Read: [PATTERN.md](patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.276`
 - Read: [PATTERN.md](patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -345,7 +345,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
-- Owner: `@jskit-ai/agent-docs@0.1.275`
+- Owner: `@jskit-ai/agent-docs@0.1.276`
 - Read: [PATTERN.md](patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`

package/skills/jskit/references/patterns/app/minimal-foundation/example/package.json

@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.28",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/skills/jskit/references/patterns/app/shell-foundation/example/package.json

@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.27",
+    "@jskit-ai/jskit-catalog": "0.2.28",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -719,6 +719,107 @@ const rows = extractJsonRestCollectionRows(await api.resources.workspaceMembersh
 }, createJsonRestContext(options.context)));
 ```
 
+### One read per table
+
+**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.**
+
+- Collect the ids from the first read, then read each related table once 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.
+- 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)).
+
+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.
+
+```js
+// good: one read per table, however many invoices there are
+const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
+  queryParams: { filters: { workspace: workspaceId } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const lineRows = await queryAllJsonRestCollectionRows(api.resources.invoiceLines, {
+  queryParams: { filters: { invoiceIds: invoiceRows.map((invoice) => invoice.id) } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const linesByInvoice = Map.groupBy(lineRows, (line) => line.invoiceId);
+return invoiceRows.map((invoice) => ({ ...invoice, lines: linesByInvoice.get(invoice.id) || [] }));
+
+// bad: one more query, and its lookups and row policy, for every invoice
+for (const invoice of invoiceRows) {
+  invoice.lines = await invoiceLines.queryDocuments({ invoiceId: invoice.id }, options);
+}
+```
+
+### Bounded access checks
+
+**A row policy costs what the rows its query reads cost, never what the
+subject's stored history costs, and a write decides access once instead of
+paying a read policy for every row it writes.**
+
+- A `rowPolicy` adds one predicate to the query it is given: a join, `EXISTS`
+  or subquery correlated with the row being read, on indexed columns. It never
+  loads everything the subject was ever linked to (every source, notice or
+  grant in their history) to build an `IN` list, and never calls another
+  owner's access check once per item of that history. The
+  [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.
+
+```js
+// good: one predicate on the row being read
+function noticeVisibilityPolicy({ query, context, column, value, db }) {
+  const userId = resolveActorId(context);
+  if (!userId) return false;
+  query.where(column("recipientId"), value("recipientId", userId)).whereExists(
+    db("sources").select(1)
+      .whereColumn("sources.id", column("sourceId"))
+      .where("sources.status", "published")
+  );
+  return true;
+}
+
+// bad: every source the recipient was ever notified about, checked one by one
+async function noticeVisibilityPolicy({ query, context, column, value }) {
+  const sourceIds = await noticeHistory.listSourceIds(resolveActorId(context));
+  const readable = [];
+  for (const sourceId of sourceIds) {
+    if (await sources.canRead(sourceId, context)) readable.push(sourceId);
+  }
+  query.whereIn(column("sourceId"), readable.map((id) => value("sourceId", id)));
+  return true;
+}
+```
+
 ### Routes
 
 **A route does HTTP work only (status, cookies, redirects) and runs an action
@@ -905,6 +1006,112 @@ export function resetInvoiceCacheForTests() {
 }
 ```
 
+### Budgets at realistic counts
+
+**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.**
+
+- 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.
+
+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.
+
+```js
+// good
+test("the invoice list reads each table once", async () => {
+  await seedInvoices(knex, { workspace, count: 300, linesEach: 5 });
+  let queries = 0;
+  const count = () => { queries += 1; };
+  knex.on("query", count);
+  try {
+    await invoices.listWithLines(workspace, { context });
+  } 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`);
+});
+
+// bad: three invoices and no budget, 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.
+
+```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 });
+});
+
+// bad
+test("delivers a batch of notices", { timeout: 600_000 }, async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+```
+
+### 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.**
+
+- The snapshot is rebuilt only when the digest of the migration and seed
+  sources changes, once and outside the timed tests; every disposable
+  database, and every database a test migrated up or down, is restored from
+  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
+  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.
+
+```js
+// good: the application's test support restores the snapshot its digest names
+before(async () => restoreTestDatabase(knex, await testDatabaseSnapshot()));
+
+// bad: every file replays every migration
+before(() => knex.migrate.latest());
+```
+
 ## Files and layout
 
 ### Size limits