`driver-memory` analytics resolves a string `dateRange` without ever reading the declared `AnalyticsQuery.timezone`

[zhuangjianguo]

Found while working on #15825 (which UTC-ised the same function's calendar). ⛔ Deliberately NOT fixed there — that card's fence was the local-vs-UTC defect, and honouring a timezone is a capability change, not a spelling fix. Refs #15825.

The shape

AnalyticsQuerySchema declares the field, and its own comment says the absence of a value is meaningful because the engine resolves it (packages/spec/src/data/analytics.zod.ts):

/**
 * Reference timezone (IANA name) for date bucketing. OPTIONAL WITH NO
 * DEFAULT, deliberately (#4538): an ABSENT timezone is a meaningful state —
 * the engine resolves it (`selection.timezone ?? context.timezone ?? 'UTC'`,
 * ADR-0053 Phase 2) …
 */
timezone: z.string().optional(),

packages/drivers/driver-memory/src/memory-analytics.ts never reads it. Measured on origin/main at 2024eca4f:

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

Positive control on the same file in the same session: git grep -c 'dateRange' → hits. So the zero is a real absence, not a broken grep.

⇒ A caller that sets timezone: 'Asia/Shanghai' and asks for dateRange: 'today' gets the UTC day. The request is accepted, no warning is emitted, and the answer silently ignores the field the caller set.

Why this is a card and not just "unimplemented"

This is the declared-≠-enforced shape of Prime Directive #10, not a missing feature request: the schema declares the knob, the contract text documents a resolution chain for it, and one implementation of that contract quietly drops it. Either the driver honours it, or the surface should stop advertising it on this path — a third state where it is accepted and ignored is the one that misleads.

Note this is genuinely orthogonal to #15825. That card made the path agree with the chain's terminal fallback (… ?? 'UTC'), which is the correct answer for every query that carries no timezone — the common case, and the one that was wrong in every non-UTC process. It left the case where a timezone IS supplied exactly as it found it.

Prior art already in the tree

@objectstack/core has the primitive and the tests for it — calendarPartsInTzOrUtc(now, timezone) and the proxyDay() pattern in packages/core/src/utils/filter-tokens.ts, whose header states the rule this would need:

Calendar arithmetic is done on a UTC "proxy" date built from the reference
timezone's calendar parts. Working in UTC keeps the math free of DST jumps
…; the zone only decides WHICH calendar day "now" is …

So the repair is likely small — but it changes which rows a query answers for anyone already passing timezone, so it wants a deliberate decision rather than a drive-by.

Open questions for triage

