@uptimizr/db 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/AGENTS.md +109 -0
  2. package/LICENSE +201 -0
  3. package/README.md +89 -0
  4. package/dist/cli/createProject.d.ts +3 -0
  5. package/dist/cli/createProject.d.ts.map +1 -0
  6. package/dist/cli/createProject.js +41 -0
  7. package/dist/cli/createProject.js.map +1 -0
  8. package/dist/cli/migrate.d.ts +3 -0
  9. package/dist/cli/migrate.d.ts.map +1 -0
  10. package/dist/cli/migrate.js +21 -0
  11. package/dist/cli/migrate.js.map +1 -0
  12. package/dist/cli/seed.d.ts +2 -0
  13. package/dist/cli/seed.d.ts.map +1 -0
  14. package/dist/cli/seed.js +175 -0
  15. package/dist/cli/seed.js.map +1 -0
  16. package/dist/duckdb/client.d.ts +42 -0
  17. package/dist/duckdb/client.d.ts.map +1 -0
  18. package/dist/duckdb/client.js +93 -0
  19. package/dist/duckdb/client.js.map +1 -0
  20. package/dist/duckdb/events.d.ts +44 -0
  21. package/dist/duckdb/events.d.ts.map +1 -0
  22. package/dist/duckdb/events.js +225 -0
  23. package/dist/duckdb/events.js.map +1 -0
  24. package/dist/duckdb/migrations.d.ts +20 -0
  25. package/dist/duckdb/migrations.d.ts.map +1 -0
  26. package/dist/duckdb/migrations.js +323 -0
  27. package/dist/duckdb/migrations.js.map +1 -0
  28. package/dist/duckdb/projects.d.ts +23 -0
  29. package/dist/duckdb/projects.d.ts.map +1 -0
  30. package/dist/duckdb/projects.js +55 -0
  31. package/dist/duckdb/projects.js.map +1 -0
  32. package/dist/duckdb/queries.d.ts +10 -0
  33. package/dist/duckdb/queries.d.ts.map +1 -0
  34. package/dist/duckdb/queries.js +10 -0
  35. package/dist/duckdb/queries.js.map +1 -0
  36. package/dist/duckdb/sceneRegistry.d.ts +15 -0
  37. package/dist/duckdb/sceneRegistry.d.ts.map +1 -0
  38. package/dist/duckdb/sceneRegistry.js +98 -0
  39. package/dist/duckdb/sceneRegistry.js.map +1 -0
  40. package/dist/env.d.ts +25 -0
  41. package/dist/env.d.ts.map +1 -0
  42. package/dist/env.js +55 -0
  43. package/dist/env.js.map +1 -0
  44. package/dist/events.d.ts +107 -0
  45. package/dist/events.d.ts.map +1 -0
  46. package/dist/events.js +153 -0
  47. package/dist/events.js.map +1 -0
  48. package/dist/index.d.ts +36 -0
  49. package/dist/index.d.ts.map +1 -0
  50. package/dist/index.js +34 -0
  51. package/dist/index.js.map +1 -0
  52. package/dist/metadata.d.ts +84 -0
  53. package/dist/metadata.d.ts.map +1 -0
  54. package/dist/metadata.js +23 -0
  55. package/dist/metadata.js.map +1 -0
  56. package/dist/parity/cases.d.ts +31 -0
  57. package/dist/parity/cases.d.ts.map +1 -0
  58. package/dist/parity/cases.js +524 -0
  59. package/dist/parity/cases.js.map +1 -0
  60. package/dist/parity/compare.d.ts +47 -0
  61. package/dist/parity/compare.d.ts.map +1 -0
  62. package/dist/parity/compare.js +90 -0
  63. package/dist/parity/compare.js.map +1 -0
  64. package/dist/parity/fixtures.d.ts +45 -0
  65. package/dist/parity/fixtures.d.ts.map +1 -0
  66. package/dist/parity/fixtures.js +157 -0
  67. package/dist/parity/fixtures.js.map +1 -0
  68. package/dist/parity/index.d.ts +12 -0
  69. package/dist/parity/index.d.ts.map +1 -0
  70. package/dist/parity/index.js +12 -0
  71. package/dist/parity/index.js.map +1 -0
  72. package/dist/query/aggregations.d.ts +393 -0
  73. package/dist/query/aggregations.d.ts.map +1 -0
  74. package/dist/query/aggregations.js +1412 -0
  75. package/dist/query/aggregations.js.map +1 -0
  76. package/dist/query/dialect.d.ts +100 -0
  77. package/dist/query/dialect.d.ts.map +1 -0
  78. package/dist/query/dialect.js +88 -0
  79. package/dist/query/dialect.js.map +1 -0
  80. package/dist/query/duckdbDialect.d.ts +27 -0
  81. package/dist/query/duckdbDialect.d.ts.map +1 -0
  82. package/dist/query/duckdbDialect.js +83 -0
  83. package/dist/query/duckdbDialect.js.map +1 -0
  84. package/dist/query/index.d.ts +22 -0
  85. package/dist/query/index.d.ts.map +1 -0
  86. package/dist/query/index.js +30 -0
  87. package/dist/query/index.js.map +1 -0
  88. package/dist/query/types.d.ts +388 -0
  89. package/dist/query/types.d.ts.map +1 -0
  90. package/dist/query/types.js +11 -0
  91. package/dist/query/types.js.map +1 -0
  92. package/llms.txt +21 -0
  93. package/package.json +71 -0
