@jskit-ai/agent-docs 0.1.53 → 0.1.54

package/guide/agent/generators/advanced-cruds.md

@@ -948,6 +948,7 @@ In JSKIT CRUD:
 - the schema defines the API contract
 - field definitions may also carry storage/lookup/ui metadata
 - the repository runtime owns computed SQL projections
+- internal JSON REST resources can expose SQL-selected query projections through `createJsonRestResourceScopeOptions(...)`
 
 Use these rules:
 
@@ -1018,7 +1019,31 @@ const repositoryRuntime = createCrudResourceRuntime(resource, {
 });
 ```
 
-Once registered there:
+For JSON REST-backed generated CRUD packages, keep the output field virtual in the resource and register the SQL projection at the JSON REST resource boundary:
+
+```js
+await addResourceIfMissing(
+  api,
+  "receivals",
+  createJsonRestResourceScopeOptions(resource, {
+    queryFields: {
+      remainingBatchWeight: {
+        type: "number",
+        select({ knex, column }) {
+          return knex.raw("?? - coalesce(??, 0)", [
+            column("received_weight"),
+            column("processed_weight")
+          ]);
+        }
+      }
+    }
+  })
+);
+```
+
+`createJsonRestResourceScopeOptions(...)` moves matching virtual fields out of the storage schema and into JSON REST `queryFields`, where they are selected for reads and ignored for writes. Prefer the `queryFields` option when the resource module is imported by both server and client code; use `storage.queryProjection` only in server-only resource modules.
+
+For the repository runtime, once registered there:
 
 - generic CRUD `list`
 - generic CRUD `findById`
@@ -1126,14 +1151,16 @@ Keep bulk action definitions page-local unless another page needs to share them.
 For a generated CRUD, treat this as the concrete file plan:
 
 - edit `src/pages/.../contacts/listFilters.js`
-- make sure the matching server route/action/repository code already accepts and applies the declared query params
+- make sure the matching server route/action/repository code accepts and applies the declared query params when filters are server-backed
 
 If the filter contract should be shared with server code, promote it into a CRUD package module and import it from both sides:
 
 - create `packages/contacts/src/shared/contactListFilters.js`
-- update `packages/contacts/src/server/registerRoutes.js` so the list route query validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)`, unless you already extracted list-query composition into `packages/contacts/src/server/listQueryValidators.js`
-- update `packages/contacts/src/server/actions.js` so the list action input validator includes that same explicit contract choice
-- update `packages/contacts/src/server/repository.js` so the list query path builds the `createCrudListFilters(...)` runtime and calls `applyQuery(...)`
+- create `packages/contacts/src/server/contactListFilterContract.js` with `createCrudListFilterContract(...)`
+- update `packages/contacts/src/server/registerRoutes.js` so the list route query validator includes `contactListFilterContract.queryValidator`
+- update `packages/contacts/src/server/actions.js` so the list action input validator includes the same `queryValidator`
+- update the provider's `createJsonRestResourceScopeOptions(...)` call so it merges `searchSchema: contactListFilterContract.jsonRestSearchSchema`
+- update `packages/contacts/src/server/repository.js` so the list query path passes `contactListFilterContract.toJsonRestQuery(query)` into `buildJsonRestQueryParams(...)`
 
 #### Client side
 
@@ -1231,101 +1258,105 @@ Use `mode: "merge"` when a preset should only change one filter group, such as t
 
 #### Server side
 
-Build the server runtime from the same shared definitions:
+Build the server contract from the same shared definitions:
 
 ```js
-const contactsListFiltersRuntime = createCrudListFilters(
+import { createCrudListFilterContract } from "@jskit-ai/crud-core/server/listFilters";
+import { CONTACTS_LIST_FILTER_DEFINITIONS } from "../shared/contactListFilters.js";
+
+const contactListFilterContract = createCrudListFilterContract(
   CONTACTS_LIST_FILTER_DEFINITIONS,
   {
     columns: {
-      onlyStaff: "is_staff",
-      onlyVip: "vip",
+      status: "status",
+      supplierContactId: "supplier_contact_id",
+      arrivalDate: "arrival_datetime",
       onlyArchived: "archived"
-    }
+    },
+    invalidValues: "reject"
   }
 );
-```
-
-There is no default query-validator mode or route-runtime alias. Keep the filter runtime for repository semantics, but author route/action query params explicitly.
-
-Strict contract example:
 
