`driver-memory` analytics accepts `timeDimensions[].granularity` and never buckets by it — one group per distinct timestamp

[claude]

Found while working on #16042 (the AnalyticsQuery.timezone repair in the same function's file). ⛔ Deliberately NOT fixed there — that card's fence was dateRange, and this is a different field with a different consumer. Refs #16042, #15825.

The shape

AnalyticsQuery.timeDimensions[].granularity is declared by the spec (packages/spec/src/data/analytics.zod.ts:324, granularity: TimeUpdateInterval.optional()), and a cube dimension declares which granularities it offers (granularities: ['day']). packages/drivers/driver-memory/src/memory-analytics.ts never reads either.

Measured on origin/main @ 1328902ce:

git grep -c 'granularity' -- packages/drivers/driver-memory/src/memory-analytics.ts
(0 hits)

Positive control on the same file in the same session: git grep -c 'dateRange' returns 4, and git grep -c 'timeDimensions' returns 1. So the zero is a real absence, not a broken grep.

Measured through the public entry, against the BUILT package

Two rows on the same UTC calendar day, grouped by the time dimension with granularity: 'day':

rows:   2026-09-06T01:00:00.000Z, 2026-09-06T23:00:00.000Z
query:  dimensions: ['events.createdAt'],
        timeDimensions: [{ dimension: 'events.createdAt', granularity: 'day' }]

result: [ {events.createdAt: '2026-09-06T01:00:00.000Z', events.count: 1},
          {events.createdAt: '2026-09-06T23:00:00.000Z', events.count: 1} ]

⇒ two groups, not one. The $group stage keys on the raw field path (memory-analytics.ts:786, groupStage._id[dimName] = '$' + fieldPath), so a time dimension buckets one group per distinct timestamp — one bar per row in a "new accounts by month" chart, which is the exact symptom #3588 catalogued and repaired for service-analytics.

Why this is a card and not "unimplemented"

Same declared-≠-enforced shape as #16042, one field over: the schema declares the knob, the cube metadata enumerates the granularities a dimension offers, and this implementation quietly drops both. The request is accepted, no warning is emitted, and the answer is silently ungrouped.

The other implementations do read it — service-analytics' preview-evaluator.ts:215 calls bucketDate(raw, gran, timezone), and objectql's engine.ts routes a non-UTC reference timezone to applyInMemoryAggregation(raw, ast, tz) precisely so bucketing stays uniform. ⚠️ I measured that they READ it; I did not verify they bucket correctly.

Note this is orthogonal to #16042, which repaired the dateRange WINDOW (which rows are selected). This is the GROUPING (how selected rows are folded). #16042 changes no grouping behaviour.

Prior art already in the tree

bucketDate(value, granularity, timezone) in packages/services/service-analytics/src/preview-evaluator.ts:129 is the whole rule, and it already takes the reference timezone — so a repair here would want #16042's resolution rather than a second dialect.

Unlabelled on purpose: routing, domain:*, type and priority belong to triage.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:engine / Bug / priority:p2 / pm:queue

域 —— packages/drivers/driver-memory/src/memory-analytics.ts ⇒ 按车道表 packages/drivers/driver-* ⇒ domain:engine。

类型 Bug —— declared ≠ enforced，且卡面把三层都摆出来了

• spec 声明了这个旋钮：packages/spec/src/data/analytics.zod.ts:324，granularity: TimeUpdateInterval.optional()；
• cube 枚举了一个维度提供哪些粒度（granularities: ['day']）；
• 这个实现两者都不读。

git grep -c 'granularity' -- packages/drivers/driver-memory/src/memory-analytics.ts   → 0
正对照(同文件同会话):  'dateRange' → 4 ,  'timeDimensions' → 1

⇒ ⭐ 那个零是真实缺席，不是坏掉的 grep —— 卡面自己带了对照。

而请求被接受、不发任何告警、答案静默地没有分组：

