fix(analytics): pin the matrix reports' date-bucket intent and drop the empty column (#523)

[yinlianghui]

Description

The v9 single-form migration dropped groupingsAcross[].dateGranularity and never carried it to the dataset dimensions, so every matrix report's date axis groups by the raw timestamp — one column per distinct value instead of one per month / quarter / day.

Re-declaring dateGranularity today does not fix that — it empties the report. The blockage was measured against the pinned packages, not assumed. On @objectstack 16.1:

1. Read scope. A granular dimension is refused by NativeSQLStrategy (canHandle bails on any timeDimension carrying a granularity), so the query falls through to ObjectQLStrategy → the auto-bridged executeAggregate, which calls engine.aggregate() with no ExecutionContext. The sharing middleware then sees an empty principal and composes { id: '__deny_all__' } for every sharingModel: 'private' object — which is all of ours. Measured on lead_metrics, booted kernel with the sharing middleware live:

   dimension	rows
   last_contacted_date raw	21
   last_contacted_date + dateGranularity: 'month'	0

2. Bucketing. A Field.datetime() column is INTEGER epoch millis in SQLite, and 16.1 buckets with a bare strftime('%Y-%m', col) → NULL for every row, i.e. one — column. Field.date() columns are TEXT and bucket correctly (close_date → 2026-Q1 … 2027-Q1), but still hit (1).

Both are fixed in 17.0.0-rc.0 — the bridge threads context and the strategy applies the read scope itself (upstream #3602/#3597), and driver-sql normalises epoch storage before formatting. That is also why #500 could not honour dateGranularity, and why the declarations belong with the 17.0 upgrade rather than ahead of it: landing them now would take three matrix reports (and, on the shared close_date, three dashboard revenue trends) from wrong buckets to no data.

So this ships what 16.1 can honour and pins the rest so the migration cannot be lost again or land silently unfinished.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• Code refactoring (comments corrected to match the code)

Related Issues

Related to #523
Context: #500 (the commit that removed the granularity notes' predecessors), upstream objectstack#3602 / #3597 (read-scope fix), objectstack#3839 ((null) → real null), objectstack#3916 (no column ordering)

Changes Made

• New guard test/dataset-granularity.test.ts — records the intended bucket for every date dimension and for each matrix report's axis, including the dedicated quarter dimension pipeline_coverage_by_quarter needs (close_date is shared with the Sales/CRM/Executive revenue trends, which want month — a second intent needs a second dimension). It fails if anyone re-declares a bucket on 16.x, and flips to demanding every declaration once the platform pin crosses 17, so the upgrade branch cannot go green with the migration unfinished. Verified in both directions by temporarily pinning the deps to 17.0.0-rc.0.
• lead_inflow_by_month_source / cases_opened_by_day_priority now exclude records with no date — that empty group is what rendered as the headerless — column. Lead report: 21 groups → 20, no null bucket; case report unchanged (no null dates in seeds, so the filter is forward-looking).
• Comment corrections. opportunity.report.ts claimed "the dataset's dateGranularity buckets it into quarters" for a declaration that does not exist; lead.report.ts and case.report.ts claimed to exercise the month/day bucket paths. The dataset notes now carry the verified mechanism (one canonical note on opportunity_metrics.close_date, pointers from the others) instead of a one-line guess.

Testing

• Unit tests pass (pnpm test — 12 files, 146 passed, 2 skipped: the 17+ branch of the new guard)
• Linting passes (pnpm lint — 1 warning, pre-existing and unrelated)
• Build succeeds (pnpm build, plus pnpm validate and pnpm typecheck)
• Manual testing completed — a booted kernel (sqlite-wasm + ObjectQL + sharing + analytics) was used to measure every claim above: the 21 → 0 deny-all, the per-field bucket keys (Field.date() buckets, Field.datetime() → NULL), and the — column disappearing from the lead report
• New tests added

Additional Notes

Two symptoms in #523 stay open on purpose and are not CRM-side:

• Column ordering (07-01, 07-05, …, 07-02) — upstream objectstack#3916. ReportSchema on 16.1 has no order/sort field at all (checked), so an author cannot express it; adding dateGranularity only makes the keys sortable, it does not sort them.
• The — column for reasons other than a missing date — objectstack#3839's '(null)' → real null change. What is fixable here (the genuinely empty group) is fixed above.

When the 17.0 upgrade lands, the migration is: declare the buckets in INTENDED_BUCKET, add close_quarter over the same close_date field, and repoint pipeline_coverage_by_quarter to it. The guard names each of those in its failure output.

---

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)
hotcrm	Ignored		Jul 31, 2026 2:35am