@jskit-ai/agent-docs 0.1.283 → 0.1.285

package/skills/jskit/references/existing-application-migration.md

@@ -96,31 +96,33 @@ application's normal verification script, and Playwright.
 
 ## 3. Choose the narrowest server seam that owns each behavior
 
-Conventional resources use `defineCrudResource()` and
-`defineCrudJsonApiFeature()` so JSKIT owns the repeated repository, service,
-permission, action, JSON API, and route mechanics. Extend that contract instead
+Conventional resources use `defineTableResource()`, `defineCrudContract()`
+and `defineCrudFeature()` so JSKIT owns the repeated repository,
+service, permission, action, JSON API, and route mechanics. Extend that contract instead
 of copying it.
 
 | Product need | Normal owner |
 | --- | --- |
 | Behavior before, around, or after one standard CRUD operation | `operationLifecycle` |
 | A resource-specific domain method or override | `decorateService` |
-| A resource-specific query, lock, or persistence operation | `decorateRepository` |
+| A resource-specific query, lock, or many-row write | `decorateRepository`, on the table's handle |
 | A named non-CRUD command on the resource | a named CRUD `action` backed by the service |
 | A separate aggregate, workflow, or capability domain | `defineFeature()` with named actions |
-| Persistence that the high-level resource APIs cannot express | an explicit custom repository owned by that Feature |
+| A report the handle cannot express | one `scopedQuery()` repository method, under `// Knex: <kind> - <reason>` ([data access](data-access.md#layer-5-reports-the-resource-cannot-express)) |
 
 For mutations, lifecycle phases before commit share one repository
 transaction. An `execute` hook that only normalizes input calls
-`standard(nextInput)` rather than reimplementing the write. Repositories own
-database access; services and hooks orchestrate repositories. External work
+`standard(nextInput)` rather than reimplementing the write. The feature that
+owns a table reads and writes it through the handles its `owns` entry gives
+its repository; services, hooks and other features call that repository or
+the owner's API, never the table. External work
 runs after commit, or a durable outbox record is written inside the transaction
 and delivered separately.
 
 Give commands product names such as `confirm`, `publish`, or `cancel`, with
 explicit input, permissions, routes where needed, audit behavior, events, and
 tests. Do not hide unrelated workflows behind a generic `execute(anything)`
-action, and do not create a custom repository merely because SQL is familiar.
+action, and do not write Knex merely because SQL is familiar.
 
 ### Reuse response serializers
 
@@ -143,9 +145,11 @@ upgrading JSKIT and declaring the directly used
 ```js
 import Fastify from "fastify";
 import SerializerSelector from "@fastify/fast-json-stringify-compiler";
-import { createCachedResponseSerializerFactory } from "@jskit-ai/kernel/server/http";
+import { createCachedResponseSerializerFactory, resolveTrustedProxies } from "@jskit-ai/kernel/server/http";
 
 const app = Fastify({
+  // TRUSTED_PROXIES: the proxies whose X-Forwarded-For is believed (loopback without it).
+  trustProxy: resolveTrustedProxies(runtimeEnv),
   schemaController: {
     compilersFactory: {
       buildSerializer: createCachedResponseSerializerFactory(SerializerSelector())
@@ -155,84 +159,142 @@ const app = Fastify({
 ```
 
 Keep the application's other Fastify options, including serializer options and
-validator configuration. This setup wraps the native default serializer builder;
+validator configuration, but replace an application's own `trustProxy` setting
+with `resolveTrustedProxies(runtimeEnv)` (`runtimeEnv` is the environment the
+server starts with, `process.env` if it has no other), and its environment
+variable with `TRUSTED_PROXIES`; see
+[sign-in protection](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/authentication#sign-in-protection)
+for the setting. This setup wraps the native default serializer builder;
 retain any deliberately chosen custom compiler instead of replacing or wrapping
 it. Native route-level compiler overrides continue to apply. Update the lockfile
 through the application's normal installation flow and restart the backend to
 activate the new setup. Updating packages or starter examples alone does not
 change an existing application's startup source.
 
-### JSON REST v2 integration
+### Data access on table resources (json-rest-api 3)
 
-Applications using `@jskit-ai/json-rest-api-core` require Node.js 24 or newer.
+Applications using `@jskit-ai/resource-runtime` require Node.js 24 or newer.
 JSKIT's repository and application default is Node.js 26. Upgrade dependencies,
-custom resource calls, and hooks together; rebuild native database dependencies
-after changing Node.
-
-The standard `defineCrudJsonApiFeature()` API keeps `queryDocuments`,
-`getDocumentById`, `createDocument`, `patchDocumentById`, and
-`deleteDocumentById`, with `{ trx, context }` repository/service options.
-Read, create, and patch services still return tagged JSON:API documents.
-Application-owned hosts use `JsonRestApi` from `json-rest-api`; the JSKIT host
-already owns that setup.
-
-For direct resource calls, replace `inputRecord` with exactly one of `data`
-(plain values) or `document` (a JSON:API document). `format` selects output
-independently: `"plain"` or `"jsonapi"`. Replace `simplified` and
-`returnFullRecord` with `format` and `returning: "full" | "minimal" | "none"`.
-The JSKIT host defaults to plain output and full write responses; standard
-document repositories explicitly request JSON:API output and full create/patch
-responses. A plain collection is still `{ data: [...], meta?, links? }`; use
-`extractJsonRestCollectionRows()` when a custom repository needs its rows.
-A query without a page returns only the resource's first 20 rows; a
-server-side read that needs every row uses `queryAllJsonRestCollectionRows()`
-([every row](typed-features.md#every-row)).
+resource calls and hooks together; rebuild native database dependencies after
+changing Node.
 
-```js
-await jsonRestApi.resources.books.patch({
-  id: recordId,
-  data: { title: "Revised title" },
-  format: "jsonapi",
-  returning: "full",
-  transaction: trx
-}, createJsonRestContext(context));
-```
+Every table has one table resource and one owner feature, and every read and
+write goes through that table's handle
+([data access](data-access.md)). Rename as you go:
 
-Keep the target ID outside the patch data. Direct plain writes use the
-belongs-to relationship name and ID, such as `author: authorId`; the standard
-repository maps a resource field's declared `as` alias. Do not send both names.
-
-Resource hooks share the mutable context supplied as the second argument
-within one operation. The normalized hook field remains
-`context.inputRecord.data`; only the public input argument changed.
-`createJsonRestContext()` clones the JSKIT execution context and its
-`visibilityContext` and `scopeValues`, allowing frozen caller contexts; other
-nested objects remain shared references. Permission hooks use
-`context.originalContext ?? context` for operation-wide caches; enrichment
-hooks use `context.parentContext`. Built-in nested operations get separate
-contexts with shallow inheritance. For an application-initiated child call,
-choose the application properties to share in a fresh context and pass
-`transaction` explicitly; reusing or blindly spreading an active operation
-context carries its working state into the child.
-
-The standard repository's `withTransaction(work)` delegates to
-`jsonRestApi.transaction(work)`. Its callback and mutation lifecycle phases
-receive the actual callable Knex transaction: custom repository SQL can use
-`await trx("audit_entries").insert(...)`, while resource calls receive it as
-`transaction`. Await every participant before returning. The helper owns
-commit, rollback, and completion hooks. Raw `knex.transaction()` handles cannot
-own resource writes, and calling `transaction()` again starts an independent
-unit; forward the existing handle to compose work.
+| Before | Now |
+| --- | --- |
+| `defineCrudResource()` | `defineTableResource()` plus `defineCrudContract()` |
+| `defineCrudJsonApiFeature()`, `createCrudResourceRuntime()` | `defineCrudFeature({ crud })` |
+| the CRUD runtime's `listByIds()`, `listByForeignIds()` | `queryAll({ filters: { [key]: ids } })` on a filter declared `{ type: "array", filterOperator: "in" }`; a page's children with `createHooksToCollectChildren()` |
+| the CRUD runtime's lookup hydration | `include` on the CRUD list or view |
+| the CRUD runtime's `virtualFields` | `queryFields` in the `owns` entry, or `decorateService` for a value SQL cannot compute |
+| the CRUD runtime's `createdAt`/`updatedAt` stamping | every handle write stamps them; only a system context sets its own |
+| the CRUD runtime's output validation | the table resource's schema, whose types json-rest-api reads each field as |
+| `defineCrudFeature`'s `ownershipFilter`, `searchSchema` | `visibility`; an `owns` entry |
+| a lifecycle hook's `trx`; a decorator's or CRUD capability's `resource` | `options`; `crud` |
+| `decorateRepository`'s `database`, `http`, `jsonRestApi` | its `repository` and `resources`, each owned table's handle |
+| `@jskit-ai/crud-core/server/fieldAccess`, `/server/lookups` | removed (nothing called them); restrict fields in the CRUD contract and its `decorateService` |
+| `runtime.json-rest-api`, `addResourceIfMissing()`, `createJsonRestResourceScopeOptions()` | `defineFeature({ owns })`; a row policy, search schema or query fields go in the `owns` entry |
+| `queryDocuments()`, `getDocumentById()` | `query({ page: { size } })`, `get(id)` |
+| `queryAllJsonRestCollectionRows()`, `queryEveryDocument()` | `queryAll(params)` |
+| `createDocument()`, `createDocuments()` | `create()`, `createMany()` |
+| `patchDocumentById()`, `patchDocumentIfLockVersion()` | `patch(id, changes, options)`, `patch(id, changes, { ...options, lockVersion })` |
+| `deleteDocumentById()` | `delete(id)` |
+| `getDocumentById(…, { forUpdate: true })`, `applyForUpdate()`, `lockScopedRecordId()` | `lock(id)` inside `withTransaction` |
+| `runInTransaction()`, `createWithTransaction()`, `joinOrOpenTransaction()`, `resolveTransaction()`, `resolveQueryOptions()`, `resolveRepoClient()` | `withTransaction(options, (txOptions) => …)` |
+| `returning: "full" \| "minimal"` | `returning: "record" \| "id"` (`"none"` is unchanged) |
+| a hand-built `visibilityContext` or scope values, `applyVisibility()`, `applyVisibilityOwners()` | the caller's context, or `systemContext(reason).forWorkspace(id)` |
+| a field's `default:` | `defaultTo:` (`default` is refused, since json-rest-api never read it) |
+| a `createdAt` or `updatedAt` default of now | nothing: drop it, since every handle write stamps them |
+| a CRUD contract that showed every column | a contract shows only its `fields`, so list every field the API showed |
+| reading every row | `queryAll`, which refuses above 10,000 rows, so page with `query()` |
+| an app's own wrappers around old calls | the handle method they wrapped, then delete the wrapper |
+
+Handles answer records, `{ id, ...fields }`, with a belongs-to field as the
+related id; the CRUD service alone answers JSON:API documents. Every call takes
+`options` last: the caller's context, and inside a transaction the `txOptions`
+`withTransaction` handed its work. A call without a context throws on a table
+that is not public.
+
+json-rest-api 3 changes what a failed write means: any failed write inside a
+managed transaction fails the whole transaction. "Insert, catch the duplicate,
+then read" inside a transaction no longer works; use
+`createMany(rows, { ...options, onConflict: { keys, action: "ignore" } })` and then read,
+or read first. A `get`, `patch`, `delete` or `lock` of a missing or hidden
+record throws json-rest-api's not-found error (a 404); with `missing: "skip"`
+it answers `null`, without failing the caller's transaction. Upsert rows carry no
+`id`, never repeat their conflict keys, and name the ownership field among
+those keys; only a table with no owners and no row policy may key the upsert on
+the id alone, `onConflict: { keys: ["id"] }`, with an id on every row. `patchWhere` and `deleteWhere` need filters, or `all: true`.
 
 Preserve `error.transactionOutcome` and its cause when translating failures:
 `none` means no transaction was acquired or accepted, `pending` leaves
 completion to the owner, `rolledBack` confirms rollback, `committed` confirms
 commit, and `unknown` means the outcome is unresolved. These describe database
-transaction evidence, not external effects. A failed JSKIT mutation
-`afterCommit` hook raises `RestApiWriteError` with outcome `committed` and does
-not undo the write. Do not turn pending, committed, or unknown write failures
-into successful missing-record results, or automatically replay a committed
-or unresolved write.
+transaction evidence, not external effects. A failed `afterCommit` hook raises
+`RestApiWriteError` with outcome `committed` and does not undo the write. Do
+not turn pending, committed, or unknown write failures into successful
+missing-record results, or automatically replay a committed or unresolved
+write.
+
+### Moving hand-written SQL behind resources
+
+An application with Knex in its repositories moves it behind table resources
+one table at a time:
+
+1. **Inventory.** List every statement that reads or writes a table: the
+   repository methods, raw queries, migrations' seed data, jobs and scripts.
+   `jskit check` and the data-access lint rules (`jskit/no-direct-knex`,
+   `jskit/no-hand-scope`) find most of them.
+2. **One owner per table.** Pick the feature that owns each table and give the
+   table one table resource with its `ownership`. Two features writing one
+   table means one of them asks the other.
+3. **Owner APIs.** Code outside the owner calls the owner's service or
+   repository capability. JSKIT's own tables already work this way: users
+   (`users.profiles`, `users.settings`), workspaces, local sign-in and console
+   settings.
+4. **Map each statement to a layer**
+   ([data access](data-access.md)): one record or page →
+   Layer 1; screens over HTTP → Layer 2; a loop of writes → a many-row write;
+   a `forUpdate` read → a lock; totals and reports → `aggregate`, a window
+   include, or one `scopedQuery()` method; work over every workspace → a job
+   with `systemScope`.
+5. **Two tests per path.** `expectScoped` proves the path never reads or
+   changes a second owner's rows; `expectFlatQueries` proves its statements do
+   not grow with its rows. Both come from `@jskit-ai/resource-runtime/test`.
+
+Keep each move behaviour-preserving
+([refactors](sanity-checks.md#refactors)).
+
+A table keyed by several columns, or by its owner's id, gets an integer `id`
+first ([Layer 1](data-access.md#layer-1-the-table-resource)).
+One new migration does it on MySQL, MariaDB and PostgreSQL: the key becomes a
+unique index before the primary key goes, so a foreign key on its first column
+keeps an index, and adding the `id` numbers the existing rows. `down` undoes it
+in reverse.
+
+```js
+const KEY = ["workspace_id", "day"];
+
+export async function up(knex) {
+  await knex.schema.alterTable("day_slots", (table) => table.unique(KEY, { indexName: "day_slots_key" }));
+  await knex.schema.alterTable("day_slots", (table) => table.dropPrimary());
+  await knex.schema.alterTable("day_slots", (table) => table.increments("id"));
+}
+
+export async function down(knex) {
+  await knex.schema.alterTable("day_slots", (table) => table.dropColumn("id"));
+  await knex.schema.alterTable("day_slots", (table) => table.primary(KEY));
+  await knex.schema.alterTable("day_slots", (table) => table.dropUnique(KEY, "day_slots_key"));
+}
+```
+
+MySQL and MariaDB commit each statement on its own, so a run that fails
+part-way resumes as the [partial-failure
+rules](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#directory-order-comes-before-filenames)
+say. Code that wrote by the old key now upserts on it, with the ownership
+column among the keys.
 
 ### Workspace invitation transaction compatibility (workspaces-core 0.1.198)
 

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

@@ -22,7 +22,7 @@ How to use it:
   - [page-scaffolding.md](./page-scaffolding.md)
 - child crud, nested crud, embedded list, subroute, separate page, parent/child layout
   - [child-cruds.md](./child-cruds.md)
-- crud, crud server, crud ui, resource contract, table creation, migrations, ownership, JSON API, standard screens
+- crud, crud server, crud ui, table resource, CRUD contract, table creation, migrations, ownership, JSON API, standard screens
   - [crud-authoring.md](./crud-authoring.md)
 - CRUD links, record placeholders, `paths.page()`, `resolveViewUrl`, `resolveEditUrl`, `resolveParams`
   - [crud-links.md](./crud-links.md)
@@ -40,11 +40,13 @@ How to use it:
   - [filters.md](./filters.md)
 - `searchSchema`, `search: true`, `applyFilter`, server search, query validators, backend filters, internal JSON REST filters
   - [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)
+- `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)
+- data access, database table, knex, raw, SQL, repository, bulk, batch, many rows, set write, upsert, lock, claim, totals, report, aggregate, newest per group, transaction, `trx`, background job, system scope, `systemContext`, owner, owns, owner API, another feature's table, scope test, `expectFlatQueries`, `requireTestDatabase`, `jskit/no-direct-knex`, `jskit/no-transaction-reader`, `jskit/no-hand-scope`, `jskit/sql-literal`, `jskit/knex-reason`, `infrastructure:`
+  - [data-access.md](./data-access.md)
 - 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, read per row, N+1 queries, slow endpoint, query budget, realistic row counts, slow tests, raised timeout, `migrate.latest()` in tests, test database snapshot, `--test-concurrency=1`, `node --test`, `jskit test`, `testConcurrency()`, `V64_TEST_CONCURRENCY`, Playwright `workers`, Vitest `maxWorkers`, tests one file at a time, test files colliding in parallel, `jskit-test: alone`, `test/*` findings of `jskit check`
+- 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, `handle.query`, `queryAll`, every row, list stops at one page, `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, `--test-concurrency=1`, `node --test`, `jskit test`, `testConcurrency()`, `V64_TEST_CONCURRENCY`, Playwright `workers`, Vitest `maxWorkers`, tests one file at a time, test files colliding in parallel, `jskit-test: alone`, `test/*` findings of `jskit check`
   - [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/crud-authoring.md

@@ -2,7 +2,7 @@
 
 # CRUD authoring
 
-Use this file for normal persisted entities, resource contracts, migrations,
+Use this file for normal persisted entities, table resources and CRUD contracts, migrations,
 JSON API routes, and matching screens.
 
 ## Start from product decisions
@@ -13,15 +13,18 @@ choice is missing. Do not turn these decisions into generator options.
 
 Read these package-owned source patterns:
 
-- `crud/resource-contract` for the shared field and ownership contract
-- `crud/json-api-resource-package` for migration and server composition
+- `database/table-resource` for the table's fields, ownership and lookups
+- `crud/crud-contract` for the HTTP surface on it
+- `crud/crud-feature-package` for migration and server composition
 - `crud/crud-screen-set` for routed list, view, create, edit, and delete UI
 
 ## Normal implementation order
 
 1. Author a source-controlled migration in the package that owns the entity.
-2. Define the resource with `defineCrudResource()`.
-3. Bind standard server behavior with `defineCrudJsonApiFeature()`.
+2. Define the table resource with `defineTableResource()` and its HTTP surface
+   with `defineCrudContract()`.
+3. Bind standard server behavior with `defineCrudFeature()`, which owns the
+   table and serves its CRUD contract.
 4. Add only product-specific service methods, lifecycle, actions, validation,
    policy, queries, messages, and orchestration.
 5. Declare the package provider and framework capabilities in `package.json`.
@@ -33,10 +36,10 @@ Read these package-owned source patterns:
 The migration and resource are both authored contracts. A live schema is useful
 for understanding an imported system, but it is never the sole source of truth.
 
-Write a field's `operations` only where it differs from the default (output,
-create required as the field is, patch; none for `primary: true` or
-`hidden: true`; output only for `readOnly: true`), and write a lookup field as `lookup: "<namespace>"`.
-The `crud/resource-contract` pattern lists what each expands to.
+A CRUD contract shows and accepts only the fields its `fields` names, so give
+every field the API shows or accepts its operations (a stored `createdAt` and
+`updatedAt` are shown without an entry), and write a lookup field as `lookup: "<namespace>"`.
+The `crud/crud-contract` and `database/table-resource` patterns list what each expands to.
 
 ## Ownership and access
 
@@ -51,7 +54,10 @@ The `crud/resource-contract` pattern lists what each expands to.
 
 Normal CRUD tables use one non-null single-column primary key. Foreign keys are
 single-column and target compatible keys. Composite unique indexes may enforce
-business rules but do not become framework identities.
+business rules but do not become framework identities: a table keyed by several
+columns, or by its owner's id, gets an integer `id` and keeps that key as a
+unique index, read with a filter and written with an upsert
+([Layer 1](../data-access.md#layer-1-the-table-resource)).
 
 ## Schema evolution
 
@@ -62,21 +68,26 @@ or rewrite a historical baseline.
 
 ## Customize without copying CRUD
 
-`defineCrudJsonApiFeature()` deliberately keeps application extension points:
+`defineCrudFeature()` deliberately keeps application extension points:
 
+- `owns` lists the feature's other tables, and the CRUD table's server-only
+  extras (`{ resource, rowPolicy, hooks }`).
 - `decorateRepository` adds the few persistence operations unique to the
-  resource.
+  resource, on the table's handle.
 - `decorateService` overrides standard methods or adds domain methods such as
   `confirm`, `publish`, `cancel`, or `sendReminder`.
 - `operationLifecycle` wraps a standard operation with `before`, `execute`,
   `after`, and mutation-only `afterCommit` phases. Mutation phases before commit
-  receive the same transaction and `execute` receives `standard(nextInput)`.
+  receive the same `options` (context and transaction) to pass on, and
+  `execute` receives `standard(nextInput)`. A deadlock reruns them, so they
+  touch only the database; an email or HTTP call goes in `afterCommit`, which
+  runs once.
 - `actions` exposes non-CRUD service methods through normal validated,
   permissioned, audited JSKIT actions and optional explicit HTTP routes.
 
 A resource whose records carry a version number names it `lockVersionField`
-and patches through the repository's `patchDocumentIfLockVersion`; see the
-database layer guide's Optimistic locking.
+and patches with the handle's `patch(id, changes, { ...options, lockVersion })`;
+see the data access guide's Layer 4: locks.
 
 Keep database reads and writes in repositories. Services and lifecycle hooks
 orchestrate repositories; they do not issue raw database queries. Put external

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

@@ -0,0 +1,19 @@
+<!-- Generated from `packages/agent-docs/heuristics/data-access.md`. -->
+
+# Data access
+
+Use when code reads or writes a database table: a repository, a batch, a lock,
+a total or report, a transaction, a background job, or another feature's table.
+
+Pick the layer ([Data access](../data-access.md)):
+
+- One record, or one page of records: the owner's handle (`get`, `query`, `create`, `patch`, `delete`).
+- Screens over HTTP: a CRUD contract on the same table resource.
+- Many rows from one action: `createMany`, `patchMany`, `patchWhere`, `deleteWhere`; never a loop of single writes.
+- 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`.
+- 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.
+- Every path: a scope test and `expectFlatQueries`; a data test fails without `TEST_DB_NAME`.

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

@@ -65,8 +65,8 @@ Server-side pattern, only when implementing real backend filter semantics:
 3. Pass the contract's `queryValidator` through the dedicated
    `listFilterQueryValidator` option of the standard CRUD list validator group
    at both the route and action boundaries.
-4. Pass the contract's `jsonRestSearchSchema` into `createJsonRestResourceScopeOptions(..., { searchSchema })`.
-5. Call `contract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)` in the JSON REST repository path.
+4. Pass the contract's `jsonRestSearchSchema` as the `searchSchema` of the CRUD table's `owns` entry: `defineCrudFeature({ crud, owns: [{ resource, searchSchema: contract.jsonRestSearchSchema }] })`.
+5. Override the service's `list` in `decorateService` so it calls `service.list(contract.toJsonRestQuery(query), options)`.
 
 Exact file checklist:
 - create `packages/<crud>/src/shared/<crud>ListFilters.js`
@@ -77,8 +77,8 @@ Exact file checklist:
 - update `packages/<crud>/src/server/actions.js` so
   `createStandardCrudListQueryValidators(...)` receives the same
   `listFilterQueryValidator`
-- update the provider's `createJsonRestResourceScopeOptions(...)` call so `searchSchema: listFilterContract.jsonRestSearchSchema` is merged into the internal JSON REST resource
-- update `packages/<crud>/src/server/repository.js` so list queries pass `listFilterContract.toJsonRestQuery(query)` into `buildJsonRestQueryParams(...)`
+- update the feature's `owns` entry for the CRUD table so `searchSchema: listFilterContract.jsonRestSearchSchema` reaches the resource
+- update the feature's `decorateService` so `list(query, options)` passes `listFilterContract.toJsonRestQuery(query)` to the standard `list`
 - update the page-local `listFilters.js` first; only edit `index.vue` if a specialist lookup label/runtime integration is needed
 - for lookup-backed filters, wire `useCrudListFilterLookups(...)` beside the existing filter runtime instead of replacing `CrudListFilterSurface`
 
@@ -168,8 +168,8 @@ Good shape:
 - shared screen runtime passes `filterRuntime.queryParams` into the list request
 - `packages/receivals/src/shared/receivalListFilters.js`
 - `createCrudListFilterContract(RECEIVAL_LIST_FILTER_DEFINITIONS, { columns, invalidValues: "reject" })`
-- `createJsonRestResourceScopeOptions(resource, { searchSchema: receivalListFilterContract.jsonRestSearchSchema })`
-- `buildJsonRestQueryParams(JSON_REST_SCOPE_NAME, receivalListFilterContract.toJsonRestQuery(query))`
+- `owns: [{ resource: receivalResource, searchSchema: receivalListFilterContract.jsonRestSearchSchema }]`
+- `list: (query, options) => service.list(receivalListFilterContract.toJsonRestQuery(query), options)` in `decorateService`
 - `const listFilters = useCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, { presets: [...] })`
 - `const filterLookups = useCrudListFilterLookups(RECEIVAL_LIST_FILTER_DEFINITIONS, { values: listFilters.values, ... })`
 - `queryParams: listFilters.queryParams`

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

@@ -6,43 +6,67 @@ Use when:
 
 - mandatory record visibility needs `OR`, `EXISTS`, joins, memberships, or hierarchy traversal
 - filtering after pagination produces empty or incomplete pages
-- another package grants access to a resource but a reverse dependency would create a cycle
+- another package must narrow who sees a resource's rows 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:
 
-- the owning CRUD provider and shared resource
-- the package-owned CRUD server pattern
-- `packages/crud-core/test/defineCrudJsonApiFeature.test.js`
+- the owning feature's `owns` entry and the shared table resource
+- the [data access](../data-access.md) guide's Layer 1
+- `packages/resource-runtime/test/resourceRuntime.test.js` (policies, `ownTable`, contributions)
 
 Default JSKIT pattern:
 
 1. Keep public search and structured filters in the existing list-filter contract.
-2. Keep direct user/workspace ownership and write stamping in autofilter.
+2. Keep direct user/workspace ownership and write stamping in the table resource's `ownership`.
 3. Put complex mandatory read visibility in a server-only row policy.
-4. Pass the policy through `createJsonRestResourceScopeOptions(resource, { rowPolicy })` in the owning provider.
-5. Derive identity from trusted execution context.
+4. Pass the policy in the owner's `owns` entry: `owns: [{ resource, rowPolicy }]`. It reads the owner's other tables through `ownTable(name)`, a read-only subquery, never by table name. Visibility rules live in the row policy, never in hand queries.
+5. Derive identity from `caller` (`caller.kind`, then `caller.userId`), never from input. In a workspace request a role
+   rule reads `context.permissions`, which the server resolves from the membership before any handle runs, with
+   `hasPermission(context.permissions, "bookings.view-all")` from `@jskit-ai/kernel/shared/support`: `includes()`
+   misses wildcard grants, such as an owner role's `*` or a `bookings.*`.
 6. Group every policy-owned `OR` branch.
 7. Return `true` after adding the predicate, return `false` to deny all rows, or throw for invalid trusted context.
 8. Keep action permissions for writes; visibility is not mutation authorization.
 
 Package composition:
 
-- the package that owns the resource also owns the row policy
-- a package that grants extra visibility depends on the resource owner
-- the resource owner does not import grant packages
-- create one application-scoped visibility object during the owner's `register()`
-- grant packages add contributions during their `register()`
-- the owner seals the contributions and builds the policy during `boot()`
+- the feature that owns the resource also owns the row policy
+- the owner accepts contributions with `{ resource, rowPolicy, acceptsContributions: true }` in `owns`
+- a package that narrows visibility further depends on the resource owner and calls `resources.contributeRowPolicy(name, policy)` on the handles its own `owns` gave it; a contribution is ANDed with the owner's policy inside its own group, so it can only narrow
+- a contribution never grants visibility: wider visibility (shared rows, grants another package records) is a rule in the owner's own policy over its own tables, and a contribution narrows every read of the table, every feature's included, so a rule for one surface is an owner API method instead
+- the resource owner does not import contributing packages
 - do not use module-global mutable registries
 
+Example, "your rooms or shared rooms":
+
+```js
+owns: [{
+  resource: roomResource,
+  acceptsContributions: true,
+  rowPolicy({ query, caller, column, ownTable }) {
+    if (caller.kind !== "user") return caller.kind !== "anonymous";
+    query.where((rooms) => rooms
+      .where(column("shared"), true)
+      .orWhereIn(column("id"), ownTable("roomMembers").select("room_id").where("user_id", caller.userId)));
+    return true;
+  }
+}]
+```
+
+A policy is told who the call runs for as `caller`: `user`, `anonymous`,
+`system` or `job`. Background work is `system` or `job`, never a missing user,
+and a job names its person only as `caller.actorId`. A policy hides a row from
+every read, including other tables' links to it, so narrowing what one screen
+lists is a filter on that screen's read.
+
 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; look at its SQL too, since a statement that runs to kilobytes is planned again on every read that carries it
-- 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"`, their default) 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)
+- 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 restriction is a predicate contribution, and another package's grant is a predicate in the owner's policy over facts the owner keeps
+- the policy runs on every single-record read, including the read-back after a handle's `create()` and `patch()` (`returning: "record"`, their default) and the lookup before `patch` and `delete`, so a write pays it once per row it writes; the many-row writes check access once per statement
+- a write decides access once, inside its transaction; a batch write that would pay an expensive read-back per row follows the data access guide's [Layer 3](../data-access.md#layer-3-many-rows-at-once)
 
 Child-resource rules: