feat(analytics): honour widget dateGranularity, sortBy/sortOrder, and limit in dataset queries (#3588)

Three presentation options were accepted by the metadata layer and then dropped
by the analytics query builder — no SQL, no error. The only symptom was the
`sql` a dataset response echoes, so a dashboard could declare
`dateGranularity: 'month'` and quietly render one bar per record.

- `DatasetSelection.dateGranularity` buckets every selected date dimension.
  Precedence per dimension: an explicit `timeDimensions` granularity, then the
  selection's, then the dataset dimension's own default — so a widget can bucket
  a trend by month without the dataset committing every consumer to it.
- `order`/`limit`/`offset` are applied to the ASSEMBLED grid: after
  measure-scoped sub-queries merge, after `compareTo` columns attach, and after
  derived measures are computed. A derived measure is therefore a valid sort
  key, and the ObjectQL aggregate path — which has no ordering grammar, and
  which native SQL hands every date-bucketed query to — orders identically to
  native SQL. A single-query selection still pushes the window into the
  statement. An order key naming nothing the selection projects is rejected
  (400) rather than ignored.
- A `limit` without an `order` orders by the selected dimensions first, so it
  truncates a reproducible window instead of an arbitrary subset.
- The four query-affecting widget `options` keys plus `stageOrder` are declared
  on `DashboardWidgetOptionsSchema`, making a typo an author-time error. The bag
  stays open, so renderer extras pass through untouched.

Two latent bugs surfaced while fixing the above:

- `order`/`limit` were forwarded to EVERY sub-query. A measure-scoped
  supplementary query selects one measure, so an inherited ORDER BY named a
  column it never selected and an inherited LIMIT truncated it before the merge,
  dropping rows from the grid. Nothing hit this only because nothing passed
  `order`.
- The `compareTo` pass hand-built its query and skipped granularity resolution,
  merging a month-bucketed primary grid against raw-timestamp comparison rows.
  No dimension key matched, so every `<measure>__compare` column came back
  empty.

`ObjectQLStrategy` now also echoes a representative `sql` (date_trunc, WHERE,
ORDER BY, LIMIT; filter values parameterized, never inlined). The `sql` field
previously vanished whenever a query was date-bucketed, leaving an author unable
to tell "not implemented" from "this strategy doesn't report".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEZLBGyNoJMLvtGPqsMPRC

Author: claude

.changeset/analytics-widget-query-options.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/spec": patch
+"@objectstack/service-analytics": patch
+"@objectstack/rest": patch
+---
+
+feat(analytics): honour widget `dateGranularity`, `sortBy`/`sortOrder`, and `limit` in the dataset query (#3588)
+
+Three presentation options were accepted by the metadata layer and then dropped
+by the analytics query builder. They reached no SQL, produced no error, and the
+only way to notice was to read the `sql` a dataset response echoes — so a
+dashboard could declare `dateGranularity: 'month'` and quietly render one bar
+per record.
+
+- **`dateGranularity` now buckets.** `DatasetSelection` gained an optional
+  `dateGranularity`, applied to every selected `date` dimension. Precedence per
+  dimension: an explicit `timeDimensions` granularity, then the selection's,
+  then the dataset dimension's own default. A widget can bucket a trend by month
+  without the dataset committing every other consumer to that granularity.
+- **`order` / `limit` / `offset` now apply on every path.** They are applied to
+  the ASSEMBLED grid — after measure-scoped sub-queries merge, after `compareTo`
+  columns attach, and after derived measures are computed — so a derived measure
+  is a valid sort key and the ObjectQL aggregate path (which has no ordering
+  grammar, and which native SQL hands every date-bucketed query to) orders
+  identically to native SQL. A single-query selection still pushes the window
+  down into the statement. An `order` key that names nothing the selection
+  projects is now rejected (400) rather than silently ignored.
+- **`limit` is deterministic.** Without an `order`, a limit orders by the
+  selected dimensions first, so it truncates a reproducible window instead of an
+  arbitrary subset.
+- **Widget `options` is a contract again.** The four query-affecting keys
+  (`dateGranularity`, `sortBy`, `sortOrder`, `limit`) plus `stageOrder` are
+  declared on `DashboardWidgetOptionsSchema`, so a typo like `sortDirection` is
+  an author-time error. The bag stays open — renderer extras (`icon`, `columns`,
+  `striped`, …) pass through untouched.
+
+Two latent bugs surfaced while fixing the above and are fixed here too:
+
+- `order`/`limit` were forwarded to EVERY sub-query. A measure-scoped
+  supplementary query selects one measure, so an inherited `ORDER BY` named a
+  column it never selected, and an inherited `LIMIT` truncated it before the
+  merge — dropping rows from the assembled grid. Nothing hit this only because
+  nothing passed `order`.
+- The `compareTo` pass built its query by hand and skipped granularity
+  resolution, so a month-bucketed primary grid was merged against raw-timestamp
+  comparison rows. No dimension key matched and every `<measure>__compare`
+  column came back empty.
+
+`ObjectQLStrategy` now also echoes a representative `sql` (with `date_trunc`,
+`WHERE`, `ORDER BY`, and `LIMIT`; filter values parameterized, never inlined).
+Previously the `sql` field simply vanished from the response whenever a query
+was date-bucketed, leaving an author unable to tell "not implemented" from "this
+strategy doesn't report".

packages/rest/src/rest-server.ts

@@ -5260,7 +5260,7 @@ export class RestServer {
                     const msg = String(error?.message ?? error ?? '');
                     // Dataset-compiler D-C / unsupported-aggregate / read-scope
                     // errors are client-side mistakes — surface as 400.
-                    if (/not declared in the dataset|not backed by a declared relationship|not supported by the v1 dataset runtime|read-scope-sql/.test(msg)) {
+                    if (/not declared in the dataset|not backed by a declared relationship|not supported by the v1 dataset runtime|read-scope-sql|not a selected dimension or measure|is not a subset of the selected dimensions/.test(msg)) {
                         return res.status(400).json({ code: 'DATASET_INVALID', message: msg.slice(0, 1000) });
                     }
                     logError('[REST] Analytics dataset query error:', error);