docs(query): stop enumerating a false closed set for the aggregate option keys

[objectstack-fleet]

Fixes #20792

Clause-②: no

Two hand-written docs sentences presented the aggregate option set as a closed three-key list. The list is false on both paths. This PR keeps each sentence's true point and drops the enumeration; no key list is pasted into prose (the generated reference owns it).

Changes

1. content/docs/protocol/objectql/query-syntax.mdx (Analytics: Revenue by Month)

   • Before: "engine.aggregate() accepts only where / groupBy / aggregations (plus a timezone for bucketing): there is no orderBy or limit on this path, so sort the returned rows yourself."
   • After: "engine.aggregate() takes a closed option set with no orderBy or limit (the full list is under EngineAggregateOptions in the Data Engine reference), so sort the returned rows yourself. It does carry a timezone for bucketing."

2. content/docs/data-modeling/queries.mdx (UTC bucketing callout)

   • Before: "the POST /api/v1/data/:object/query route forwards only where / groupBy / aggregations, so a query sent over REST always buckets on UTC calendar boundaries."
   • After: "the POST /api/v1/data/:object/query route does not forward timezone to the engine, so a query sent over REST always buckets on UTC calendar boundaries."

3. content/docs/kernel/contracts/data-engine.mdx (### EngineAggregateOptions, added in a second commit 7837c5c)

   • Before: an interface literal listing four of the eight keys, with groupBy typed as a string array.
   • After: a one-line pointer to the generated reference, /docs/references/data/data-engine#engineaggregateoptions; the AggregationNode interface and the distinct removal note are kept.

Code anchors (origin/main at 96e7244)

• packages/objectql/src/engine.ts:562-565: ENGINE_AGGREGATE_OPTION_KEYS = context, where, groupBy, aggregations, having, timezone, search, searchFields. Enforced at :16277 (rejectUnknownEngineOptions). No orderBy / limit, so the kept point holds.
• packages/metadata-protocol/src/protocol.ts:11324-11343: the engine.aggregate call inside findData forwards where, groupBy, aggregations, having, search, searchFields, context. timezone is not in the bag, and no timezone read exists in findData (:10937 to the call), so REST buckets on UTC.
• packages/rest/src/rest-server.ts:8808,8849: POST /data/:object/query calls p.findData(...), confirming the route reaches that path.
• Generated reference already lists all eight keys: content/docs/references/data/data-engine.mdx:891-906.

Census (hand-written content/docs/**, excluding references/ and releases/)

Prose patterns: "only where", "accepts only", "forwards only", "groupBy/aggregations", aggregate()-with-only/accepts/forwards, "drops having/search/timezone". Interface and type-literal patterns (added after review): EngineAggregateOptions, AggregateOptions, groupBy?:, aggregations?:, aggregate-signature blocks. Hits: the three fixed above (query-syntax.mdxsentence,queries.mdxsentence,kernel/contracts/data-engine.mdxinterface literal). Checked and left:kernel/contracts/data-engine.mdx:28,39(an import and theaggregate(...)signature, which name the type and copy no keys),:573(deprecated schema names),query-syntax.mdx:74-75(the QueryAST literal for find, not the aggregate option set),query-syntax.mdx:85, :1434, api/error-catalog.mdx:301, api/data-api.mdx:194`. No further enumeration.

Acceptance notes

• Stale comment on ENGINE_DRIVER_PASSTHROUGH_KEYS deliberately left out of this PR, as ruled.
• No changeset: docs-only, content/docs is not a published surface.

Verification

Gate list from node scripts/pm/dispatch-gates.mjs --commands (40 families), each run at head 7837c5c with exit 0 (after building @objectstack/lint..., @objectstack/spec and @objectstack/client-react... for the gates that read built output); --ran reconciliation: 40 derived, 40 run, 0 NOT-MEASURED, 0 UNRUN.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01VDtqoecgES7ScQYGbFVDRv

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: ddcc241958bfec38270e8fde7424a767090f4ca0
Local-runs: none

① Derived judgments

Read against origin/main d2b188fb57. The files below are byte-identical to the branch base except engine.ts, whose line numbers moved while the aggregate key set is unchanged.

• query-syntax.mdx:1337-1340: TRUE on every clause.
  • "closed": ENGINE_AGGREGATE_OPTION_KEYS (engine.ts:567-570) is enforced by rejectUnknownEngineOptions (:16361, :753-775).
  • The link to the Data Engine reference exists, and ## EngineAggregateOptions there (:891-906) lists all eight keys.
  • "no orderBy/limit": both keys are refused.
  • "timezone for bucketing": engine.ts:16705, :16776.
• queries.mdx:670-673: TRUE.
  • POST /data/:object/query (rest-server.ts:8808, :8849) reaches findData's only engine.aggregate call (protocol.ts:11324-11343), whose option bag carries no timezone.
  • The wire QueryAST has no timezone key, and bucketing reads only query.timezone, so "always UTC" holds.
• Triage rules: no key list is pasted into the prose, and both true conclusions are kept. TRUE.
• Remaining enumeration in hand-written content/docs/**: FOUND.
  • content/docs/kernel/contracts/data-engine.mdx:467-475 (hand-written per scripts/docs-audit/handwritten-docs.json:116) prints interface EngineAggregateOptions { where?; groupBy?: string[]; aggregations?; context? }. That is four of eight keys, the same false-by-omission set.
  • groupBy is also typed string[], hiding the structured form.
  • Triage 5906439697: "A third hit rides this card." The dev's census matched prose patterns only.

② Semver level

None. Docs only, no packages/**, no changeset needed; Clause-②: no is consistent.

③ Boundary flags

• Branch cut by hand from 96e724475c: accepted. The merge-base is on main, there is one commit, and merge-tree is clean.
• Gate exit codes absent from the --ran file: a reporting limitation of the tool's format, not a defect of the change.

Implemented-by: claude/issue-20792-aggregate-option-docs
Reviewed-by: session_01VDtqoecgES7ScQYGbFVDRv

VERDICT: FAIL

Required fix:

• In content/docs/kernel/contracts/data-engine.mdx:467-475, replace the four-key EngineAggregateOptions literal. Preferred, per triage's no-second-copy rule: a one-line pointer to /docs/references/data/data-engine#engineaggregateoptions, dropping the literal and keeping the AggregationNode block.
• Record the hit in the PR's census section.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 7837c5c8236a83b645d3e404874de975a26ee503
Local-runs: none

① Derived judgments

Read against origin/main 4cc5bcd858. The branch is ddcc241958 then 7837c5c823; the delta between them is content/docs/kernel/contracts/data-engine.mdx only.

• query-syntax.mdx:1336-1340: byte-identical to the sentence reviewed at ddcc241958, and still TRUE.
  • "closed option set": ENGINE_AGGREGATE_OPTION_KEYS, engine.ts:567-570, enforced at :16361 via :753-775.
  • "no orderBy/limit": both keys are refused.
  • "full list in the Data Engine reference": references/data/data-engine.mdx:891-906 lists all eight.
  • "timezone for bucketing": engine.ts:568, :16705, :16776.
• queries.mdx:669-673: byte-identical, and still TRUE.
  • POST /data/:object/query (rest-server.ts:8801-8849) reaches the only engine.aggregate call (protocol.ts:11324-11343), which forwards no timezone.
  • buildDriverOptions' execCtx.timezone (engine.ts:5127-5130) serves autonumber only. Bucketing reads only query.timezone, and the wire QuerySchema has no timezone. "Always UTC" holds.
• kernel/contracts/data-engine.mdx:467-483, the new edit: TRUE.
  • The pointer names the generated reference.
  • "aggregations takes AggregationNode entries": data-engine.zod.ts:368.
  • The anchor #engineaggregateoptions resolves: fumadocs remark-heading uses github-slugger, and the same form is used at api/metadata-api.mdx:66 and protocol/objectui/layout-dsl.mdx:570.
  • The kept AggregationNode block matches AggregationNodeSchema (query.zod.ts:272-296), including the distinct retirement.
• Own census over hand-written content/docs/**, prose and type literals: no remaining enumeration of the aggregate option set. Every hit was checked and cleared: EngineQueryOptions / QueryAST find literals, the legacy aggregate key note at query-syntax.mdx:1435, and the import and signature lines.
• Triage rules (5906439697): both true conclusions kept, no pasted key list, and the third hit rides the card. TRUE.

② Semver level

None. Three content/docs/** files and nothing under packages/**; no changeset; Clause-②: no is consistent.

③ Boundary flags

• The --ran file carries no exit codes: a limitation of the tool's format, not a defect.
• The dist built in round one was reused: accepted. The only change since is a docs file that no build consumes.

Implemented-by: claude/issue-20792-aggregate-option-docs
Reviewed-by: session_01VDtqoecgES7ScQYGbFVDRv

VERDICT: PASS