feat(spec,objectql,metadata-protocol): grouped and aggregated queries honour search

[objectstack-fleet]

Fixes #20358
Clause-②: yes

What this does

A grouped or aggregated query now honours ADR-0061 search. Route (A) from triage (5871414670):

• @objectstack/spec (packages/spec/src/data/data-engine.zod.ts): EngineAggregateOptionsSchema declares search and searchFields with the same Zod expression as EngineQueryOptionsSchema (z.union([z.string(), FullTextSearchSchema]), z.array(z.string())). The structured search arm carries flag defaults, so the aggregate options now have two shapes. ADR-0122 and check:spec-parsed-alias therefore require EngineAggregateOptionsParsed. It is declared, and its isomorphism pin leaves type-alias-convention.pin.test.ts (780 to 779). That is the one added export: check:api-surface reports 0 breaking, 1 added.
• @objectstack/objectql (packages/objectql/src/engine.ts): ENGINE_AGGREGATE_OPTION_KEYS gains the two keys. aggregate() runs them through the existing expandSearchOnAst, via a small carrier helper (expandSearchOnAggregateOptions), and does not add a second expander. The expansion sits at the same point in the sequence as on find: after the where doors (lowerWhereFilterArray), and before the AST is built, tokens resolve and the security middlewares run. The helper returns a copy of the caller's bag, so the bag is never written through.
• @objectstack/metadata-protocol (packages/metadata-protocol/src/protocol.ts): findData's grouped branch passes search / searchFields to engine.aggregate. searchFields was already validated before the branch fork (the INVALID_FIELD gate), so both branches refuse the same bad override.

Mechanism hypotheses, measured:

• ① Only EngineAggregateOptionsSchema is read. DataEngineAggregateOptionsSchema (the deprecated legacy schema) has no runtime reader: git grep finds it only in packages/spec tests and the type-alias pin. It is left unwidened.
• ② The grouped branch site held as described.
• ③ At base, the engine refused search on aggregate (rejectUnknownEngineOptions), confirmed.
• ④ The card's before-state reproduced at the public door (below).

Landing site beyond the three declared files: the public-door pin went into packages/rest/src/list-view-grouping-query-door.test.ts as a new §10. That file already drives the card's 186-row fixture through the real RestServer → findData → ObjectQL.aggregate → sqlite SqlDriver chain on both aggregate tiers. The pin is test-only, and no second harness was written.

Before / after at POST /api/v1/data/:object/query