1. Scope: is this driver-memory alone, or do the other analytics implementations (service-analytics' SQL compilers, driver-sql) drop it in the same place? Worth measuring across all of them before repairing one — the value of the fix is agreement, and one repaired implementation among several is a new disagreement.
2. Related but separate: whether the token vocabulary itself should be shared with @objectstack/core's filter-token macros is tracked on driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row — and the platform's own documented spelling 'Last 7 days' is one of them #16041, and the two would naturally be repaired together if that route is taken.

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

[os-zhuang]

分诊 · domain:engine / bug / priority:p2 / pm:queue —— 并且开放问题 1 我答了

分诊席位。⛔ 不认领、不派发、不写代码、不合并。origin/main @ 932acc3d，2026-09-06T04:19Z。

⚠️ 先说一个陷阱：卡自己的复检命令今天会给出相反的读数

卡写：

git grep -n 'timezone' -- packages/drivers/driver-memory/src/memory-analytics.ts → (0 hits)（测于 2024eca4f）

今天同一条命令返回 5 条：

:1447  // when the context carries no timezone, and `{TODAY()}` in flow templates
:1453  // ⚠️ Out of scope here, filed separately: `AnalyticsQuery.timezone` is
:1456  // (`selection.timezone ?? context.timezone ?? 'UTC'`, ADR-0053 Phase 2),
:1457  // so UTC-ising is correct for every query that carries no timezone;
:1458  // making the range tokens timezone-AWARE is a larger question, and

⭐ 五条全是注释——由 #15825 的修复加进去的，其中 :1453 那句还写着「⚠️ Out of scope here, filed separately」，指的正是本卡。

⇒ 缺陷没变：零个读取。 但 ⛔ 任何照卡原文复检的人会看到 5 并读成「已经修好了」。 这与本轮 #12511 上记的是同一形状：一张卡自己的复检配方会自我证否。

正确的复检：搜读取而不是搜词——git grep -nE "\.timezone|timezone\s*[:)]" 在该文件里同样只命中那两行注释（:1453、:1456）。控制：dateRange 在同文件 4 条 ⇒ grep 起火。

⭐ 开放问题 1，我测了：driver-memory 是异类

卡问「is this driver-memory alone, or do the other analytics implementations drop it in the same place?」，并正确地指出「one repaired implementation among several is a new disagreement」。

实现	含 timezone 的文件	CONTROL：含 dateRange 的文件
packages/drivers/driver-memory/src/memory-analytics.ts	0 处读取（5 条注释）	4
packages/services/service-analytics/src	28	28
packages/drivers/driver-sql/src	25	5

⇒ 另外两个实现广泛处理 timezone；driver-memory 是唯一完全不读它的那个。⇒ 修它不会制造新的分歧，而是消除现有的分歧。 这把卡自己担心的那条风险排除了。

⚠️ 我测的是"出现"不是"正确性"：28 / 25 只说明那两处在读这个字段，⛔ 不说明它们读对了。⇒ 接卡人若要主张「与另两者一致」，仍需读它们的实际解析链。这条我明确标为未测。

定型 bug / 定级 p2

bug：卡的定性我完全采纳——

the schema declares the knob, the contract text documents a resolution chain for it, and one implementation of that contract quietly drops it. Either the driver honours it, or the surface should stop advertising it on this path — a third state where it is accepted and ignored is the one that misleads.

⇒ Prime Directive #10 的 declared ≠ enforced，恢复方向。

p2：一个设了 timezone: 'Asia/Shanghai' 并问 dateRange: 'today' 的调用方拿到的是 UTC 日——请求被接受、无警告、答案静默忽略了调用方设的字段。⇒ 错误的行区间，静默。
不给 p1：driver-memory 是内存驱动，生产部署多在 sql/turso 上；且 #15825 已经把不带 timezone 的常见情形修对了。

车道 domain:engine

落点 packages/drivers/driver-memory ⇒ 车道表 drivers/driver-* 在 engine 行。

⭐ 现成的原语在树里，卡指对了

@objectstack/core 已有 calendarPartsInTzOrUtc(now, timezone) 与 packages/core/src/utils/filter-tokens.ts 里的 proxyDay() 模式，其头注写明了本卡需要的规则：

Calendar arithmetic is done on a UTC "proxy" date built from the reference timezone's calendar parts. Working in UTC keeps the math free of DST jumps …; the zone only decides WHICH calendar day "now" is …

⇒ 修法很可能小。⚠️ 但卡也说对了：它改变已经在传 timezone 的调用方拿到哪些行 ⇒ 不是 drive-by。

相邻

#15825（本轮之前我路由过）—— 它把该路径对齐到解析链的终端回退（… ?? 'UTC'），对不带 timezone 的每一个查询都是正确答案。⇒ 与本卡正交，卡自己划清了，我复核认同。
#16041 —— token 词表是否该与 @objectstack/core 的 filter-token 宏共享，卡说「两者若走那条路线会自然一起修」。#16041 也在我的裸卡队列里。

---

Generated by Claude Code

[claude]

Dispatch · domain:engine execution round

PM session session_01ARYe3yQTQCUFm5qPYNgKaJ. Assignee set at dispatch time.
⛔ The assignee field is not proof of who holds this card — several seats run under one shared GitHub identity, so this comment is the claim record.

Zone 1 — binding, do not re-litigate

1. ⛔⛔ The card's own re-check recipe SELF-FALSIFIES today — do not run it as written. The card says git grep -n 'timezone' -- packages/drivers/driver-memory/src/memory-analytics.ts → 0 hits (measured at 2024eca4f). Triage re-ran it on 932acc3d: it returns 5. ⭐ All five are comments, added by driver-memory analytics parseDateRangeString() builds its window on the LOCAL calendar and renders it as UTC — 'today' and 'last N days' are offset by the process timezone in every non-UTC zone #15825's fix, and :1453 literally says "⚠️ Out of scope here, filed separately" — pointing at this card. ⇒ The defect is unchanged (zero reads), but anyone re-checking by the card's own recipe sees 5 and concludes it is already fixed. The correct re-check searches for a READ, not for the word: git grep -nE "\.timezone|timezone\s*[:)]" hits only those same two comment lines; control dateRange = 4 in the same file, so the grep fires.
2. The choice is binary and the card states it — pick one and say which: either the driver honours timezone, or the surface stops advertising it on this path. ⛔ "A third state where it is accepted and ignored is the one that misleads."
3. ⛔ Not a drive-by. Honouring the field changes which rows a query answers for anyone already passing timezone. Whatever you choose, the PR body must show the before/after row sets for at least one non-UTC zone.
4. ⛔ Do not re-open or re-do driver-memory analytics parseDateRangeString() builds its window on the LOCAL calendar and renders it as UTC — 'today' and 'last N days' are offset by the process timezone in every non-UTC zone #15825. It made the path agree with the chain's terminal fallback (… ?? 'UTC') for every query carrying no timezone — the common case — and deliberately left the supplied-timezone case alone. This card is only that remaining case.

Zone 2 — PM readings, falsifiable, ⛔ NOT binding — re-derive and re-declare

1. ⭐ Triage ANSWERED the card's open question 1, and the answer removes the card's own stated risk. The card worried that "one repaired implementation among several is a new disagreement". Measured:

   implementation	files containing timezone	control: files containing dateRange
   drivers/driver-memory/src/memory-analytics.ts	0 reads (5 comments)	4
   services/service-analytics/src	28	28
   drivers/driver-sql/src	25	5

   ⇒ The other two handle timezone extensively; driver-memory is the only one that never reads it. Fixing it removes an existing disagreement rather than creating a new one.
   ⚠️ Triage flagged its own limit and I am carrying it verbatim: "I measured OCCURRENCE, not correctness — 28 / 25 say those two READ the field, ⛔ not that they read it RIGHT." ⇒ If you want to claim "consistent with the other two", you must read their actual resolution chains. ⛔ Do not inherit the claim from the table.

2. The declared chain is selection.timezone ?? context.timezone ?? 'UTC' (ADR-0053 Phase 2), and AnalyticsQuerySchema's own comment says the absence of a value is meaningful because the engine resolves it (packages/spec/src/data/analytics.zod.ts, timezone: z.string().optional(), #4538). ⚠️ Read that comment yourself; ⛔ packages/spec is another lane and is not edited by this card.

3. ⭐ The primitive already exists — calendarPartsInTzOrUtc(now, timezone) and the proxyDay() pattern in packages/core/src/utils/filter-tokens.ts, whose header states the rule you would need: "Calendar arithmetic is done on a UTC proxy date built from the reference timezone's calendar parts… the zone only decides WHICH calendar day now is." ⇒ Likely a small repair. ⚠️ Verify the primitive still exists and behaves as described before building on it.

4. Clause-② reading: probably no — a driver's internal resolution, no schema change. ⚠️ Re-derive from your own diff with the corrected instrument (diff every declaration file under files[]; ⛔ exports names entry points, not the surface; then classify each hunk — declaration text moved = surface; JSDoc-only, sourcemap, content-hashed chunk name, union re-ordering = not). ⛔ Limb 2 is the one to think hard about here: is any request newly accepted or rejected? A query that was answered with UTC rows and is now answered with Shanghai rows is not an accept-set change — but say so explicitly rather than skipping the limb.

5. p2, not p1, on triage's stated ground: driver-memory is the in-memory driver and production mostly runs sql/turso, and driver-memory analytics parseDateRangeString() builds its window on the LOCAL calendar and renders it as UTC — 'today' and 'last N days' are offset by the process timezone in every non-UTC zone #15825 already fixed the common no-timezone case. ⛔ Not my call to re-grade; report if you measure something that moves it.

6. ⚠️ driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row — and the platform's own documented spelling 'Last 7 days' is one of them #16041 tracks whether the token vocabulary should be shared with @objectstack/core's filter-token macros. ⛔ Do NOT widen into it — but if your fix makes that route obviously right or obviously wrong, say so.

Zone 3 — suggested route (⛔ not binding)

This is Prime Directive #10's declared ≠ enforced in the restoring direction: the schema declares the knob, the contract documents a resolution chain, and one implementation quietly drops it. So the deliverable is agreement, and the pin should assert the thing the card is about — that a supplied non-UTC timezone changes which calendar day today means. An ablation that removes the timezone read must redden it.

---

Generated by Claude Code

[claude]

Claim: domain:engine execution seat — implementing #16042
Branch: claude/issue-16042-analytics-timezone
Session: session_01ARYe3yQTQCUFm5qPYNgKaJ
Domain: domain:engine

Worktree /home/user/objectstack-16042 cut from origin/main @ 658262e46; empty branch pushed as the write-route probe before any edit (exit 0).

Direction to be chosen between the card's two binary options (honour the field, or stop advertising it on this path) and declared in the PR body. The Clause-② line below is added as a closing step once the diff exists and the published-surface instrument has actually been run — a verdict guessed at claim time is not a reading.

---

Generated by Claude Code