-```js
-const contactsListFilters = CONTACTS_LIST_FILTER_DEFINITIONS;
-
-const contactsListFiltersQueryValidator = {
-  schema: createCrudListFilterQuerySchema({
-    status: createCrudListFilterQueryField(contactsListFilters.status, {
-      invalidValues: "reject"
-    }),
-    arrivalDate: createCrudListFilterQueryField(contactsListFilters.arrivalDate, {
-      invalidValues: "reject"
-    })
-  }),
-  mode: "patch"
-};
+export { contactListFilterContract };
 ```
 
-Lenient contract example:
+That one contract gives the server:
 
-```js
-const contactsListFiltersQueryValidator = {
-  schema: createCrudListFilterQuerySchema({
-    status: createCrudListFilterQueryField(CONTACTS_LIST_FILTER_DEFINITIONS.status, {
-      invalidValues: "discard"
-    }),
-    arrivalDate: createCrudListFilterQueryField(CONTACTS_LIST_FILTER_DEFINITIONS.arrivalDate, {
-      invalidValues: "discard"
-    })
-  }),
-  mode: "patch"
-};
-```
+- `queryValidator` for route/action input validation
+- `jsonRestSearchSchema` for JSON REST resource registration
+- `toJsonRestQuery(query)` for repository query normalization
+- `applyQuery(...)` when a non-JSON REST repository still needs direct Knex filtering
 
-Wire the explicit query contract into the list validator and the repository:
+Wire the contract into route and action validators:
 
 ```js
 const listRouteQueryValidator = composeSchemaDefinitions([
   listCursorPaginationQueryValidator,
   listSearchQueryValidator,
-  contactsListFiltersQueryValidator,
   listParentFilterQueryValidator,
+  contactListFilterContract.queryValidator,
   lookupIncludeQueryValidator
 ], {
   mode: "patch"
 });
 ```
 
-Use that same explicit `contactsListFiltersQueryValidator` anywhere else the list query is validated, such as the composed list action input validator if your CRUD package validates query shape at both the route and action boundaries.
+Use the same `contactListFilterContract.queryValidator` anywhere else the list query is validated, such as the composed list action input validator if your CRUD package validates query shape at both the route and action boundaries.
+
+Merge the JSON REST search schema when the provider registers the resource:
+
+```js
+await addResourceIfMissing(
+  api,
+  JSON_REST_SCOPE_NAME,
+  createJsonRestResourceScopeOptions(resource, {
+    searchSchema: contactListFilterContract.jsonRestSearchSchema,
+    writeSerializers: {
+      "datetime-utc": toDatabaseDateTimeUtc
+    }
+  })
+);
+```
+
+Normalize the list query before building JSON REST query params:
+
+```js
+async function queryDocuments(query = {}, options = {}) {
+  return api.resources.contacts.query(
+    {
+      queryParams: buildJsonRestQueryParams(
+        JSON_REST_SCOPE_NAME,
+        contactListFilterContract.toJsonRestQuery(query)
+      ),
+      transaction: options?.trx || null,
+      simplified: false
+    },
+    createJsonRestContext(options?.context || null)
+  );
+}
+```
+
+`enumMany` and `recordIdMany` filters stay arrays. Date and number ranges become internal JSON REST search keys, so callers keep one public query key such as `arrivalDate` while the backend receives precise lower/upper filter operations.
 
 Choose the invalid-value contract deliberately:
 
-- there is no default mode and no fallback alias, so every structured filter field must choose `invalidValues: "reject"` or `invalidValues: "discard"` explicitly
+- `createCrudListFilterContract(...)` defaults to `invalidValues: "reject"` for a strict server boundary
+- set `invalidValues` explicitly when a package is choosing a non-default validation posture
 - use `invalidValues: "reject"` when malformed filter values should fail validation and produce a 400-style contract error
 - use `invalidValues: "discard"` when malformed filter values should be ignored and normalization should drop them
 - route query validation runs before auth, so this choice changes whether malformed unauthenticated requests fail at validation or fall through to auth
 - for normal HTTP CRUD handlers, route-level `discard` means the handler receives already-parsed filter values for the explicit fields you listed, so the action layer will not see those discarded bad values again later
