@jskit-ai/agent-docs 0.1.105 → 0.1.107

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

@@ -1336,8 +1336,8 @@ If the filter contract should be shared with server code, promote it into a CRUD
 
 - create `packages/contacts/src/shared/contactListFilters.js`
 - 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 `packages/contacts/src/server/registerRoutes.js` so `createCrudJsonApiRouteContracts(...)` receives `listFilterQueryValidator: contactListFilterContract.queryValidator`
+- update `packages/contacts/src/server/actions.js` so `createStandardCrudListQueryValidators(...)` receives the same `listFilterQueryValidator`
 - 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(...)`
 
@@ -1466,21 +1466,49 @@ That one contract gives the server:
 - `toJsonRestQuery(query)` for repository query normalization
 - `applyQuery(...)` when a non-JSON REST repository still needs direct Knex filtering
 
-Wire the contract into route and action validators:
+Wire the contract independently into the standard route and action query
+groups:
 
 ```js
-const listRouteQueryValidator = composeSchemaDefinitions([
-  listCursorPaginationQueryValidator,
-  listSearchQueryValidator,
-  listParentFilterQueryValidator,
-  contactListFilterContract.queryValidator,
-  lookupIncludeQueryValidator
-], {
-  mode: "patch"
+const {
+  listRouteContract
+} = createCrudJsonApiRouteContracts({
+  resource,
+  listFilterQueryValidator: contactListFilterContract.queryValidator
 });
 ```
 
-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.
+```js
+input: composeSchemaDefinitions([
+  workspaceSlugParamsValidator,
+  ...createStandardCrudListQueryValidators({
+    resource,
+    listFilterQueryValidator: contactListFilterContract.queryValidator
+  })
+])
+```
+
+This does not couple route and action layers together. Each layer still owns
+its validator; both consume the same explicit standard group so pagination,
+search, parent filters, includes, typed sparse fieldsets, and structured
+filters cannot drift.
+
+If `resource.contract.listFilters.queryValidator` already owns the filter
+validator, call `createStandardCrudListQueryValidators({ resource })` instead.
+Append a validator after the standard group only for genuinely additional,
+non-filter query input. Never provide the same filter validator through both
+paths.
+
+Do not manually reconstruct the standard list group from its individual
+validators. Standard view actions likewise compose:
+
+```js
+input: composeSchemaDefinitions([
+  workspaceSlugParamsValidator,
+  recordIdParamsValidator,
+  ...createStandardCrudViewQueryValidators()
+])
+```
 
 Merge the JSON REST search schema when the provider registers the resource:
 
@@ -1532,6 +1560,13 @@ Choose the invalid-value contract deliberately:
 - 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 `createCrudListFilterContract(...)` for server-backed structured filters so route/action validators, JSON REST search schema, and repository query normalization stay derived from one shared definition.
+- Compose standard list and view query validators with
+  `createStandardCrudListQueryValidators(...)` and
+  `createStandardCrudViewQueryValidators()` rather than repeating the
+  individual standard validators.
+- Pass a server-backed structured-filter validator through
+  `listFilterQueryValidator`; append validators separately only for
+  additional non-filter query input.
 - 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(...)` 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.

package/guide/agent/generators/crud-generators.md

@@ -424,6 +424,22 @@ The same rule applies after later server scaffolds such as `addresses` and `comm
 
 For standard CRUDs, that file is intentionally compact. It uses `defineCrudResource(...)` from `@jskit-ai/resource-crud-core`, authors the canonical `schema` / `searchSchema` / `defaultSort` / `autofilter` shape once, and lets JSKIT derive the standard CRUD operation contracts from it.
 
+The generated server action validators are compact for the same reason.
+Standard list actions compose
+`createStandardCrudListQueryValidators({ resource })`; standard view actions
+compose `createStandardCrudViewQueryValidators()`. Do not expand those groups
+back into individual pagination, search, parent-filter, include, or
+sparse-field validators.
+
+When a CRUD adds a server-backed structured-filter contract, pass its
+`queryValidator` through the list group's dedicated
+`listFilterQueryValidator` option. If
+`resource.contract.listFilters.queryValidator` already owns it, `{ resource }`
+is sufficient. A validator belongs after the standard group only when it is
+genuinely additional, non-filter query input. This keeps route and action
+validation independent while preventing the two boundaries from drifting as
+the standard query contract evolves.
+
 ### Step 3: scaffold the UI
 
 Once the resource file exists, generate the UI route tree:

package/package.json

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

package/patterns/filters.md

@@ -60,19 +60,58 @@ Server-side pattern, only when implementing real backend filter semantics:
 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 a server contract from that module with `createCrudListFilterContract(...)`.
-3. Use the contract's `queryValidator` in route/action input composition.
+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.
 
 Exact file checklist:
 - create `packages/<crud>/src/shared/<crud>ListFilters.js`
 - 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 `packages/<crud>/src/server/registerRoutes.js` so
+  `createCrudJsonApiRouteContracts(...)` receives
+  `listFilterQueryValidator: listFilterContract.queryValidator`
+- 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 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`
 
+Standard route and action query composition:
+
+```js
+const {
+  listRouteContract
+} = createCrudJsonApiRouteContracts({
+  resource,
+  listFilterQueryValidator: recordsListFilterContract.queryValidator
+});
+```
+
+```js
+input: composeSchemaDefinitions([
+  workspaceSlugParamsValidator,
+  ...createStandardCrudListQueryValidators({
+    resource,
+    listFilterQueryValidator: recordsListFilterContract.queryValidator
+  })
+])
+```
+
+If `resource.contract.listFilters.queryValidator` already owns the filter
+validator, pass only `{ resource }`. Append a validator after the standard
+group only for genuinely additional, non-filter query input. Never supply the
+same filter validator through both paths.
+
+Do not reconstruct the standard list group from individual pagination,
+search, parent-filter, include, or sparse-field validators. The group keeps
+the independently validated route and action layers aligned as standard query
+features evolve. Standard view actions use
+`createStandardCrudViewQueryValidators()` for the same reason.
+
 Validation mode is part of the contract:
 - `createCrudListFilterContract(...)` defaults to `invalidValues: "reject"` for a strict server boundary
 - set `invalidValues` explicitly when a package is choosing a non-default validation posture
@@ -111,6 +150,8 @@ 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
 - hand-rolled route/action validators or repository filters that duplicate `createCrudListFilterContract(...)`
+- manually rebuilding the standard CRUD list/view validator groups from individual validators
+- appending a list-filter validator after `createStandardCrudListQueryValidators(...)` when it belongs in the dedicated `listFilterQueryValidator` option
 - 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
@@ -139,6 +180,10 @@ 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, JSON REST search schema, and repository query projection derived from that source through `createCrudListFilterContract(...)`
+- route and action boundaries independently compose
+  `createStandardCrudListQueryValidators(...)`, using the dedicated
+  `listFilterQueryValidator` option when the resource does not already own it
+- standard view actions compose `createStandardCrudViewQueryValidators()`
 - client query params/chips/reset logic derived from that source
 - initial route/default resolution completes before the first list request
 - lookup-backed filters use the shared lookup helper, not a page-local mini-framework

package/patterns/server-search.md

@@ -128,26 +128,40 @@ Keep `applyFilter` focused on query semantics:
 - do not put permission checks there
 - do not turn it into a second service layer
 
-Add route validators when:
+Add public query validation when:
 - the filter key is public and may arrive from HTTP query params
 - the page/UI needs a stable, validated query contract
 - malformed values should either be rejected or deliberately discarded
 
-Example route layer:
+For standard CRUD routes and actions, pass the structured-filter validator
+through the standard group's dedicated option:
 
 ```js
 input: composeSchemaDefinitions([
   workspaceSlugParamsValidator,
-  listCursorPaginationQueryValidator,
-  listSearchQueryValidator,
-  vetsListFiltersQueryValidator,
+  ...createStandardCrudListQueryValidators({
+    resource,
+    listFilterQueryValidator: vetsListFilterContract.queryValidator
+  })
 ])
 ```
 
 That means:
-- `q` and the structured filter keys are accepted publicly
+- 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
 
+Use the same `listFilterQueryValidator` option with
+`createCrudJsonApiRouteContracts(...)` at the route boundary. The layers
+remain independently validated; they share a small standard validator group
+rather than duplicating its current members.
+
+If `resource.contract.listFilters.queryValidator` already owns the filter
+validator, call `createStandardCrudListQueryValidators({ resource })`.
+Append validators separately only for genuinely additional, non-filter query
+input. Standard view actions use
+`createStandardCrudViewQueryValidators()`.
+
 For structured list filters, prefer the generated contract shape:
 
 ```js
@@ -229,5 +243,5 @@ function buildScopedQuery(query = {}, context = null) {
 - Same key, same field, simple behavior: `search: true`
 - Public alias or multi-field search: `searchSchema`
 - Complex SQL semantics: `searchSchema` + `applyFilter`
-- Public HTTP query key: add a route validator
+- 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