merge: main (#4344 action-body write lint, #4351/#4355 hook-bodies docs)

Both landed on the same surface while this branch was open, so the merge is a
reconciliation rather than a textual resolution:

- #4344 built the same `actions` + `objects[].actions` walk, with the same
  value-dedupe of defineStack's merged copies (it found the double-report the
  same way). Two walks over one surface would drift silently, so its
  `collectActionBodies` is now exported (module-level, not via the barrel —
  same posture as BODY_WRITE_SYSTEM_FIELDS), carries the bound object, and this
  rule consumes it. The duplicate walk and its helpers are deleted.

- The two rules split one write surface and answer different questions, so the
  suite, the barrel and the spec JSDoc now say which is which: `ctx.api` writes
  → does this field exist (did-you-mean); `ctx.record` writes → none of them
  land, declared or not (no did-you-mean, because the name is not the bug).

- #4351/#4355 rewrote the hook-bodies write-set section this branch also
  edited. Its write-shape table listed three shapes and said nothing about
  `ctx.record`, which this branch now checks — added the row plus the note that
  it is a different defect, and that the record rule's statically-opaque cases
  are covered by the runtime recorder instead.

Verified after the merge: lint 642, spec 7160, runtime 989, cli 628, spec
check:generated 8/8, typecheck + eslint clean, showcase 0 findings clean and
exactly 1 with the repro planted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/action-body-write-set-lint.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/lint": minor
+"@objectstack/spec": patch
+---
+
+feat(lint): L2 action-body writes to undeclared fields warn at author time (#4271)
+
+The write-set lint that #4305 gave L2 hook bodies now covers the other surface
+that carries one. An action body is the same artefact: the same
+`HookBodySchema` union, parsed by the same `HookBodySchema.safeParse` in
+`actionBodyRunnerFactory`, run in the same QuickJS sandbox. So it fails the
+same way — `ctx.api.object('crm_deal').update({ stag: 'won' })` inside an
+action succeeds, returns success to the caller, and the unknown column simply
+never lands. Half the surface was still blind.
+
+**New rule — `action-body-write-unknown-field` (advisory).** Wired into
+`REFERENCE_INTEGRITY_RULES`, so `os validate`, `os lint` and `os compile` all
+report it; it never blocks a build. Both places the runtime reads actions from
+are walked — top-level `actions` and `objects[].actions` — and a
+`defineStack`-merged action, which lives in both, is reported once at its
+authored path. That dedupe is by VALUE (bound object + name + body source), not
+by object identity the way `collectBundleActions` can afford: the suite runs on
+the schema-PARSED stack, and parsing rebuilds every node, so the two copies
+arrive as distinct objects that are merely equal. An identity check passes a
+shared-reference unit fixture and then reports the showcase app's one warning
+twice — which is exactly what it did before the end-to-end run caught it.
+
+**Only the `ctx.api` write family carries over, and that is the point.** An
+action's `ctx.input` is its PARAMS bag (`input: unwrapProxyToPlain(actionCtx
+?.params)`), not a record, so resolving those names against object fields would
+flag every correctly-named parameter — a pure false-positive machine, and a
+false positive kills an advisory lint. `ctx.record` is not a write surface
+either: the runner hands the body a plain snapshot and never writes it back, so
+`ctx.record.x = …` is discarded for *declared* and undeclared fields alike —
+a different defect from "the unknown column vanishes", and flagging only its
+undeclared half would imply the declared half persists.
+
+So the rule ships a declared **partition** of the shared
+`HOOK_BODY_WRITE_PATTERNS` rather than a second ledger:
+`ACTION_BODY_WRITE_PATTERN_IDS` (today: `api-crud-literal`) and
+`ACTION_BODY_WRITE_EXCLUSIONS` (`input-property-assign`,
+`input-object-assign`), each exclusion carrying its reason. The two halves are
+tested to cover the shared ledger exactly, so a fourth pattern landing on the
+hook side fails this rule's test until someone classifies it — silence is not a
+decision. Every applicable pattern is additionally proved end-to-end through
+the full validator (prefilter, pattern filter and field check included), and
+every exclusion is proved to be about applicability rather than an
+unextractable shape: the shared extractor still sees it, and this rule still
+reports nothing for it.
+
+One extractor, one field index, one implicit-field set, shared with the hook
+rule rather than copied. The action rule is the same check on the other body
+surface, so a second copy of `IMPLICIT_FIELDS` would drift exactly the way the
+five hand-copied system-field lists #4330 collapsed did.
+
+The lint stays off the kernel boot path, and lands one notch tighter than the
+hook side: the only applicable pattern is rooted at `ctx.api`, so an action
+body that never mentions it does not even parse, let alone load the ~9 MB
+TypeScript compiler. Guarded by `lazy-deps.test.ts`.
+
+`@objectstack/spec`: `ScriptBodySchema` and `ActionSchema.body` now point at
+the action-side rule and spell out that `ctx.input` (params) and `ctx.record`
+(a discarded snapshot) are not record-write surfaces — doc comments only, no
+schema or generated-artifact change.

.changeset/hook-bodies-write-set-docs.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(hook-bodies): the write-set section said the write side had no static checking, which #4305/#4344 made false (#4351) — rewritten as an accurate coverage description (three literal patterns, advisory `hook-body-write-unknown-field` / `action-body-write-unknown-field`, and the shapes the parser must skip, so a missing warning is not read as proof of correctness), the "accepted gap with no planned closure" conclusion retracted (#3700 stays accurate history; the gap was closed from the other end, by parsing the write set), the runtime paragraph corrected against measured behaviour, and the three now-stale cross-links in `hooks.mdx` updated to the renamed anchor. Releases nothing.

.changeset/request-body-schema-validation.md

@@ -0,0 +1,31 @@
+---
+'@objectstack/spec': patch
+'@objectstack/rest': minor
+'@objectstack/runtime': minor
+---
+
+Request bodies are now checked against the schemas the API catalog declares for them (#3899, the request-side dual of #3877).
+
+**Routes that now answer `400 VALIDATION_FAILED` + `fields[]` for a body violating their declared `requestSchema`** (previously the body was consumed raw, and a malformed one silently executed different semantics):
+
+- `POST /data/:object/query` — body must be a QueryAST (`FindDataRequestSchema`); a garbage body used to degrade into an unfiltered full read. The path `object` is now pinned into the forwarded query (a body `object` can no longer contradict the path).
+- `POST /data/:object` / `PATCH /data/:object/:id` — body must be a record object (`CreateDataRequestSchema` / `UpdateDataRequestSchema`).
+- `POST /data/:object/batch` — body must be a `BatchUpdateRequestSchema` (`operation` + `records[]`).
+- `POST /data/:object/createMany` — body must be a bare JSON array of records (`CreateManyDataRequestSchema`); `{ records: [...] }` (updateMany's envelope) is rejected with a pointer.
+- `POST /notifications/read` — body must be `{ ids: string[] }` (`MarkNotificationsReadRequestSchema`); a misnamed key used to become `markRead(userId, [])` — a 200 no-op that never cleared the badge.
+
+**Dispatcher automation routes now validate their bodies** (no catalog schema; hand-written guards):
+
+- `POST /automation` and `PUT /automation/:name` require a flow-definition object, and POST requires a non-empty `name` — a mistyped `name` used to register the flow under the key `undefined` and echo 200.
+- `POST /automation/:name/toggle` is strictly `{ enabled?: boolean }` — `{"enable": false}` (one letter off) used to ENABLE the flow and answer 200 `{enabled: true}`; it is now a 400 naming the offending key. An empty body still means enable.
+
+**`QuerySchema` now declares the search contract ADR-0061 actually serves** (additive): `search` accepts the canonical bare query string as well as the structured `FullTextSearch` form, and the server-validated `searchFields` narrowing is formally declared. Previously the schema declared only the object form while every surface (and the ADR's own conformance proof) sent the string — drift that surfaced the moment request bodies started being validated.
+
+**Catalog corrections in `@objectstack/spec` (`plugin-rest-api.zod.ts`)** — documentation-only tables:
+
+- `DEFAULT_NOTIFICATION_ROUTES` drops the four device/preferences endpoints — those server routes were removed in #3612 (never built), yet the table kept declaring them, `requestSchema` and all.
+- `DEFAULT_AUTOMATION_ROUTES`' trigger endpoint path is corrected `/trigger` → `/trigger/:name` (the mounted path; the flow name rides the path) and its `AutomationTriggerRequestSchema` declaration is removed — that schema never described this route's wire shape.
+- `DEFAULT_DATA_CRUD_ROUTES` gains the `POST /:object/query` entry (mounted since forever, previously undeclared), repoints create/update to the schemas the routes actually validate (`CreateDataRequestSchema` / `UpdateDataRequestSchema` — the old `CreateRequestSchema`/`UpdateRequestSchema` names described a `{ data }` envelope the wire never had), and drops `requestSchema` from GET/DELETE entries (path/query-bound inputs; nothing can violate them as a body).
+- New gates: catalog `requestSchema`/`responseSchema` strings must resolve to real exported Zod schemas, `requestSchema` may only sit on body-carrying methods, and every declared `requestSchema` on a mounted route has a violating-body → 400 conformance case (`packages/rest` + `packages/runtime` request-schema-gate suites).
+
+Migration: clients that already send the documented shapes are unaffected. If you relied on a malformed body being silently accepted (e.g. posting `{ records: [...] }` to `createMany`, a non-boolean `enabled` to toggle, or an off-schema analytics/query body), fix the request to the declared shape — the 400's `fields[]` names each offending key.

.changeset/rest-list-search-groupby-aggregations-rejected.md

@@ -0,0 +1,72 @@
+---
+"@objectstack/metadata-protocol": patch
+"@objectstack/objectql": patch
+"@objectstack/spec": patch
+"@objectstack/rest": patch
+---
+
+fix(data): `searchFields` / `groupBy` / `aggregations` naming a field that does not exist are rejected, not silently degraded (#4254)
+
+#4226 closed `sort` / `select` / `expand`; with the filter axis (#4134 / #4164 /
+#4181 / #4121) that made four field-naming read axes that either apply or fail.
+The same machine kept leaking on the remaining three, and each failure corrupted
+something the closed axes never touched:
+
+```
+search=alpha&searchFields=no_such  -> 200  MORE rows than the narrowing allowed
+groupBy=[no_such]                  -> 200  [{no_such: null, n: <true count>}]  N groups collapsed into 1
+sum(no_such)                       -> 200  0 — indistinguishable from a real zero
+```
+
+Each is now refused at the shared normalizer, so `GET /data/:object`,
+`POST /data/:object/query`, the export route and the runtime dispatcher give
+one answer instead of four.
+
+- **`searchFields` → `400 INVALID_FIELD`.** The `select` failure with the sign
+  flipped outward: the engine dropped unknown names and, when that emptied the
+  override, fell back to the FULL searchable set — so a parameter that exists
+  only to narrow a search widened it, and it changed which ROWS came back, not
+  just which columns. Its only in-framework caller is `GET /data/:object/export`
+  — the route whose `search` support just shipped so exports would stop
+  downloading "the unsearched superset … in a file that looks authoritative";
+  a typo'd `searchFields` did exactly that, one parameter over. Three causes,
+  three messages, because the fixes differ (the split #4226 drew on expand): a
+  name that is no field is a request typo; a REAL field outside the searchable
+  set needs the object changed (its message names the declared
+  `searchableFields` or the auto-default's type rule, whichever applies); and
+  a `searchableFields` entry that names no field is a STALE DECLARATION — a
+  bug on the object, called out as such because clients (objectui's list
+  search) echo the declaration verbatim. The allowed set is resolved by the
+  same `@objectstack/spec/data` function the engine's search expansion
+  consumes (`resolveSearchFieldResolution`, moved from objectql), so the gate
+  cannot drift from what search actually scans.
+- **`groupBy` → `400 INVALID_FIELD`.** The in-memory aggregation path projects
+  an unknown column as `null` for every row, so all rows landed in ONE bucket
+  whose count is the true row count — structurally perfect, identical to "this
+  column really holds a single value". A chart draws one bar; nothing says the
+  grouping never ran. Native SQL aggregation errors on the same input, so which
+  backend a deployment sits on decided the answer — the "two routes, opposite
+  answers" split, one axis over.
+- **`aggregations` → `400 INVALID_FIELD`.** `sum(<typo>)` folded a column of
+  `undefined` to `0` — the exact number an empty quarter produces, in reports
+  whose whole job is to be believed (`avg`/`min`/`max` answered `null` the same
+  way). `count` with no `field` (or the `'*'` sentinel) is the one legitimate
+  field-less form and passes.
+- **Unreadable SHAPES on the aggregation axes → `400 INVALID_QUERY`** — the
+  standard-catalog code that had no emitter since it was written, like
+  `INVALID_SORT` before #4226. A string `groupBy`, an entry naming no field, a
+  function or `dateGranularity` outside the spec enums, a missing `alias`: each
+  slipped past the `Array.isArray` routing guard (rows returned UNGROUPED) or
+  computed a silent placeholder (`null` results, a column keyed `"undefined"`,
+  one bucket per raw value under an unknown granularity).
+
+Tiering is unchanged from #4226: registry + field map present → authoritative;
+no registry / no field map / legacy array field map → the NAME gates skip (shape
+gates still apply — they need no schema). The engine's own tolerance is
+untouched: internal callers reaching `engine.find()` / `engine.aggregate()`
+directly are unaffected. `@objectstack/rest` also stops logging
+`INVALID_FILTER` / `INVALID_SORT` / `INVALID_QUERY` rejections as
+"[REST] Unhandled error" — they are client mistakes the response already
+explains, as `INVALID_FIELD` always was.
+
+Requests that name real fields are unaffected.

.changeset/typecheck-covers-the-test-layer.md

@@ -0,0 +1,4 @@
+---
+---
+
+ci(dx): the type-check coverage ratchet now judges the test layer too (#4311). #4324 counted a package covered the moment it declared a `typecheck` script — but 27 of the 48 it waved through `exclude` `**/*.test.ts` from the very `tsconfig.json` that `tsc --noEmit` reads, hiding 568 test files and 1451 errors behind a green check (`@objectstack/spec` alone: 272 files, 902 errors). A new `TESTS_COVERED` invariant fails any package that excludes its own tests without a measured `TEST_DEBT` entry, and the gate now prints both layers so the src figure can never again stand in for the whole. Nine packages that were already clean with tests included had the exclusion dropped outright; nine more graduate out of DEBT after repairing 44 NodeNext imports missing their `.js` extension — a repair that closed 110 errors (most of the "noise" tier was one unresolved import degrading symbols to `any`) and exposed 12 real defects in `service-settings` that those broken imports had been masking. Dev scripts, tests and CI only; releases nothing.

AGENTS.md

@@ -29,6 +29,19 @@ workspace package declares a `typecheck` script or carries a measured DEBT/EXEMP
 in `scripts/check-type-check-coverage.mjs`. New packages must arrive covered; a package
 that graduates deletes its ledger entry in the same PR.
 
+**Do not `exclude` `*.test.ts` / `*.spec.ts` from a package's `tsconfig.json`.** `tsc
+--noEmit` reads that config, so an exclusion there hides the tests from the check the
+`typecheck` script advertises — a green gate over source nothing read, which is the
+#4311 defect itself. The ratchet's `TESTS_COVERED` invariant fails on any new exclusion;
+the packages that already had one carry a measured `TEST_DEBT` entry and graduate by
+dropping the exclusion.
+
+One trap worth knowing before you read any of these counts: under `moduleResolution:
+NodeNext` a relative import missing its `.js` extension does not resolve, every symbol it
+names becomes `any`, and the callbacks over those symbols then report TS7006 "implicitly
+any". A pile of TS7006 is usually one broken import upstream, not a package that needs
+type annotations — fix the extension first and re-measure.
+
 ### Running the dev server
 
 | Scenario | Command | Notes |

content/docs/api/data-api.mdx

@@ -24,7 +24,8 @@ Query records with filtering, sorting, selection, and pagination.
 | `top` | query | Max records to return. No default — omitting it returns all matching records. |
 | `skip` | query | Offset |
 | `expand` | query | Comma-separated list of relations to eager-load. Must name a reference field (`lookup` / `master_detail` / `user` / `tree`) — otherwise `400 INVALID_FIELD`. |
-| `search` | query | Full-text search query |
+| `search` | query | Full-text search term, scanned case-insensitively across the object's searchable fields (its declared `searchableFields`, or a text-like auto-default when none are declared). |
+| `searchFields` | query | Comma-separated subset of the searchable fields for `search` to scan — narrows the scan, never widens it. A name outside the searchable set is `400 INVALID_FIELD`. |
 
 > **Note:** OData-style `$`-prefixed parameters (`$filter`, `$select`, `$orderby`, `$top`, `$skip`, `$expand`, `$count`, `$search`) are also accepted directly on this same endpoint as aliases — they're normalized internally to the parameter names above. There is no separate standalone OData endpoint.
 
@@ -116,6 +117,46 @@ a direction that is neither `asc` nor `desc`) is `400 INVALID_SORT`.
 `GET /data/:object/:id` applies the same `select` and `expand` rules, so the
 list and single-record routes cannot disagree about one field map.
 
+#### Neither is a search narrowing, a grouping, or an aggregation
+
+The last three field-naming axes follow the same rule. Each of these used to
+answer `200` with something that looked exactly like a served query — and each
+corrupts something the earlier axes do not:
+
+| Request | Result |
+|:---|:---|
+| `?search=alpha&searchFields=title` | scans only `title` |
+| `?search=alpha&searchFields=no_such_field` | `400 INVALID_FIELD` |
+| `?search=alpha&searchFields=amount` | `400 INVALID_FIELD` — real field, but not searchable |
+| `groupBy: ["status"]` | one bucket per status value |
+| `groupBy: ["no_such_field"]` | `400 INVALID_FIELD` |
+| `aggregations: [{function:"sum", field:"amount", alias:"total"}]` | the real total |
+| `aggregations: [{function:"sum", field:"no_such_field", alias:"total"}]` | `400 INVALID_FIELD` |
+| `aggregations: [{function:"count", alias:"n"}]` | `count(*)` — the one legitimate field-less form |
+
+- **`searchFields`** — the only parameter whose failure changed which **rows**
+  came back. An unknown name used to be dropped, and an override left empty
+  fell back to scanning *every* searchable column: a parameter that exists
+  only to **narrow** a search failed by **widening** it. Three causes get
+  three messages, because the fixes differ: a name that is no field (a typo in
+  the request), a real field outside the searchable set (declare it in
+  `searchableFields`), and a `searchableFields` entry that names no field (a
+  stale declaration — the bug is on the object, and clients that echo the
+  declaration verbatim are told so).
+- **`groupBy`** — an unknown column projected `null` for every row, so all
+  rows fell into **one bucket** whose count is the true row count:
+  structurally perfect, indistinguishable from a column that really holds a
+  single value. A chart draws one bar and nothing says the grouping never ran.
+- **`aggregations`** — `sum` over an unknown column folded blanks to **`0`**,
+  the exact number a genuinely empty quarter produces (`avg`/`min`/`max`
+  answered `null` the same way), in reports whose whole job is to be believed.
+
+A `groupBy` / `aggregations` value the spec cannot read at all — a bare string
+instead of an array, an entry that names no field, a function or date
+granularity outside the spec's enums, a missing `alias` — is
+`400 INVALID_QUERY`: those shapes were silently ignored, returning **ungrouped
+raw rows** with nothing to say the aggregation never happened.
+
 **Response**:
 ```json
 {