-- the filter runtime is still a deliberate two-phase exception: schema parsing owns query-field values, then `applyQuery(...)` maps those parsed values back through filter keys and SQL semantics
-
-```js
-async function list(query = {}, callOptions = {}) {
-  return crudRepositoryList(repositoryRuntime, knex, query, options, callOptions, {
-    modifyQuery(dbQuery, context = {}) {
-      return contactsListFiltersRuntime.applyQuery(dbQuery, context.query || {});
-    }
-  });
-}
-```
+- the filter contract is still a deliberate two-phase exception: schema parsing owns public query-field values, then `toJsonRestQuery(...)` maps those parsed values to JSON REST filter keys and SQL semantics
 
 #### Best practices
 
 - Keep client-only filters in the generated page-local `listFilters.js`. Move definitions into a CRUD package only when server code or another page needs to share them.
 - Keep the filter keys identical all the way through: definition key, query param key, and repository meaning.
-- Prefer `createCrudListFilterQueryField(...)` plus `createCrudListFilterQuerySchema(...)` at route/action boundaries so accepted structured-filter params stay visible in app code.
+- Prefer `createCrudListFilterContract(...)` for server-backed structured filters so route/action validators, JSON REST search schema, and repository query normalization stay derived from one shared definition.
 - Use `type: "presence"` for null/not-null filters such as assigned vs unassigned storage. Do not model those as custom enums plus `applyQuery(...)` overrides unless the SQL semantics are genuinely different from `whereNotNull(...)` / `whereNull(...)`.
-- Use `createCrudListFilters(...)` unless the list semantics are truly unusual.
+- Use `createCrudListFilters(...)` directly only for non-JSON REST repository code that needs direct Knex filtering without JSON REST registration.
 - Use `q` for free-text and explicit query params for structured filters.
-- Run `jskit doctor` after wiring filters. It flags inline filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`.
+- Run `jskit doctor` after wiring filters.
 
 ### Pattern 4: lookup-backed structured filters
 
@@ -1456,7 +1487,7 @@ The runtime already handles both together.
 
 #### Server side
 
-Let the generic list search handle `q`, and let your custom validator/repository code handle the structured filters.
+Let the generic list search handle `q`, and let `createCrudListFilterContract(...)` handle the structured route/action validators, JSON REST search schema, and repository query normalization.
 
 #### Best practices
 
@@ -1612,8 +1643,10 @@ Use `scaffold-field` when it fits, then review the generated result. It patches
 Touch:
 
 - `packages/<crud>/src/shared/<crud>ListFilters.js` and make it the only authored filter-definition module
-- `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)`, or `packages/<crud>/src/server/listQueryValidators.js` if you extracted list-query composition there
-- `packages/<crud>/src/server/repository.js` so the list query applies the runtime
+- `packages/<crud>/src/server/<crud>ListFilterContract.js` with `createCrudListFilterContract(...)`
+- `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so list validators include `<crud>ListFilterContract.queryValidator`, or `packages/<crud>/src/server/listQueryValidators.js` if you extracted list-query composition there
+- the provider registration so `createJsonRestResourceScopeOptions(resource, { searchSchema: <crud>ListFilterContract.jsonRestSearchSchema })` merges the JSON REST search schema
+- `packages/<crud>/src/server/repository.js` so the list query calls `<crud>ListFilterContract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)`
 - the app-owned list page or list-runtime composable that calls `useCrudList(...)`
 
 If the filter is lookup-backed, touch that same client file again to wire `useCrudListFilterLookups(...)`.

package/package.json

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

package/patterns/crud-repository-mapping.md

@@ -12,8 +12,9 @@ Default JSKIT pattern:
 4. Let generic CRUD runtime handle standard writable `date-time` fields automatically at the DB write seam.
 5. Use `storage.writeSerializer` only for non-default write serialization.
 6. Use `storage: { virtual: true }` for computed output fields.
