Merge remote-tracking branch 'origin/main' into claude/query-top-limit-alias-fold

# Conflicts:
#	packages/metadata-protocol/src/protocol.ts

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/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/slot-lookup-ratchet-enforcement.md

@@ -0,0 +1,19 @@
+---
+---
+
+ci(tooling): enforce the #4251 slot-lookup sweep ratchet with a counted baseline
+
+The grandfather list shipped as paths in `eslint.config.mjs` under a comment
+reading "NEVER add an entry" — a promise nothing checked. ESLint cannot express
+a ratchet: an ignored file is ignored completely, so a NEW `getService<any>(…)`
+added to an already-listed file rode the old entry with `pnpm lint` green.
+
+The list moves to `scripts/slot-lookup-baseline.json` (file → site count) and
+becomes the single source: its keys are the config's `ignores`, its values are
+what `pnpm check:slot-lookup` enforces. The script re-runs ESLint with the
+grandfathering lifted and matches reports by the rule's exact message, so the
+counter cannot drift from the rule. It fails on a new file, a grown count, a
+stale entry, and — via a key-set comparison against the merge base with main —
+on a file being ADDED to the list, which no count check can see.
+
+Tooling and CI only; releases nothing.

.github/workflows/lint.yml

@@ -26,6 +26,12 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
+        with:
+          # The slot-lookup ratchet compares the baseline against its state at
+          # the merge base with main — the only way to see a file being ADDED
+          # to the grandfather list. A shallow clone has no merge base, and the
+          # check would degrade to "not verified" on every run.
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v7
@@ -57,6 +63,15 @@ jobs:
       - name: ESLint
         run: pnpm lint
 
+      # Slot-lookup sweep ratchet (#4251). `pnpm lint` above bans erasing a
+      # service-lookup result to `any` across packages/, but the files still
+      # holding pre-existing sites are grandfathered by path — and an ignored
+      # file is ignored COMPLETELY, so new erasures added to one ride the old
+      # entry in silence. This re-measures those files with the grandfathering
+      # lifted and holds them to a per-file count, so the list can only shrink.
+      - name: Slot-lookup ratchet
+        run: pnpm check:slot-lookup
+
       # Raw NUL guard (#3127): one literal U+0000 byte makes grep/ripgrep treat
       # the whole file as binary and silently return ZERO matches — the file drops
       # out of code search and out of every grep-based lint, with no error saying

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
 {

content/docs/api/error-catalog.mdx

@@ -74,7 +74,10 @@ ObjectStack uses a structured error system with **9 error categories** and **53
 **Cause:** A field name in the request does not exist on the target object. On a
 list read this also covers an unreserved query parameter — `GET /data/:object`
 reads those as field filters, so one naming no field could only match zero
-records and is rejected rather than answered with an empty page.  
+records and is rejected rather than answered with an empty page — plus every
+other read axis that names a field: `select`, `expand` (a real field that holds
+no reference gets its own message), `searchFields` (a real field outside the
+searchable set gets its own message), `groupBy`, and `aggregations[].field`.  
 **Fix:** Check the object schema for valid field names. Use `os meta get object <name>` to inspect the object's fields. If the name was meant as a
 *parameter* rather than a field, use the real one — page size is `top` / `$top`
 / `limit`, not `pageSize` / `perPage`; the response's `error` names the
@@ -117,8 +120,20 @@ substitute. See the [Data API](/docs/api/data-api).
 **Retry:** `no_retry`
 
 ### `INVALID_QUERY`
-**Cause:** The query structure is malformed.  
-**Fix:** Check the query syntax against the [Query Cheat Sheet](/docs/data-modeling/queries).  
+**Cause:** A `groupBy` / `aggregations` value the spec cannot read: a bare
+string where an array belongs, an entry that names no field, an aggregation
+function or `dateGranularity` outside the spec's enums, or a missing `alias`.
+(Field names that simply don't exist on the object are `INVALID_FIELD`
+instead.)  
+**Fix:** Check the aggregation shapes against the
+[Query Cheat Sheet](/docs/data-modeling/queries) — e.g.
+`{ "groupBy": ["status"], "aggregations": [{ "function": "sum", "field":
+"amount", "alias": "total" }] }`. `count` is the only function that may omit
+`field`.  
+**Why it is an error and not an empty result:** every one of these shapes used
+to be silently ignored or mis-read — rows came back **ungrouped**, or an
+unknown function computed `null` — in a response indistinguishable from a
+served aggregation.  
 **Retry:** `no_retry`
 
 ### `INVALID_FILTER`

content/docs/data-modeling/queries.mdx

@@ -364,6 +364,19 @@ three (only `count`/`sum`/`avg`/`min`/`max` are mapped), and the in-memory drive
 silently returns `null` for them. Avoid these three on SQL- or memory-backed objects.
 </Callout>
 
+<Callout type="info">
+Over the REST/protocol ingress, `groupBy` and `aggregations` are validated
+before they reach any driver. A field the object does not have is
+`400 INVALID_FIELD` — the in-memory fallback used to collapse an unknown
+`groupBy` column into one `null`-keyed bucket, and to answer `sum(<typo>)`
+with `0`. A value the spec cannot read (a non-array, an entry naming no
+field, a function or `dateGranularity` outside the enums above, a missing
+`alias`) is `400 INVALID_QUERY` — those shapes used to be ignored, returning
+ungrouped raw rows. `count` with no `field` (or `field: "*"`) is the one
+legitimate field-less form and passes. Internal callers reaching
+`engine.aggregate()` directly are unaffected.
+</Callout>
+
 ### Aggregation Example
 
 ```typescript
@@ -449,6 +462,17 @@ Only `query` and `fields` are implemented. The engine expands `search` into a dr
 `operator`.
 </Callout>
 
+<Callout type="info">
+`fields` (and its query-parameter spelling, `?searchFields=` / `?$searchFields=`) can only
+**narrow** the scan within the server-resolved searchable set — the object's declared
+`searchableFields`, or a text-like auto-default when none are declared. Over the
+REST/protocol ingress a name outside that set is `400 INVALID_FIELD`, with distinct
+messages for a field that does not exist and a real field that is not searchable. The
+engine used to drop unknown names and fall back to the full searchable set — a parameter
+that exists to narrow a search, silently widening it. Internal callers reaching
+`engine.find()` directly are unaffected.
+</Callout>
+
 ### Pinyin recall (Chinese deployments)
 
 When pinyin search is enabled (`OS_SEARCH_PINYIN_ENABLED` — auto-on when the stack's