@jskit-ai/agent-docs 0.1.283 → 0.1.284

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
 
@@ -62,21 +65,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:
 

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

@@ -5,28 +5,26 @@
 Use when:
 - a CRUD list accepts `q` or other server-side query params
 - a resource needs alias filters such as `onlyArchived -> archived`
-- a list needs access-scoped filters that the repository injects before querying
+- a list needs filters with compound SQL (status buckets, null/not-null semantics)
 - the user asks where search belongs on the server in a current JSKIT app
 
 Core rule:
-- for current JSKIT CRUD apps, the server search contract lives in `resource.searchSchema` on the internal JSON REST path
+- the server search contract lives in the table resource's `searchSchema`; a server-only entry (one with `applyFilter`) goes in the owner's `owns` entry, `{ resource, searchSchema }`
 - route validators decide which public query keys HTTP callers may send
-- repositories may add internal-only filter keys before forwarding the query to JSON REST
-- structured list filters should use `createCrudListFilterContract(...)` so route/action validators, JSON REST search schema, and repository query normalization are derived from one definition
+- who may see a row is never a filter: it is the row policy ([row-policies.md](./row-policies.md)), applied by the handle on every read
+- structured list filters should use `createCrudListFilterContract(...)` so route/action validators, the search schema, and query normalization are derived from one definition
 
-The standard CRUD repository pattern follows this path:
+The standard CRUD service lists through the table's handle:
 
 ```js
-return api.resources.contacts.query({
-  queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, contactListFilterContract.toJsonRestQuery(query)),
-  format: "jsonapi"
-}, createJsonRestContext(context));
+// what defineCrudFeature's service does; a decorateService list maps structured filters first
+return repository.query(buildJsonRestQueryParams("contacts", contactListFilterContract.toJsonRestQuery(query)), { ...options, format: "jsonapi" });
 ```
 
 The normal layer split is:
 1. `actions.js` / `registerRoutes.js`: accept and validate public query keys
-2. `repository.js`: add internal-only filter keys such as visibility scope, or call `listFilterContract.toJsonRestQuery(query)` for structured filters
-3. provider/resource registration: merge backend filter behavior into JSON REST with `createJsonRestResourceScopeOptions(resource, { searchSchema })`
+2. the feature's `decorateService`: call `listFilterContract.toJsonRestQuery(query)` for structured filters before the standard `list`; visibility belongs in the row policy, never in a filter key
+3. the owner feature: backend filter behavior goes in the table resource's `searchSchema`, or a server-only one in its `owns` entry (`{ resource, searchSchema }`)
 
 ### Shared list and HTTP transport
 
@@ -74,13 +72,13 @@ Do not use `search: true` when:
 - you want a different public key than the storage field
 - you need one key to search several fields
 - you need custom SQL semantics
-- you need an internal-only injected filter
+- you need a key the service maps from a structured filter
 
 Use explicit `searchSchema` when:
 - the public key differs from the field name
 - one key searches multiple fields
 - the route/API contract should stay stable even if field names change
-- the filter is internal-only and injected by the repository
+- the key is internal and only the service's structured-filter mapping sends it
 - you need to override the simple `search: true` behavior
 
 Example:
@@ -110,32 +108,23 @@ Important merge rule:
 Use `applyFilter` when:
 - `actualField`, `oneOf`, and normal operators are not enough
 - the filter needs compound SQL