-7. Register computed SQL projections once in the repository runtime with `virtualFields`.
-8. Let generic CRUD read paths apply those projections automatically.
+7. For `createCrudResourceRuntime(...)` repositories, register computed SQL projections once with `virtualFields`.
+8. For internal JSON REST repositories, register SQL-selected output fields with `createJsonRestResourceScopeOptions(resource, { queryFields })`.
+9. Let generic read paths apply those projections automatically.
 
 Field metadata rules:
 - for a normal override, write:
@@ -80,6 +81,35 @@ const repositoryRuntime = createCrudResourceRuntime(resource, {
 });
 ```
 
+Internal JSON REST pattern:
+- keep the API field in the resource schema as `storage: { virtual: true }`
+- pass server-only SQL projection callbacks through `createJsonRestResourceScopeOptions(...)`
+- keep query projection SQL in the provider/server registration file, not in browser-imported page code
+
+Example:
+
+```js
+await addResourceIfMissing(
+  api,
+  "receivals",
+  createJsonRestResourceScopeOptions(resource, {
+    queryFields: {
+      remainingProcessableWeight: {
+        type: "number",
+        select({ knex, column }) {
+          return knex.raw("?? - coalesce(??, 0)", [
+            column("received_weight"),
+            column("processed_weight")
+          ]);
+        }
+      }
+    }
+  })
+);
+```
+
+If the resource module is server-only, a field may also declare `storage.queryProjection`; `createJsonRestResourceScopeOptions(...)` moves it into JSON REST `queryFields` and removes the virtual field from the storage schema. Prefer the `queryFields` option when the resource module is shared with client code.
+
 What CRUD core does for you:
 - default select columns include only column-backed output fields
 - create/update write payloads serialize standard writable `date-time` fields centrally
@@ -99,5 +129,5 @@ Review checks:
 - standard datetime DB write serialization stays automatic and runtime-owned
 - any non-default DB write serialization lives in `storage.writeSerializer`, not in per-repository hooks
 - computed fields use `storage: { virtual: true }`
-- repository runtime registers matching `virtualFields`
+- repository runtime registers matching `virtualFields`, or the JSON REST provider registers matching `queryFields`
 - no per-method projection duplication when generic CRUD reads already cover the field

package/patterns/filters.md

@@ -35,25 +35,30 @@ Generated client shape:
 - `<CrudListFilterSurface :filters="listFilters" :runtime="filterRuntime" />`
 
 Server-side pattern, only when implementing real backend filter semantics:
-1. Put reusable server-aware filter definitions in the CRUD package if the filter contract needs to be shared outside one generated page.
+1. Put reusable filter definitions in the CRUD package if server code or multiple pages need the same contract.
    Example path: `packages/<crud>/src/shared/<crud>ListFilters.js`
-2. Build the server runtime from that module with `createCrudListFilters(...)`.
-3. Build route/action validators explicitly with `createCrudListFilterQueryField(...)` plus `createCrudListFilterQuerySchema(...)`, and use `applyQuery(...)` in the repository. There is no default validator mode or route-runtime alias.
+2. Build a server contract from that module with `createCrudListFilterContract(...)`.
+3. Use the contract's `queryValidator` in route/action input composition.
+4. Pass the contract's `jsonRestSearchSchema` into `createJsonRestResourceScopeOptions(..., { searchSchema })`.
+5. Call `contract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)` in the JSON REST repository path.
 
 Exact file checklist:
 - create `packages/<crud>/src/shared/<crud>ListFilters.js`
-- update `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list query validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)` inside `createCrudListFilterQuerySchema(...)`, or update `packages/<crud>/src/server/listQueryValidators.js` if that package already extracts list-query composition there
-- update `packages/<crud>/src/server/repository.js` so list queries call the runtime's `applyQuery(...)`
+- create `packages/<crud>/src/server/<crud>ListFilterContract.js` with `createCrudListFilterContract(...)`
+- update `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list query validator includes `listFilterContract.queryValidator`
+- 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 generated 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 generated filter runtime instead of replacing `CrudListFilterSurface`
 
 Validation mode is part of the contract:
