Analytics drivers (memory, SQL) align `dateRange` string handling to the closed preset vocabulary (driver half of #16041)

[os-zhuang]

Driver half of #16041, split by director ruling (decision batch #57, 2026-09-06, option A — contract first).

Blocked-by: #16041 (spec half — AnalyticsQuerySchema.dateRange string arm closes to the date-range-presets.ts vocabulary plus today; unrecognised strings are refused with the ADR-0112 envelope; the spec example is corrected). This card unblocks when the spec change lands.

Scope

Once the contract is closed:

• driver-memory analytics: an unparseable / unrecognised dateRange string is refused with the ADR-0112 envelope emitted by the schema, never silently accepted as "matches everything".
• SQL drivers (postgres, sqlite, mysql — whichever implement the analytics path): same refusal, same envelope; the preset vocabulary lowers to the same window boundaries the memory driver uses, so results agree across drivers.
• Conformance: one shared test fixture that runs the preset list plus a handful of unrecognised strings through every analytics driver and asserts identical accept/refuse outcomes and identical window boundaries for the accepted presets.

Out of scope

• Changing the vocabulary itself — that is 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 (spec).
• Any new preset. If a driver needs one, it is a spec card, not a driver patch (「本项目以协议为基准。所以开发应该对其协议，协议有问题应该立卡修改协议」).

Acceptance

• memory driver refuses unrecognised dateRange strings with the ADR-0112 envelope
• SQL drivers refuse identically
• shared conformance fixture passes on every analytics-capable driver
• changeset present

[huangyiirene]

A door the closed vocabulary does not reach — for this card's conformance fixture

Found by the dev on the spec half (#16041, PR #16618) while measuring the consumer sweep. Not fixed there — it falls inside this card's completion range and the dataset executor was fenced off from that seat. Recording rather than filing a third card.

REST /analytics/dataset/query types selection.timeDimensions from AnalyticsQuery, but does not Zod-parse it at that door. So once #16041 lands, a dateRange string outside the closed vocabulary is still accepted at that route and reaches dataset-executor unrefused — the type narrows, the runtime door does not.

That matters because it is the same failure shape the batch #57 ruling exists to close, one route over: the whole point of contract-first was that "drivers then align to the closed contract rather than each guessing", and a door that never parses cannot align. The two doors #16041 does cover (/analytics/query, /analytics/sql, via packages/runtime/src/domains/analytics.ts) lift the schema's refusal into 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED; the dataset route has no such lift because it has no parse.

⇒ Suggested for this card, in preference order:

1. Cover it in the shared conformance fixture this card already owes — a dateRange outside the vocabulary must be refused identically at /analytics/dataset/query as at the other two. That is the cheapest place to catch it and it is already in scope: the ruling gives this card "memory and SQL drivers refuse identically and share one conformance fixture".
2. If it turns out the fix is a schema door at that route rather than driver alignment, that is arguably its own card — say so rather than widening this one, and I would rather see it split than smuggled in.

⚠️ Do not assume the direction of the current failure. The two backends fail oppositely on an uninterpretable value — measured on #16041: driver-memory matches every Date-typed row (a Date compares above a String under BSON cross-type ordering, so both garbage bounds are satisfied), while driver-sql historically read 0 rows. Same bad input, opposite wrong answers, neither an error. Which one the dataset path exhibits is unmeasured; measure it before writing the fixture's expectation.

Two other things from the spec half worth carrying

• The refusal code is ANALYTICS_DATE_RANGE_UNRECOGNIZED, registered under @objectstack/runtime because the runtime door is the emitter. Spec also exports the structural predicate isAnalyticsDateRangeRefusalIssue, so you can recognise the schema's refusal without re-parsing its message. The door lifts to 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED when every issue is that refusal, else the generic 400 VALIDATION_FAILED + fields[] — worth matching rather than inventing a second convention.
• The vocabulary is snake_case and case-sensitive, derived directly from DATE_RANGE_PRESETS (z.enum(DATE_RANGE_PRESETS)) so it cannot drift from that module — isDateRangePresetName('Last 7 Days') is pinned false. ⛔ Do not hand-copy the list into the drivers; derive it the same way, or that module's own history (it previously existed in three drifting copies) repeats.

⛔ This card stays pm:blocked until #16618 merges; nothing here is actionable before then.

---

Generated by Claude Code

[huangyiirene]

This card now owes a concrete reinstatement — and it is more urgent than "driver cleanup"

PR #16618 (the spec half, #16041) retires 15 driver-memory pins as a consequence of the narrowing, under the maintainer's option-B decision of 2026-09-07. This card owes them back, and the requirement below is specific so nobody has to re-derive it.

⚠️ First, the thing that changes this card's priority

Measured by driving the built driver-memory dist directly with each of the 13 preset names over 5 probe rows (2020, 2026-08-31, 2026-09-05, now, 2099):

input	parseDateRangeString result	rows matched
today	a real window	1/5
yesterday, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_7_days, last_30_days, last_90_days	[name, name] — the fallback	5/5, including 2020 and 2099
last 7 days / last 3 days (the retired dialect)	real windows	3/5, 2/5

⇒ Once #16041 lands, a valid preset like last_30_days is accepted by the schema and then silently widens in driver-memory — every row, 2099 included. That is the same defect class #16041 exists to abolish, relocated onto the newly-blessed vocabulary, and it stays open until this card aligns the parser.

It is not p1 — triage established the parser is driver-memory-local (absent from driver-sql and service-analytics), so it is off the production SQL path. But "the documented vocabulary silently returns all of history" is a worse resting state than the one #16041 found, and this card is the only thing that closes it.

The three reinstatements, concretely

(A) The 13 DST cells — memory-analytics-date-range-dst.test.ts. Re-author as preset cells once the parser understands them. ⚠️ Not a mechanical re-spelling — the semantics differ and the transition instants must be re-measured:

• last_7_days / last_30_days / last_90_days are rolling day-leg windows ⇒ direct replacements for the day cells (last 3 days, last 7 days).
• last_week / last_month / last_quarter / last_year are calendar windows (the previous week / month / quarter / year), not n units back ⇒ the week, month and year cells need re-measured transition instants under those semantics.

Each retired cell asserted that the in-zone row set equals the TZ=UTC row set and is non-trivial (selected strictly between 0 and the probe count), after a control proving the local-arithmetic spelling disagrees at that instant. Zones covered, to reinstate: spring-forward — America/New_York, America/Los_Angeles, America/St_Johns (−03:30), Europe/London, Europe/Berlin (week + year); fall-back — Australia/Sydney, Pacific/Auckland, Pacific/Chatham (+12:45), America/Santiago, plus America/New_York and Europe/London on the month leg.

(B) The timezone case — "last 7 days starts 7 days before the ZONE's day, at the zone's midnight". Reinstate as last_7_days with the same probes. What it pinned: the window opening at 2026-08-30T16:00:00.000Z for Asia/Shanghai versus UTC's 2026-08-30T00:00:00.000Z, with the no-timezone control taking the extra 16 hours of rows.

(C) The fallback fence — "the unrecognised-range fallback carries no calendar". ⛔ Do not reinstate as written: its input is now refused at the schema. Replace it with a driver-side refusal pin asserting the ADR-0112 code and status, shared by memory and SQL — which is the conformance fixture this card already owes.

Still open on this card, from the spec half

/analytics/dataset/query types selection.timeDimensions from AnalyticsQuery but never Zod-parses at that door, so an out-of-vocabulary value still reaches dataset-executor unrefused (routed earlier, comment 5570949379).

Contract facts to build against

Refusal code ANALYTICS_DATE_RANGE_UNRECOGNIZED, registered under @objectstack/runtime; spec exports the structural predicate isAnalyticsDateRangeRefusalIssue; the runtime door lifts to 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED when every issue is that refusal, else generic 400 VALIDATION_FAILED + fields[]. The vocabulary is z.enum(DATE_RANGE_PRESETS) — derived from that module, snake_case, case-sensitive. ⛔ Do not hand-copy the list into the drivers; derive it, or that module's three-drifting-copies history repeats.

⛔ Still pm:blocked until #16618 merges.

---

Generated by Claude Code

[huangyiirene]

Unblocked — the spec half merged

PR #16618 merged 2026-09-07 15:56Z; card #16041 is closed. This card's blocker is gone.

⚠️ It still carries pm:blocked. That label is the engine lane's to move, not this seat's — flagging it rather than reaching across, because a card sitting blocked after its blocker cleared is exactly how #16495 lost two days this week (its own body records the lane reading it as "blocked on the spec lane" while the spec lane had nothing to be blocked on).

What this card now owns, and why it is more urgent than it looks

The concrete reinstatement requirement is in comment 5572379368 — read it before planning. The headline, measured on the built driver-memory dist: once #16618 landed, a valid preset such as last_30_days is accepted by the schema and then falls to parseDateRangeString's [name, name] fallback, matching every row including 2099. Only today yields a real window. So the silent-widening defect #16041 abolished at the contract is, until this card lands, relocated onto the newly-blessed vocabulary. Off the production SQL path — the parser is driver-memory-local — which is why it is p2, not p1.

Plus 15 pins to reinstate

#16618 retired 15 driver-memory date-range pins whose input the contract no longer admits (maintainer ruling batch #57 + the option-B decision of 2026-09-07). Each is it.todo(...) with its original title, so pnpm --filter @objectstack/driver-memory test lists all 15 by name — that list is the worklist.

⚠️ The trap, restated because it is the easy thing to get wrong: last_7_days / last_30_days / last_90_days are rolling day-leg windows and replace the day cells directly, but last_week / last_month / last_quarter / last_year are calendar windows — the previous week/month/quarter/year, not n units back. ⇒ the week, month and year DST cells need re-measured transition instants, not a mechanical re-spelling.

Also owed here: the utc-window fallback fence becomes a driver-side refusal pin on ANALYTICS_DATE_RANGE_UNRECOGNIZED (code + status, ADR-0112) shared by memory and SQL, and /analytics/dataset/query still never Zod-parses timeDimensions at its door (5570949379).

---

Generated by Claude Code