Before (reproduced by reverting only the protocol pass-through, which is the base's door behaviour; the engine change is inert when the key is not sent): { groupBy: ['business_unit'], aggregations: [count], search: 'harbour' } answered five groups, northgate_operations 86 / northgate_quality 61 / riverside_plant 31 / northgate_plant 7 / harbour_office 1, the unsearched answer. On both tiers, the flat { search: 'harbour' } returned one row.

After: [{ business_unit: 'harbour_office', count: 1 }], total: 1, on both tiers.

Tests

Head of this PR: 2196566d3f. The full suites ran on 3576fd34e7 (this branch with origin/main acd009521e merged in). The two commits after it change only packages/objectql/src/engine-aggregate-search.test.ts: the find double now applies the caller's limit (check:objectql-double-limit), and three as any erasures became typed calls (check:query-options-erasure). That file and objectql's typecheck were re-run on 2196566d3f. All vitest runs used --maxWorkers=2.

package	run	result
@objectstack/objectql	vitest run --project local	328 files, 6084 passed
@objectstack/objectql	vitest run --project repo	5 passed
@objectstack/objectql	typecheck (tsc + scripts + test layer)	exit 0, re-run on 2196566d3f
@objectstack/objectql	src/engine-aggregate-search.test.ts on 2196566d3f	17 passed
@objectstack/metadata-protocol	vitest run	189 files (+3 skipped), 2750 passed, 19 skipped
@objectstack/metadata-protocol	typecheck	exit 0
@objectstack/rest	vitest run --project local	216 files, 3923 passed, 26 skipped
@objectstack/rest	vitest run --project repo	8 passed
@objectstack/rest	typecheck (tsc + test layer)	exit 0
@objectstack/spec	vitest run --project local	568 files, 16692 passed, 1 todo
@objectstack/spec	vitest run --project repo	690 passed
@objectstack/spec	typecheck (tsc + scripts + test layer)	exit 0

The filter direction is the changed packages themselves. @objectstack/rest is included because it hosts the public-door pin and its route tests cover grouped queries. The downstream consumers of the widened EngineAggregateOptions type are covered by the ones that compile against it here (objectql, metadata-protocol and rest typecheck); check:api-surface shows 0 removed or narrowed.

New pins:

• packages/rest/src/list-view-grouping-query-door.test.ts §10, the public door, both aggregate tiers (driver-sql native GROUP BY, and the in-memory lowering). Each tier assertion checks which face served the query.
  • The measured case: search: 'harbour' returns the ONE group, total: 1, and equals the grouping of the flat searched rows. The in-memory tier's rows read carries $icontains and no search key.
  • search: 'northgate': every header number, sum_amount included, equals the grouping of the flat searched rows.
  • searchFields: ['owner'] narrows the answer to the owner_3 rows. The oracle is the fixture generator, not the door. The one-row unit drops out, and the narrowed answer differs from the default-field answer.
  • search + having: search drops riverside_plant, and having drops northgate_plant.
  • aggregations with no groupBy: 154, where the unsearched control gives 186.
  • A grouped query with an unscannable searchFields is 400 / INVALID_FIELD.
• packages/objectql/src/engine-aggregate-search.test.ts, both tiers:
  • the grouped answer equals the grouping of find()'s searched rows (default fields, narrowed, structured form, AND-ed with where, multi-term);
  • one expander: the where the driver receives from aggregate deep-equals the one find sends for the same bag, and neither AST carries search / searchFields;
  • the aggregate over a search equals the aggregate over the same filter written as where;
  • no-groupBy aggregations, search + having, and the caller's frozen bag is not written through;
  • $search / $searchFields are still refused on aggregate, as unknown options;
  • drift pin: a proof table must cover ENGINE_OPTION_KEY_SETS.aggregate exactly, and every legal key must have an observable effect. This is the question findOne's drift pin asks, now asked of this verb.
• packages/spec/src/data/data-engine.test.ts: a parse keeps both keys in both search forms, and the aggregate options refuse the values the query options refuse. The two keys' input JSON Schemas deep-equal EngineQueryOptionsSchema's (one declaration on both verbs).
• The existing drift pin engine-unknown-option.test.ts (each legal set equals its schema's shape) holds unchanged. So does the unknown-key refusal pin for aggregate ('bogus'), byte for byte.

Reverse verification (one-shot, not left in the tree)

Both ablations committed the fix first, then mutated through scripts/ablation-replace.mjs (literal anchor, on-disk counts and blob hashes). Each armed an absolute-path restore trap, and each restore was proven by blob equality with HEAD and an empty git diff HEAD.

• A: protocol pass-through removed (the base's door behaviour), pinned through dist/.
  • Mutation: the anchor search: options.search, + searchFields: options.searchFields, was deleted, taking the blob from 508f88c8c8e0 to f8a47dbaf791. @objectstack/metadata-protocol was rebuilt, and ablation-dist-preflight --absent confirmed the marker was gone from all 24 built files.
  • list-view-grouping-query-door.test.ts: 10 failed / 34 passed. Every positive §10 case failed on both tiers, in the predicted direction: the measured case received the five unsearched groups, 86/61/31/7/1. The searchFields refusal case stayed green, because that gate sits before the branch fork.
  • Restore: rebuilt, the marker was present again in both dist chunks, the tree was clean, and the file returned to 44 passed.
• B: engine expansion call removed (the keys stay legal but are never executed), in source (objectql tests import ./engine.js).
  • engine-aggregate-search.test.ts: 13 failed / 4 passed. The 12 behavioural cases failed across both tiers, and so did the drift pin, on its search proof, which is the declared-but-unexecuted shape it exists to catch. The 4 that stayed green were the frozen-bag case and the two $search refusals, none of which depend on the expansion.
  • Restore: blob 177d256d61d4 equals HEAD, and git diff HEAD is empty.

Gates

node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 114 commands. All 114 were run on 2196566d3f, each exit captured before any pipe and reconciled with --ran: 114 derived, 112 run, 2 NOT-MEASURED, 0 UNRUN. 111 exited 0, including check:spec-parsed-alias, check:api-surface, check:authorable-surface, check:docs, check:export-origins, check:generated, check:liveness, check:query-options-erasure, check:objectql-double-limit, check:where-matcher, check:engine-double-contract, check:adr-0087-registration, check:changeset-no-major and check:nul-bytes.

check:skill-examples refused its prerequisite on the first run (client-react not built). It was run after building @objectstack/client-react..., and 259 prose examples type-check (exit 0).

• NOT MEASURED: check:dual-build-cjs-loads, reason: exit 3, PREREQUISITE NOT MET (it needs every package's dist/; CI builds them).
• NOT MEASURED: check:type-check-debt, reason: my 420 s timeout fired mid re-measure (exit 124). It needs the whole ./packages closure built, which lint.yml does first.
• NOT MEASURED: check-engine-split-ratio --days 90, reason: the clone is shallow and the gate refused (exit 2) rather than compute over a truncated window.

Spec artefacts, regenerated only where check:generated proved them stale:

• api-surface/data.json (+EngineAggregateOptionsParsed: 0 breaking, 1 added);
• export-origins/data.json;
• content/docs/references/data/data-engine.mdx;
• authorable-surface/data.json (+2 rows, written by the spec build's gen:schema).

After the merge of origin/main, check:generated reported all 15 artifacts up to date against a freshly built packages/spec/dist.

Acceptance notes

• Published skill row now understates the aggregate key set, and is not edited here. In skills/objectstack-query/SKILL.md, the Calling Convention table lists engine aggregate's legal keys as context, where, groupBy, aggregations, having, timezone, and after this PR the closed set also holds search and searchFields. The row understates the set: nothing it names is refused, but a reader would not know search works. skills/** is a Tier H governed surface and outside this card's declared file surface, so the one-row edit (0 net lines) is left for the seat to route. It is raised in the dev report.
• findData's grouped branch still spells the bag as any. Every key in it is now declared, so the erasure could go. Dropping it moves protocol.ts's count in the shrink-only scripts/query-options-erasure-baseline.json (6 to 5), which is outside this card's surface. Carrier: whoever next touches that branch.
• The engine's unknown-option refusal is a bare Error, with no ADR-0112 code / status. This is pre-existing and unchanged byte for byte. findData never builds the aggregate bag from caller keys, so the refusal is not reachable from POST /data/:object/query, and it stays pinned by message as before.
• engine.count still takes no search. So the flat branch under search + limit still reports a page-local total estimate, which is documented behaviour and unchanged here.
• objectui follow-up (triage note 3). The console's workaround, which hands grouping back to the page window while a toolbar search is active, can end once a release carries this. compileListViewGroupQuery does not carry search itself; a client spreads search onto the compiled body, as §10 does. That card is the accepting seat's to file, with Blocked-by: on this one.
• DataEngineAggregateOptionsSchema is deliberately not widened. It is the deprecated legacy aggregate schema, with no runtime reader (measured by git grep: packages/spec tests and the type-alias pin only).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/metadata-protocol, @objectstack/objectql, @objectstack/spec, touching 13 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/api-surface/data.json, packages/spec/authorable-surface/data.json, packages/spec/export-origins/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

16 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 9801da1234761c14eb88663635792723e41d359f.

⛔ 7 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 3 changed file(s) yielded no anchor (packages/spec/api-surface/data.json, packages/spec/authorable-surface/data.json, packages/spec/export-origins/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 70 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 9801da1234761c14eb88663635792723e41d359f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e420e174128269e203658b042d036956ea1a14b6 — the merge of head 91e08b5f6402f55bd107c2cbc8e5e34fa74aa817 into base 9801da1234761c14eb88663635792723e41d359f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e420e174128269e203658b042d036956ea1a14b6 && git checkout e420e174128269e203658b042d036956ea1a14b6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9801da1234761c14eb88663635792723e41d359f 91e08b5f6402f55bd107c2cbc8e5e34fa74aa817 && git checkout -B drift-repro 9801da1234761c14eb88663635792723e41d359f && git merge --no-ff 91e08b5f6402f55bd107c2cbc8e5e34fa74aa817

node scripts/docs-audit/affected-docs.mjs --json 9801da1234761c14eb88663635792723e41d359f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 9801da1234761c14eb88663635792723e41d359f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 2196566d3fb74d497a2c2ca9dc3cc65a8a82d4ff
Local-runs: none

Inputs, and nothing else: card #20358 (body and every comment — the filing and triage 5862519690, the retriage request 5868769184, the retriage answer 5871414670 (route A, re-routed to domain:spec), the claim 5872209176, the os-dev-report 5875170281); PR #20487 (body, comments: none, reviews: none, file list: 12 files, +668/-5) and the net diff origin/main...refs/os-seat2/pr20487 at merge base acd009521e; the check-runs on the head. Read-only throughout: git object reads and REST GETs; nothing built, run or re-run.

Check-runs on this head: none exist. The check-runs listing for 2196566d3f answers total_count: 0; the workflow-runs listing by head_sha answers 0 and by branch claude/issue-20358-aggregate-honours-search answers 0; the five check-suites (vercel, fly-io, claude, cloudflare, objectstack-fleet) are queued with 0 runs; the only commit status is Vercel success (advisory). Cause, read from the workflow files at the head: lint.yml and ci.yml trigger on pull_request and merge_group (push only on main), and the PR is mergeable_state: dirty, for which the platform queues no pull_request run. So not one of the seven required contexts (Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard) is concluded on this head, and none is presumed green here. This record judges the diff; the gate verdicts are owed by the merge round's head, where the seat's mechanical delta check and the enqueue pre-check (every check green) apply. Per the brief, the conflict itself (packages/spec/src/type-alias-convention.pin.test.ts plus three generated spec artefacts) is not a FAIL reason.

① Derived judgments

Accept-set changes.

1. EngineAggregateOptionsSchema (packages/spec/src/data/data-engine.zod.ts) gains search: z.union([z.string(), FullTextSearchSchema]).optional() and searchFields: z.array(z.string()).optional() — the same Zod expressions as EngineQueryOptionsSchema (lines 142 and 151), pinned by the new spec test's per-key input JSON Schema deep-equal. RIGHT: route (A) exactly as triage 5871414670 named it; the schema is non-strict, so a parse used to strip both keys.
2. ENGINE_AGGREGATE_OPTION_KEYS (packages/objectql/src/engine.ts) gains search and searchFields; ENGINE_OPTION_KEY_SETS.aggregate follows by reference. RIGHT: a key rejectUnknownEngineOptions refused at base is now accepted AND executed. The existing drift pin engine-unknown-option.test.ts (each legal set equals its schema's shape minus tombstones) holds by construction and is not in the diff; the new proof-table pin requires every legal aggregate key to have an observable driver effect. $search and $searchFields stay refused on aggregate (pinned, with the refusal text naming the two new legal keys).
3. ctx.api.object(name).aggregate() (ObjectQLObject.aggregate, engine.ts ~17400) spreads the caller's bag into engine.aggregate, so it inherits the widening without an edit. RIGHT, and the changeset names it.
4. IMPLICIT, and not named by the dev: DataEngineAggregateRequestSchema.query is EngineAggregateOptionsSchema.extend(RpcLegacyFilterMixin) (data-engine.zod.ts:1308), so the RPC envelope's aggregate arm — and DataEngineRequestSchema's union through it — now accepts search / searchFields. The regenerated content/docs/references/data/data-engine.mdx shows it: the DataEngineAggregateRequest.query and DataEngineRequest option tables gained the two rows beside filter. Judged RIGHT and harmless: a whole-tree git grep at the head finds no runtime reader of DataEngineAggregateRequest* or DataEngineRequestSchema outside packages/spec; the api-surface entry is the same const; the widening is the same two optional keys from one declaration. Recorded so the derived surface is named.
5. DataEngineAggregateOptionsSchema (legacy, deprecated) is left unwidened. VERIFIED from the code, not from the dev's prose: it is composed from BaseEngineOptionsSchema.extend({ filter, groupBy, aggregations with method }) independently of the widened schema, and a whole-tree git grep at the head finds only its declaration, its z.input alias, the spec generated artefacts (declaration-map, json-schema manifest, authorable-surface base, dropped-refinements baseline), one sentence in content/docs/kernel/contracts/data-engine.mdx, and its isomorphism pin — no runtime reader. Mechanism hypothesis 1 holds; its iso pin staying (pin file line 785) is consistent, since its input still equals its infer.
6. The other runtime callers of engine.aggregate (packages/mcp/src/stdio-data-bridge.ts:439, packages/services/service-analytics/src/plugin.ts:346, packages/runtime/src/action-execution.ts:360, packages/objectql/src/summary-aggregate.ts:111) build their bags from named keys or hand-declared slices (McpDataBridge.aggregate declares where, groupBy, aggregations, timezone; the MCP tool input is a hand-authored z.object with its own alias table), so the widening reaches none of them and nothing new is dropped at a second door. The MCP aggregate tool offering no search is pre-existing and not this card's.

Public-surface changes.

7. New export EngineAggregateOptionsParsed (z.infer of the schema); api-surface/data.json +1 (0 breaking, 1 added), export-origins/data.json +1. RIGHT and forced: ADR-0122 rule 2 (scripts/check-spec-parsed-alias.mjs) requires a bare z.input alias's schema to name its parsed state or be tsc-pinned isomorphic, and FullTextSearchSchema carries .default() flags (fuzzy, operator, highlight), so input no longer equals infer — the same reason EngineQueryOptionsParsed exists. The pin Iso_data_dataEngine__EngineAggregateOptionsSchema leaves and the count moves 780 to 779 in all three spellings the file carries (section header, test title, toHaveLength), with the runtime companion recomputing it from source.
8. authorable-surface/data.json +2 rows (data/EngineAggregateOptions:search, data/EngineAggregateOptions:searchFields). RIGHT: written by the spec build's gen:schema, matching the two keys.
9. content/docs/references/data/data-engine.mdx regenerated (+19) — an AUTO-GEN tree, not hand-edited. RIGHT.

Security ordering, answered from the code on both verbs.

10. find runs expandSearchOnAst at engine.ts:11246, before executeWithMiddleware at ~11313. aggregate runs expandSearchOnAggregateOptions at :16247 — after foldEngineOptionAliases, rejectUnknownEngineOptions and lowerWhereFilterArray; before rejectCredentialAggregation (which reads only aggregations[].field); before the having doors; before the AST is built at :16463 (where: query.where reads the reassigned, expanded bag); before resolveWhereTokens; and before executeWithMiddleware at :16514. The same point in the sequence as find. RIGHT.
11. FLS oracle: the security plugin's step 2.9 predicate guard (packages/plugins/plugin-security/src/security-plugin.ts ~3572 to 3611, assertReadableQueryFields from predicate-guard.ts) runs on opCtx.ast for every read operation (the options.where substitution applies to update and delete only), and collectQueryFields walks ast.where, having, orderBy, groupBy, aggregations[].field and aggregations[].filter. Because the search expansion has already been ANDed into ast.where as { field: { $icontains } } clauses on BOTH verbs, a searchFields naming an FLS-hidden or partially masked field — or a default searchable field hidden for this caller — is refused 403 field_predicate_denied before RLS injection, identically on find and aggregate. No grouped-count oracle opens that find does not already close. RLS and sharing injection (step 3, and the read-depth branch that lists aggregate beside find, findOne and count) runs after, composing { $and: [caller where including search, rls] } the same way on both verbs — ADR-0061 D5 (no separate unguarded search path) holds. RIGHT. The searchable set is server-resolved by resolveSearchFields in @objectstack/spec/data (declared searchableFields or auto-default; secret, encrypted and PII fields excluded; an override intersected, never widened) and consults no caller permission — one rule on both verbs — and the protocol's assertSearchFieldsAreSearchable gate sits above the branch fork (protocol.ts ~10937), so an unscannable override is 400 INVALID_FIELD on both branches (pinned in rest §10).

One expander, both tiers.

12. expandSearchOnAggregateOptions builds a carrier { object, where, search, searchFields } and calls the same private expandSearchOnAst with this._registry.getObject(object) — the schema find passes as _findSchema — so field resolution, the searchFields over search.fields precedence, the term-AND / field-OR shape, the enum label-to-value mapping and the pinyin companion clause are one code path; it returns a copy with the two keys gone (the caller's frozen bag is pinned untouched) and returns the same reference when neither key is present. Both aggregate tiers read the post-middleware ast: native drv.aggregate(object, ast, ...), and the in-memory lowering's driver.find(object, rowsAst) where rowsAst is ast minus groupBy, aggregations and having — where rides through on both. The objectql pin deep-equals the driver-received where of aggregate against find's for four bags on both tiers; the rest door pin checks the in-memory tier's rows read carries $icontains and no search key. RIGHT — no second expander.

Protocol.

13. findData's grouped branch passes search: options.search and searchFields: options.searchFields, read after the $search / $searchFields alias consumption and after the searchable-fields gate, so both branches read the same normalised values; the flat branch is untouched; engine.count still takes no search (documented, unchanged). RIGHT. The bag stays as any — see ③.

Tests and the sibling. The rest door §10 (11 cases, both tiers with the serving tier asserted, flat-parity and unsearched controls, searchFields narrowing with the fixture generator as oracle, search with having, no-groupBy, the INVALID_FIELD refusal), the objectql file (17: parity, one-expander deep-equal, where-equivalence, frozen bag, $search refusal, the proof-table drift pin over ENGINE_OPTION_KEY_SETS.aggregate) and the spec file (3) pin the mechanism at the door, the engine and the declaration. The two ablations in the PR body turn red in the predicted direction (A: door 10 failed / 34 passed; B: engine 13 failed / 4 passed, the drift pin included) — the dev's readings, cited here and not re-run. objectui at the pinned sha: packages/plugin-grid/src/useServerGrouping.ts:311 deliberately strips $search / $searchFields off the header query (the workaround the card names), and packages/types/src/data.ts and packages/data-objectstack/src/index.ts consume EngineAggregateOptions as a type — two added optional keys are source-compatible, so the sibling is unaffected.

② Semver level

.changeset/20358-aggregate-honours-search.md grades @objectstack/spec minor, @objectstack/objectql minor, @objectstack/metadata-protocol patch; the PR body carries Clause-②: yes and the changeset body Clause-②: yes (widening).

• Clause-②: yes (widening) is RIGHT: two published accept sets (EngineAggregateOptionsSchema; the engine's ENGINE_AGGREGATE_OPTION_KEYS) admit two keys they refused or stripped before, nothing previously admitted is refused, nothing is renamed or retired, and one public export is added. (widening) is the only legal arm for that direction; not (narrowing), not breaking, so no ADR-0087 disposition marker is owed (check-adr-0087-registration: a non-breaking changeset is not its business) and "Nothing to migrate" is true.
• @objectstack/spec minor — RIGHT: a purely additive widening of a published schema plus a new export takes at least minor (the WHICH LEVEL ruling mechanised in check-changeset-no-major.mjs).
• @objectstack/objectql minor — RIGHT: its accept set widens, reachable through engine.aggregate and ctx.api.object().aggregate().
• @objectstack/metadata-protocol patch — RIGHT: its wire accept set does not change (QuerySchema.search was already accepted on POST /data/:object/query; FindDataRequestSchema is untouched); what changes is that the grouped branch now honours a key it accepted — a bug fix in a released package, patch, never skip-changeset. The level gate is PR-scoped ("at least one package whose src/** the diff moves at minor or above") and is satisfied twice.
• skip-changeset absent — RIGHT.

③ Boundary flags

Dev deviations (os-dev-report 5875170281, six):

1. Landing site beyond the three declared source files: packages/rest/src/list-view-grouping-query-door.test.ts §10, test only, in the file that already drives the card's 186-row fixture through RestServer, findData, ObjectQL.aggregate and sqlite on both tiers. ACCEPTED — triage execution note 2 landed without a second harness.
2. Extra export EngineAggregateOptionsParsed and the iso-pin removal (780 to 779). ACCEPTED — forced by ADR-0122 rule 2, inside the owned file surface (① item 7).
3. origin/main merged into the branch before the full-suite run (merge commit 3576fd34e7). ACCEPTED as process; the head is dirty against current main again, which is the merge round now running.
4. authorable-surface/data.json +2 rows written by the spec build's gen:schema. ACCEPTED — mechanical, matches the keys (① item 8).
5. Commit trailers in AGENTS.md's model-free form and the session-URL PR footer, not the harness reminder's model-named trailer. ACCEPTED — AGENTS.md is the source of truth, and the reminder itself yields to a repo rule.
6. Stopped its own queued runner (its own process group) to merge main first. Not a diff concern; noted.

open_questions[0] — the skills/objectstack-query/SKILL.md Calling Convention row (engine aggregate: context, where, groupBy, aggregations, having, timezone; "a key outside the row is refused by name"). The seat's answer — route A, a separate skills-lane card after landing, the row stays out of this PR — STANDS, judged from the code:

• Nothing in this diff makes the sentence false BEFORE landing: the row describes the engine main and the published packages have, and at base rejectUnknownEngineOptions still refuses search on aggregate (mechanism hypothesis 3, and the untouched 'bogus' refusal pin).
• After landing on main the row UNDERSTATES: search / searchFields become legal and executed on aggregate, so "a key outside the row is refused by name" is false for those two keys. It never causes a refused call; the harm is an agent that believes the row and groups a page of searched rows on the client — the workaround this card retires.
• No gate pins the row against ENGINE_OPTION_KEY_SETS: scripts/check-corpus-claim-drift.mjs cites SKILL.md:154 (the SQL / NoSQL column header) only, and packages/spec/scripts/skill-map-guards.test.ts nothing — the staleness is silent, not a red gate. The diff touches no governed surface (Prime Directive feat: Comprehensive CRM example demonstrating all ObjectStack protocol features #14 register: no docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md), so keeping the row out leaves this PR on its default landing path; this record is the at-tier clause-② review the claim owed.
• Sequencing note for the seat, not an escalation: skills/ ships to customer projects (the create-objectstack scaffold copies it), so a release that consumes this changeset before the row lands publishes a skill that contradicts the published engine for that release. Land the row before the next cut when practical — one table row, and it understates rather than refuses.

out_of_scope_findings (three):

• The as any on the grouped-branch aggregate bag could go now that every key in it is declared (scripts/query-options-erasure-baseline.json, shrink-only, protocol.ts 6 to 5). AGREED out of scope: the diff adds two keys inside the existing erasure without moving the count; carrier: whoever next touches that branch.
• rejectUnknownEngineOptions throws a bare Error without an ADR-0112 code. AGREED pre-existing and byte-unchanged; unreachable from POST /data/:object/query for aggregate because findData builds the bag from named keys.
• The objectui follow-up ending the page-window grouping workaround under a toolbar search (useServerGrouping.ts:311), Blocked-by: this card — the accepting seat's to file (triage note 3).

Additional flags raised by this review, none blocking:

• ① item 4 (the RPC envelope's implicit widening) is named because the dev's mechanism hypothesis 1 measured the legacy schema's readers only. No action needed.
• No security pin accompanies the change (a search over an FLS-hidden field on aggregate answering 403). Not a defect: the guard's coverage is by construction (opCtx.ast on every read verb) and the diff does not touch it; a pin is a hardening the next security-lane touch may add.
• Check-runs: none on this head (above). A precondition for enqueue, not a verdict input.
• The PR is a draft with os-tesla assigned, no comments and no reviews at the reading.

Implemented-by: claude/issue-20358-aggregate-honours-search
Reviewed-by: session_014EJ1ED8X4MMrT18BhVx4tx

VERDICT: PASS

---

Generated by Claude Code