fix(service-analytics): the echo prints a date bucket only in the driver's own expression

ObjectQLStrategy.generateSql no longer prints a representative
date_trunc for a bucket no driver expression stands for. At a UTC or
unset timezone, a dateBucketSql hook that answers nothing (driver-memory,
driver-mongodb, a granularity the driver leaves to the engine, a host
that wires no hook) now refuses with the NOT_IMPLEMENTED / 501 declared
refusal the non-UTC arm already answers, on every dialect.

Claude-Session: https://claude.ai/code/session_01DiCSbmJrkzNhuEAier4VoJ
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/services/service-analytics/src/analytics-service.ts

@@ -1145,9 +1145,9 @@ export interface AnalyticsServiceConfig {
    *
    * Answered by the plugin from the driver that executes the aggregate. Asked
    * only at a UTC or unset `timezone`: a non-UTC one is bucketed in memory, and
-   * the echo refuses it whatever is wired (#21630). At UTC, a host that wires
-   * nothing keeps the echo's representative `date_trunc(…)`, except on SQLite,
-   * where the echo refuses (#21595).
+   * the echo refuses it whatever is wired (#21630). At UTC, where this answers
+   * `undefined` or is not wired, the echo refuses the bucket too, on every
+   * dialect (#21647): it prints a bucket in no expression but the driver's.
    */
   dateBucketSql?: (object: string, field: string, granularity: string) => string | undefined;
   /**

packages/services/service-analytics/src/plugin.ts

@@ -1233,9 +1233,10 @@ export class AnalyticsServicePlugin implements Plugin {
      * single source of its bucketing and no second table lives here.
      *
      * `undefined` on every tier that cannot answer: no data engine, a driver
-     * without the member (memory, mongo), a granularity the driver buckets in
-     * memory (it answers `null`), a throw. `undefined` keeps the echo's
-     * representative `date_trunc(…)`.
+     * without the member (memory, mongo), a granularity the driver leaves to
+     * the engine's in-memory bucketing (it answers `null`), a throw. On
+     * `undefined` the echo refuses the bucket (#21647): it prints a bucket in
+     * no expression but the one answered here.
      */
     const dateBucketSql = (objectName: string, field: string, granularity: string): string | undefined => {
       try {

packages/services/service-analytics/src/strategies/objectql-strategy.ts

@@ -37,7 +37,7 @@ import { projectedDimensions } from '../order-key-door.js';
 // dataset door's post-pass (#3588) — this face orders by it, never by a copy.
 import { applyOrdering, applyWindow } from '../dataset-executor.js';
 import { type LikeShape } from '../like-pattern.js';
-import { textMatchPredicateSql, sqlDialectFor } from '../text-match-sql.js';
+import { textMatchPredicateSql, sqlDialectFor, type AnalyticsSqlDialect } from '../text-match-sql.js';
 import { resolveAnalyticsDateRangeString } from '@objectstack/core';
 import { explicitDateRangeWindow } from '../date-range-array-arm.js';
 import {
@@ -142,26 +142,41 @@ interface CrossObjectPlan {
 }
 
 /**
- * The echo of a date bucket that no statement the engine runs produces: it
- * refuses rather than print one.
+ * Why the echo of a date bucket refuses: the in-memory zone, or no driver
+ * expression for the bucket (with the dialect the host names, `'unknown'` when
+ * it names none).
+ */
+type BucketEchoRefusalCause = { zone: string } | { dialect: AnalyticsSqlDialect };
+
+/**
+ * The echo of a date bucket that no driver expression stands for: it refuses
+ * rather than print one.
  *
- * `generateSql` prints a date-bucketed dimension in the expression the driver
- * groups by (the `dateBucketSql` hook). Two cases have no such expression, and
- * both refuse here:
+ * [#21647] One rule. `generateSql` prints a date-bucketed dimension only in
+ * the expression the driver itself renders for it (the `dateBucketSql` hook),
+ * at a UTC or unset `timezone`. Everything else refuses here, and the
+ * refusal names its cause:
  *
- * - [#21630] **A non-UTC `timezone`, on every dialect.** The engine then
+ * - [#21630] **A non-UTC `timezone`, on every driver.** The engine then
  *   buckets in memory on that zone's calendar (ADR-0053 Phase 2, D2;
- *   `tzRequiresInMemory` in objectql's `engine.ts`) on every driver: the driver
- *   only fetches the rows, and no statement the database runs groups by those
- *   keys. The representative `date_trunc('<granularity>', col)` this printed
- *   instead groups on the database SESSION's calendar where it runs at all.
- *   Measured on PostgreSQL 16.14 with the server at `Asia/Shanghai`, it
- *   answered timestamp keys such as `2025-12-31T16:00:00.000Z` where the face
- *   answers `2026-01`, and at `America/New_York` it grouped 20 and 8 where the
- *   face groups 27 and 1. SQLite and MySQL have no `date_trunc` at all.
- * - [#21595] **SQLite, where no driver expression answers**: a host whose hook
- *   answers nothing for a SQLite datasource. `date_trunc` is not a SQLite
- *   function, so the representative text is a statement SQLite refuses.
+ *   `tzRequiresInMemory` in objectql's `engine.ts`): the driver only fetches
+ *   the rows, and no statement the database runs groups by those keys. The
+ *   `date_trunc('<granularity>', col)` this used to print groups on the
+ *   database SESSION's calendar where it runs at all. Measured on PostgreSQL
+ *   16.14 with the server at `Asia/Shanghai`, it answered timestamp keys such
+ *   as `2025-12-31T16:00:00.000Z` where the face answers `2026-01`, and at
+ *   `America/New_York` it grouped 20 and 8 where the face groups 27 and 1.
+ * - [#21647] **No driver expression for the bucket, on every driver.** The
+ *   hook answers nothing: a driver that runs no SQL (`driver-memory`, whose
+ *   bucket the engine computes in memory; `driver-mongodb`, which buckets in
+ *   its own aggregation pipeline), a SQL driver with no expression for the
+ *   granularity (the engine buckets it in memory), or a host that wires no
+ *   hook. The echo used to print `date_trunc` there and call it
+ *   representative. Measured on `driver-memory` at UTC, the face answered
+ *   `2026-01` and `2026-W02` from rows the driver only fetched, while both
+ *   faces printed `date_trunc('month', closed_at)`, a statement nothing ran.
+ *   [#21595] SQLite, which has no `date_trunc` at all, was the first case of
+ *   this arm.
  *
  * `NOT_IMPLEMENTED` / 501, for the reason `driver-sql`'s own bucket refusal
  * gives: the query is spelled correctly and served, and the gap is the
@@ -174,21 +189,27 @@ interface CrossObjectPlan {
  * `sql`, and the dry run (`/analytics/sql`) refuses. Both are within the
  * declared response contracts: `sql` is optional on the query answer, and the
  * dry run answers in the error envelope.
- *
- * `zone` is the non-UTC `timezone` of the first case; `undefined` is the
- * SQLite case.
  */
-function bucketEchoRefused(dimension: string, granularity: string, zone: string | undefined): Error {
+function bucketEchoRefused(dimension: string, granularity: string, cause: BucketEchoRefusalCause): Error {
   const err = new Error(
     `[analytics] cannot render display SQL for the "${granularity}" bucket of "${dimension}"` +
-      (zone !== undefined
-        ? ` with timezone "${zone}". The query itself is SERVED: the engine buckets it in memory on that zone's ` +
-          `calendar, so no statement the database runs groups by those bucket keys. Refusing rather than printing ` +
-          `one that groups on another calendar. Run the query itself (/analytics/query) to get its rows; with ` +
-          `timezone "UTC" or none, a SQL driver groups the bucket itself and this dry run renders its expression.`
-        : ` on SQLite. The query itself is SERVED, but the driver behind this datasource renders no bucket ` +
-          `expression for it. Refusing rather than printing date_trunc(...), which is not a SQLite function. ` +
-          `Run the query itself (/analytics/query) to get its rows.`),
+      ('zone' in cause
+        ? ` with timezone "${cause.zone}". The query itself is SERVED: the engine buckets it in memory on that ` +
+          `zone's calendar, so no statement the database runs groups by those bucket keys. Refusing rather than ` +
+          `printing one that groups on another calendar. Run the query itself (/analytics/query) to get its rows; ` +
+          `with timezone "UTC" or none, this dry run renders the expression the driver groups the bucket by, ` +
+          `where the driver has one.`
+        : (cause.dialect === 'unknown'
+            ? `: the driver behind this datasource names no SQL dialect and renders no expression for it. A ` +
+              `driver that runs no SQL, such as the in-memory or MongoDB driver, buckets it without one: the ` +
+              `engine in memory, MongoDB in its own aggregation pipeline. A host that wires no dateBucketSql hook ` +
+              `cannot ask its driver at all.`
+            : `: no SQL expression for it is known on this "${cause.dialect}" datasource. Either its driver ` +
+              `renders none for this granularity, and the engine buckets it in memory, or this host wires no ` +
+              `dateBucketSql hook to ask the driver.`) +
+          ` The query itself is SERVED. Refusing rather than printing a bucket expression nothing here ran: ` +
+          `this dry run prints only the expression the driver itself groups the bucket by. Run the query itself ` +
+          `(/analytics/query) to get its rows.`),
   ) as Error & { code?: string; status?: number; refusal?: true };
   err.code = StandardErrorCode.enum.NOT_IMPLEMENTED;
   err.status = 501;
@@ -411,7 +432,7 @@ export class ObjectQLStrategy implements AnalyticsStrategy {
     });
 
     const fields = this.buildFieldMeta(query, cube);
-    // Echo a representative SQL alongside the rows (#3588). `NativeSQLStrategy`
+    // Echo the SQL the query stands for alongside the rows (#3588). `NativeSQLStrategy`
     // returns the statement it actually ran, and dataset responses surface that
     // string — it is how an author checks what their widget compiled to. This
     // path builds an AST, so it had nothing to echo, and the `sql` field simply
@@ -476,15 +497,14 @@ export class ObjectQLStrategy implements AnalyticsStrategy {
    *
    * [#21441] A date bucket renders the expression the driver itself groups by
    * for its dialect, through the `dateBucketSql` hook, so the echo runs there
-   * and answers the face's bucket keys. [#21630] A non-UTC `timezone`, which
-   * the engine buckets in memory on that zone's calendar, refuses on every
-   * dialect ({@link bucketEchoRefused}): no statement the engine runs groups
-   * by those keys. At a UTC or unset `timezone`, the bucket stays
-   * REPRESENTATIVE where the hook answers nothing (no hook, or a driver with no
-   * bucket expression, such as a non-SQL driver) and prints
-   * `date_trunc('<granularity>', col)`. [#21595] Except on SQLite, which has no
-   * `date_trunc`: there the echo refuses too, so it never prints a statement
-   * SQLite refuses.
+   * and answers the face's bucket keys. [#21647] That expression is the only
+   * thing a bucket is ever printed as. Where there is none, the echo refuses
+   * ({@link bucketEchoRefused}), on every driver and every dialect: a non-UTC
+   * `timezone`, which the engine buckets in memory on that zone's calendar
+   * (#21630), and a hook that answers nothing at UTC, which is a driver that
+   * runs no SQL, a granularity the driver leaves to the engine, or a host that
+   * wires no hook (#21595 was SQLite's case of it). No bucket expression is
+   * written here.
    *
    * Filter VALUES are rendered as `$n` placeholders and returned in `params`,
    * never inlined: the echoed statement travels to the browser, and a filter
@@ -601,9 +621,24 @@ export class ObjectQLStrategy implements AnalyticsStrategy {
     // `tzRequiresInMemory` in objectql's `engine.ts`, the same test on the same
     // `timezone`), so no statement the database runs groups by those keys, and
     // the echo refuses on every dialect before the hook is asked
-    // ({@link bucketEchoRefused}). Where nothing answers at UTC, the bucket
-    // keeps the representative `date_trunc`, except on SQLite, which has no
-    // `date_trunc`: there the echo refuses too (#21595).
+    // ({@link bucketEchoRefused}).
+    //
+    // [#21647] Where the hook answers nothing at UTC, the echo refuses too, on
+    // every dialect. That is the engine's other in-memory condition, read off
+    // the driver rather than restated here: every `driver-sql` dialect answers
+    // `null` exactly where its `supports.queryDateGranularity` is false (both
+    // read `dateGranularityCapabilities`), which is where the engine buckets in
+    // memory. A driver that runs no SQL has no hook to answer: `driver-memory`
+    // advertises no granularity, so the engine buckets in memory, and
+    // `driver-mongodb` buckets in its own pipeline, which no SQL stands for
+    // either. The engine's predicate itself is not reachable from here.
+    //
+    // Two cells print the driver's expression while the engine buckets in
+    // memory, because the hook answers there and the expression, run on that
+    // dialect, answers the face's keys: a measure carrying its own `filter`
+    // (the engine aggregates every such query in memory, #10576), and
+    // `driver-turso`'s remote face (it advertises no granularity, and inherits
+    // the SQLite expression, which libSQL runs).
     const zone = query.timezone;
     const inMemoryZone = zone && zone !== 'UTC' ? zone : undefined;
     const driverBucketSql = (col: string, granularity: string): string | undefined => {
@@ -621,11 +656,10 @@ export class ObjectQLStrategy implements AnalyticsStrategy {
       const col = this.resolveFieldName(cube, dim, 'dimension');
       const gran = granByDim.get(dim);
       if (!gran) return col;
-      if (inMemoryZone !== undefined) throw bucketEchoRefused(dim, gran, inMemoryZone);
+      if (inMemoryZone !== undefined) throw bucketEchoRefused(dim, gran, { zone: inMemoryZone });
       const bucket = driverBucketSql(col, gran);
-      if (bucket !== undefined) return bucket;
-      if (sqlDialectFor(ctx, tableName) === 'sqlite') throw bucketEchoRefused(dim, gran, undefined);
-      return `date_trunc('${gran}', ${col})`;
+      if (bucket === undefined) throw bucketEchoRefused(dim, gran, { dialect: sqlDialectFor(ctx, tableName) });
+      return bucket;
     };
 
     if (query.dimensions) {