@uptimizr/db 0.5.0 → 0.7.0

package/dist/query/aggregations.js

@@ -9,7 +9,7 @@
  * Invariant: no multi-tenant concepts here. Filtering is by `project_id` and the
  * optional scene/source/session dimensions only.
  */
-import { ParamBag, cameraModeClause, dayRangeClause, rangeClause, regionClause, sceneClause, sessionClause, sourceClause, } from "./dialect.js";
+import { ParamBag, cameraModeClause, dayRangeClause, meshClause, rangeClause, regionClause, sceneClause, sessionClause, sourceClause, } from "./dialect.js";
 /** World/gaze voxel coordinates derive from the raycast `hit_point` vector. */
 const HIT_POINT_COLS = { x: "hit_point[1]", y: "hit_point[2]", z: "hit_point[3]" };
 /** Floor-plan cells derive from the camera `position` vector (Y is height). */
@@ -84,6 +84,48 @@ export function buildPointerHeatmap(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Per-mesh texture-space (UV) heatmap (#149): bin the `uv` texture coordinates of
+ * interaction events (`pointer_click`, `mesh_interaction`, `hover_dwell`) on one
+ * mesh into a `bins x bins` grid over the object's own `[0, 1]` UV space. This is
+ * the surface-attention companion to the world-space voxel heatmap — "which part
+ * of the product model gets attention", independent of where the object sits in
+ * the scene. `uv` rides in the JSON `payload` (no promoted column), so it is read
+ * with the dialect's `jsonFloat`. The promoted `mesh` column already coalesces a
+ * pointer hit's `hitMesh` with an interaction's `mesh`, so one filter spans all
+ * three event types. Output matches {@link buildPointerHeatmap}'s `HeatmapBinRow`
+ * (`gx`, `gy`, `count`) so it reuses the 2D heatmap renderer.
+ */
+export function buildMeshUvHeatmap(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const bins = bag.add("bins", "u32", opts.bins ?? 50);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const source = sourceClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const mesh = meshClause(bag, opts);
+    const u = d.jsonFloat("payload", "uv", "0");
+    const v = d.jsonFloat("payload", "uv", "1");
+    return {
+        query: `
+      SELECT gx, gy, count() AS count
+      FROM (
+        SELECT
+          floor(${u} * ${bins}) AS gx,
+          floor(${v} * ${bins}) AS gy
+        FROM events
+        WHERE project_id = ${pid}
+          AND event_type IN ('pointer_click', 'mesh_interaction', 'hover_dwell')
+          AND ${u} IS NOT NULL
+          AND ${v} IS NOT NULL${range}${scene}${source}${session}${mesh}
+      ) AS uv_hits
+      GROUP BY gx, gy
+      ORDER BY count DESC
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * World-space (3D) pointer heatmap: voxel-bin the raycast hit points of pointer
  * events into a uniform grid of `cellSize`-sized cubes. Results are capped to the
@@ -251,6 +293,55 @@ export function buildCameraDirectionHeatmap(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * 360° view-coverage histogram (#146): how much of a 3D object each session
+ * actually looked at, bucketed across sessions. Each session's `camera_sample`
+ * `direction` samples are binned into the **same** azimuth/elevation grid as the
+ * view-direction dome ({@link buildCameraDirectionHeatmap}); the fraction of the
+ * `bins × bins` cells a session visited is its coverage score (0–100%). Sessions
+ * are then grouped into four coverage buckets — `0` (0–25%), `25` (25–50%), `50`
+ * (50–75%), `75` (75–100%) — answering "how many visitors saw <25% of the
+ * product". A single integer `bin_id = azimuth_bin * bins + elevation_bin` keeps
+ * the distinct-cell count cross-dialect (no `COUNT(DISTINCT a, b)`), and
+ * `least(floor(pct / 25), 3)` folds a full-coverage (100%) session into the top
+ * bucket instead of a spurious fifth `100` bucket. Purely derived from the
+ * existing `camera_sample` stream — no schema change.
+ */
+export function buildViewCoverageHistogram(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const bins = bag.add("bins", "u32", opts.bins ?? 36);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const cameraMode = cameraModeClause(bag, d, projectId, opts);
+    return {
+        query: `
+      SELECT
+        least(floor(coverage_pct / 25), 3) * 25 AS bucket,
+        count() AS sessions
+      FROM (
+        SELECT
+          session_id,
+          count(DISTINCT bin_id) * 100.0 / (${bins} * ${bins}) AS coverage_pct
+        FROM (
+          SELECT
+            session_id,
+            floor((atan2(direction[3], direction[1]) + pi()) / (2 * pi()) * ${bins}) * ${bins}
+              + floor((asin(direction[2] / greatest(${d.vectorNorm("direction")}, 1e-6)) + pi() / 2) / pi() * ${bins}) AS bin_id
+          FROM events
+          WHERE project_id = ${pid}
+            AND event_type = 'camera_sample'
+            AND length(direction) = 3${range}${scene}${session}${cameraMode}
+        ) binned
+        GROUP BY session_id
+      ) per_session
+      GROUP BY bucket
+      ORDER BY bucket ASC
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * Top-down "floor plan" camera-position heatmap (ADR 0026): bin `camera_sample`
  * world positions onto the X/Z ground plane in `cellSize`-sized cells, tracking the
@@ -699,6 +790,59 @@ export function buildMeshDwell(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Blind-spot / never-noticed meshes (#143): the inverse of the Top-meshes and
+ * part-popularity leaderboards. Cross-references what was *rendered* against what
+ * was *engaged with* — per mesh, the total `mesh_visibility` on-screen time vs.
+ * the count of `mesh_interaction` events and the `hover_dwell` hesitation. A mesh
+ * with high visibility but zero (or near-zero) interaction + hover is a blind
+ * spot: a product detail nobody noticed, or a prop/room that renders but nobody
+ * investigates.
+ *
+ * Engagement is deliberately the two *active-attention* signals the issue names —
+ * `mesh_interaction` (the source-neutral pick/hover/drag signal, ADR 0011) and
+ * `hover_dwell` (hover-without-action, #48). Passive gaze (`camera_sample`) is
+ * not engagement, and raw `pointer_click` is excluded because a mesh-hitting click
+ * already surfaces as a `mesh_interaction`. Both durations live in the shared
+ * `visible_ms` column (events.ts maps `mesh_visibility.visibleMs` and
+ * `hover_dwell.dwellMs` onto it), so the whole report is one grouped scan.
+ *
+ * `HAVING sum(visible_ms) WHERE mesh_visibility > 0` keeps only meshes that were
+ * actually seen (a blind spot must first be visible). Ranked by engagement
+ * ascending, then visibility descending, so the most-seen-yet-least-touched
+ * meshes rank first.
+ */
+export function buildMeshBlindSpots(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const limit = bag.add("limit", "u32", opts.limit ?? 25);
+    return {
+        query: `
+      SELECT
+        mesh,
+        sum(CASE WHEN event_type = 'mesh_visibility' THEN visible_ms ELSE 0 END) AS visible_ms,
+        sum(CASE WHEN event_type = 'mesh_visibility' THEN 1 ELSE 0 END) AS vis_samples,
+        sum(CASE WHEN event_type = 'mesh_interaction' THEN 1 ELSE 0 END) AS interactions,
+        sum(CASE WHEN event_type = 'hover_dwell' THEN visible_ms ELSE 0 END) AS hover_ms,
+        sum(CASE WHEN event_type = 'hover_dwell' THEN 1 ELSE 0 END) AS hover_episodes
+      FROM events
+      WHERE project_id = ${pid}
+        AND event_type IN ('mesh_visibility', 'mesh_interaction', 'hover_dwell')
+        AND mesh != ''${range}${scene}${session}
+      GROUP BY mesh
+      HAVING sum(CASE WHEN event_type = 'mesh_visibility' THEN visible_ms ELSE 0 END) > 0
+      ORDER BY
+        sum(CASE WHEN event_type = 'mesh_interaction' THEN 1 ELSE 0 END)
+          + sum(CASE WHEN event_type = 'hover_dwell' THEN 1 ELSE 0 END) ASC,
+        sum(CASE WHEN event_type = 'mesh_visibility' THEN visible_ms ELSE 0 END) DESC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * Interaction-kind breakdown (#72): per-mesh counts of each interaction *kind*
  * (hover / pick / click / drag / select / squeeze / grab / release / teleport)
@@ -731,6 +875,73 @@ export function buildMeshInteractionKinds(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Reachability report (#151): how far each interacted mesh sat from where the
+ * user actually stood. ASOF-join every `mesh_interaction` that carries a world
+ * `point` (→ `hit_point`) to the nearest **preceding** `camera_sample` in the
+ * same session, take the Euclidean standpoint→hit distance, and histogram it per
+ * mesh in `bucketSize`-wide world-unit bands. Meshes/UI whose interactions
+ * cluster in far bands are consistently reached from an uncomfortable range —
+ * actionable feedback for VR UI placement and first-person layout.
+ *
+ * The standpoint is the click-time camera **position** (the shared coordinate
+ * frame, ADR 0018); interactions with no preceding camera sample in range can't
+ * be measured, so the inner ASOF join drops them. Same nearest-in-time caveat as
+ * the click-gaze / navigation joins: camera samples are frequent enough that the
+ * approximation is sound for discrete interaction events. Honors the shared
+ * scene/source/session filters (source constrains the *interaction* side only —
+ * a `camera_sample`'s `source` is the realized `'mouse'` default, ADR 0011).
+ */
+export function buildReachability(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const bucketSize = bag.add("bucketSize", "f64", opts.bucketSize ?? 0.5);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const source = sourceClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const limit = bag.add("limit", "u32", opts.limit ?? 500);
+    return {
+        query: `
+      SELECT
+        seg.mesh AS mesh,
+        floor(seg.dist / ${bucketSize}) AS bucket,
+        count() AS count,
+        avg(seg.dist) AS avg_distance
+      FROM (
+        SELECT
+          i.mesh AS mesh,
+          sqrt(
+            (i.hx - m.px) * (i.hx - m.px) +
+            (i.hy - m.py) * (i.hy - m.py) +
+            (i.hz - m.pz) * (i.hz - m.pz)
+          ) AS dist
+        FROM (
+          SELECT session_id, ts, mesh,
+            hit_point[1] AS hx, hit_point[2] AS hy, hit_point[3] AS hz
+          FROM events
+          WHERE project_id = ${pid}
+            AND event_type = 'mesh_interaction'
+            AND mesh != ''
+            AND length(hit_point) = 3${range}${scene}${source}${session}
+        ) AS i
+        ${d.asofInnerJoin} (
+          SELECT session_id, ts,
+            position[1] AS px, position[2] AS py, position[3] AS pz
+          FROM events
+          WHERE project_id = ${pid}
+            AND event_type = 'camera_sample'
+            AND length(position) = 3${range}${scene}${session}
+        ) AS m
+        ON i.session_id = m.session_id AND i.ts >= m.ts
+      ) AS seg
+      GROUP BY mesh, bucket
+      ORDER BY count DESC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * Dead-click rate (#46): of all `pointer_click` events, how many hit nothing
  * (the hit-test missed, so `mesh` is empty / no `hitMesh`). A high dead-click
@@ -956,6 +1167,142 @@ export function buildStabilityCounts(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Opt-in engine-diagnostic counts from `graphics_diagnostic` (ADR 0021 part 2):
+ * the fully-crossed `(severity, category, backend)` group with the total incident
+ * count per cell, so the dashboard can derive the by-category, by-severity, and
+ * by-backend breakdowns from a single query by summing.
+ *
+ * The diagnostic fields ride in the `payload` JSON (they are not promoted
+ * columns, per ADR 0004 — nothing is promoted unless an aggregation needs it),
+ * so `severity` / `category` / `backend` are read with `jsonText` and `backend`
+ * `coalesce`s to `''` ("unknown") when the connector omitted it.
+ *
+ * **Rollup-or-marker (ADR 0021 decision 4).** Each event carries *either* one
+ * discrete incident (no `count`) *or* a per-session rollup (`count = N`). The
+ * incident total is `sum(coalesce(count, 1))`, so a marker folds in as 1 and a
+ * rollup as N — markers and rollups land in the same counters. Capture is off by
+ * default, so the common case is an empty result.
+ */
+export function buildGraphicsDiagnosticCounts(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const severity = d.jsonText("payload", "severity");
+    const category = d.jsonText("payload", "category");
+    const backend = d.jsonText("payload", "backend");
+    const count = d.jsonInt("payload", "count");
+    return {
+        query: `
+      SELECT
+        ${severity} AS severity,
+        ${category} AS category,
+        coalesce(${backend}, '') AS backend,
+        sum(coalesce(${count}, 1)) AS incidents
+      FROM events
+      WHERE project_id = ${pid} AND event_type = 'graphics_diagnostic'${range}${scene}${session}
+      GROUP BY severity, category, backend
+      ORDER BY incidents DESC
+    `,
+        query_params: bag.values,
+    };
+}
+/**
+ * Spatial error heatmap (issue #154): voxel-bin the world `position` of
+ * positioned `runtime_error` and `graphics_diagnostic` events into a uniform grid
+ * of `cellSize`-sized cubes, returning the busiest `limit` voxels. This reveals
+ * *where* in the scene things break — errors/crashes clustering around specific
+ * geometry, a shader-heavy area, or a level region — instead of only *when*.
+ *
+ * `position` is best-effort connector-side (the camera pose at the moment the
+ * error/diagnostic fired), so only rows that carry a full 3-vector participate
+ * (`length(position) = 3`); errors from pages with no 3D connector are naturally
+ * excluded. Reuses the already-promoted `position` column — no migration.
+ *
+ * Optional {@link ErrorHeatmapOptions} filters (severity/category/errorKind) read
+ * from the `payload` JSON, mirroring {@link buildGraphicsDiagnosticCounts}: a
+ * severity/category filter narrows to engine diagnostics, an errorKind filter
+ * narrows to JS errors. `region` drill-down and `scene`/`session` scoping compose
+ * like the other spatial heatmaps.
+ */
+export function buildErrorHeatmap(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const cellSize = bag.add("cellSize", "f64", opts.cellSize ?? 1);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const region = regionClause(bag, opts, POSITION_COLS);
+    const limit = bag.add("limit", "u32", opts.limit ?? 1000);
+    const filters = [];
+    if (opts.severity != null && opts.severity.length > 0) {
+        filters.push(`${d.jsonText("payload", "severity")} = ${bag.add("severity", "string", opts.severity)}`);
+    }
+    if (opts.category != null && opts.category.length > 0) {
+        filters.push(`${d.jsonText("payload", "category")} = ${bag.add("category", "string", opts.category)}`);
+    }
+    if (opts.errorKind != null && opts.errorKind.length > 0) {
+        filters.push(`${d.jsonText("payload", "kind")} = ${bag.add("errorKind", "string", opts.errorKind)}`);
+    }
+    const filter = filters.length ? ` AND ${filters.join(" AND ")}` : "";
+    return {
+        query: `
+      SELECT
+        floor(position[1] / ${cellSize}) AS vx,
+        floor(position[2] / ${cellSize}) AS vy,
+        floor(position[3] / ${cellSize}) AS vz,
+        count() AS count
+      FROM events
+      WHERE project_id = ${pid}
+        AND event_type IN ('runtime_error', 'graphics_diagnostic')
+        AND length(position) = 3${range}${scene}${session}${region}${filter}
+      GROUP BY vx, vy, vz
+      ORDER BY count DESC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
+/**
+ * Always-on rendering-technology mix from `session_start.graphics` (ADR 0021 part
+ * 1): the fully-crossed `(api, backend, api_version, shading_language)` group with
+ * one session count per cell, so the dashboard can derive the by-api, by-backend,
+ * by-version, and by-shading-language breakdowns from a single query by summing.
+ *
+ * The graphics fields ride in the `payload` JSON (they are not promoted columns,
+ * per ADR 0004 — nothing is promoted unless an aggregation needs it), so each is
+ * read with `jsonText` and `coalesce`s to `''` ("unknown") when the connector
+ * omitted it. Unlike the opt-in `graphics_diagnostic` counts, `session_start` is
+ * always-on, so a populated result is the common case.
+ */
+export function buildRenderingTechnology(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const api = d.jsonText("payload", "graphics", "api");
+    const backend = d.jsonText("payload", "graphics", "backend");
+    const apiVersion = d.jsonText("payload", "graphics", "apiVersion");
+    const shadingLanguage = d.jsonText("payload", "graphics", "shadingLanguage");
+    return {
+        query: `
+      SELECT
+        coalesce(${api}, '') AS api,
+        coalesce(${backend}, '') AS backend,
+        coalesce(${apiVersion}, '') AS api_version,
+        coalesce(${shadingLanguage}, '') AS shading_language,
+        count() AS sessions
+      FROM events
+      WHERE project_id = ${pid} AND event_type = 'session_start'${range}${scene}${session}
+      GROUP BY api, backend, api_version, shading_language
+      ORDER BY sessions DESC
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * Capability / fidelity transitions from `capability_change` (#49, design §E):
  * per (kind, from, to), how many times the app reported that fallback or
@@ -1214,6 +1561,82 @@ export function buildJankRate(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Perf-correlated churn (#144): does a stutter actually cost sessions? Correlates
+ * perf dips against early session end. Of the sessions that ended in range
+ * (`sessions`), `churn_sessions` ended within `windowMs` of an FPS dip (a
+ * `frame_perf` sample below `fpsThreshold`) or a `compile_stall` of at least
+ * `stallMs` — the felt hitches that plausibly drove the user away, as opposed to
+ * background noise that the perf-distribution panel averages over.
+ *
+ * Semantics — a session churns iff it has a `session_end` **and** at least one
+ * qualifying dip whose timestamp lies in `[end - windowMs, end]` (its earliest
+ * `session_end` is the anchor). `fps_churn_sessions` / `stall_churn_sessions`
+ * attribute the cause; a session whose window held both is counted in each cause
+ * column but only once in `churn_sessions`, so the cause columns can sum to more
+ * than the total.
+ *
+ * Implementation — an `ends` CTE (each session's first `session_end`) joined to a
+ * `dips` CTE (the qualifying `frame_perf` / `compile_stall` rows) on `session_id`,
+ * with the window enforced through the dialect's `epochMs` so the timestamp math
+ * is engine-neutral. This uses only `JOIN` / `min` / `max` / `count` — **no window
+ * or ASOF functions** — so it renders identically on DuckDB (OSS) and ClickHouse
+ * (scale tier). Aggregating over the (possibly empty) `correlated` set always
+ * yields one row; the `sessions` denominator is an uncorrelated scalar sub-select
+ * so it stands even when nothing churned. Privacy (ADR 0003): aggregate counts
+ * only, no per-session identifiers leave the query.
+ */
+export function buildPerfChurn(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const windowMs = bag.add("windowMs", "u32", opts.windowMs ?? 30_000);
+    const fpsThreshold = bag.add("fpsThreshold", "f64", opts.fpsThreshold ?? 30);
+    const stallMs = bag.add("stallMs", "f64", opts.stallMs ?? 100);
+    const dipTs = d.epochMs("dips.ts");
+    const endTs = d.epochMs("ends.end_ts");
+    return {
+        query: `
+      WITH ends AS (
+        SELECT session_id, min(ts) AS end_ts
+        FROM events
+        WHERE project_id = ${pid} AND event_type = 'session_end'${range}${scene}${session}
+        GROUP BY session_id
+      ),
+      dips AS (
+        SELECT
+          session_id,
+          ts,
+          CASE WHEN event_type = 'frame_perf' THEN 1 ELSE 0 END AS is_fps,
+          CASE WHEN event_type = 'compile_stall' THEN 1 ELSE 0 END AS is_stall
+        FROM events
+        WHERE project_id = ${pid}${range}${scene}${session}
+          AND (
+            (event_type = 'frame_perf' AND fps < ${fpsThreshold})
+            OR (event_type = 'compile_stall' AND visible_ms >= ${stallMs})
+          )
+      ),
+      correlated AS (
+        SELECT
+          ends.session_id AS session_id,
+          max(dips.is_fps) AS had_fps,
+          max(dips.is_stall) AS had_stall
+        FROM ends JOIN dips ON ends.session_id = dips.session_id
+        WHERE ${dipTs} <= ${endTs} AND ${dipTs} >= ${endTs} - ${windowMs}
+        GROUP BY ends.session_id
+      )
+      SELECT
+        (SELECT count() FROM ends) AS sessions,
+        count() AS churn_sessions,
+        sum(had_fps) AS fps_churn_sessions,
+        sum(had_stall) AS stall_churn_sessions
+      FROM correlated
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * FPS segmented by device class, computed **per-session then aggregated** (ADR
  * 0028 §2). Each session's median FPS is attributed to the graphics backend,
@@ -1467,6 +1890,47 @@ export function buildSceneCoverage(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Spatial FPS heatmap (#145): voxel-bin `frame_perf` samples by their captured
+ * camera `position` into a uniform grid of `cellSize`-sized cubes, reporting each
+ * occupied cell's sample count, mean FPS, and worst single FPS. This answers
+ * *where* performance degrades ("FPS is bad in the boss room"), the spatial
+ * complement to the time-bucketed {@link buildPerfDistribution}/{@link buildFpsHistogram}.
+ *
+ * It reads the same promoted `position` column the camera-position heatmaps use —
+ * `frame_perf` now carries an optional camera position, filled by the connector at
+ * sample time — so no join against the separately-sampled `camera_sample` stream is
+ * needed. Rows are ordered worst-FPS-first so the capped top-`limit` slice surfaces
+ * the jankiest cells rather than an arbitrary corner of the scene.
+ */
+export function buildPerfHeatmap(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const cellSize = bag.add("cellSize", "f64", opts.cellSize ?? 1);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const limit = bag.add("limit", "u32", opts.limit ?? 2000);
+    return {
+        query: `
+      SELECT
+        floor(position[1] / ${cellSize}) AS vx,
+        floor(position[2] / ${cellSize}) AS vy,
+        floor(position[3] / ${cellSize}) AS vz,
+        count() AS samples,
+        avg(fps) AS avg_fps,
+        min(fps) AS min_fps
+      FROM events
+      WHERE project_id = ${pid}
+        AND event_type = 'frame_perf'
+        AND length(position) = 3${range}${scene}${session}
+      GROUP BY vx, vy, vz
+      ORDER BY avg_fps ASC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * Camera distance / zoom distribution (derived, scene-metrics §B): histogram the
  * distance from the camera *position* of each `camera_sample` to a reference
@@ -1557,6 +2021,91 @@ export function buildNavigationStats(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Path-retrace / backtracking ratio (#153): a confusion signal derived from the
+ * same `camera_sample` position stream that feeds desire lines, surfaced as a
+ * per-scene leaderboard. It answers "which areas do visitors keep re-walking?" —
+ * a high backtrack ratio flags a dead end, a missed cue, or a puzzle that isn't
+ * reading clearly.
+ *
+ * Algorithm — the coarse-grid revisit proxy (the cheap first cut, not true
+ * reverse-segment retracing): bin each session's positions onto a `cellSize`
+ * X/Z grid, then collapse consecutive samples in the same cell into ordered cell
+ * *entries* (so standing still / dwelling never counts) via an ASOF self-join to
+ * the immediately preceding sample. A row is an entry when it has no predecessor
+ * (the session's first sample) or its cell differs from the predecessor's. The
+ * `present` sentinel makes the unmatched-predecessor test engine-agnostic:
+ * DuckDB null-fills a LEFT-join miss while ClickHouse zero-fills it, so `present`
+ * (`1` only on a real match) is the portable "has a predecessor" flag.
+ *
+ * Per (session, scene): `revisits = entries − distinct_cells` — every entry into
+ * a cell beyond its first is a re-entry. Pooled per scene, the leaderboard
+ * reports `backtrack_ratio = Σ revisits / Σ entries` alongside the raw counts.
+ * Only plain `count()` and a dedup subquery are used (no multi-column
+ * `COUNT(DISTINCT …)`), so DuckDB and ClickHouse agree.
+ */
+export function buildBacktrackRatio(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const cellSize = bag.add("cellSize", "f64", opts.cellSize ?? 2);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const limit = bag.add("limit", "u32", opts.limit ?? 100);
+    const sampleSelect = `
+        SELECT session_id, scene_id AS scene, ts,
+          floor(position[1] / ${cellSize}) AS gx,
+          floor(position[3] / ${cellSize}) AS gz
+        FROM events
+        WHERE project_id = ${pid}
+          AND event_type = 'camera_sample'
+          AND length(position) = 3${range}${scene}${session}`;
+    // Ordered cell entries (consecutive same-cell samples collapsed): a sample is
+    // an entry when it has no predecessor or its cell changed vs. the predecessor.
+    const entries = `
+      SELECT c.session_id AS session_id, c.scene AS scene, c.gx AS gx, c.gz AS gz
+      FROM (${sampleSelect}
+      ) AS c
+      ${d.asofLeftJoin} (
+        SELECT session_id, ts, 1 AS present, gx, gz FROM (${sampleSelect}
+        ) AS s
+      ) AS m
+      ON c.session_id = m.session_id AND c.ts > m.ts
+      WHERE m.present IS NULL OR m.present = 0 OR c.gx <> m.gx OR c.gz <> m.gz`;
+    return {
+        query: `
+      SELECT
+        scene,
+        count() AS sessions,
+        sum(total_entries) AS entries,
+        sum(revisits) AS revisits,
+        CASE WHEN sum(total_entries) > 0
+             THEN sum(revisits) * 1.0 / sum(total_entries) ELSE 0 END AS backtrack_ratio
+      FROM (
+        SELECT
+          e.session_id AS session_id,
+          e.scene AS scene,
+          count() AS total_entries,
+          count() - dc.distinct_cells AS revisits
+        FROM (${entries}
+        ) AS e
+        JOIN (
+          SELECT session_id, scene, count() AS distinct_cells
+          FROM (
+            SELECT DISTINCT session_id, scene, gx, gz FROM (${entries}
+            ) AS de
+          ) AS ded
+          GROUP BY session_id, scene
+        ) AS dc ON e.session_id = dc.session_id AND e.scene = dc.scene
+        GROUP BY e.session_id, e.scene, dc.distinct_cells
+      ) AS per_session
+      GROUP BY scene
+      ORDER BY backtrack_ratio DESC, entries DESC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
 /** XR input sources that distinguish hand-tracking, controllers and gaze. */
 const XR_SOURCES = "('xr-controller', 'hand', 'gaze', 'transient')";
 /**
@@ -1754,6 +2303,54 @@ export function buildXrAbandonment(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * XR locomotion & comfort (#148): per session that used an XR input source, its
+ * locomotion-style breakdown and wall-clock span. This turns the existing
+ * `camera_gesture` / `mesh_interaction` streams into a comfort signal for VR
+ * developers — constant smooth `fly` locomotion (a motion-sickness risk) vs.
+ * teleport-dominant sessions — and lets the consumer correlate heavy locomotion
+ * with early exits (a short span, a discomfort / "rage-quit" proxy).
+ *
+ * A teleport emits **both** a `camera_gesture { kind: "fly" }` and a
+ * `mesh_interaction { kind: "teleport" }` (ADR 0025), so `fly_gestures` counts
+ * every fly (smooth + teleport) while `teleports` isolates the discrete jumps;
+ * the consumer derives smooth locomotion as `fly_gestures - teleports`. Sessions
+ * with no XR input are omitted entirely (same XR-session gate as
+ * {@link buildXrAbandonment}). Wall-clock bounds are engine-specific and excluded
+ * from parity; the counts are compared.
+ */
+export function buildXrLocomotionComfort(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const limit = bag.add("limit", "u32", opts.limit ?? 500);
+    return {
+        query: `
+      SELECT
+        session_id,
+        sum(CASE WHEN event_type = 'camera_gesture' AND name = 'fly' THEN 1 ELSE 0 END) AS fly_gestures,
+        sum(CASE WHEN event_type = 'camera_gesture' AND name = 'navigate' THEN 1 ELSE 0 END) AS navigate_gestures,
+        sum(CASE WHEN event_type = 'mesh_interaction' AND name = 'teleport' THEN 1 ELSE 0 END) AS teleports,
+        sum(CASE WHEN event_type = 'camera_gesture' AND name IN ('fly', 'navigate') THEN visible_ms ELSE 0 END) AS locomotion_ms,
+        min(ts) AS started_at,
+        max(ts) AS ended_at
+      FROM events
+      WHERE project_id = ${pid}${range}${scene}${session}
+        AND session_id IN (
+          SELECT session_id
+          FROM events
+          WHERE project_id = ${pid}
+            AND source IN ${XR_SOURCES}
+        )
+      GROUP BY session_id
+      ORDER BY locomotion_ms DESC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * Render one funnel step's predicate against the wide `events` columns (ADR
  * 0038). Every field compiles to plain equality on a promoted column, so the
@@ -1838,4 +2435,272 @@ export function buildFunnel(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Canned scene/level retention funnel (#147): session counts flowing scene →
+ * scene in the order they were observed, built directly from `scene_change`
+ * markers with **no caller-authored steps** (the zero-config complement to the
+ * ADR 0038 funnel). Each `scene_change` envelope carries the scene now active in
+ * `scene_id`, so a session's ordered `scene_change` targets are the levels it
+ * moved through; every **consecutive pair** is a directed link.
+ *
+ * Semantics — for one session, order its `scene_change` events by `ts`; the link
+ * `A → B` exists whenever `B`'s marker is the *next* `scene_change` after an `A`
+ * marker. A link's weight is the number of **distinct sessions** that made that
+ * consecutive transition, so it reads as level-to-level retention. Sessions with
+ * a single `scene_change` contribute no link (there is no "from").
+ *
+ * Implementation — `sc` is the per-session ordered `scene_change` stream; `nxt`
+ * finds, for each marker, the timestamp of the very next marker in the same
+ * session via a self-join + `MIN` (no window/ASOF functions, so it renders
+ * identically on DuckDB and ClickHouse — the same parity discipline as
+ * {@link buildFunnel}); joining that back to `sc` resolves the `to_scene`. The
+ * final `GROUP BY` counts distinct sessions per `(from_scene, to_scene)` pair.
+ * A same-timestamp tie between two markers can fan out to multiple `to` rows;
+ * this is a benign edge case for a preset over human-paced scene switches.
+ */
+export function buildSceneRetention(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const limit = bag.add("limit", "u32", opts.limit ?? 100);
+    return {
+        query: `
+      WITH sc AS (
+        SELECT session_id, ts, scene_id
+        FROM events
+        WHERE project_id = ${pid} AND event_type = 'scene_change'${range}
+      ),
+      nxt AS (
+        SELECT a.session_id AS session_id, a.ts AS from_ts, a.scene_id AS from_scene,
+               min(b.ts) AS to_ts
+        FROM sc a JOIN sc b ON b.session_id = a.session_id AND b.ts > a.ts
+        GROUP BY a.session_id, a.ts, a.scene_id
+      ),
+      links AS (
+        SELECT nxt.session_id AS session_id, nxt.from_scene AS from_scene,
+               sc.scene_id AS to_scene
+        FROM nxt JOIN sc ON sc.session_id = nxt.session_id AND sc.ts = nxt.to_ts
+      )
+      SELECT from_scene, to_scene, count(DISTINCT session_id) AS sessions
+      FROM links
+      GROUP BY from_scene, to_scene
+      ORDER BY sessions DESC, from_scene ASC, to_scene ASC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
+/** Default load-time band boundaries (ms) for the load→bounce funnel (#152). */
+const DEFAULT_LOAD_BANDS = [1000, 3000, 5000];
+/**
+ * Interaction event types that count as post-load engagement (#152). A session
+ * that produces none of these at/after its initial load is a "bounce". Mirrors
+ * the issue's `pointer_*` / `mesh_interaction` / `camera_gesture` set.
+ */
+const INTERACTION_EVENT_TYPES = "('pointer_move', 'pointer_down', 'pointer_up', 'pointer_click', 'mesh_interaction', 'camera_gesture')";
+/**
+ * Load → bounce/abandon funnel (#152): bucket sessions by their initial load
+ * time and report how many **bounced** per band — a bounce being a session that
+ * produced no interaction event (`pointer_*` / `mesh_interaction` /
+ * `camera_gesture`) at or after its first `asset_load`. Turns "slow load costs
+ * you customers" into a concrete per-band number.
+ *
+ * Semantics — a session's load time is the `loadMs` of its **earliest**
+ * `asset_load` (the initial scene load). Engagement is any interaction event in
+ * the same session at a timestamp `>=` that load event's timestamp, across
+ * scenes — bounce is a session-level signal, so the engagement check is not
+ * re-bounded by the range's `until` (a load near the window's end is not counted
+ * as a false bounce). Sessions with no `asset_load` in scope are excluded.
+ * `loadMs` lives in the `payload` JSON (it is not a promoted column), so it is
+ * read with `jsonInt`.
+ *
+ * Bands come from `opts.bands` (ascending exclusive upper bounds in ms), or the
+ * `[1000, 3000, 5000]` default → four bands. The builder emits a plain `CASE`
+ * over the bound band values plus `JOIN` / `min` / `count` / `sum` — **no window
+ * or ASOF functions** — so it renders identically on DuckDB (OSS) and ClickHouse
+ * (scale tier). Band labels are the caller's concern.
+ */
+export function buildLoadBounceFunnel(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const loadMs = d.jsonInt("payload", "loadMs");
+    const bands = opts.bands != null && opts.bands.length > 0 ? opts.bands : DEFAULT_LOAD_BANDS;
+    const bandCase = `CASE\n${bands
+        .map((upper, i) => `          WHEN load_ms < ${bag.add(`band${i}`, "f64", upper)} THEN ${i}`)
+        .join("\n")}\n          ELSE ${bands.length}\n        END`;
+    return {
+        query: `
+      WITH first_load AS (
+        SELECT session_id, min(ts) AS load_ts
+        FROM events
+        WHERE project_id = ${pid} AND event_type = 'asset_load'${range}${scene}
+        GROUP BY session_id
+      ),
+      load_ms AS (
+        SELECT fl.session_id AS session_id, fl.load_ts AS load_ts,
+               min(${loadMs}) AS load_ms
+        FROM events AS e JOIN first_load AS fl
+          ON e.session_id = fl.session_id AND e.ts = fl.load_ts
+        WHERE e.project_id = ${pid} AND e.event_type = 'asset_load'
+        GROUP BY fl.session_id, fl.load_ts
+      ),
+      engaged AS (
+        SELECT lm.session_id AS session_id, count() AS interactions
+        FROM events AS e JOIN load_ms AS lm
+          ON e.session_id = lm.session_id
+        WHERE e.project_id = ${pid}
+          AND e.event_type IN ${INTERACTION_EVENT_TYPES}
+          AND e.ts >= lm.load_ts
+        GROUP BY lm.session_id
+      )
+      SELECT
+        ${bandCase} AS band,
+        count() AS sessions,
+        sum(CASE WHEN coalesce(eng.interactions, 0) = 0 THEN 1 ELSE 0 END) AS bounced
+      FROM load_ms AS lm LEFT JOIN engaged AS eng ON lm.session_id = eng.session_id
+      WHERE lm.load_ms IS NOT NULL
+      GROUP BY band
+      ORDER BY band ASC
+    `,
+        query_params: bag.values,
+    };
+}
+function leaderboardPredicate(bag, step, prefix) {
+    const parts = [`event_type = ${bag.add(`${prefix}Type`, "string", step.type)}`];
+    if (step.name != null && step.name.length > 0) {
+        parts.push(`name = ${bag.add(`${prefix}Name`, "string", step.name)}`);
+    }
+    if (step.mesh != null && step.mesh.length > 0) {
+        parts.push(`mesh = ${bag.add(`${prefix}Mesh`, "string", step.mesh)}`);
+    }
+    return parts.join(" AND ");
+}
+/**
+ * Variant → conversion leaderboard for product configurators (#150).
+ *
+ * A **variant** is an event matching the `variant` predicate (default: every
+ * `custom` event), grouped by its promoted `name` column — the color / material /
+ * SKU discriminator configurators emit as custom-event names (payload `props` are
+ * not portably queryable, so `name` is the grouping key; ADR 0038). Per variant
+ * the leaderboard reports:
+ *
+ * - **views** — how many matching events fired, and over how many distinct
+ *   **sessions**;
+ * - **conversions** — distinct sessions that fired the optional `conversion`
+ *   event at or after their first view of that variant (ordered, first-touch);
+ *   `0` when no `conversion` predicate is supplied. The consumer derives the rate
+ *   as `conversions / sessions`;
+ * - **avg_dwell_ms** — the mean gap from each view to the next *boundary* in the
+ *   same session: a later view of a **different** variant (a switch) or a later
+ *   conversion event. A re-view of the *same* variant is not a boundary. Views
+ *   with no later boundary are excluded from the average.
+ *
+ * Implementation — a CTE chain using only `JOIN` / `min` / `avg` / `count` /
+ * `UNION ALL` (no window or ASOF functions), so it renders identically on DuckDB
+ * (OSS) and ClickHouse (scale tier) (ADR 0020) and is injection-safe. Session
+ * scope (range / scene / camera-mode) applies to both the variant and conversion
+ * event sets. Ranked by views, capped to `limit`.
+ *
+ * The predicates come from the caller (request input / CLI / hosted) — OSS has no
+ * authoring surface (ADR 0038).
+ */
+export function buildVariantLeaderboard(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const cameraMode = cameraModeClause(bag, d, projectId, opts);
+    const limit = bag.add("limit", "u32", opts.limit ?? 50);
+    const variantPred = leaderboardPredicate(bag, opts.variant ?? { type: "custom" }, "v");
+    const hasConversion = opts.conversion != null;
+    const conversionPred = hasConversion
+        ? leaderboardPredicate(bag, opts.conversion, "c")
+        : "";
+    // Every variant event: (session, variant name, ts). `name` is the discriminator.
+    const ctes = [
+        `variant_views AS (
+        SELECT session_id, name AS variant, ts
+        FROM events
+        WHERE project_id = ${pid} AND ${variantPred}${range}${scene}${cameraMode}
+      )`,
+    ];
+    // Conversion events (optional): (session, ts), same session scope.
+    if (hasConversion) {
+        ctes.push(`conversions AS (
+        SELECT session_id, ts
+        FROM events
+        WHERE project_id = ${pid} AND ${conversionPred}${range}${scene}${cameraMode}
+      )`);
+    }
+    // Per-view aggregates: total views and distinct sessions per variant.
+    ctes.push(`view_counts AS (
+        SELECT variant, count() AS views, count(DISTINCT session_id) AS sessions
+        FROM variant_views
+        GROUP BY variant
+      )`);
+    // First time each session saw each variant — the ordered anchor for conversion.
+    ctes.push(`first_view AS (
+        SELECT session_id, variant, min(ts) AS t0
+        FROM variant_views
+        GROUP BY session_id, variant
+      )`);
+    // Distinct sessions that converted at/after first seeing the variant (ordered).
+    if (hasConversion) {
+        ctes.push(`converted AS (
+        SELECT fv.variant AS variant, count(DISTINCT fv.session_id) AS conversions
+        FROM first_view fv
+        JOIN conversions c ON c.session_id = fv.session_id AND c.ts >= fv.t0
+        GROUP BY fv.variant
+      )`);
+    }
+    // Boundaries for dwell: every variant view (carrying its variant, is_conv = 0)
+    // plus every conversion event (is_conv = 1). A view's next boundary is the
+    // earliest later boundary that is a conversion OR a different variant.
+    const boundaryParts = [
+        `SELECT session_id, ts, variant AS b_variant, 0 AS is_conv FROM variant_views`,
+    ];
+    if (hasConversion) {
+        boundaryParts.push(`SELECT session_id, ts, '' AS b_variant, 1 AS is_conv FROM conversions`);
+    }
+    ctes.push(`boundaries AS (
+        ${boundaryParts.join("\n        UNION ALL ")}
+      )`);
+    // Per view: gap to its next boundary. The JOIN drops views with no boundary,
+    // so they are excluded from the average (as specified).
+    ctes.push(`view_dwell AS (
+        SELECT v.variant AS variant,
+               ${d.epochMs("min(b.ts)")} - ${d.epochMs("v.ts")} AS dwell_ms
+        FROM variant_views v
+        JOIN boundaries b
+          ON b.session_id = v.session_id
+         AND b.ts > v.ts
+         AND NOT (b.is_conv = 0 AND b.b_variant = v.variant)
+        GROUP BY v.session_id, v.variant, v.ts
+      )`);
+    ctes.push(`dwell AS (
+        SELECT variant, avg(dwell_ms) AS avg_dwell_ms
+        FROM view_dwell
+        GROUP BY variant
+      )`);
+    const conversionsSelect = hasConversion ? `coalesce(cv.conversions, 0)` : `0`;
+    const convJoin = hasConversion ? `\n      LEFT JOIN converted cv ON cv.variant = vc.variant` : "";
+    return {
+        query: `
+      WITH ${ctes.join(",\n      ")}
+      SELECT
+        vc.variant AS variant,
+        vc.views AS views,
+        vc.sessions AS sessions,
+        ${conversionsSelect} AS conversions,
+        coalesce(dw.avg_dwell_ms, 0) AS avg_dwell_ms
+      FROM view_counts vc
+      LEFT JOIN dwell dw ON dw.variant = vc.variant${convJoin}
+      ORDER BY vc.views DESC, vc.variant ASC
+      LIMIT ${limit}
+    `,
+        query_params: bag.values,
+    };
+}
 //# sourceMappingURL=aggregations.js.map