fix(driver-sql): bucket a Field.date as its calendar day on PostgreSQL and MySQL

[objectstack-fleet]

Fixes #21485
Clause-②: no

What changes

SqlDriver.buildDateBucketExpr now reads the column's declared type from the object it already receives. A declared Field.date is bucketed as its own calendar day with no zone conversion. A Field.datetime, or a column with no declaration, keeps the UTC-instant expression byte for byte.

dialect	Field.date (new)	Field.datetime / undeclared (unchanged)
PostgreSQL	to_char((col)::date::timestamp, FMT)	to_char((col)::timestamptz AT TIME ZONE 'UTC', FMT)
MySQL	date_format(col, FMT)	date_format(convert_tz(col, @@session.time_zone, '+00:00'), FMT)
SQLite	unchanged (strftime on TEXT, no zone)	unchanged

Both callers render this one function, so both follow without a second edit: aggregate()'s GROUP BY (buildDateBucketExpr(g.field, g.dateGranularity, table), with table = coercionKey(builder)), and the public dateBucketSql(objectName, …) member that the analytics SQL echo reads. No service-analytics source is touched.

The mechanism, measured

PostgreSQL 16.14 with the server's TimeZone at Asia/Shanghai, at the expression:

date value	old day	old week	old month	new (all five granularities)
2026-06-01	2026-05-31	2026-W22	2026-05	2026-06-01 / 2026-W23 / 2026-06 / 2026-Q2 / 2026
2026-01-01	2025-12-31	2026-W01	2025-12	2026-01-01 / 2026-W01 / 2026-01 / 2026-Q1 / 2026
2024-12-30	2024-12-29	2024-W52	2024-12	2024-12-30 / 2025-W01 / 2024-12 / 2024-Q4 / 2024

Casting a date to timestamptz makes midnight in the session zone; AT TIME ZONE 'UTC' then reads the previous UTC day on any session east of UTC. A session west of UTC does not shift (midnight local is later the same UTC day), which is why only east-of-UTC servers show it.

Why ::date::timestamp and not the bare ::date the dispatch suggested. EXPLAIN VERBOSE shows to_char((d)::date, …) resolves to to_char((d)::timestamp with time zone, …) through the implicit cast, so the bare form still round-trips the session zone. Measured over every day 1900..2100 in ten zones, that round trip differs from the zone-free form on exactly one day each in Pacific/Apia (2011-12-30 prints 2011-12-31) and Pacific/Kiritimati (1994-12-31 prints 1995-01-01), the days those zones skipped. ::date::timestamp resolves to_char(timestamp without time zone, …) and consults no zone.

MySQL (H2), measured on MySQL 8.0.46 (the Ubuntu mysql-server-core-8.0 binary, run from a private datadir in this container) at a global +08:00. At the expression, convert_tz(d, '+08:00', '+00:00') shifts a DATE exactly like PostgreSQL: 2026-06-01 → day 2026-05-31, month 2026-05; 2024-12-30 → 2024-W52. Through the driver's default composition it does not, because the driver pins its own session to +00:00 (withUtcSession), which makes convert_tz the identity. A host pool.afterCreate that sets the session zone (the driver chains it after its own hook) brings the shift back. Per triage's ruling ("gets the same split if a DATE shifts"; "No server-timezone dependence for a date on any dialect"), the MySQL arm gets the same split.

Pins

• packages/drivers/driver-sql/src/sql-driver-21485-date-bucket-calendar-day.test.ts (new). One matrix over DIALECT_CELLS through declareDialectCell: date and datetime × every granularity the dialect buckets in SQL (declared per dialect and asserted equal to supports.queryDateGranularity, so the iterated set cannot shrink silently) × session zone. Each cell asserts both doors: aggregate() and the dateBucketSql() text run as SQL. The rows sit on month, quarter, year and ISO-week boundaries, plus the empty bucket.
  • sqlite: the zone-free control.
  • live postgres / live mysql, each twice: as provisioned (both axes, after assertThreeWayZoneSkew) and session at +08:00 through a host pool.afterCreate (the date axis, after asserting the session really is at +08:00). The second run is red-capable on any server, and it is the only red-capable route on MySQL.
