diff --git a/‎.changeset/17973-compare-preset-lowering.md‎
Lines changed: 67 additions & 0 deletions b/‎.changeset/17973-compare-preset-lowering.md‎
Lines changed: 67 additions & 0 deletions
diff --git a/‎packages/services/service-analytics/src/__tests__/analytics-date-range-conformance.test.ts‎
Lines changed: 145 additions & 0 deletions b/‎packages/services/service-analytics/src/__tests__/analytics-date-range-conformance.test.ts‎
Lines changed: 145 additions & 0 deletions
diff --git a/‎packages/services/service-analytics/src/dataset-executor.ts‎
Lines changed: 102 additions & 3 deletions b/‎packages/services/service-analytics/src/dataset-executor.ts‎
Lines changed: 102 additions & 3 deletions
@@ -0,0 +1,67 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(analytics): a `dateRange` preset plus `compareTo` is lowered and shifted instead of refused as an "invalid date" (#17973)
+
+`DatasetExecutor.runCompare` read the STRING arm of `dateRange` as
+`[range, range]` — the degenerate fallback #17015 removed from every other
+analytics face. `parseUTC` was handed the preset NAME, so a declared, honoured
+member of the closed vocabulary was refused outright. Measured end to end
+through the executor, a valid preset plus `compareTo`:
+
+```
+DATASET_INVALID  400  [dataset-executor] invalid date in dateRange: "last_30_days"
+```
+
+The diagnostic is not merely unhelpful, it is FALSE. `last_30_days` is exactly
+what the schema, the dashboard date filter and the docs tell an author to
+write, so "invalid date" sends them to check a date that is already correct —
+a repair that does not exist. This face was not in #17015's kit, so nothing
+measured it and nothing noticed.
+
+Both arms now go through one face lowering, which calls the shared
+`resolveAnalyticsDateRangeString` for the string arm — the same call the
+ObjectQL strategy, the native-SQL strategy, the draft-preview evaluator and
+driver-memory's cube face make — and the lowered window is then projected onto
+the comparison math's UTC calendar, with `endExclusive` honoured so that a
+calendar preset's exclusive upper bound does not itself add a day to the
+projected window. On the UTC calendar, `this_month` plus
+`compareTo: { kind: 'previousYear' }` now compares September against the
+previous September, rather than refusing. ⚠️ Outside UTC the projection costs a
+day of its own — third note below.
+
+Three consequences worth knowing when you upgrade:
+
+- **A string outside the vocabulary now answers the shared envelope.** On this
+  path it used to be `DATASET_INVALID`; it is now
+  `ANALYTICS_DATE_RANGE_UNRECOGNIZED` / 400, the ADR-0112 envelope the other
+  faces already raise, with the message that lists the thirteen declared preset
+  names. One condition, one envelope. Code keying on `DATASET_INVALID` for an
+  unrecognised `dateRange` STRING should key on
+  `ANALYTICS_DATE_RANGE_UNRECOGNIZED` instead.
+- **The caller's explicit `[start, end]` window is untouched**, bound for bound,
+  with the inclusive upper reading it has always had — including the
+  `DATASET_INVALID "invalid date in dateRange"` refusal for a bound that is not
+  a date, which is unchanged.
+- **⚠️ A calendar preset lowered in a NON-UTC zone gives a comparison window one
+  day too wide** — in either direction, depending on which side of UTC the zone
+  sits. The comparison math is UTC-calendar throughout (`parseUTC` reads a bare
+  day as UTC midnight, `toISODate` emits a UTC day), so a window computed
+  against another zone's calendar is projected onto UTC day boundaries: east of
+  UTC the start lands a day early, west of UTC the end lands a day late.
+  Measured through the executor, `this_month` plus
+  `compareTo: { kind: 'previousYear' }` frozen at `2026-09-09` —
+  `UTC` gives `['2025-09-01','2025-09-30']` (30 days, correct),
+  `Asia/Shanghai` gives `['2025-08-31','2025-09-30']` and `America/New_York`
+  gives `['2025-09-01','2025-10-01']` (31 days each). ⛔ This is NOT a
+  regression: the same input used to be refused outright, so no
+  previously-working input behaves differently — what changed is that the
+  preset arm produces a window at all, which is what makes the projection
+  observable. Tracked in #18245. It is deliberately not repaired here, because
+  a timezone-aware calendar-day extraction in this module would be the second
+  implementation `analytics-date-range.ts`'s own header exists to refuse.
+
+`runCompare` is also registered as a face in the shared `dateRange` conformance
+kit, so the next face that forgets to lower a preset is caught by a test rather
+than by a customer.
@@ -48,8 +48,11 @@ import {
 import { DatasetSchema } from '@objectstack/spec/ui';
 import type { Cube } from '@objectstack/spec/data';
 import type { ExecutionContext } from '@objectstack/spec/kernel';
+import type { AnalyticsQuery, AnalyticsResult, IAnalyticsService } from '@objectstack/spec/contracts';
 import { AnalyticsService } from '../analytics-service.js';
 import { evaluateAnalyticsQueryOverRows, lowerPreviewDateRange } from '../preview-evaluator.js';
+import { compileDataset } from '../dataset-compiler.js';
+import { DatasetExecutor, lowerDatasetCompareDateRange } from '../dataset-executor.js';
 
 /** Frozen so the three rolling presets, whose bound is NOW, are comparable. */
 const NOW = new Date('2026-09-09T12:34:56.789Z');
@@ -130,10 +133,33 @@ async function lowerViaPreview(range: string | readonly string[]): Promise<Lower
     return lowerPreviewDateRange(range);
 }
 
+/**
+ * [#17973] The dataset executor's `compareTo` window — the FOURTH face in this
+ * package, and the one #17015 never reached. It kept the degenerate
+ * `[range, range]` fallback every sibling shed, so a DECLARED preset plus
+ * `compareTo` was refused outright. MEASURED on `b3b43b6ea`, before the fix:
+ *
+ * ```
+ * DATASET_INVALID  400  [dataset-executor] invalid date in dateRange: "last_30_days"
+ * ```
+ *
+ * ⛔ Read off the lowering rather than an emitted filter, for the preview
+ * face's reason and one more of its own: what this face EMITS is the SHIFTED
+ * window, so the window it resolved cannot be recovered from the query it
+ * issues without inverting the shift. `lowerDatasetCompareDateRange` is the ONE
+ * call site `runCompare` uses for either arm; the `APPLIES the window it
+ * reports` block below is the control that it really is wired there, driven end
+ * to end through the executor.
+ */
+async function lowerViaCompare(range: string | readonly string[]): Promise<LoweredDateRangeWindow> {
+    return lowerDatasetCompareDateRange(range);
+}
+
 const FACES: AnalyticsDateRangeFace[] = [
     { name: 'service-analytics (ObjectQL strategy)', lower: lowerViaObjectql },
     { name: 'service-analytics (native SQL strategy)', lower: lowerViaNativeSql },
     { name: 'service-analytics (draft-preview evaluator)', lower: lowerViaPreview },
+    { name: 'service-analytics (dataset executor compareTo)', lower: lowerViaCompare },
 ];
 
 beforeEach(() => {
@@ -253,3 +279,122 @@ describe('#16322 — the draft-preview evaluator APPLIES the window it reports',
         ])).toEqual(['lower', 'upper']);
     });
 });
