feat(analytics): raw-value drill sidecar for totals/subtotal rows (#3214)

[os-zhuang]

Summary

Closes#3214.

ADR-0021 D2 drill metadata snapshots each row's raw grouped values into a parallel drillRawRows array beforeresolveDimensionLabels overwrites row[dim] with the display label — so a report drill filters by the stored value (FK id, select option value). But that snapshot only covered result.rows.

The totals/subtotal rows added in #1753 also carry dimension values (a row subtotal is keyed by its row bucket) and go through the same label resolution (analytics-service.ts, the for (const total of result.totals ?? []) loop). No raw values were captured for them, so a subtotal row ended up in the pre-#1750 state — display label only, stored value lost. A drill from a subtotal (e.g. clicking a "Q2 · Backlog" cell) then couldn't exact-match a lookup/select dimension.

Changes

• packages/services/service-analytics/src/analytics-service.ts — in the ADR-0021 D2 drill block (the pre-label-resolution pass), also snapshot totals rows into a new drillRawTotals sidecar:
  • Aligned to result.totals by index: drillRawTotals[i] ↔ result.totals[i], drillRawTotals[i][j] ↔ result.totals[i].rows[j].
  • Restricted to the drillable dimensions each grouping actually groups by, so the grand-total grouping ([]) contributes an empty map per row (which keeps the index alignment and drills the whole, unfiltered object).
  • Purely additive extra props on the result, same as feat(analytics): dimension labels + drill-through metadata for dataset reports #2080 — no spec-contract change.
• packages/services/service-analytics/src/__tests__/query-dataset.test.ts — two new tests:
  • alignment/shape of drillRawTotals across a subtotal grouping + grand total;
  • the raw FK survives in the sidecar even after label resolution rewrites the subtotal row's dimension to the display name.
• Changeset (minor for @objectstack/service-analytics).

Notes

objectui's ReportView.handleDatasetDrill consumes drillRawRows for data rows only and subtotal drill isn't wired up yet, so this gap is latent today — this closes it on the framework side so the raw values are available if/when subtotal drill ships.

Verification

• vitest run for @objectstack/service-analytics — 166 passed (14 files), including the 2 new tests.
• tsc --noEmit — no new type errors introduced (two unrelated pre-existing errors in analytics-service.test.ts / native-sql-granularity-decline.test.ts are untouched by this change).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vejtto9wLCMUjQ9NFrXqnK

---

Generated by Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 18, 2026 1:58pm

[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.