-- there is no default mode and no fallback alias, so every explicit structured filter field must choose `invalidValues: "reject"` or `invalidValues: "discard"` deliberately
+- `createCrudListFilterContract(...)` defaults to `invalidValues: "reject"` for a strict server boundary
+- set `invalidValues` explicitly when a package is choosing a non-default validation posture
 - use `invalidValues: "reject"` when malformed filter values should fail validation and return a 400-style contract error
 - use `invalidValues: "discard"` when malformed filter values should be ignored and normalization should drop them
 - route query validation runs before auth, so this choice affects whether malformed unauthenticated requests fail at validation or fall through to auth
 - for normal HTTP CRUD handlers, route-level `discard` means the action layer receives already-parsed values for those explicit filter fields; do not assume route `discard` plus action `reject` will still reject malformed HTTP query strings later
-- CRUD list filters are still a deliberate two-phase exception: schema parsing owns query-field values, then the server runtime reprojects those parsed values through filter keys and `applyQuery(...)`
+- CRUD list filters are still a deliberate two-phase exception: schema parsing owns public query-field values, then the server contract reprojects parsed values to JSON REST filters with `toJsonRestQuery(...)`
 
 Keep separate:
 - free-text search uses `records.searchQuery` and `q`
@@ -77,18 +82,18 @@ Use runtime presets when:
 
 Put unusual SQL semantics on the server:
 - examples: `pending` meaning `whereNull("ccp1_passed")`, or business-specific status buckets that combine multiple columns
-- implement those in `createCrudListFilters(..., { apply: { ... } })`
+- implement those in `createCrudListFilterContract(..., { apply: { ... } })`
 - do not use custom `apply` just for null/not-null checks when `type: "presence"` fits
 
 Avoid:
 - local filter composables that duplicate the same keys the server already knows about
 - a custom validator shape that does not match the page state
-- hiding accepted structured filter params behind whole-query validator generation when the route/action contract can list them directly
+- hand-rolled route/action validators or repository filters that duplicate `createCrudListFilterContract(...)`
 - hand-rolled preset apply/reset/active-state helpers when `useCrudListFilters(..., { presets })`, `applyPreset(...)`, and `matchesPreset(...)` fit
 - per-screen `useList()` wrappers for lookup-backed filters when `useCrudListFilterLookups(...)` fits
 - editing generated `.vue` files just to add basic filter controls; use the page-local `listFilters.js` seam first
 - overloading `q` with structured filter meaning