+
+/**
+ * [#17973] ⭐ The executor face is registered above on its LOWERING; these cases
+ * are why that registration means anything — and they are the pin the card
+ * asks for, because "the string changed" is not the claim. The claim is that a
+ * declared preset is LOWERED to a real window and that window is SHIFTED.
+ *
+ * Driven end to end through `DatasetExecutor.execute`, reading the `dateRange`
+ * of every pass the executor issues. ⛔ The expectations are stated LITERALLY
+ * against the frozen clock and only cross-checked against the shared resolver —
+ * ⛔ never computed with `shiftRange`, which would restate the implementation
+ * and pass for any window at all.
+ *
+ * ⚠️ The PRIMARY pass keeps the preset NAME on purpose: the strategy behind it
+ * is itself a registered face and lowers it there (#16322). Only the comparison
+ * pass carries a resolved window, because only it is shifted.
+ */
+const CMP_DATASET = DatasetSchema.parse({
+    name: 'trend', label: 'Trend', object: 'events', include: [],
+    dimensions: [{ name: 'created_at', field: 'created_at', type: 'date', dateGranularity: 'month' }],
+    measures: [{ name: 'count', aggregate: 'count' }],
+});
+
+/** The `dateRange` of every pass the executor issues — primary first, then the shifted compare pass. */
+async function comparePasses(
+    dateRange: string | readonly unknown[],
+    kind: 'previousPeriod' | 'previousYear',
+): Promise<unknown[]> {
+    const seen: AnalyticsQuery[] = [];
+    const svc: IAnalyticsService = {
+        query: vi.fn(async (q: AnalyticsQuery): Promise<AnalyticsResult> => {
+            seen.push(q);
+            return { rows: [], fields: [] };
+        }),
+        getMeta: async () => [],
+    };
+    await new DatasetExecutor(svc).execute(
+        compileDataset(CMP_DATASET),
+        {
+            dimensions: ['created_at'], measures: ['count'],
+            timeDimensions: [{ dimension: 'created_at', dateRange, granularity: 'month' }],
+            compareTo: { kind },
+        } as never,
+        CTX,
+    );
+    return seen.map((q) => (q.timeDimensions ?? []).map((t) => (t as { dateRange?: unknown }).dateRange));
+}
+
+describe('#17973 — the dataset executor APPLIES the window it reports', () => {
+    // The frozen clock is the file-level `beforeEach`; the rolling presets' upper
+    // bound is NOW, so it has to be the same NOW here.
+
+    it('a CALENDAR preset is LOWERED, its exclusive end honoured, and the window SHIFTED', async () => {
+        // The shared resolver's own answer for the frozen clock: September 2026,
+        // ending at OCTOBER's first instant because the calendar presets stop
+        // BEFORE their end.
+        const w = resolveAnalyticsDateRangeString('this_month', { now: NOW });
+        expect([w.start, w.end, w.endExclusive])
+            .toEqual(['2026-09-01T00:00:00.000Z', '2026-10-01T00:00:00.000Z', true]);
+
+        // ⇒ the days that window COVERS are the 1st to the 30th — ⛔ not to the
+        // 1st of October, which is the off-by-one an inclusive reading of an
+        // exclusive bound produces — and `previousYear` is those same days a
+        // calendar year back.
+        expect(await comparePasses('this_month', 'previousYear')).toEqual([
+            ['this_month'],
+            [['2025-09-01', '2025-09-30']],
+        ]);
+    });
+
+    it('a ROLLING preset reaches NOW\'s own day and `previousPeriod` shifts by the window\'s length', async () => {
+        const w = resolveAnalyticsDateRangeString('last_30_days', { now: NOW });
+        // Ends at NOW, a moment it REACHES (#16179 leaves the rolling leg inclusive).
+        expect([w.start, w.end, w.endExclusive])
+            .toEqual(['2026-08-10T00:00:00.000Z', '2026-09-09T12:34:56.789Z', false]);
+
+        // 2026-08-10 through 2026-09-09 inclusive is 31 days; `previousPeriod` is
+        // the equal-length window ending the day before this one starts.
+        expect(await comparePasses('last_30_days', 'previousPeriod')).toEqual([
+            ['last_30_days'],
+            [['2026-07-10', '2026-08-09']],
+        ]);
+    });
+
+    it('⛔ distinct presets select DISTINCT comparison windows', async () => {
+        // The fallback's real signature: twelve of thirteen names collapsed onto
+        // one window, so a green "it did not throw" is not enough — the windows
+        // have to differ from each other.
+        const windows = new Set<string>();
+        for (const preset of ['today', 'this_week', 'this_month', 'this_quarter', 'this_year']) {
+            windows.add(JSON.stringify((await comparePasses(preset, 'previousYear'))[1]));
+        }
+        expect(windows.size).toBe(5);
+    });
+
+    it('⛔ an unrecognised string is REFUSED with the ADR-0112 envelope, not DATASET_INVALID', async () => {
+        // ⛔ On the ENVELOPE, not `toThrow()`: this face DID throw before the fix
+        // — it threw `DATASET_INVALID "invalid date in dateRange"`, its own
+        // envelope for a condition four faces already answered with one.
+        let thrown: (Error & { code?: string; status?: number }) | undefined;
+        try {
+            await comparePasses('not a range at all', 'previousPeriod');
+        } catch (e) {
+            thrown = e as Error & { code?: string; status?: number };
+        }
+        expect(thrown?.code).toBe('ANALYTICS_DATE_RANGE_UNRECOGNIZED');
+        expect(thrown?.status).toBe(400);
+    });
+
+    it('⛔ CONTROL — the CALLER\'s explicit window is still shifted bound for bound', async () => {
+        // ⭐ Without this, every assertion above is satisfied by a face that
+        // rewrote the array arm too. The answer is byte-identical to the one
+        // #17124 pinned before this change.
+        expect(await comparePasses(['2026-01-01', '2026-01-31'], 'previousPeriod')).toEqual([
+            [['2026-01-01', '2026-01-31']],
+            [['2025-12-01', '2025-12-31']],
+        ]);
+    });
+});
@@ -9,7 +9,13 @@ import type {
 } from '@objectstack/spec/contracts';
 import { emptyGroupValueFor, type FilterCondition } from '@objectstack/spec/data';
 import type { ExecutionContext } from '@objectstack/spec/kernel';