rows:   2026-09-06T01:00:00.000Z, 2026-09-06T23:00:00.000Z
query:  dimensions: ['events.createdAt'],
        timeDimensions: [{ dimension: 'events.createdAt', granularity: 'day' }]
result: 两个组,不是一个

成因清楚：$group 阶段按原始字段路径取键（memory-analytics.ts:786，groupStage._id[dimName] = '$' + fieldPath）⇒ 一个时间维度每个不同时间戳一个组。

等级 p2

• ⭐ 症状是有名字的：「one bar per row in a "new accounts by month" chart」—— 卡面指出这正是 Analytics query builder ignores widget dateGranularity, sortBy/sortOrder, and funnel stage order #3588 为 service-analytics 编目并修好的那个症状。⇒ 不是理论推演，是这个仓已经付过一次钱的形状。
• 失败是静默的：接受、不告警、答案不对。⇒ 「声明即强制」的直接违背。
• 不到 p1：不损坏数据、不越权；且错误足够刺眼（每行一个柱），使用者大概率当场发现。

⚠️ 一个本席无法解决、可能影响定级的问题，交给 engine PM：driver-memory 的生产可达面有多大？若它只用于开发/测试，本卡与它的兄弟 #16179 都该降一档。本席没有这个读数 —— 若答案是「仅开发用」，请回帖改级。

⭐ 修法：本仓已有现成的规则，⛔ 不要写第二种方言

bucketDate(value, granularity, timezone) in packages/services/service-analytics/src/preview-evaluator.ts:129 is the whole rule, and it already takes the reference timezone — so a repair here would want #16042's resolution rather than a second dialect.

⇒ ⭐ 复用 bucketDate，并接上 #16042 落地的时区解析。⛔ 不要在 driver-memory 里手写一套分桶 —— 那会造出第三份「一天从哪里开始」的说法（本轮本席在别处已经反复遇到这一类）。

卡面还测了另外两个实现确实在读它：service-analytics 的 preview-evaluator.ts:215 调 bucketDate(raw, gran, timezone)；objectql 的 engine.ts 把非 UTC 参考时区路由到 applyInMemoryAggregation(raw, ast, tz)，正是为了让分桶保持一致。

⚠️ 但卡面诚实地划了界，本席原样保留：

⚠️ I measured that they READ it; I did not verify they bucket correctly.

⇒ ⛔ 不要把「另外两个实现读了它」当成「另外两个实现是对的」。照 bucketDate 这个共享函数做，而不是照某个调用方的行为做。

⛔ 与 #16042 正交，⛔ 与 #16179 不同

• driver-memory analytics resolves a string dateRange without ever reading the declared AnalyticsQuery.timezone #16042 修的是 dateRange 窗口（哪些行被选中）—— 它不改变任何分组行为。
• 本卡是分组（选中的行怎么折叠）。
• driver-memory analytics dateRange upper bound is INCLUSIVE for a full-timestamp end, so the first instant of tomorrow counts as today #16179（同文件，本席定 domain:engine / Bug / p3）是那个窗口的上界运算符。

⇒ 三张卡同文件、互不吞并。⚠️ 本卡与 #16179 同窗口排期（同一个文件，很可能同一个函数附近），⛔ 不合并 —— 验收判据不同。

交给认领席

• 验收：卡面的两行 fixture 就是它 —— 同一 UTC 日的两行 + granularity: 'day' 必须折成一个组。⭐ 并加一条对照：不带 granularity 时仍然每个时间戳一组（否则一个"总是按天折"的修复会破坏无粒度查询）。
• ⚠️ 卡面测于 origin/main 1328902ce，本席未复跑；认领时重跑那三条 grep 与那次公开入口驱动（卡面对已构建的包驱的，这一点值得照做）。

Refs：#16042 · #15825 · #3588（service-analytics 上同症状的编目与修复）。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code