-- inline filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`; keep definitions in a named module
+- inline filter-definition objects passed into `useCrudListFilters(...)`, `createCrudListFilters(...)`, or `createCrudListFilterContract(...)`; keep definitions in a named module
 
 Good shape:
 - `src/pages/home/customers/listFilters.js`
@@ -96,7 +101,9 @@ Good shape:
 - generated page passes `listFilters` into `useCrudListScreen(...)`
 - shared screen runtime passes `filterRuntime.queryParams` into the list request
 - `packages/receivals/src/shared/receivalListFilters.js`
-- `createCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, ...)`
+- `createCrudListFilterContract(RECEIVAL_LIST_FILTER_DEFINITIONS, { columns, invalidValues: "reject" })`
+- `createJsonRestResourceScopeOptions(resource, { searchSchema: receivalListFilterContract.jsonRestSearchSchema })`
+- `buildJsonRestQueryParams(JSON_REST_SCOPE_NAME, receivalListFilterContract.toJsonRestQuery(query))`
 - `const listFilters = useCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, { presets: [...] })`
 - `const filterLookups = useCrudListFilterLookups(RECEIVAL_LIST_FILTER_DEFINITIONS, { values: listFilters.values, ... })`
 - `queryParams: listFilters.queryParams`
@@ -108,7 +115,7 @@ Preset contract notes:
 
 Review checks:
 - one filter definition source of truth: generated page-local `listFilters.js` for client-only filters, or a shared CRUD-package module when server code imports the same definitions
-- server validator/repository logic derived from that source, with route/action query params still listed explicitly
+- server validator, JSON REST search schema, and repository query projection derived from that source through `createCrudListFilterContract(...)`
 - client query params/chips/reset logic derived from that source
 - lookup-backed filters use the shared lookup helper, not a page-local mini-framework
 - the two-phase server exception is intentional and documented, not accidental drift

package/patterns/generated-ui-contract-tracking.md

@@ -55,7 +55,7 @@ Generated JSKIT apps should feel like real adaptive apps by default, not framewo
 - Item 3 is complete for current generated surfaces: page, CRUD, shell, and starter outputs require compact/medium/expanded coverage, horizontal overflow checks, generated screen checks, and 48px tap target checks. Calendar/grid/bottom-sheet specialist generators remain future scope until those generators exist.
 - Item 5 is complete for current generators: `primary`, `secondary`, `utility`, `detail`, `workflow`, and `none` are centralized in the generated UI contract, generators consume that contract, and `utility` resolves to seeded `shell.global-actions` topology.
 - Item 6 is complete for the default shell: compact app bars use compact density and bounded top-left/top-right regions, while primary navigation remains in semantic bottom navigation instead of app-bar chrome.
-- CRUD filters are client-side by default: generated list pages create a page-local `listFilters.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `filterRuntime.queryParams` into the list request and renders `CrudListFilterSurface`. Server filter behavior remains explicit app/package work.
+- CRUD filters are client-side by default: generated list pages create a page-local `listFilters.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `filterRuntime.queryParams` into the list request and renders `CrudListFilterSurface`. When server filtering is needed, promote the definitions into a shared package module and use `createCrudListFilterContract(...)` so route/action validators, JSON REST search schema, and repository query normalization stay derived from the same definition.
 - CRUD bulk actions are client-side by default: generated list pages create a page-local `listBulkActions.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `useCrudListBulkActions(...)` and keeps selection controls hidden until actions are declared.
 - Generated CRUD page templates delegate their screen chrome to shared `users-web` screen components (`CrudListScreen`, `CrudViewScreen`, and `CrudAddEditScreen`) so list/view/form load states, retry actions, responsive shell layout, filters, and bulk actions do not drift across generated pages.
 - Routine resource-load errors stay local to the generated screen and retry affordance. Action feedback uses the shell error policy through `action-feedback`.

package/patterns/server-search.md

@@ -10,20 +10,21 @@ Core rule:
 - for current JSKIT CRUD apps, the server search contract lives in `resource.searchSchema` on the internal JSON REST path
 - 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
 
 Fresh generated CRUD repositories already follow this path:
 
 ```js
 return api.resources.contacts.query({
-  queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, query),
+  queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, contactListFilterContract.toJsonRestQuery(query)),
   simplified: false
 }, createJsonRestContext(context));
 ```
 
 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
-3. `*Resource.js`: define the backend filter behavior in `searchSchema`
+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 })`
 
 ## Decision Rules
 
@@ -147,6 +148,26 @@ That means:
 - `q` and the structured filter keys are accepted publicly
 - the repository may still add internal-only keys later
 
+For structured list filters, prefer the generated contract shape:
+
+```js
+const receivalListFilterContract = createCrudListFilterContract(
+  RECEIVAL_LIST_FILTER_DEFINITIONS,
+  {
+    columns: {
+      status: "status",
+      supplierContactId: "supplier_contact_id",
+      arrivalDate: "arrival_datetime"
+    },
+    invalidValues: "reject"
+  }
+);
+```
+
+Use `receivalListFilterContract.queryValidator` at route/action boundaries. Use `receivalListFilterContract.jsonRestSearchSchema` when registering the JSON REST resource. Use `receivalListFilterContract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)`.
+
+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"`
 - filters that must never be supplied by the client directly