-- the filter encodes visibility rules, status buckets, or null/not-null semantics that are more complex than a direct field comparison
+- the filter encodes status buckets or null/not-null semantics that are more complex than a direct field comparison (never visibility: that is the row policy)
 
 Example:
 
 ```js
 searchSchema: {
-  "__viewerAccess": {
+  dueState: {
     type: "string",
     applyFilter(query, rawValue) {
       const value = String(rawValue || "").trim();
-
-      query.whereNull("deleted_at");
-      if (value === "privileged") {
+      if (value === "overdue") {
+        query.whereNull("paid_at").where("due_at", "<", new Date());
         return;
       }
-
-      const userId = value.startsWith("user:")
-        ? String(value.slice(5) || "").trim()
-        : "";
-
-      query.where(function () {
-        this.where("user_added", 0);
-        if (userId) {
-          this.orWhere("added_by_user_id", userId);
-        }
-      });
+      if (value === "paid") {
+        query.whereNotNull("paid_at");
+      }
     }
   }
 }
@@ -143,6 +132,7 @@ searchSchema: {
 
 Keep `applyFilter` focused on query semantics:
 - build the SQL/knex filter there
+- read only the row's own columns in a filter a `patchWhere` or `deleteWhere` decides on: one that reads another table through a subquery is not detected, and is no compare-and-set on MySQL and MariaDB
 - do not put permission checks there
 - do not turn it into a second service layer
 
@@ -167,7 +157,7 @@ input: composeSchemaDefinitions([
 That means:
 - pagination, `q`, parent filters, includes, sparse fieldsets, and the
   structured filter keys remain one standard group
-- the repository may still add internal-only keys later
+- the service may still map structured keys before the standard list
 
 Use the same `listFilterQueryValidator` option with
 `createCrudJsonApiRouteContracts(...)` at the route boundary. The layers
@@ -196,14 +186,17 @@ const receivalListFilterContract = createCrudListFilterContract(
 );
 ```
 
-Use `receivalListFilterContract.queryValidator` at route/action boundaries. Use `receivalListFilterContract.jsonRestSearchSchema` when registering the JSON REST resource. Use `receivalListFilterContract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)`.
+Use `receivalListFilterContract.queryValidator` at route/action boundaries. Use `receivalListFilterContract.jsonRestSearchSchema` as the `searchSchema` of the table's `owns` entry. Use `receivalListFilterContract.toJsonRestQuery(query)` in the service's `list` before the standard one.
 
 That contract preserves arrays for `enumMany` and `recordIdMany`, maps range filters to internal JSON REST search keys, and keeps those internal keys out of the public HTTP query contract.
 
 Do not add route validators for:
-- repository-injected internal keys such as `"__viewerAccess"`
+- internal keys that only the service's structured-filter mapping sends
 - filters that must never be supplied by the client directly
 
+Who may see a row is never a search key at all: it is the row policy, which
+the handle applies to every read whatever the query says.
+
 ## Recommended Shapes
 
 Simple direct field exposure:
@@ -236,15 +229,10 @@ searchSchema: {
 }
 ```
 
-Repository-injected internal filter:
+Visibility, by the owner, on every read:
 
 ```js
