fix(analytics): apply the effective date granularity to labels and drill ranges (#3588 follow-up)

[os-zhuang]

Follow-up to #3652 (issue #3588). Found by browser-verifying that merge, not by the test suite — which passed throughout, because each site was correct in isolation.

What was wrong

selection.dateGranularity reached the GROUP BY, but two post-processing steps kept reading the dataset dimension's default: the bucket-label formatter and the drill-range inverter. So a query was grouped one way and described another.

Driving a real dashboard query against a dataset whose dimension declares dateGranularity: 'month':

selection	rows came back as	should be
year	created_at: "1970-01"	"2026"
day	ten days collapsed to two duplicated month keys	ten distinct day keys
quarter	correct label, drillRanges: [{}, {}]	quarter ranges
week / day	drillRanges: [{}, …]	week / day ranges

The 1970-01 is the tell: a year bucket's key is "2026", which the month formatter re-read as 2026 milliseconds past the epoch.

The fix

Granularity precedence now lives in one exported function, resolveDimensionGranularity, called from all three sites that must agree — the query's GROUP BY, the label formatter, and the range inverter. The drift was possible only because each resolved it independently, so the fix is the shared resolver rather than three parallel patches.

Two things this surfaced, fixed here too:

• A dataset dimension declaring no granularity, bucketed by the widget, could never drill. The range sidecar keyed off the dataset's own dateGranularity, so it skipped exactly the case Analytics query builder ignores widget dateGranularity, sortBy/sortOrder, and funnel stage order #3588 is about (hotcrm's account_metrics.created_at).
• formatDateBucket mistook a bare year key for an epoch timestamp."2026" is the only bucket key that collides with its pure-digit epoch heuristic — "2026-Q2", "2026-07", "2026-07-15" all fail it. Idempotence over already-formatted keys is that function's stated contract; the year case just never held. This one predates feat(analytics): honour widget dateGranularity, sortBy/sortOrder, and limit in dataset queries (#3588) #3652 and affects any dataset declaring dateGranularity: 'year'.

Verification

Browser-driven against the showcase app, before and after. All five granularities now label correctly and every one carries its half-open drill range:

day → 2026-06-17, 2026-07-02, … (was: two duplicated month keys)
week → 2026-W28, 2026-W29, … drill ranges now present
month → 2026-06, 2026-07 (unchanged — the one case that worked)
quarter → 2026-Q2, 2026-Q3 drill ranges now present
year → 2026 (was: 1970 / 1970-01)

Tests: 11 new in dataset-granularity-postprocess.test.ts, pinning each broken case plus the precedence table; full @objectstack/service-analytics suite 219 passed.

The test service returns the bucket key the driver would actually produce for the granularity requested, so a query/post-processing mismatch reproduces exactly as it did in the browser — a mock that echoed a fixed key would have stayed green through the original bug.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 27, 2026 1:55pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): packages/services.

6 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx(via packages/services)
• content/docs/kernel/runtime-services/audit-service.mdx(via packages/services)
• content/docs/kernel/runtime-services/index.mdx(via packages/services)
• content/docs/kernel/runtime-services/settings-service.mdx(via packages/services)
• content/docs/plugins/packages.mdx(via packages/services)
• content/docs/protocol/kernel/i18n-standard.mdx(via packages/services)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.