@@ -0,0 +1,393 @@
1
+ /**
2
+ * Dialect-agnostic analytics aggregations (ADR 0020).
3
+ *
4
+ * Each builder describes an aggregation once and renders it through a
5
+ * {@link Dialect}, returning a {@link QuerySpec}. ClickHouse-specific syntax is
6
+ * confined to the dialect; the query *logic* lives here and is shared by every
7
+ * engine (DuckDB for OSS, single-tenant ClickHouse for the scale tier).
8
+ *
9
+ * Invariant: no multi-tenant concepts here. Filtering is by `project_id` and the
10
+ * optional scene/source/session dimensions only.
11
+ */
12
+ import { type Dialect } from "./dialect.js";
13
+ import type { QuerySpec, CameraModeOptions, RangeOptions, SceneOptions, SessionOptions, SourceOptions, TimeseriesOptions } from "./types.js";
14
+ /** List sessions for a project with event counts and time bounds. */
15
+ export declare function buildListSessions(projectId: string, opts: RangeOptions & CameraModeOptions & {
16
+ limit?: number;
17
+ }, d: Dialect): QuerySpec;
18
+ /**
19
+ * 2D pointer heatmap: bin normalized screen positions into a `bins x bins` grid.
20
+ * Covers `pointer_move` and `pointer_click`.
21
+ */
22
+ export declare function buildPointerHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions & CameraModeOptions & {
23
+ bins?: number;
24
+ }, d: Dialect): QuerySpec;
25
+ /**
26
+ * World-space (3D) pointer heatmap: voxel-bin the raycast hit points of pointer
27
+ * events into a uniform grid of `cellSize`-sized cubes. Results are capped to the
28
+ * busiest `limit` voxels.
29
+ */
30
+ export declare function buildWorldHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & CameraModeOptions & {
31
+ cellSize?: number;
32
+ limit?: number;
33
+ }, d: Dialect): QuerySpec;
34
+ /**
35
+ * World-space (3D) gaze heatmap (ADR 0030): voxel-bin the camera-pose gaze
36
+ * surface hits (`camera_sample.hitPoint`) into the same uniform grid as the
37
+ * pointer world heatmap. This is the "what did people actually look at" map — it
38
+ * lands on real geometry and serves orbit/viewer, first-person, and XR scenes
39
+ * alike. Distinct from the click-driven world heatmap (looked-at vs clicked) and
40
+ * from the abstract direction sphere (surface vs angle). Results are capped to
41
+ * the busiest `limit` voxels; an optional `session` scopes it to one visit
42
+ * (ADR 0010 §1a). Gaze has no pointer input-source, so there is no `source` filter.
43
+ */
44
+ export declare function buildGazeHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & CameraModeOptions & {
45
+ cellSize?: number;
46
+ limit?: number;
47
+ }, d: Dialect): QuerySpec;
48
+ /**
49
+ * View-direction heatmap: bin camera forward vectors by spherical angles.
50
+ * `azimuth = atan2(z, x)`, `elevation = asin(y / |v|)`, each bucketed into `bins`.
51
+ */
52
+ export declare function buildCameraDirectionHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & CameraModeOptions & {
53
+ bins?: number;
54
+ }, d: Dialect): QuerySpec;
55
+ /**
56
+ * Top-down "floor plan" camera-position heatmap (ADR 0026): bin `camera_sample`
57
+ * world positions onto the X/Z ground plane in `cellSize`-sized cells, tracking the
58
+ * mean height per cell. For first-person (`cameraType: "free"`) sessions this is
59
+ * the "where do visitors walk / dwell" map; capped to the busiest `limit` cells.
60
+ */
61
+ export declare function buildCameraPositionHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & CameraModeOptions & {
62
+ cellSize?: number;
63
+ limit?: number;
64
+ }, d: Dialect): QuerySpec;
65
+ /**
66
+ * A single session's walked path (ADR 0026): the ordered `camera_sample` world
67
+ * positions for one session, oldest first. Drives the dashboard's trajectory view
68
+ * (a poly-line over the floor plan). Capped to `limit` points.
69
+ */
70
+ export declare function buildSessionTrajectory(projectId: string, opts: RangeOptions & SceneOptions & {
71
+ session: string;
72
+ limit?: number;
73
+ }, d: Dialect): QuerySpec;
74
+ /**
75
+ * Click ↔ gaze correlation: aggregate each `pointer_click` into a ray from an
76
+ * origin voxel to a hit voxel, where the voxel size matches the world heatmap so
77
+ * origins and hits share the same grid.
78
+ *
79
+ * Origin selection (ADR 0011 — source-agnostic): pose-enabled sources (XR
80
+ * controllers, hands, gaze) carry their own world-space pointing ray, so when a
81
+ * click has a `ray.origin` we use it verbatim — the controller/hand/gaze is the
82
+ * true pointing origin, not the headset/camera. Flat pointers (mouse, touch,
83
+ * stylus) have no native ray, so they fall back to the nearest preceding
84
+ * `camera_sample` in the same session (the historical view-gated behavior). The
85
+ * camera join is therefore a LEFT join so pose clicks survive even in sessions
86
+ * that never emit a `camera_sample`; rows with neither a ray nor a camera origin
87
+ * are dropped.
88
+ */
89
+ export declare function buildClickGazeRay(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions & {
90
+ cellSize?: number;
91
+ limit?: number;
92
+ }, d: Dialect): QuerySpec;
93
+ /**
94
+ * Aggregate gaze→mesh flow links: ASOF-join each `pointer_click` to the nearest
95
+ * preceding `camera_sample` in the same session, then group by
96
+ * `(direction-bin, mesh)`. Each row is one weighted link from a direction bin to
97
+ * a clicked mesh.
98
+ *
99
+ * Position-aware mode (design §7.8): when `groupByOrigin` is set or an
100
+ * `originVoxel` filter is given, the click-time camera **position** is restored
101
+ * as a source dimension — rows additionally carry the standpoint voxel
102
+ * (`origin_v*`) and its averaged world point (`origin_*`). The standpoint origin
103
+ * prefers the click's own ray origin for pose sources (ADR 0011), falling back
104
+ * to the joined `camera_sample` position. Omitting both options reproduces the
105
+ * §7.5 direction-only links unchanged.
106
+ */
107
+ export declare function buildFlowHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & CameraModeOptions & {
108
+ bins?: number;
109
+ limit?: number;
110
+ /** Standpoint voxel edge (world units) for position-aware mode (§7.8). */
111
+ cellSize?: number;
112
+ /** Group links by standpoint voxel in addition to direction + mesh (§7.8). */
113
+ groupByOrigin?: boolean;
114
+ /** Restrict to clicks whose standpoint falls in this voxel (§7.8). */
115
+ originVoxel?: readonly [number, number, number];
116
+ }, d: Dialect): QuerySpec;
117
+ /** Most-interacted meshes (from `mesh_interaction` and pointer hits). */
118
+ export declare function buildTopMeshes(projectId: string, opts: RangeOptions & SessionOptions & {
119
+ limit?: number;
120
+ }, d: Dialect): QuerySpec;
121
+ /**
122
+ * Per-object attention / dwell from `mesh_visibility` summaries (#37). Sums the
123
+ * bucketed on-screen and gaze-centred time per mesh and tracks the peak screen
124
+ * fraction, ranked by total dwell. The 3D analog of time-on-element.
125
+ */
126
+ export declare function buildMeshDwell(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
127
+ limit?: number;
128
+ }, d: Dialect): QuerySpec;
129
+ /**
130
+ * Dead-click rate (#46): of all `pointer_click` events, how many hit nothing
131
+ * (the hit-test missed, so `mesh` is empty / no `hitMesh`). A high dead-click
132
+ * rate is a 3D discoverability problem — users click where they expect something
133
+ * interactive and get no response. Reuses `inputSourceShape` filters (ADR 0011).
134
+ */
135
+ export declare function buildDeadClicks(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions, d: Dialect): QuerySpec;
136
+ /**
137
+ * Rage clicks (#47): rapid repeated clicks on the same mesh — a frustration
138
+ * signal ("I keep clicking this and nothing happens"). Derived purely from the
139
+ * `pointer_click` stream: clicks are bucketed into fixed `interval`-second
140
+ * windows per `(session, mesh)`, and a bucket with at least `minRepeats` clicks
141
+ * is reported as a rage cluster, ranked by burst size. Only clicks that hit a
142
+ * mesh count here; rapid clicks on empty space are the dead-click signal (#46).
143
+ * Reuses `inputSourceShape` filters (ADR 0011).
144
+ */
145
+ export declare function buildRageClicks(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions & {
146
+ interval?: number;
147
+ minRepeats?: number;
148
+ limit?: number;
149
+ }, d: Dialect): QuerySpec;
150
+ /**
151
+ * Hover hesitation from `hover_dwell` summaries (#48): per mesh, the total time
152
+ * visitors lingered on an object *without clicking it*, the number of hesitation
153
+ * episodes, and the longest single hover. High dwell with few interactions flags
154
+ * objects that look interactive but aren't — or aren't obviously clickable. The
155
+ * connector emits one bucketed episode per hover (its `dwellMs` is stored in the
156
+ * shared `visible_ms` column). Reuses `inputSourceShape` filters (ADR 0011).
157
+ */
158
+ export declare function buildHoverDwell(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions & {
159
+ limit?: number;
160
+ }, d: Dialect): QuerySpec;
161
+ /**
162
+ * Shader / pipeline compile stalls (#42, design §C): per phase, the number of
163
+ * compile hitches and their total / average / worst main-thread duration.
164
+ * Compilation is the #1 source of first-interaction jank, so this surfaces the
165
+ * felt cost that `frame_perf` averages away. The connector emits one
166
+ * `compile_stall` per compile; its `durationMs` is stored in the shared
167
+ * `visible_ms` column and its coarse `phase` label in the `name` column.
168
+ */
169
+ export declare function buildCompileStalls(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
170
+ limit?: number;
171
+ }, d: Dialect): QuerySpec;
172
+ /**
173
+ * GPU / memory footprint summary from `resource_sample` samples (#44, design §C).
174
+ * Reports the average and peak of each footprint metric over the range — the
175
+ * actual cost the scene asked of the device (vs. `session_start.device` caps).
176
+ * Unreported metrics are stored as `0`; `NULLIF(..., 0)` keeps those out of the
177
+ * averages so a metric one engine omits doesn't dilute another's.
178
+ */
179
+ export declare function buildResourceSummary(projectId: string, opts: RangeOptions & SessionOptions, d: Dialect): QuerySpec;
180
+ /**
181
+ * GPU/memory footprint **percentiles**, computed per-session then aggregated
182
+ * (ADR 0028 §1), from `resource_sample`. Reports a typical (p50) and a peak
183
+ * (p95) value per session for JS heap, texture bytes, and triangle count, then
184
+ * summarizes each as the median across sessions — so a single heavy session does
185
+ * not set the headline footprint. Unreported metrics (stored `0`) are excluded
186
+ * via `nullIf`. Complements {@link buildResourceSummary}'s pooled avg/max with a
187
+ * distribution-honest view.
188
+ */
189
+ export declare function buildResourcePercentiles(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
190
+ /**
191
+ * Stability-incident counts over the range: WebGL/WebGPU context losses
192
+ * (`context_lost`) and shader/pipeline compile stalls (`compile_stall`), plus the
193
+ * total incident count. These are the hard failures `frame_perf` cannot show — a
194
+ * context loss blanks the canvas, a compile stall freezes first interaction. An
195
+ * empty range reports `0` (not NULL) via `coalesce`.
196
+ */
197
+ export declare function buildStabilityCounts(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
198
+ /**
199
+ * Capability / fidelity transitions from `capability_change` (#49, design §E):
200
+ * per (kind, from, to), how many times the app reported that fallback or
201
+ * recovery. Explains perf / visual-fidelity variance across the user base (e.g.
202
+ * how many sessions fell back WebGPU→WebGL2). `kind` is carried by the shared
203
+ * `name` column; the capability tokens live in `cap_from` / `cap_to`.
204
+ */
205
+ export declare function buildCapabilityChanges(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
206
+ limit?: number;
207
+ }, d: Dialect): QuerySpec;
208
+ /**
209
+ * Camera-navigation gesture breakdown from `camera_gesture` (ADR 0025): per
210
+ * gesture `kind` (orbit / pan / dolly / zoom / roll / fly / navigate), how often
211
+ * users moved the viewpoint and how long each gesture lasted. This separates
212
+ * deliberate navigation intent from object selection (a click that doesn't move
213
+ * the camera emits no gesture), revealing how an audience explores a scene. The
214
+ * gesture `kind` is carried by the shared `name` column and its `durationMs` by
215
+ * the shared `visible_ms` column.
216
+ */
217
+ export declare function buildCameraGestures(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions & {
218
+ limit?: number;
219
+ }, d: Dialect): QuerySpec;
220
+ /** Aggregate rendering-performance summary from `frame_perf` samples. */
221
+ export declare function buildPerfSummary(projectId: string, opts: RangeOptions & SessionOptions, d: Dialect): QuerySpec;
222
+ /**
223
+ * FPS distribution, computed **per-session then aggregated** (ADR 0028 §1). Each
224
+ * session contributes its own p05/p50/p95 FPS, so neither long sessions nor
225
+ * high-frame-rate devices dominate the headline; the reported percentiles are
226
+ * the median across sessions of each per-session percentile ("median-of-medians").
227
+ * `sessions` is the number of contributing sessions and `samples` the total
228
+ * `frame_perf` sample count.
229
+ */
230
+ export declare function buildPerfDistribution(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
231
+ /**
232
+ * Histogram of **per-session median FPS** (ADR 0028 §1). One session contributes
233
+ * a single data point — its median FPS — bucketed into `bucket`-wide FPS bins
234
+ * (default 10). `bucket` is the inclusive lower bound of each bin and `sessions`
235
+ * the number of sessions whose median FPS falls in it. Plotting session medians
236
+ * rather than raw samples keeps the shape honest about how many *experiences*
237
+ * were smooth, instead of letting a few chatty sessions skew the curve.
238
+ */
239
+ export declare function buildFpsHistogram(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
240
+ bucket?: number;
241
+ }, d: Dialect): QuerySpec;
242
+ /**
243
+ * Frame-time percentiles in milliseconds, computed **per-session then
244
+ * aggregated** (ADR 0028 §1). `p50_ms` is the median across sessions of each
245
+ * session's median `frame_time_ms` (the typical frame cost); `p95_ms` is the
246
+ * median across sessions of each session's worst-window `frame_time_p95_ms` —
247
+ * the SDK already reports a per-window p95, so the tail is read from that
248
+ * promoted column rather than re-derived from window means. Zero-valued detail
249
+ * (unreported by older samples / non-`frame_perf` rows) is ignored via `nullIf`.
250
+ */
251
+ export declare function buildFrameTimePercentiles(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
252
+ /**
253
+ * Jank rate, computed **per-session then aggregated** (ADR 0028 §1). Each
254
+ * session's rate is its total `long_frames` divided by its `frame_perf` sample
255
+ * windows; the headline is the median session rate plus the worst-decile (p90)
256
+ * session rate, so a handful of janky sessions surface instead of being averaged
257
+ * away. `total_long_frames` is the raw jank count and `sessions` the number of
258
+ * contributing sessions.
259
+ */
260
+ export declare function buildJankRate(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
261
+ /**
262
+ * FPS segmented by device class, computed **per-session then aggregated** (ADR
263
+ * 0028 §2). Each session's median FPS is attributed to the graphics backend,
264
+ * mobile flag, and GPU `renderer` recorded in its `session_start.device` block —
265
+ * data already on the wire, so there is no SDK or schema change. Device fields
266
+ * are read from the `session_start` payload JSON (they are not promoted columns)
267
+ * and `coalesce`d to `''` when a session never reported them. `p50_fps` is the
268
+ * median across sessions in the group of each session's median FPS.
269
+ */
270
+ export declare function buildPerfByDevice(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
271
+ /**
272
+ * FPS segmented by scene, computed **per-session then aggregated** (ADR 0028 §1).
273
+ * Each session's median FPS is attributed to its scene (a session renders one
274
+ * scene); `p50_fps` is the median across the scene's sessions of each session's
275
+ * median FPS, so neither long sessions nor a busy scene's traffic skews the
276
+ * comparison between scenes.
277
+ */
278
+ export declare function buildPerfByScene(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
279
+ /**
280
+ * Daily rendering-performance trend, read from the `perf_daily` materialized
281
+ * view (migration 0003/0004). Aggregate states are merged with `-Merge`.
282
+ */
283
+ export declare function buildPerfDaily(projectId: string, opts: RangeOptions & {
284
+ limit?: number;
285
+ }, d: Dialect): QuerySpec;
286
+ /**
287
+ * Daily event-count trend per event type, read from the `events_daily`
288
+ * materialized view (migration 0005/0006). SummingMergeTree counts are summed.
289
+ */
290
+ export declare function buildEventsDaily(projectId: string, opts: RangeOptions & {
291
+ limit?: number;
292
+ }, d: Dialect): QuerySpec;
293
+ /**
294
+ * Distinct developer-assigned scenes for a project (ADR 0010), with an event
295
+ * `count` and the most recent activity `last_seen`. Time-range aware.
296
+ */
297
+ export declare function buildDistinctScenes(projectId: string, opts: RangeOptions & {
298
+ limit?: number;
299
+ }, d: Dialect): QuerySpec;
300
+ /**
301
+ * Event-volume time-series: bucket events into fixed `interval`-second windows
302
+ * and return the per-bucket count plus the average FPS of any `frame_perf`
303
+ * samples in that bucket. Optionally scoped to one scene and/or event type.
304
+ */
305
+ export declare function buildTimeseries(projectId: string, opts: RangeOptions & SceneOptions & TimeseriesOptions, d: Dialect): QuerySpec;
306
+ /**
307
+ * Per-event-type counts over the range (optionally one scene). Powers the scene
308
+ * health panel — error rate, context-loss incidents, focus/visibility gaps, etc.
309
+ */
310
+ export declare function buildEventTypeCounts(projectId: string, opts: RangeOptions & SceneOptions, d: Dialect): QuerySpec;
311
+ /**
312
+ * Scene coverage / dead zones (derived, ADR — scene-metrics §B): voxel-bin the
313
+ * camera *position* of `camera_sample` into a uniform grid of `cellSize`-sized
314
+ * cubes. Each row is an occupied voxel with its visit `count`. Exploration
315
+ * completeness ("saw 40% of the scene") and never-visited regions are computed by
316
+ * the consumer against the scene AABB voxel count — the AABB lives in the scene
317
+ * registry, not the events table, so it is layered in at presentation time.
318
+ */
319
+ export declare function buildSceneCoverage(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
320
+ cellSize?: number;
321
+ limit?: number;
322
+ }, d: Dialect): QuerySpec;
323
+ /**
324
+ * Camera distance / zoom distribution (derived, scene-metrics §B): histogram the
325
+ * distance from the camera *position* of each `camera_sample` to a reference
326
+ * `center` (the scene-AABB center, passed in world units; defaults to the
327
+ * origin), bucketed into `bucketSize`-wide bins. A proxy for engagement intensity
328
+ * — how close visitors get to the subject.
329
+ */
330
+ export declare function buildCameraDistance(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
331
+ center?: readonly [number, number, number];
332
+ bucketSize?: number;
333
+ limit?: number;
334
+ }, d: Dialect): QuerySpec;
335
+ /**
336
+ * Navigation effort / friction (derived, scene-metrics §B): per session, ASOF
337
+ * self-join each `camera_sample` to the immediately preceding one and accumulate
338
+ * the inter-sample travel distance. `total_distance` is the path length; segments
339
+ * whose distance clears `moveThreshold` count as *active* (the rest are idle
340
+ * dwell), so a high segment count with low active distance flags a "stuck" / lost
341
+ * visitor. World units throughout.
342
+ */
343
+ export declare function buildNavigationStats(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
344
+ moveThreshold?: number;
345
+ limit?: number;
346
+ }, d: Dialect): QuerySpec;
347
+ /**
348
+ * Input-source breakdown (ADR 0011): for every interaction event that carries an
349
+ * input source, how many fired per `(event_type, source)`, and how many distinct
350
+ * sessions used that pairing. This turns `source` from a filter-only dimension
351
+ * into an actual insight — e.g. how many `mesh_interaction`s came from an
352
+ * `xr-controller` vs a `mouse`, or whether `pointer_click`s skew to `touch`.
353
+ * Honors the same scene/source/session filters as the rest of the surface.
354
+ */
355
+ export declare function buildInteractionsBySource(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions & {
356
+ limit?: number;
357
+ }, d: Dialect): QuerySpec;
358
+ /**
359
+ * XR motion-sickness proxy (derived, scene-metrics §F): per session, the
360
+ * head/view rotation *rate* over the `camera_sample` pose stream. Each sample is
361
+ * ASOF self-joined to its immediate predecessor and the angle between the two
362
+ * (normalized) view directions is accumulated — `total_turn_rad` is the angular
363
+ * path, `max_turn_rad` the worst single jerk, and `rapid_segments` counts steps
364
+ * whose turn clears `rapidTurn` (rad). The pose cadence is fixed by the sampling
365
+ * profile, so the per-sample angular delta is a discomfort proxy: rapid view
366
+ * rotation correlates with simulator sickness, most acutely in a headset.
367
+ */
368
+ export declare function buildXrRotationRate(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
369
+ rapidTurn?: number;
370
+ limit?: number;
371
+ }, d: Dialect): QuerySpec;
372
+ /**
373
+ * XR input-source usage (derived, scene-metrics §F): hand vs. controller (vs.
374
+ * gaze / transient) split, read from `source` on the existing interaction events.
375
+ * One row per XR `source` with its interaction `count` and the number of
376
+ * `sessions` that used it — flat-screen sources (`mouse`, `touch`, …) are
377
+ * excluded so the breakdown is purely the immersive input mix.
378
+ */
379
+ export declare function buildXrSourceUsage(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
380
+ limit?: number;
381
+ }, d: Dialect): QuerySpec;
382
+ /**
383
+ * XR session abandonment (derived, scene-metrics §F): for every session that
384
+ * used an XR input source, its first/last timestamps and event/interaction
385
+ * counts. Comfort drop-off is read by the consumer as a short
386
+ * `ended_at - started_at` span (a headset session cut short) — the wall-clock
387
+ * bounds are engine-specific and excluded from parity, while the counts are
388
+ * compared. Sessions with no XR input are omitted entirely.
389
+ */
390
+ export declare function buildXrAbandonment(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & {
391
+ limit?: number;
392
+ }, d: Dialect): QuerySpec;
393
+ //# sourceMappingURL=aggregations.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../src/query/aggregations.ts"],"names":[],"mappings":"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"}