@@ -0,0 +1,21 @@
+---
+'@objectstack/service-analytics': patch
+---
+
+fix(service-analytics)!: the /analytics/sql dry run refuses a date bucket over a column that is not a date or datetime, as the query does, instead of rendering it
+
+Clause-②: no (narrowing) — `/analytics/sql` (`AnalyticsService.generateSql`) now refuses `INVALID_FIELD` / 400 at `groupBy.N.dateGranularity` a time-dimension granularity over a field declared neither a date nor a datetime (text, select, number, boolean, time, …), with the refusal `/analytics/query` gives the same selection, field for field; it rendered a statement for it (or, at a non-UTC zone, answered `NOT_IMPLEMENTED` / 501 saying the query is served). Nothing is widened: no export, public member, answer member, error code or status is added.
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no export or type of the package root changes: a dry run that rendered a statement the query refuses is refused with the query's refusal, already on the wire. There is nothing for a migration to rewrite and no tombstone. -->
+
+**BREAKING** accept-set narrowing on the `/analytics/sql` dry run (`@objectstack/service-analytics`). `/analytics/query` is unchanged.
+
+- **Before.** Measured on real SQLite on `main` `ab085a04`. `/analytics/query` refused a month bucket over a text, select or boolean column, a year bucket over a number and a day bucket over a `time` column with the engine's `INVALID_FIELD` / 400 at `groupBy.N.dateGranularity`. The dry run rendered `strftime('%Y-%m', region)` and its kin, on the direct and the cross-object path, and for a cube dimension's one declared granularity asked raw. At `America/New_York` it answered `NOT_IMPLEMENTED` / 501.
+- **Now.** The dry run judges the keys `execute()` hands the engine (its cross-object path's when the selection routes there) with the reading the draft preview already used (#28852), now `dataset-date-bucket-door.ts`. It runs after the dry run's `dateRange` read and its column-asked-twice refusal, as `query()` refuses, and gives the engine's refusal: the same message, `object`, `param`, `path`, `field` and `fields`. A field with no declared type, or a `formula`, is not judged, as in the engine.
+- **Unchanged.** A date or datetime bucket renders byte for byte, the statement the query echoes.
+- **Who sees it.** A caller of the dry run for a selection the query refuses: the query's refusal, instead of SQL for a statement that never runs.
+
+**The remedy.** Group by the column without a granularity, or bucket a date or datetime field.
+
+Also in this change, the draft preview of `queryDataset` lowers its row filters (the `where`, then the time-dimension windows) once, before its column-asked-twice and date-bucket refusals, where the ObjectQL strategy lowers them. So a selection carrying an unrecognised `dateRange` beside one column asked twice or beside a bucket over a non-date column is refused about the `dateRange` (`ANALYTICS_DATE_RANGE_UNRECOGNIZED` / 400) on every face, and a refused filter beside a non-date bucket is refused about the filter. The preview answered the other refusal.
@@ -531,6 +531,12 @@ const LEDGER: readonly LedgerRow[] = [
         method: 'analytics.query', receiver: 'service', count: 4, verdict: 'NOT_SDK',
         why: 'the real AnalyticsService that AnalyticsServicePlugin registers over a live engine, called directly (no HTTP, no dispatcher envelope) to compare the query\'s refusal with the dry run\'s (one column asked twice, and a bad dateRange beside it, #28852), and to read the `sql` and rows the query serves',
     },
+    // ── [#28977] the /analytics/sql dry run vs the query for a date bucket over a column that is not a date: producer reads only ──
+    {
+        file: 'packages/services/service-analytics/src/__tests__/objectql-echo-non-date-bucket.test.ts',
+        method: 'analytics.query', receiver: 'service', count: 2, verdict: 'NOT_SDK',
+        why: 'the real AnalyticsService that AnalyticsServicePlugin registers over a live engine, called directly (no HTTP, no dispatcher envelope) to compare the query\'s refusal with the dry run\'s (a date bucket over a text, select, number, boolean or time column), and to read the `sql` the query serves for a date and a datetime bucket',
+    },
     {
         file: 'packages/client/src/analytics-automation-json-erasure.test.ts',
         method: 'analytics.meta', receiver: 'sdk', count: 2, verdict: 'PAYLOAD_DEPENDENT',
@@ -771,14 +777,19 @@ describe('#13079 §2 — positive controls on the matcher itself', () => {
         // plugin-registered AnalyticsService to compare the query's refusal
         // and served `sql` with `generateSql`'s. [#28852] A fourth site there:
         // the refusal precedence beside an unrecognised `dateRange`.
-        expect(service.length, literalNote()).toBe(15);
+        // [#28977] A seventh, two sites: the dry-run parity pin for a date
+        // bucket over a column that is not a date calls the same
+        // plugin-registered AnalyticsService to compare the query's refusal
+        // and served `sql` with `generateSql`'s.
+        expect(service.length, literalNote()).toBe(17);
         expect([...new Set(service.map((s) => s.file))].sort()).toEqual([
             'packages/client/src/analytics-automation-json-erasure.test.ts',
             'packages/drivers/driver-memory/src/memory-exists-non-boolean-refusal.test.ts',
             'packages/rest/src/analytics-nested-relation-filter.test.ts',
             'packages/services/service-analytics/src/__tests__/objectql-echo-bucket-enumeration.test.ts',
             'packages/services/service-analytics/src/__tests__/objectql-echo-column-twice.test.ts',
             'packages/services/service-analytics/src/__tests__/objectql-echo-date-bucket.test.ts',
+            'packages/services/service-analytics/src/__tests__/objectql-echo-non-date-bucket.test.ts',
         ]);
         expect(service.every((s) => s.method === 'analytics.query')).toBe(true);
     });
@@ -825,14 +836,15 @@ describe('#13079 §3 — every call site is classified', () => {
         expect(production, literalNote()).toEqual([]);
     });
 
-    it('records the split: 18 payload pins, 10 result-insensitive, 15 not-SDK', () => {
+    it('records the split: 18 payload pins, 10 result-insensitive, 17 not-SDK', () => {
         expect(verdictTotal('PAYLOAD_DEPENDENT')).toBe(18);
         expect(verdictTotal('RESULT_INSENSITIVE')).toBe(10);
         // [#21441] 8 -> 9: the date-bucket echo pin's producer call (§2).
         // [#21647] 9 -> 11: the bucket echo enumeration's two producer calls (§2).
         // [#28841] 11 -> 14: the dry-run parity pin's three producer calls (§2).
         // [#28852] 14 -> 15: its dateRange-precedence call.
-        expect(verdictTotal('NOT_SDK')).toBe(15);
+        // [#28977] 15 -> 17: the non-date bucket dry-run parity pin's two producer calls (§2).
+        expect(verdictTotal('NOT_SDK')).toBe(17);
         // The three above are LEDGER sums and cannot move on a census reading;
         // this one is census-derived, so it carries the note. [#13874]
         expect(sdkSites.length, literalNote()).toBe(28);
 
@@ -0,0 +1,189 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#28977] The `/analytics/sql` dry run refuses a date bucket over a column
+ * declared neither a date nor a datetime, as `/analytics/query` does, on real
+ * SQLite (the #28841 harness: real ObjectQL + SqlDriver, the default
+ * composition).
+ *
+ * ## The shape this closes
+ *
+ * The query hands `engine.aggregate` the keys the ObjectQL strategy builds
+ * (native declines every bucketed selection to it), and the engine refuses a
+ * bucket over any other declared type: `INVALID_FIELD` / 400 at
+ * `groupBy.N.dateGranularity`. The dry run rendered the bucket without reading
+ * the column's type, so on `main` `ab085a04` it printed a statement for each:
+ *
+ * | selection | the dry run rendered |
+ * |:--|:--|
+ * | text `region` by month | `strftime('%Y-%m', \`region\`)` |
+ * | select, number, boolean, `time` | the same over that column |
+ * | `account.name` beside a text bucket (the cross-object path) | the join and the bucket |
+ * | a cube dimension over `region` declaring one granularity, asked raw | the bucket |
+ * | text `region` by month at `America/New_York` | `NOT_IMPLEMENTED` / 501 saying the query is served |
+ *
+ * It now judges the keys `execute()` hands the engine with the service's one
+ * reading of it (`dataset-date-bucket-door.ts`, #28852), after the `dateRange`
+ * read and the column-asked-twice door as `query()` refuses, so it answers the
+ * query's refusal field for field. A date and a datetime bucket still render
+ * byte for byte (pinned below).
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { ObjectQL } from '@objectstack/objectql';
+import { SqlDriver } from '@objectstack/driver-sql';
+import type { Cube } from '@objectstack/spec/data';
+import type { AnalyticsService } from '../analytics-service.js';
+import { AnalyticsServicePlugin } from '../plugin.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
+
+const DEAL = 'os28977_deal';
+const ACCOUNT = 'os28977_account';
+const CUBE = 'os28977_cube';
+
+const CUBES = [
+  {
+    name: CUBE,
+    title: 'Date bucket cube',
+    sql: DEAL,
+    public: true,
+    measures: { amount_sum: { type: 'sum', sql: 'amount', label: 'Amount' } },
+    dimensions: {
+      region: { type: 'string', sql: 'region', label: 'Region' },
+      // A time dimension over a text column, declaring one granularity: asked
+      // raw, it is bucketed by that granularity (`withDeclaredGranularityDefaults`).
+      region_month: { type: 'time', sql: 'region', label: 'Region month', granularities: ['month'] },
+    },
+  },
+] as unknown as Cube[];
+
+const quiet = { debug() {}, info() {}, warn() {}, error() {}, child() { return quiet; } };
+
+type Query = Record<string, unknown>;
+const td = (dimension: string, granularity: string, extra: Query = {}) => ({ dimension, granularity, ...extra });
+/** The inferred cube over the deal object, which serves a lookup path as a cross-object dimension. */
+const onObject = (extra: Query): Query => ({ cube: DEAL, measures: ['amount_sum'], ...extra });
+const onCube = (extra: Query): Query => ({ cube: CUBE, measures: ['amount_sum'], ...extra });
+
+/** The engine's refusal for a bucket over `field`, declared `type`, at `path`. */
+const refusalFor = (field: string, type: string, granularity: string, path: string) => ({
+  message:
+    `aggregate('${DEAL}'): ${path} buckets '${field}' by '${granularity}', but '${field}' is a `
+    + `declared ${type} field — only a date or datetime field can be date-bucketed. The query was NOT run. Group by `
+    + `'${field}' without 'dateGranularity', or bucket a date or datetime field. A value that is not a date has no `
+    + 'calendar position: every row fell into one null bucket (or, for a number, an epoch bucket) while the answer '
+    + 'looked served.',
+  code: 'INVALID_FIELD', status: 400, httpStatus: 400,
+  object: DEAL, param: 'groupBy', path, field, fields: [field],
+});
+
+describe('[#28977] the /analytics/sql dry run refuses a date bucket over a column that is not a date, as the query does', () => {
+  let engine: ObjectQL;
+  let analytics: AnalyticsService;
+
+  beforeAll(async () => {
+    const driver = new SqlDriver({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true } as never);
+    engine = new ObjectQL({ logger: quiet } as never);
+    engine.registerDriver(driver as never, true);
+    await engine.init();
+    engine.registry.registerObject({ name: ACCOUNT, label: 'Account', fields: { name: { name: 'name', type: 'text' } } } as never);
+    engine.registry.registerObject({
+      name: DEAL,
+      label: 'Deal',
+      fields: {
+        region: { name: 'region', type: 'text' },
+        stage: { name: 'stage', type: 'select', options: [{ label: 'Won', value: 'won' }, { label: 'Lost', value: 'lost' }] },
+        amount: { name: 'amount', type: 'number' },
+        flag: { name: 'flag', type: 'boolean' },
+        opened_time: { name: 'opened_time', type: 'time' },
+        closed_at: { name: 'closed_at', type: 'datetime' },
+        closed_on: { name: 'closed_on', type: 'date' },
+        account: { name: 'account', type: 'lookup', reference: ACCOUNT },
+      },
+    } as never);
+    await engine.syncSchemas();
+    await installDefaultOrganization(engine as never);
+    await engine.insert(ACCOUNT, { id: 'a1', name: 'Acme' } as never);
+    await engine.insert(DEAL, {
+      id: 'd1', region: 'amer', stage: 'won', amount: 10, flag: true, opened_time: '10:00',
+      closed_at: '2026-03-01T00:00:00.000Z', closed_on: '2026-03-02', account: 'a1',
+    } as never);
+
+    // The default composition: no `queryCapabilities` override.
+    const registered: Record<string, unknown> = {};
+    await new AnalyticsServicePlugin({ cubes: CUBES, debugSql: true } as never).init({
+      getService: (name: string) => (name === 'data' ? engine : registered[name]),
+      registerService: (name: string, svc: unknown) => { registered[name] = svc; },
+      replaceService: (name: string, svc: unknown) => { registered[name] = svc; },
+      hook: () => {},
+      logger: quiet,
+    } as never);
+    analytics = registered.analytics as AnalyticsService;
+  });
+
+  afterAll(async () => {
+    try { await engine?.destroy(); } catch { /* noop */ }
+  });
+
+  /** The refusal `p` rejects with, as the keys a caller reads; a resolution fails the case. */
+  const refusalOf = async (face: string, p: Promise<unknown>) => {
+    const err = (await p.then(
+      () => { throw new Error(`${face}: expected a refusal, but it resolved`); },
+      (e: unknown) => e,
+    )) as Error & Record<string, unknown>;
+    return {
+      message: err.message, code: err.code, status: err.status, httpStatus: err.httpStatus,
+      object: err.object, param: err.param, path: err.path, field: err.field, fields: err.fields,
+    };
+  };
+
+  /** The query's refusal and the dry run's, for one selection. */
+  const bothRefusals = async (query: Query) => ({
+    asQuery: await refusalOf('query', analytics.query({ ...query } as never)),
+    asSql: await refusalOf('sql', analytics.generateSql({ ...query } as never)),
+  });
+
+  it.each<[string, Query, [field: string, type: string, granularity: string, path: string]]>([
+    ['text', onObject({ timeDimensions: [td('region', 'month')] }), ['region', 'text', 'month', 'groupBy.0.dateGranularity']],
+    ['select', onObject({ timeDimensions: [td('stage', 'month')] }), ['stage', 'select', 'month', 'groupBy.0.dateGranularity']],
+    ['number', onObject({ timeDimensions: [td('amount', 'year')] }), ['amount', 'number', 'year', 'groupBy.0.dateGranularity']],
+    ['boolean', onObject({ timeDimensions: [td('flag', 'month')] }), ['flag', 'boolean', 'month', 'groupBy.0.dateGranularity']],
+    ['time', onObject({ timeDimensions: [td('opened_time', 'day')] }), ['opened_time', 'time', 'day', 'groupBy.0.dateGranularity']],
+  ])('refuses a bucket over a %s column with the query\'s refusal, field for field', async (_label, query, expected) => {
+    const { asQuery, asSql } = await bothRefusals(query);
+    expect(asQuery).toEqual(refusalFor(...expected));
+    expect(asSql, 'the dry run vs the query').toEqual(asQuery);
+  });
+
+  it.each<[string, Query, string]>([
+    ["beside a cross-object 'account.name' (its FK column first)", onObject({ dimensions: ['account.name'], timeDimensions: [td('region', 'month')] }), 'groupBy.1.dateGranularity'],
+    ['after a raw date column and a datetime bucket', onObject({ dimensions: ['closed_on'], timeDimensions: [td('closed_at', 'month'), td('region', 'month')] }), 'groupBy.2.dateGranularity'],
+    ["by a cube dimension's one declared granularity, asked raw", onCube({ dimensions: ['region_month'] }), 'groupBy.0.dateGranularity'],
+    ['at a non-UTC zone, where the dry run said the query is served (501)', onObject({ timeDimensions: [td('region', 'month')], timezone: 'America/New_York' }), 'groupBy.0.dateGranularity'],
+  ])('refuses a text bucket %s with the query\'s refusal, field for field', async (_label, query, path) => {
+    const { asQuery, asSql } = await bothRefusals(query);
+    expect(asQuery).toEqual(refusalFor('region', 'text', 'month', path));
+    expect(asSql, 'the dry run vs the query').toEqual(asQuery);
+  });
+
+  it.each<[string, Query, string]>([
+    ['an unrecognised dateRange on the bucket itself', onObject({ timeDimensions: [td('region', 'month', { dateRange: 'not a range' })] }), 'ANALYTICS_DATE_RANGE_UNRECOGNIZED'],
+    ['a one-entry dateRange on another entry', onObject({ timeDimensions: [td('region', 'month'), td('closed_at', 'year', { dateRange: ['2026-01-01'] })] }), 'ANALYTICS_DATE_RANGE_UNRECOGNIZED'],
+    ['the column asked twice', onObject({ timeDimensions: [td('region', 'month'), td('region', 'year')] }), 'INVALID_QUERY'],
+  ])('answers %s before a text bucket, as the query does', async (_label, query, code) => {
+    const { asQuery, asSql } = await bothRefusals(query);
+    expect(asQuery).toMatchObject({ code, status: 400 });
+    expect(asSql, 'the dry run vs the query').toEqual(asQuery);
+  });
+
+  it.each<[string, string]>([
+    ['date', 'closed_on'],
+    ['datetime', 'closed_at'],
+  ])('still renders a %s bucket byte for byte, the statement the query echoes', async (_label, column) => {
+    const query = onObject({ timeDimensions: [td(column, 'month')] });
+    const sql = `SELECT strftime('%Y-%m', \`${column}\`) AS "${column}", SUM(amount) AS "amount_sum" FROM "${DEAL}" `
+      + `GROUP BY strftime('%Y-%m', \`${column}\`)`;
+    expect(await analytics.generateSql({ ...query } as never)).toEqual({ sql, params: [] });
+    expect((await analytics.query({ ...query } as never)).sql).toBe(sql);
+  });
+});