@@ -197,6 +218,7 @@ function buildScopedQuery(query = {}, context = null) {
 ## Keep These Boundaries Clean
 
 - 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.

package/reference/autogen/packages/crud-core.md

@@ -133,7 +133,9 @@ Exports
 - `CRUD_LIST_FILTER_INVALID_VALUES_DISCARD`
 - `createCrudListFilterQueryField(filterDefinition = {}, { invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {})`
 - `createCrudListFilterQuerySchema(structure = {})`
+- `createCrudListFilterJsonRestSearchSchema(runtime = {}, { columns = {}, apply = {} } = {})`
 - `createCrudListFilters(definitions = {}, { columns = {}, apply = {} } = {})`
+- `createCrudListFilterContract(definitions = {}, { columns = {}, apply = {}, invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {})`
 Local functions
 - `cloneTransportSchema(value)`
 - `buildSingleOrMultiTransportSchema(itemSchema)`
@@ -144,6 +146,18 @@ Local functions
 - `buildFilterQuerySchemaDefinition(filterEntries = [], { invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {})`
 - `projectNormalizedFilterValues(filterEntries = [], source = {}, errors = {})`
 - `normalizeColumnsMap(columns = {})`
+- `resolveJsonRestFilterActualField(filter = {}, columns = {})`
+- `renderInternalJsonRestFilterKey(filter = {}, suffix = "")`
+- `createJsonRestSearchSchemaEntry({ type = "string", actualField = "", filterOperator = "=", extra = {} } = {})`
+- `buildJsonRestFilterItemSchema(filter = {})`
+- `buildJsonRestSimpleFilterSearchSchemaEntry(filter = {}, { actualField = "" } = {})`
+- `buildJsonRestRangeFilterSearchSchemaEntries(filter = {}, { actualField = "" } = {})`
+- `buildJsonRestPresenceFilterSearchSchemaEntry(filter = {}, { actualField = "" } = {})`
+- `buildJsonRestCustomFilterSearchSchemaEntry(filter = {}, customApply = null)`
+- `resolveCrudListFilterEntries(value = {})`
+- `addJsonRestDateFilterValues(target = {}, filter = {}, value = "")`
+- `addJsonRestFilterValue(target = {}, filter = {}, value)`
+- `normalizeCrudListFilterJsonRestQuery(runtime = {}, query = {})`
 - `applyDefaultFilterQuery(queryBuilder, filter = {}, value, column = "")`
 
 ### `src/server/listQueryValidators.js`
@@ -295,7 +309,7 @@ Local functions
 
 ### `src/server/routeContracts.js`
 Exports
-- `createCrudJsonApiRouteContracts({ resource = {}, routeParamsValidator = null, listSearchQueryValidator = defaultListSearchQueryValidator, lookupIncludeQueryValidator = defaultLookupIncludeQueryValidator } = {})`
+- `createCrudJsonApiRouteContracts({ resource = {}, routeParamsValidator = null, listSearchQueryValidator = defaultListSearchQueryValidator, lookupIncludeQueryValidator = defaultLookupIncludeQueryValidator, listFilterQueryValidator = null } = {})`
 Local functions
 - `isRecord(value)`
 - `resolveSchemaFieldDefinitions(definition = null)`

package/reference/autogen/packages/json-rest-api-core.md

@@ -26,7 +26,7 @@ Exports
 - `buildJsonRestQueryParams(resourceType = "", query = {}, { include = undefined } = {})`
 - `createJsonApiInputRecord(resourceType = "", attributes = {}, { id = null, relationships = null, resource = null } = {})`
 - `createJsonApiRelationship(resourceType = "", id = null)`
-- `createJsonRestResourceScopeOptions(resource = {}, { writeSerializers = {}, normalizeId = null } = {})`
+- `createJsonRestResourceScopeOptions(resource = {}, { writeSerializers = {}, normalizeId = null, searchSchema = null, queryFields = null } = {})`
 - `createJsonRestContext(context = null)`
 - `extractJsonRestCollectionRows(payload = null)`
 - `isJsonRestResourceMissingError(error = null)`
@@ -40,9 +40,13 @@ Local functions
 - `cloneJsonRestResourceValue(value, { writeSerializers = {} } = {})`
 - `normalizeScopeValue(value)`
 - `normalizeJsonRestText(value, { fallback = "" } = {})`
+- `normalizeJsonRestFilterValue(value)`
 - `normalizeJsonRestObject(value)`
 - `normalizeJsonRestList(value)`
 - `resolveJsonRestCollectionRelationships(resource = {})`
+- `normalizeJsonRestQueryField(fieldName = "", fieldDefinition = {}, projectionDefinition = null)`
+- `isJsonRestVirtualField(fieldDefinition = null)`
+- `applyJsonRestQueryFields(scopeOptions = {}, extraQueryFields = {})`
 - `extractJsonApiInputRelationships(attributes = {}, resource = null, relationships = null)`
 
 ### root