-import { bucketKeyToCalendarRange, filterTokenContextFrom, resolveFilterTokens } from '@objectstack/core';
+import {
+  bucketKeyToCalendarRange,
+  filterTokenContextFrom,
+  resolveAnalyticsDateRangeString,
+  resolveFilterTokens,
+  type LoweredDateRangeWindow,
+} from '@objectstack/core';
 import type { CompiledDataset, DerivedMeasureSpec } from './dataset-compiler.js';
 import { explicitDateRangeWindow } from './date-range-array-arm.js';
 import { datasetInvalidError } from './dataset-refusal.js';
@@ -500,6 +506,79 @@ function shiftYear(date: string, years: number): string {
   return toISODate(d.getTime());
 }
 
+/**
+ * [#17973] Lower one `dateRange` the way `compareTo` reads it — this executor's
+ * face in the shared `dateRange` conformance kit
+ * (`analyticsDateRangeConformanceFindings`), and the ONE call site
+ * {@link DatasetExecutor.runCompare} uses for either arm.
+ *
+ * ## What was wrong
+ *
+ * The STRING arm was spelled `[td.dateRange, td.dateRange]` — the degenerate
+ * `[range, range]` fallback #17015 removed from every OTHER analytics face.
+ * `parseUTC` was handed the preset NAME, so a DECLARED, honoured member of the
+ * closed vocabulary was refused. MEASURED on `b3b43b6ea`, `last_30_days` plus
+ * `compareTo`:
+ *
+ * ```
+ * DATASET_INVALID  400  [dataset-executor] invalid date in dateRange: "last_30_days"
+ * ```
+ *
+ * ⇒ the diagnostic is not merely unhelpful, it is FALSE, and it sends the
+ * author to check a date that is exactly what the schema and the docs tell them
+ * to write. This face was not in #17015's kit, so nothing measured it.
+ *
+ * ## Why it reports INSTANTS while `runCompare` shifts DAYS
+ *
+ * What is reported here is the window the VOCABULARY resolved, which is what
+ * the kit holds every face to. Projecting it onto this module's UTC calendar is
+ * a per-face calendar translation and stays downstream, in
+ * {@link inclusiveUtcDayWindow} — the same split `lowerPreviewDateRange` makes
+ * when it leaves the #3777 bare-day widening in its own predicate.
+ *
+ * ⛔ The ARRAY arm is the CALLER's explicit window and is handed back bound for
+ * bound, with the inclusive upper reading it has always had (#16179) — the
+ * refusal for anything that is not a two-bound window is
+ * `explicitDateRangeWindow`'s, unchanged (#17124).
+ *
+ * @throws the ADR-0112 `400 ANALYTICS_DATE_RANGE_UNRECOGNIZED` envelope for a
+ *   string outside `DATE_RANGE_PRESETS` — the same envelope the sibling faces
+ *   raise, replacing the `DATASET_INVALID` this arm used to answer with.
+ */
+export function lowerDatasetCompareDateRange(
+  dateRange: string | readonly unknown[],
+  timezone?: string,
+): LoweredDateRangeWindow {
+  if (!Array.isArray(dateRange)) {
+    const window = resolveAnalyticsDateRangeString(dateRange as string, { timezone });
+    return { start: window.start, end: window.end, endExclusive: window.endExclusive };
+  }
+  const [start, end] = explicitDateRangeWindow(dateRange as readonly unknown[]);
+  return { start, end, endExclusive: false };
+}
+
+/**
+ * [#17973] The UTC calendar days a lowered window covers, as the INCLUSIVE
+ * `[first, last]` pair every piece of `compareTo` math in this module takes.
+ *
+ * {@link shiftRange} measures `previousPeriod`'s length as a count of whole
+ * days between two day-starts, and {@link alignedCompareBucketKey} reads
+ * `currentRange[1]` as the LAST bucket the window contains — so both bounds
+ * must name days the window really covers.
+ *
+ * ⚠️ `endExclusive` is therefore load-bearing, not decoration: the ten calendar
+ * presets report the first instant AFTER the window (`this_month` ends at the
+ * next month's start), so the last day they cover is the one holding the
+ * instant before that bound. Reading their bound as inclusive would make every
+ * calendar preset one day too long and shift `previousPeriod` by a day. The
+ * three rolling presets end at NOW, a moment they REACH, so their bound is
+ * already the last day.
+ */
+function inclusiveUtcDayWindow(window: LoweredDateRangeWindow): [string, string] {
+  const endMs = parseUTC(window.end);
+  return [toISODate(parseUTC(window.start)), toISODate(window.endExclusive ? endMs - 1 : endMs)];
+}
+
 /**
  * Resolve which time dimension a `compareTo` shifts (#5011).
  *
@@ -1313,9 +1392,29 @@ export class DatasetExecutor {
     // bound in from the lower one, so a one-element array silently became a
     // point window HERE while the primary pass it is compared against may have
     // read the same document as all of history.
+    //
+    // [#17973] The STRING arm is the CLOSED preset vocabulary, lowered by the one
+    // shared `resolveAnalyticsDateRangeString` every other face calls and then
+    // projected onto this module's UTC calendar. ⛔ What this replaced was the
+    // degenerate `[range, range]` fallback #17015 removed everywhere else: it
+    // handed `parseUTC` the preset NAME, so `last_30_days` — declared, honoured,
+    // and exactly what the schema tells an author to write — came back as
+    // `DATASET_INVALID "invalid date in dateRange"`. A false diagnostic on a
+    // valid input has no repair to send the author to.
+    //
+    // The timezone precedence is `buildQuery`'s, verbatim, so the comparison
+    // window is resolved in the SAME calendar as the primary pass it is
+    // compared against — a preset resolved here in UTC while the primary pass
+    // read it in the org's zone would misalign the two grids by a day.
+    const lowered = lowerDatasetCompareDateRange(
+      td.dateRange as string | readonly unknown[],
+      selection.timezone ?? context?.timezone ?? 'UTC',
+    );
     const range: [string, string] = Array.isArray(td.dateRange)
-      ? explicitDateRangeWindow(td.dateRange as readonly unknown[])
-      : [td.dateRange as string, td.dateRange as string];
+      ? // The caller's own bounds, untouched — `explicitDateRangeWindow` already
+        // refused anything that is not a two-bound window (#17124).
+        [lowered.start, lowered.end]
+      : inclusiveUtcDayWindow(lowered);
     const shifted = shiftRange(range, cmp.kind);
     const shiftedTd = (selection.timeDimensions ?? []).map((t) =>
       t.dimension === dimension ? { ...t, dateRange: shifted } : t,