• sql-driver-temporal-dialect.test.ts: a no-server pin (runs in Test Core too). On pg and mysql2, a declared Field.date expression names no timestamptz, time zone, convert_tz or time_zone; on pg it carries ::date::timestamp; the undeclared control keeps the UTC-instant arm.

Where the live pins run in CI (H4). Job Temporal Conformance (live PG + MySQL) (required), step Run driver-sql suite against both live servers. It runs the whole driver-sql package with OS_TEST_POSTGRES_URL, OS_TEST_MYSQL_URL, OS_EXPECT_LIVE_DIALECT_MATRIX=1 and TZ=America/New_York, with PostgreSQL at Asia/Shanghai and MySQL at a global +08:00. No workflow edit is needed. PR #21577 (#21564) wires the separate service-analytics step and is not part of this PR.

Reverse verification and ablation

All runs: PostgreSQL 16.14 at Asia/Shanghai, MySQL 8.0.46 at +08:00, process TZ=America/New_York, OS_EXPECT_LIVE_DIALECT_MATRIX=1; the new file plus sql-driver-temporal-dialect.test.ts.

1. Before the fix was written (the test committed alone, 26b8310fb): the new file 15 failed / 32 passed of 47. The date axis was red at all five granularities on live postgres as provisioned, live postgres at +08:00, and live mysql at +08:00. Live mysql as provisioned (the driver's UTC pin), every datetime cell and sqlite were green.
2. Fix committed (aa061685b), then sql-driver.ts reverted to the base text (git restore --source=f6b752083; on-disk anchors calendarDay 3 → 0, the old PostgreSQL month text 0 → 1): 16 failed / 45 passed of 61. That is the same 15 live cells, plus the no-server pin. Restored with git checkout HEAD -- packages/drivers/driver-sql/src/sql-driver.ts. The hash-object was be60fd469…, equal to the HEAD blob; git diff HEAD and git status --porcelain were empty.
3. Fix in place: 61 of 61 green.
4. Ablation, the ::timestamp hop (scripts/ablation-replace.mjs, anchor 1 → 0): (??)::date::timestamp replaced by the bare (??)::date. Predicted: the live pins stay green at Asia/Shanghai (the round trip is the identity there) and only the no-server pin reds. Observed: 1 failed / 60 passed, the no-server pin. Restored blob = HEAD, git diff HEAD empty.
5. The four service-analytics cells the card measured (objectql-face-order-limit.test.ts, which resolves @objectstack/driver-sql through dist/): the fix was disabled in dist/ (const calendarDay = false, rebuilt, ablation-dist-preflight marker present in 2 built files). Result: 4 failed / 22 passed of 26, exactly the card's four. After restore + rebuild + --absent preflight: the file plus objectql-echo-date-bucket.test.ts gave 42 of 42 green against live PostgreSQL at Asia/Shanghai. No assertion change is needed in objectql-face-order-limit.test.ts, so this PR does not touch it.

Dispatch hypotheses

• H1, holds. Both call sites pass the object name as the coercion key (aggregate: coercionKey(builder); dateBucketSql: objectName, which the analytics echo fills from extractObjectName(cube)). temporalFieldKind(table, field) answers 'date' from dateFields, which only type: 'date' populates. No new parameter.
• H2, measured (above). PostgreSQL: the card's mechanism, confirmed. MySQL: the DATE shifts under any east-of-UTC session; through the driver only with a host-set session zone.
• H3. Only type: 'date' feeds dateFields. SQLite stores a date as TEXT, and strftime reads it with no zone, so the SQLite arm has no instance of this class; its sqlite cells are the control. The SQLite week arm is untouched (analytics on SQLite: a week-bucketed (or non-UTC zone) dimension still echoes date_trunc, which SQLite refuses; driver-sql has no SQLite week expression #21595).
• H4, answered above.

Driver conformance ledger

pnpm check:driver-conformance, before (f6b752083) and after (c20518cfd7): 50 covered, 0 DEBT, 0 exempt, both times. The dialect axis was 8 suites (7 matrix, 1 named cell), 0 DIALECT ledger, both times. The new file imports no shared spec/data case-set, so it adds no cell. A spec-level shared case-set would have made every one of the five drivers consume it or carry DEBT. That is outside this card's file surface and against the no-new-DEBT commitment, so the matrix is driver-local.

Local verification

• pnpm --filter @objectstack/driver-sql exec vitest run --maxWorkers=2, with all three dialects live as in CI, at eab3f3bde (after merging origin/main b610eabf7): 228 files, 5521 passed, 1 skipped (the skip is pre-existing, in schema-drift.base-type-mismatch.test.ts). The run printed "all 3 dialects were exercised".
• At the final head c20518cfd7, whose last commit only removes the as any casts in the new test: pnpm --filter @objectstack/driver-sql typecheck was green (--listFiles lists all 228 test files). The new file, sql-driver-temporal-dialect.test.ts and live-dialect-matrix.isolation.test.ts gave 81 of 81 green with all three dialects live.
• Gates at c20518cfd7: node scripts/pm/dispatch-gates.mjs --commands derived 65, and all 65 were run with exit 0. --ran printed: "65 derived famil(ies) accounted for, 65 run, 0 NOT-MEASURED". One gate was red on the way: check:query-options-erasure, because the new test's as any raised the test surface 236 → 237. It was answered by typing the query and the config, not by raising the number.
• ESLint, a narrowed run: the three changed .ts files, all in the lint population (--print-config resolves a config for each), 3 files / 0 errors / 0 warnings in the --format json output at c20518cfd7. eslint.config.mjs enables no type-aware linting (no parserOptions.project), so this diff cannot move any untouched file's verdict. The full pnpm lint is CI's.

Acceptance notes

• MySQL datetime under a host-set session zone (outside this card's ruling, not changed). Measured through the driver on MySQL 8.0.46 with a host pool.afterCreate setting time_zone = '+08:00': 2026-06-01T03:00:00.000Z stores 2026-06-01 03:00:00.000 in DATETIME(3), and find() reads it back correctly, but aggregate() by day answers 2026-05-31. convert_tz(…, @@session.time_zone, '+00:00') is right for a legacy TIMESTAMP column and wrong for a DATETIME(3) that already holds the UTC wall clock. Under the driver's default composition it is the identity. No in-repo host sets the session zone, so this is noted here, not filed.
• An external (federated) object that declares type: 'date' over a remote timestamptz column would now bucket by the session-local day (::date on a timestamptz). That is an inference only, not measured, and no producer is named.
• service-analytics comments (strategies/objectql-strategy.ts, strategies/types.ts) and the objectql-echo-date-bucket.test.ts docblock quote the PostgreSQL … AT TIME ZONE 'UTC' … text. That is still the datetime expression; they are not edited, because a service-analytics source edit is outside this PR's surface.
• Raise rule: no hosted or shipped deployment was measured running PostgreSQL at a non-UTC TimeZone. The non-UTC readings here are a private server in this container.
• Merged origin/main b610eabf7 (two commits, packages/spec and docs only, disjoint from this diff) before the full-suite run.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql, touching 2 documentable anchor(s).

9 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/data-modeling/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/data-modeling/queries.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/permissions/tenant-audit-census.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/lifecycle.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/objectql/query-syntax.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/objectql/types.mdx (via SqlDriver (symbol, a top-level class))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/releases/v17/17-5.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/releases/v17/17-6.mdx (via SqlDriver (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 11 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 9a4182a752fd53b24a14bbcd2e1b4270e1174e7a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1fed374c53c3c6e38de207195f7333b5dd6669b4 — the merge of head c20518cfd7787f8ba3f82d74fc85ca4254e416e8 into base 9a4182a752fd53b24a14bbcd2e1b4270e1174e7a, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1fed374c53c3c6e38de207195f7333b5dd6669b4 && git checkout 1fed374c53c3c6e38de207195f7333b5dd6669b4
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9a4182a752fd53b24a14bbcd2e1b4270e1174e7a c20518cfd7787f8ba3f82d74fc85ca4254e416e8 && git checkout -B drift-repro 9a4182a752fd53b24a14bbcd2e1b4270e1174e7a && git merge --no-ff c20518cfd7787f8ba3f82d74fc85ca4254e416e8

node scripts/docs-audit/affected-docs.mjs --json 9a4182a752fd53b24a14bbcd2e1b4270e1174e7a

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 9a4182a752fd53b24a14bbcd2e1b4270e1174e7a → pass the list as
args.docs, on the commit named under Which tree this was computed on.