-function buildScopedQuery(query = {}, context = null) {
-  return {
-    ...(query || {}),
-    "__viewerAccess": resolveViewerAccess(context)
-  };
-}
+owns: [{ resource: contactResource, rowPolicy: ownContactsOrShared }]
 ```
 
 ## Keep These Boundaries Clean
@@ -252,8 +240,8 @@ function buildScopedQuery(query = {}, context = null) {
 - Put backend filter behavior in `searchSchema`, not in page code.
 - Use `createCrudListFilterContract(...)` for structured list filters before writing custom JSON REST query glue.
 - Put permission checks in the action/service layer, not in `applyFilter`.
-- Put repository-only scoping in the repository, not in route query validation.
-- Do not expose a query key publicly just because the repository uses it internally.
+- Put visibility in the owner's row policy, never in a search key or route query validation.
+- Do not expose a query key publicly just because the service maps to it internally.
 - Do not rely on route validators alone; a public key still needs a matching backend search definition.
 
 ## Quick Rule Of Thumb
@@ -262,4 +250,4 @@ function buildScopedQuery(query = {}, context = null) {
 - Public alias or multi-field search: `searchSchema`
 - Complex SQL semantics: `searchSchema` + `applyFilter`
 - Public HTTP query key: add it through the standard route/action query group
-- Internal-only repository key: inject it in `repository.js`, skip the public validator
+- Who may see a row: the owner's row policy, never a key

package/skills/jskit/references/heuristics/table-resource-fields.md

@@ -0,0 +1,78 @@
+<!-- Generated from `packages/agent-docs/heuristics/table-resource-fields.md`. -->
+
+# Table Resource Fields
+
+Use when:
+- a table resource field needs an explicit column mapping
+- a field should appear in records but is not a real column
+- the user mentions computed fields, projections or date write serialization
+
+Default JSKIT pattern:
+1. The table resource's schema describes the record; each field maps to its column itself.
+2. Use `storage: { column: "<column>" }` (or `actualField`) only when the default snake_case column is wrong.
+3. Standard writable `dateTime` fields are serialized at the write seam automatically; `storage.writeSerializer` is only for non-default serialization.
+4. A computed output field is `storage: { virtual: true }` in the shared schema, and its SQL goes in the owner's `owns` entry as `queryFields`, on the server.
+5. Handles apply those projections on every read; no repository method re-selects them.
+6. A field's default value is `defaultTo`; `default` is refused, since json-rest-api would ignore it.
+7. A field no request may see (an ownership id, a bearer token) is `hidden: true`, and stays hidden: the owner's code
+   reads it by naming it in a handle read's `fields`, and a system context may name it through another feature's
+   CRUD repository. Unhiding it puts it in every read's answer, other features' included; never read it with `scopedQuery`.
+
+Field metadata rules:
+
+```js
+// a column override
+createdAt: { type: "dateTime", required: true, storage: { column: "created_at" } }
+
+// a non-default write serializer
+arrivalDatetime: { type: "dateTime", required: true, storage: { writeSerializer: "datetime-utc" } }
+
+// a computed output field
+remainingWeight: { type: "number", required: true, storage: { virtual: true } }
+```
+
+- omit `actualField`/`storage` when the field is column-backed and the default snake_case mapping is correct
+- `storage: { virtual: true }` cannot also define `actualField`, `storage.column` or `storage.writeSerializer`
+- `storage: { virtual: true }` fields are never written
+
+Computed fields (server only):
+
+```js
+const ReceivalsFeature = defineFeature({
+  id: "receivals",
+  owns: [{
+    resource: receivalResource,
+    queryFields: {
+      remainingWeight: {
+        type: "number",
+        select({ raw, column }) {
+          return raw("?? - coalesce(??, 0)", [column("receivedWeight"), column("processedWeight")]);
+        }
+      }
+    }
+  }],
+  setup: ({ resources }) => ({ receivals: createReceivalsRepository(resources) })
+});
+```
+
+Keep projection SQL in the server feature that owns the table, never in the shared resource that ships to the browser.
+`select` receives `raw`, which builds one SQL expression from a string literal and its bindings (a value only: it never runs on its own),
+`column(field)`, which names a field's column, and the read's `filters`; never Knex. The expression is the field's value
+only, so it reads no other table.
+
+What the resource runtime does for you:
+- reads select only column-backed fields plus the registered query fields
+- writes serialize standard writable `dateTime` fields, and any explicit `storage.writeSerializer`
+- database reads serialize `date`, `time` and `dateTime` values to their strict `json-rest-schema` strings before validation, respecting `temporalPrecision`
+- search and filters only use column-backed fields
+
+Avoid:
+- `clearSelect()` / re-select hacks in a repository method to add a computed field
+- SQL fragments or joins in shared field metadata
+- `storage` modes beyond the documented `column`, `writeSerializer` and `virtual`
+
+Review checks:
+- one table resource per table, and field definitions own their mapping
+- non-default write serialization lives in `storage.writeSerializer`, not in repository code
+- every `storage: { virtual: true }` field has a matching `queryFields` entry in the owner's `owns`
+- no JavaScript `Date` object crosses a strict resource validation boundary; scoped-query reports return ISO/RFC 3339 strings explicitly

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

@@ -63,11 +63,11 @@ ends with the same link.
   - [One helper per package](../typed-features.md#one-helper-per-package)
 - `options?.trx || options?.transaction`, a hand-read actor, cursor or created id
   - [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, `page: { size: 500 }` or `limit: 500` that returns 100 rows
+- a list read with `query()` where every row is meant (`queryAll()`), a list that stops at one page, `page: { size: 500 }` refused above the page limit
   - [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 list whose query count grows with its rows, a slow list endpoint
+- `await handle.get(…)`, `handle.query(…)` 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 list whose query count grows with its rows, a slow list endpoint
   - [Lists read related rows in batches](../typed-features.md#lists-read-related-rows-in-batches)
-- 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
+- a `rowPolicy` that loads a person's whole history or calls an access check per item, `create()` per row of a batch instead of `createMany()`, 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)