@uptimizr/metrics 0.0.0 → 0.2.0

package/dist/registry.d.ts

@@ -49,7 +49,7 @@ import type { EventType } from "@uptimizr/schema";
  * so adding, renaming or deleting an aggregation without updating this list
  * fails the build and names the offender.
  */
-export declare const AGGREGATION_BUILDER_NAMES: readonly ["buildAggregateTrajectories", "buildArPlacementAttempts", "buildArPlacementSurfaces", "buildArPlacementTimeToPlace", "buildBacktrackRatio", "buildBoundaryContacts", "buildBoundaryHeatmap", "buildBoundaryHeatmapStats", "buildCameraDirectionHeatmap", "buildCameraDistance", "buildCameraGestures", "buildCameraPositionHeatmap", "buildCapabilityChanges", "buildClickGazeRay", "buildCompileStalls", "buildDeadClicks", "buildDistinctScenes", "buildErrorHeatmap", "buildEventTypeCounts", "buildEventsDaily", "buildFlowHeatmap", "buildFpsHistogram", "buildFrameTimePercentiles", "buildFunnel", "buildGazeHeatmap", "buildGazeHeatmapStats", "buildGraphicsDiagnosticCounts", "buildHoverDwell", "buildInteractionsBySource", "buildJankRate", "buildListSessions", "buildLoadBounceFunnel", "buildMeshBlindSpots", "buildMeshDwell", "buildMeshInteractionKinds", "buildMeshUvHeatmap", "buildNavigationStats", "buildPerfByDevice", "buildPerfByScene", "buildPerfChurn", "buildPerfDaily", "buildPerfDistribution", "buildPerfHeatmap", "buildPerfSummary", "buildPointerHeatmap", "buildRageClicks", "buildReachability", "buildRenderScaleTruth", "buildRenderingTechnology", "buildResourcePercentiles", "buildResourceSummary", "buildSceneCoverage", "buildSceneRetention", "buildSessionTrajectory", "buildStabilityCounts", "buildTimeseries", "buildTopInputActions", "buildTopMeshes", "buildTopMeshesBySource", "buildTopMeshesTrend", "buildTrackingQuality", "buildVariantLeaderboard", "buildViewCoverageHistogram", "buildWorldHeatmap", "buildWorldHeatmapStats", "buildXrAbandonment", "buildXrLocomotionComfort", "buildXrRotationRate", "buildXrSourceUsage"];
+export declare const AGGREGATION_BUILDER_NAMES: readonly ["buildAggregateTrajectories", "buildArPlacementAttempts", "buildArPlacementSurfaces", "buildArPlacementTimeToPlace", "buildBacktrackRatio", "buildBoundaryContacts", "buildBoundaryHeatmap", "buildBoundaryHeatmapStats", "buildCameraDirectionHeatmap", "buildCameraDistance", "buildCameraGestures", "buildCameraPositionHeatmap", "buildCapabilityChanges", "buildClickGazeRay", "buildCompileStalls", "buildCustomEventVocabulary", "buildDeadClicks", "buildDistinctScenes", "buildErrorHeatmap", "buildEventTypeCounts", "buildEventsDaily", "buildFlowHeatmap", "buildFpsHistogram", "buildFrameTimePercentiles", "buildFunnel", "buildGazeHeatmap", "buildGazeHeatmapStats", "buildGraphicsDiagnosticCounts", "buildHoverDwell", "buildInteractionsBySource", "buildJankRate", "buildListSessions", "buildLoadBounceFunnel", "buildMeshBlindSpots", "buildMeshDwell", "buildMeshInteractionKinds", "buildMeshUvHeatmap", "buildNavigationStats", "buildPerfByDevice", "buildPerfByScene", "buildPerfChurn", "buildPerfDaily", "buildPerfDistribution", "buildPerfHeatmap", "buildPerfSummary", "buildPointerHeatmap", "buildRageClicks", "buildReachability", "buildRenderScaleTruth", "buildRenderingTechnology", "buildResourcePercentiles", "buildResourceSummary", "buildSceneCoverage", "buildSceneRetention", "buildSessionTrajectory", "buildStabilityCounts", "buildTimeseries", "buildTopInputActions", "buildTopMeshes", "buildTopMeshesBySource", "buildTopMeshesTrend", "buildTrackingQuality", "buildVariantLeaderboard", "buildViewCoverageHistogram", "buildWorldHeatmap", "buildWorldHeatmapStats", "buildXrAbandonment", "buildXrLocomotionComfort", "buildXrRotationRate", "buildXrSourceUsage"];
 /** Every exported `build*` aggregation name. The registry must cover them all. */
 export type AggregationBuilderName = (typeof AGGREGATION_BUILDER_NAMES)[number];
 /**
@@ -61,18 +61,66 @@ export type AggregationBuilderName = (typeof AGGREGATION_BUILDER_NAMES)[number];
 export type DimensionId = "scene" | "session" | "mesh" | "name" | "source" | "event_type" | "cameraMode" | "device.engine" | "device.renderer" | "device.isMobile" | "device.browser" | "device.os";
 /** Where each {@link DimensionId} reads from in the event model. */
 export declare const DIMENSION_COLUMNS: Readonly<Record<DimensionId, string>>;
+/**
+ * The column a {@link DimensionId} appears as in a metric's `row` when that
+ * metric is keyed by it.
+ *
+ * Several dimensions are *filterable* on a metric without being part of its
+ * grain (`top_meshes` can be scoped to a `session` but returns one row per
+ * mesh), which is what {@link MetricDefinition.grainDimensions} exists to
+ * express — this map is how that declaration is **checked**: every grain
+ * dimension must project one of the names listed here, and
+ * `src/__tests__/registry.test.ts` fails the build when one does not.
+ *
+ * Alternatives are listed where the projection name has varied: a scene rollup
+ * spells `scene` as `scene_id` and a transition as `from_scene`, and the `name`
+ * column surfaces as `kind` (an interaction or gesture kind), `action` (an input
+ * action) or `phase` (a compile stall). The **first** entry is the canonical
+ * spelling the generic group-by tier projects when the metric's own row does not
+ * already name one. `cameraMode` has none: no aggregation projects the camera
+ * type as a column, so it is a filter on the delegated tier and a generic-only
+ * group-by column (`camera_mode`) on the other.
+ */
+export declare const DIMENSION_ROW_COLUMNS: Readonly<Record<DimensionId, readonly string[]>>;
+/**
+ * The dimensions the **generic group-by tier** can render (design sketch §C.2).
+ *
+ * Restricted to what the store promotes to a column (`scene_id`, `session_id`,
+ * `mesh`, `name`, `source`, `event_type`) plus the session attributes every
+ * engine can read out of one `session_start` sub-select with the same SQL
+ * (`cameraMode`, the four `device.*` strings). `device.isMobile` is deliberately
+ * absent: it is the one session attribute that is a boolean rather than a label,
+ * so grouping by it would produce `"true"` / `"false"` text on some engines and
+ * `1` / `0` on others — the exact cross-engine disagreement this tier exists to
+ * avoid. Filter by it instead, or group by `device.os`.
+ */
+export declare const GENERIC_DIMENSIONS: readonly DimensionId[];
 /**
  * Every request parameter the query surface accepts. Closed union, declared
  * once: a metric's `filters` are exactly the keys of the Zod querystring that
  * serves its endpoint (asserted by the collector's registry route test), and the
  * DSL will accept the same names.
  */
-export type FilterId = "since" | "until" | "scene" | "session" | "source" | "mesh" | "region" | "cameraMode" | "bins" | "limit" | "cellSize" | "interval" | "type" | "bucket" | "bucketMs" | "bucketSize" | "minRepeats" | "windowMs" | "fpsThreshold" | "stallMs" | "moveThreshold" | "rapidTurn" | "centerX" | "centerY" | "centerZ" | "severity" | "category" | "errorKind" | "groupByOrigin" | "originVoxel" | "steps" | "bands" | "variant" | "conversion" | "format";
+export type FilterId = "since" | "until" | "scene" | "session" | "source" | "mesh" | "region" | "cameraMode" | "bins" | "limit" | "cellSize" | "interval" | "type" | "bucket" | "bucketMs" | "bucketSize" | "minRepeats" | "windowMs" | "fpsThreshold" | "stallMs" | "moveThreshold" | "rapidTurn" | "centerX" | "centerY" | "centerZ" | "severity" | "category" | "errorKind" | "groupByOrigin" | "originVoxel" | "steps" | "bands" | "variant" | "conversion" | "minDwellMs" | "maxEntries" | "metric" | "metrics" | "window" | "refSince" | "refUntil" | "sensitivity" | "weights" | "format";
 /**
  * The option interface (in `types.ts`) a {@link FilterId} feeds. `BuilderOptions`
  * means the builder's own inline option bag rather than a shared interface.
  */
 export type FilterOptionInterface = "RangeOptions" | "SceneOptions" | "SourceOptions" | "SessionOptions" | "MeshOptions" | "RegionOptions" | "CameraModeOptions" | "TimeseriesOptions" | "ErrorHeatmapOptions" | "PerfChurnOptions" | "FunnelOptions" | "LoadBounceFunnelOptions" | "VariantLeaderboardOptions" | "BuilderOptions"
+/**
+ * Not an aggregation option either: the parameter is consumed by
+ * `buildSessionNarrative` — the pure compaction behind
+ * `GET /api/v1/sessions/:id/narrative` (ADR 0051 §7) — and never reaches a
+ * SQL builder.
+ */
+ | "SessionNarrativeOptions"
+/**
+ * The option bag of an insight primitive (ADR 0051 §4). Not an aggregation
+ * option: it is consumed by `@uptimizr/db`'s pure `src/insights/` layer, which
+ * runs *over* another metric's bucket series rather than producing SQL of its
+ * own.
+ */
+ | "InsightOptions"
 /**
  * Not an aggregation option at all: the parameter is consumed by the
  * collector's response layer and never reaches a builder. Only `format`
@@ -121,7 +169,23 @@ export interface ColumnSemantics {
 /** What one row of a metric represents. */
 export type MetricGrain = "project" | "scene" | "session" | "mesh" | "bin" | "voxel" | "bucket" | "row";
 /** Grouping used by the docs, the capabilities resource and the health score. */
-export type MetricCategory = "attention" | "interaction" | "navigation" | "performance" | "errors" | "xr" | "ar" | "sessions" | "conversion";
+export type MetricCategory = "attention" | "interaction" | "navigation" | "performance" | "errors" | "xr" | "ar" | "sessions" | "conversion"
+/** Derived readings *about* other metrics — baselines, movers (ADR 0051 §4). */
+ | "insights";
+/**
+ * The API-key capability an endpoint requires (ADR 0051 §7).
+ *
+ * `query` is the whole aggregate read surface and is the default. `query:raw`
+ * is the narrow, opt-in door to per-session data: the collector honours it only
+ * when `ENABLE_RAW_SESSION_RETENTION` is on (ADR 0003), and a generated tool for
+ * such a metric must be registered **only** for a key that holds it.
+ *
+ * Declared as a literal union rather than imported from `@uptimizr/db`'s
+ * `ApiKeyCapability`: that package depends on *this* one, and the registry may
+ * never depend on a database driver. `@uptimizr/db` re-checks the two in its own
+ * test suite.
+ */
+export type MetricCapability = "query" | "query:raw";
 /** The collector route a metric is served on. */
 export interface MetricEndpoint {
     method: "GET";
@@ -132,6 +196,74 @@ export interface MetricEndpoint {
      * of a trajectory). One entry per `:param` segment, in order.
      */
     pathParams?: readonly FilterId[];
+    /**
+     * The capability a key must hold to call it. Omitted means `query` — the
+     * ordinary aggregate read surface. See {@link MetricCapability}.
+     */
+    capability?: MetricCapability;
+}
+/**
+ * The capability `metric`'s endpoint requires, with the `query` default applied.
+ * Consumers partition the catalog with this rather than reading the optional
+ * field directly, so "no capability declared" cannot be mistaken for "no
+ * capability required".
+ */
+export declare function metricCapability(metric: MetricDefinition): MetricCapability;
+/**
+ * How one column of a generic group-by result is computed. Four aggregate
+ * shapes, all of which SQL:2003 spells identically and every supported engine
+ * implements the same way — that is the whole test for admission.
+ */
+export type GenericMeasureKind = 
+/** `count(*)` — rows in the group. */
+"count"
+/** `count(DISTINCT session_id)` — sessions represented in the group. */
+ | "sessions"
+/** `sum(<column>)` over a promoted numeric column. */
+ | "sum"
+/** `avg(<column>)` over a promoted numeric column. */
+ | "avg"
+/** `max(<column>)` over a promoted numeric column. */
+ | "max";
+/** One measure column a generic group-by result carries. */
+export interface GenericMeasure {
+    /** The output column name. Must also be a column of the metric's `row`. */
+    column: string;
+    kind: GenericMeasureKind;
+    /**
+     * The promoted event column the aggregate reads. Required for `sum` / `avg` /
+     * `max`, meaningless for `count` / `sessions`.
+     */
+    of?: string;
+}
+/**
+ * Extra scope the generic builder applies beyond `event_type`, so a regrouped
+ * result counts the same events the metric's own builder counts.
+ *
+ * `top_meshes` is `count(*) … WHERE mesh != ''`; dropping that predicate when
+ * grouping by `source` would silently fold every mesh-less event into an empty
+ * mesh bucket. Each value is one non-empty-string predicate on a promoted
+ * column — closed, so the generic SQL stays free of anything caller-supplied.
+ */
+export type GenericScope = "hasMesh" | "hasName";
+/**
+ * The generic group-by declaration (design sketch §C.2, tier 2).
+ *
+ * Together these say: "over *these* events, narrowed by *this* scope, *these*
+ * measures can be recomputed at any grain the metric declares". The builder that
+ * reads it lives in `@uptimizr/db`'s `query/dsl/generic.ts`; nothing here knows
+ * what SQL is.
+ */
+export interface GenericGroupBy {
+    /**
+     * Event types in scope. Empty means **every** event type — only
+     * `event_counts`, whose subject really is the whole stream, leaves it empty.
+     */
+    eventTypes: readonly EventType[];
+    /** Additional closed predicates on promoted columns. */
+    scope?: readonly GenericScope[];
+    /** The measure columns the result carries, in order. The first is `measure`. */
+    measures: readonly GenericMeasure[];
 }
 /** Comparison semantics for `compare`, `movers` and `anomalies` (ADR 0051 §4). */
 export interface MetricComparison {
@@ -142,6 +274,13 @@ export interface MetricComparison {
     /** Minimum denominator before a delta is worth reporting. */
     minSample: number;
 }
+/**
+ * How a **derived** metric is computed, when it has no `build*` aggregation of
+ * its own. One value per module in `@uptimizr/db`'s `src/insights/`
+ * (ADR 0051 §4) — statistics over another metric's portable bucket series,
+ * evaluated in TypeScript so no two SQL engines can disagree about them.
+ */
+export type MetricDerivation = "insight";
 /**
  * Everything a consumer needs to call a metric, read its result and judge how
  * far to trust it.
@@ -158,12 +297,57 @@ export interface MetricDefinition {
      * aggregations, but are part of the agent surface.
      */
     builder?: AggregationBuilderName;
+    /**
+     * Marks a **derived** entry: a metric computed in pure TypeScript *over other
+     * metrics' data* rather than by a `build*` aggregation of its own — the insight
+     * primitives (ADR 0051 §4). Like a resource it has no builder; unlike a
+     * resource it is a real aggregate, served on an endpoint with a querystring,
+     * a time range and the `format` envelope. The two are distinguished by this
+     * flag rather than by `builder === undefined`, so the registry guards that
+     * pin the resource set and the envelope surface stay exact.
+     *
+     * The value names where the computation lives, for a reader following the
+     * trail from a tool description to the code.
+     */
+    derived?: MetricDerivation;
     /** The canned collector route, when one exists. */
     endpoint?: MetricEndpoint;
     /** What one row represents. */
     grain: MetricGrain;
-    /** The dimension columns this metric's rows are keyed by. */
+    /**
+     * Every dimension this metric can be **keyed or filtered by** — the
+     * vocabulary, not the grain. `top_meshes` lists `session` because it can be
+     * scoped to one, while its rows are one per mesh. {@link grainDimensions} is
+     * the grain; for a {@link genericGroupBy} metric this list is also the set a
+     * caller may group by.
+     */
     dimensions: readonly DimensionId[];
+    /**
+     * The dimensions one row is **actually keyed by** — the metric's native grain,
+     * and what a `dimensions`-less DSL query returns.
+     *
+     * Declared rather than derived (ADR 0051 §3, #304). v1 read the grain back out
+     * of `row.shape`, which was correct but left the registry unable to *say* what
+     * it knew; the generic group-by tier has to distinguish "this metric cannot be
+     * grouped by that" from "it can, through the generic builder", and that is a
+     * statement about the metric rather than about the spelling of its columns.
+     * The old derivation survives as a gate: `src/__tests__/registry.test.ts`
+     * asserts every entry here is a subset of {@link dimensions} and really
+     * projects a column of `row`.
+     */
+    grainDimensions: readonly DimensionId[];
+    /**
+     * How the **generic group-by tier** (design sketch §C.2, tier 2) recomputes
+     * this metric at an arbitrary grain — omitted when it cannot.
+     *
+     * Present only where the measure is portable: a `count(*)`, a
+     * `count(DISTINCT session_id)`, or a `sum`/`avg`/`max` over a **promoted**
+     * column. Those render identically on all four engines whatever the group-by
+     * is. A spatial metric's measure *is* a binning of coordinates and a
+     * percentile does not decompose across an arbitrary grain, so neither declares
+     * one and both stay delegated.
+     */
+    genericGroupBy?: GenericGroupBy;
     /** Accepted querystring parameters — exactly the endpoint's Zod keys. */
     filters: readonly FilterId[];
     /** Output row schema: the source for OpenAPI, tool output schemas and coercion. */
@@ -197,7 +381,7 @@ export interface MetricDefinition {
  * calls `top_meshes` today must keep working when the catalog is generated from
  * this registry (design sketch §A.4).
  */
-export type MetricId = "list_sessions" | "pointer_heatmap" | "world_heatmap" | "camera_heatmap" | "click_rays" | "flow_links" | "top_meshes" | "perf_summary" | "list_scenes" | "timeseries" | "event_counts" | "session_meta" | "scene_representation" | "funnel" | "aggregate_paths" | "rendering_technology" | "xr_rotation" | "xr_sources" | "xr_abandonment" | "xr_locomotion" | "mesh_uv_heatmap" | "world_heatmap_stats" | "gaze_heatmap" | "gaze_heatmap_stats" | "view_coverage_histogram" | "position_heatmap" | "session_trajectory" | "scene_coverage" | "camera_distance" | "mesh_sources" | "mesh_trend" | "mesh_dwell" | "mesh_blind_spots" | "mesh_interaction_kinds" | "mesh_reachability" | "dead_clicks" | "rage_clicks" | "hover_dwell" | "interaction_sources" | "top_input_actions" | "camera_gestures" | "navigation_stats" | "backtrack_ratio" | "render_scale_truth" | "perf_distribution" | "fps_histogram" | "frame_time_percentiles" | "jank_rate" | "perf_churn" | "perf_by_device" | "perf_by_scene" | "perf_heatmap" | "perf_daily" | "events_daily" | "compile_stalls" | "resource_summary" | "resource_percentiles" | "stability_counts" | "graphics_diagnostics" | "error_heatmap" | "capability_changes" | "boundary_heatmap" | "boundary_heatmap_stats" | "xr_boundary_contacts" | "xr_tracking_quality" | "ar_placement_time_to_place" | "ar_placement_attempts" | "ar_placement_surfaces" | "scene_retention" | "load_bounce_funnel" | "variant_leaderboard";
+export type MetricId = "list_sessions" | "pointer_heatmap" | "world_heatmap" | "camera_heatmap" | "click_rays" | "flow_links" | "top_meshes" | "perf_summary" | "list_scenes" | "timeseries" | "event_counts" | "session_meta" | "scene_representation" | "funnel" | "aggregate_paths" | "rendering_technology" | "xr_rotation" | "xr_sources" | "xr_abandonment" | "xr_locomotion" | "mesh_uv_heatmap" | "world_heatmap_stats" | "gaze_heatmap" | "gaze_heatmap_stats" | "view_coverage_histogram" | "position_heatmap" | "session_trajectory" | "scene_coverage" | "camera_distance" | "mesh_sources" | "mesh_trend" | "mesh_dwell" | "mesh_blind_spots" | "mesh_interaction_kinds" | "mesh_reachability" | "dead_clicks" | "rage_clicks" | "hover_dwell" | "interaction_sources" | "top_input_actions" | "camera_gestures" | "custom_event_vocabulary" | "navigation_stats" | "backtrack_ratio" | "render_scale_truth" | "perf_distribution" | "fps_histogram" | "frame_time_percentiles" | "jank_rate" | "perf_churn" | "perf_by_device" | "perf_by_scene" | "perf_heatmap" | "perf_daily" | "events_daily" | "compile_stalls" | "resource_summary" | "resource_percentiles" | "stability_counts" | "graphics_diagnostics" | "error_heatmap" | "capability_changes" | "boundary_heatmap" | "boundary_heatmap_stats" | "xr_boundary_contacts" | "xr_tracking_quality" | "ar_placement_time_to_place" | "ar_placement_attempts" | "ar_placement_surfaces" | "scene_retention" | "load_bounce_funnel" | "variant_leaderboard" | "session_narrative" | "insight_baseline" | "insight_movers" | "insight_anomalies" | "insight_significance" | "insight_scene_health";
 /**
  * The metric registry: one entry per `build*` aggregation, plus the two
  * builder-less resource reads that are part of the agent surface.
@@ -219,7 +403,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: "session"[];
-        filters: ("cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("format" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             visitor_id: z.ZodString;
@@ -277,6 +462,7 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: "session"[];
+        grainDimensions: never[];
         filters: never[];
         row: z.ZodObject<{
             sessionId: z.ZodString;
@@ -315,6 +501,94 @@ export declare const METRIC_REGISTRY: {
         related: ("list_sessions" | "perf_by_device")[];
         category: "sessions";
     };
+    session_narrative: {
+        id: "session_narrative";
+        title: string;
+        description: string;
+        endpoint: {
+            method: "GET";
+            path: string;
+            pathParams: "session"[];
+            capability: "query:raw";
+        };
+        grain: "row";
+        dimensions: "session"[];
+        grainDimensions: never[];
+        filters: ("format" | "fpsThreshold" | "minDwellMs" | "maxEntries")[];
+        row: z.ZodObject<{
+            tMs: z.ZodNumber;
+            kind: z.ZodEnum<{
+                scene: "scene";
+                dwell: "dwell";
+                interaction: "interaction";
+                perf_dip: "perf_dip";
+                error: "error";
+                diagnostic: "diagnostic";
+                capability: "capability";
+                xr: "xr";
+                end: "end";
+                summary: "summary";
+            }>;
+            summary: z.ZodString;
+            refs: z.ZodObject<{
+                mesh: z.ZodOptional<z.ZodString>;
+                scene: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            count: z.ZodOptional<z.ZodNumber>;
+            totals: z.ZodOptional<z.ZodObject<{
+                events: z.ZodNumber;
+                durationMs: z.ZodNumber;
+                scenes: z.ZodNumber;
+                meshes: z.ZodNumber;
+                interactions: z.ZodNumber;
+                dips: z.ZodNumber;
+                errors: z.ZodNumber;
+            }, z.core.$strip>>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+        columns: {
+            tMs: {
+                description: string;
+                unit: "ms";
+            };
+            kind: {
+                description: string;
+                unit: "label";
+                label: true;
+            };
+            summary: {
+                description: string;
+            };
+            refs: {
+                description: string;
+            };
+            durationMs: {
+                description: string;
+                unit: "ms";
+            };
+            count: {
+                description: string;
+                unit: "count";
+            };
+            totals: {
+                description: string;
+            };
+            truncated: {
+                description: string;
+            };
+        };
+        limits: {
+            maxRows: 1000;
+            maxSummaryRows: 200;
+        };
+        interpretation: string;
+        caveats: string[];
+        sourceChannels: ("session_start" | "session_end" | "frame_perf" | "pointer_click" | "mesh_interaction" | "mesh_visibility" | "hover_dwell" | "capability_change" | "scene_change" | "graphics_diagnostic" | "runtime_error" | "input_action" | "xr_boundary_proximity" | "custom")[];
+        related: ("list_sessions" | "session_meta" | "session_trajectory")[];
+        category: "sessions";
+    };
     scene_representation: {
         id: "scene_representation";
         title: string;
@@ -326,6 +600,7 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "scene";
         dimensions: "scene"[];
+        grainDimensions: never[];
         filters: never[];
         row: z.ZodObject<{
             projectId: z.ZodString;
@@ -416,7 +691,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "scene";
         dimensions: "scene"[];
-        filters: ("since" | "until" | "limit" | "format")[];
+        grainDimensions: "scene"[];
+        filters: ("format" | "since" | "until" | "limit")[];
         row: z.ZodObject<{
             scene_id: z.ZodString;
             events: z.ZodNumber;
@@ -464,11 +740,12 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: ("scene" | "event_type")[];
-        filters: ("scene" | "since" | "until" | "interval" | "type" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "type" | "format" | "since" | "until" | "interval")[];
         row: z.ZodObject<{
             bucket: z.ZodNumber;
             events: z.ZodNumber;
-            avg_fps: z.ZodNumber;
+            avg_fps: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strip>;
         columns: {
             bucket: {
@@ -512,8 +789,16 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "row";
-        dimensions: ("scene" | "event_type")[];
-        filters: ("scene" | "since" | "until" | "format")[];
+        dimensions: ("scene" | "mesh" | "name" | "session" | "source" | "event_type" | "cameraMode" | "device.engine" | "device.renderer" | "device.browser" | "device.os")[];
+        grainDimensions: "event_type"[];
+        genericGroupBy: {
+            eventTypes: never[];
+            measures: {
+                column: string;
+                kind: "count";
+            }[];
+        };
+        filters: ("scene" | "format" | "since" | "until")[];
         row: z.ZodObject<{
             event_type: z.ZodString;
             count: z.ZodNumber;
@@ -552,6 +837,7 @@ export declare const METRIC_REGISTRY: {
         builder: "buildEventsDaily";
         grain: "bucket";
         dimensions: "event_type"[];
+        grainDimensions: "event_type"[];
         filters: never[];
         row: z.ZodObject<{
             day: z.ZodString;
@@ -601,7 +887,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bin";
         dimensions: ("scene" | "session" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             gx: z.ZodNumber;
             gy: z.ZodNumber;
@@ -648,8 +935,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "bin";
-        dimensions: ("scene" | "session" | "mesh" | "source")[];
-        filters: ("scene" | "session" | "mesh" | "source" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "source")[];
+        grainDimensions: never[];
+        filters: ("scene" | "mesh" | "format" | "session" | "source" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             gx: z.ZodNumber;
             gy: z.ZodNumber;
@@ -677,7 +965,7 @@ export declare const METRIC_REGISTRY: {
         };
         interpretation: string;
         caveats: string[];
-        sourceChannels: ("hover_dwell" | "pointer_click" | "mesh_interaction")[];
+        sourceChannels: ("pointer_click" | "mesh_interaction" | "hover_dwell")[];
         related: ("pointer_heatmap" | "top_meshes" | "mesh_interaction_kinds")[];
         comparable: {
             primary: string;
@@ -697,7 +985,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "voxel";
         dimensions: ("scene" | "source" | "cameraMode")[];
-        filters: ("scene" | "source" | "cameraMode" | "since" | "until" | "region" | "limit" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "source" | "cameraMode" | "since" | "until" | "region" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             vx: z.ZodNumber;
             vy: z.ZodNumber;
@@ -750,7 +1039,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "source" | "cameraMode")[];
-        filters: ("scene" | "source" | "cameraMode" | "since" | "until" | "region" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "source" | "cameraMode" | "since" | "until" | "region" | "cellSize")[];
         row: z.ZodObject<{
             cells: z.ZodNumber;
             hits: z.ZodNumber;
@@ -787,7 +1077,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "voxel";
         dimensions: ("scene" | "session" | "cameraMode")[];
-        filters: ("scene" | "session" | "cameraMode" | "since" | "until" | "region" | "limit" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "cameraMode" | "since" | "until" | "region" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             vx: z.ZodNumber;
             vy: z.ZodNumber;
@@ -840,7 +1131,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session" | "cameraMode")[];
-        filters: ("scene" | "session" | "cameraMode" | "since" | "until" | "region" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "cameraMode" | "since" | "until" | "region" | "cellSize")[];
         row: z.ZodObject<{
             cells: z.ZodNumber;
             hits: z.ZodNumber;
@@ -877,7 +1169,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bin";
         dimensions: ("scene" | "session" | "cameraMode")[];
-        filters: ("scene" | "session" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             azimuth_bin: z.ZodNumber;
             elevation_bin: z.ZodNumber;
@@ -925,7 +1218,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: ("scene" | "session" | "cameraMode")[];
-        filters: ("scene" | "session" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             bucket: z.ZodNumber;
             sessions: z.ZodNumber;
@@ -969,7 +1263,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bin";
         dimensions: ("scene" | "session" | "cameraMode")[];
-        filters: ("scene" | "session" | "cameraMode" | "since" | "until" | "region" | "limit" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "cameraMode" | "since" | "until" | "region" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             gx: z.ZodNumber;
             gz: z.ZodNumber;
@@ -1023,7 +1318,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "since" | "until" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "since" | "until" | "limit")[];
         row: z.ZodObject<{
             ts: z.ZodNumber;
             x: z.ZodNumber;
@@ -1070,7 +1366,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "session" | "cameraMode")[];
-        filters: ("scene" | "cameraMode" | "since" | "until" | "limit" | "cellSize" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("scene" | "format" | "cameraMode" | "since" | "until" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             ts: z.ZodNumber;
@@ -1117,7 +1414,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "voxel";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "limit" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             vx: z.ZodNumber;
             vy: z.ZodNumber;
@@ -1170,7 +1468,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "limit" | "bucketSize" | "centerX" | "centerY" | "centerZ" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "limit" | "bucketSize" | "centerX" | "centerY" | "centerZ")[];
         row: z.ZodObject<{
             bucket: z.ZodNumber;
             count: z.ZodNumber;
@@ -1208,8 +1507,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "voxel";
-        dimensions: ("scene" | "session" | "mesh" | "source")[];
-        filters: ("scene" | "session" | "source" | "since" | "until" | "limit" | "cellSize" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "source")[];
+        grainDimensions: "mesh"[];
+        filters: ("scene" | "format" | "session" | "source" | "since" | "until" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             cam_vx: z.ZodNumber;
             cam_vy: z.ZodNumber;
@@ -1311,8 +1611,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "bin";
-        dimensions: ("scene" | "session" | "mesh" | "cameraMode")[];
-        filters: ("scene" | "session" | "cameraMode" | "since" | "until" | "bins" | "limit" | "cellSize" | "groupByOrigin" | "originVoxel" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "cameraMode")[];
+        grainDimensions: "mesh"[];
+        filters: ("scene" | "format" | "session" | "cameraMode" | "since" | "until" | "bins" | "limit" | "cellSize" | "groupByOrigin" | "originVoxel")[];
         row: z.ZodObject<{
             azimuth_bin: z.ZodNumber;
             elevation_bin: z.ZodNumber;
@@ -1394,8 +1695,17 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "mesh";
-        dimensions: ("session" | "mesh")[];
-        filters: ("session" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "source" | "event_type" | "cameraMode" | "device.engine" | "device.renderer" | "device.browser" | "device.os")[];
+        grainDimensions: "mesh"[];
+        genericGroupBy: {
+            eventTypes: never[];
+            scope: "hasMesh"[];
+            measures: {
+                column: string;
+                kind: "count";
+            }[];
+        };
+        filters: ("format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             count: z.ZodNumber;
@@ -1437,8 +1747,17 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "mesh";
-        dimensions: ("scene" | "session" | "mesh" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "name" | "session" | "source" | "event_type" | "cameraMode" | "device.engine" | "device.renderer" | "device.browser" | "device.os")[];
+        grainDimensions: ("mesh" | "source")[];
+        genericGroupBy: {
+            eventTypes: ("pointer_click" | "mesh_interaction")[];
+            scope: "hasMesh"[];
+            measures: {
+                column: string;
+                kind: "count";
+            }[];
+        };
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             source: z.ZodString;
@@ -1485,8 +1804,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "bucket";
-        dimensions: ("scene" | "session" | "mesh" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "interval" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "source" | "cameraMode")[];
+        grainDimensions: "mesh"[];
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "interval")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             bucket: z.ZodNumber;
@@ -1534,8 +1854,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "mesh";
-        dimensions: ("scene" | "session" | "mesh")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "session")[];
+        grainDimensions: "mesh"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             visible_ms: z.ZodNumber;
@@ -1574,7 +1895,7 @@ export declare const METRIC_REGISTRY: {
         interpretation: string;
         caveats: string[];
         sourceChannels: "mesh_visibility"[];
-        related: ("top_meshes" | "gaze_heatmap" | "mesh_blind_spots" | "hover_dwell")[];
+        related: ("hover_dwell" | "top_meshes" | "gaze_heatmap" | "mesh_blind_spots")[];
         comparable: {
             primary: string;
             direction: "neutral";
@@ -1592,8 +1913,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "mesh";
-        dimensions: ("scene" | "session" | "mesh")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "session")[];
+        grainDimensions: "mesh"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             visible_ms: z.ZodNumber;
@@ -1636,8 +1958,8 @@ export declare const METRIC_REGISTRY: {
         };
         interpretation: string;
         caveats: string[];
-        sourceChannels: ("hover_dwell" | "mesh_interaction" | "mesh_visibility")[];
-        related: ("top_meshes" | "gaze_heatmap" | "mesh_dwell" | "hover_dwell")[];
+        sourceChannels: ("mesh_interaction" | "mesh_visibility" | "hover_dwell")[];
+        related: ("hover_dwell" | "top_meshes" | "gaze_heatmap" | "mesh_dwell")[];
         comparable: {
             primary: string;
             direction: "up";
@@ -1655,8 +1977,17 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "mesh";
-        dimensions: ("scene" | "session" | "mesh" | "name" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "name" | "session" | "source" | "cameraMode" | "device.engine" | "device.renderer" | "device.browser" | "device.os")[];
+        grainDimensions: ("mesh" | "name")[];
+        genericGroupBy: {
+            eventTypes: "mesh_interaction"[];
+            scope: "hasMesh"[];
+            measures: {
+                column: string;
+                kind: "count";
+            }[];
+        };
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             kind: z.ZodString;
@@ -1685,7 +2016,7 @@ export declare const METRIC_REGISTRY: {
         interpretation: string;
         caveats: string[];
         sourceChannels: "mesh_interaction"[];
-        related: ("top_meshes" | "mesh_sources" | "hover_dwell")[];
+        related: ("hover_dwell" | "top_meshes" | "mesh_sources")[];
         comparable: {
             primary: string;
             direction: "neutral";
@@ -1703,8 +2034,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "mesh";
-        dimensions: ("scene" | "session" | "mesh" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "bucketSize" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "source" | "cameraMode")[];
+        grainDimensions: "mesh"[];
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "bucketSize")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             bucket: z.ZodNumber;
@@ -1757,7 +2089,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             total_clicks: z.ZodNumber;
             dead_clicks: z.ZodNullable<z.ZodNumber>;
@@ -1781,7 +2114,7 @@ export declare const METRIC_REGISTRY: {
         interpretation: string;
         caveats: string[];
         sourceChannels: "pointer_click"[];
-        related: ("pointer_heatmap" | "top_meshes" | "rage_clicks" | "hover_dwell")[];
+        related: ("hover_dwell" | "pointer_heatmap" | "top_meshes" | "rage_clicks")[];
         comparable: {
             primary: string;
             direction: "down";
@@ -1799,8 +2132,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "row";
-        dimensions: ("scene" | "session" | "mesh" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "interval" | "minRepeats" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "source" | "cameraMode")[];
+        grainDimensions: ("mesh" | "session")[];
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "interval" | "minRepeats")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             mesh: z.ZodString;
@@ -1834,7 +2168,7 @@ export declare const METRIC_REGISTRY: {
         interpretation: string;
         caveats: string[];
         sourceChannels: "pointer_click"[];
-        related: ("mesh_interaction_kinds" | "dead_clicks" | "hover_dwell")[];
+        related: ("hover_dwell" | "mesh_interaction_kinds" | "dead_clicks")[];
         comparable: {
             primary: string;
             direction: "down";
@@ -1852,8 +2186,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "mesh";
-        dimensions: ("scene" | "session" | "mesh" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "session" | "source" | "cameraMode")[];
+        grainDimensions: "mesh"[];
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             mesh: z.ZodString;
             dwell_ms: z.ZodNumber;
@@ -1905,8 +2240,19 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "row";
-        dimensions: ("scene" | "session" | "source" | "event_type" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "mesh" | "name" | "session" | "source" | "event_type" | "cameraMode" | "device.engine" | "device.renderer" | "device.browser" | "device.os")[];
+        grainDimensions: ("source" | "event_type")[];
+        genericGroupBy: {
+            eventTypes: ("pointer_move" | "pointer_click" | "pointer_down" | "pointer_up" | "camera_gesture" | "mesh_interaction" | "hover_dwell" | "input_action")[];
+            measures: ({
+                column: string;
+                kind: "count";
+            } | {
+                column: string;
+                kind: "sessions";
+            })[];
+        };
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             event_type: z.ZodString;
             source: z.ZodString;
@@ -1958,8 +2304,17 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "row";
-        dimensions: ("scene" | "session" | "name" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "name" | "session" | "source" | "cameraMode" | "device.engine" | "device.renderer" | "device.browser" | "device.os")[];
+        grainDimensions: ("name" | "source")[];
+        genericGroupBy: {
+            eventTypes: "input_action"[];
+            scope: "hasName"[];
+            measures: {
+                column: string;
+                kind: "count";
+            }[];
+        };
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             action: z.ZodString;
             source: z.ZodString;
@@ -1996,6 +2351,61 @@ export declare const METRIC_REGISTRY: {
         };
         category: "interaction";
     };
+    custom_event_vocabulary: {
+        id: "custom_event_vocabulary";
+        title: string;
+        description: string;
+        builder: "buildCustomEventVocabulary";
+        endpoint: {
+            method: "GET";
+            path: string;
+        };
+        grain: "row";
+        dimensions: ("scene" | "name")[];
+        grainDimensions: "name"[];
+        filters: ("scene" | "format" | "since" | "until" | "limit")[];
+        row: z.ZodObject<{
+            name: z.ZodString;
+            count: z.ZodNumber;
+            sessions: z.ZodNumber;
+            props: z.ZodRecord<z.ZodString, z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                null: "null";
+                mixed: "mixed";
+            }>>;
+        }, z.core.$strip>;
+        columns: {
+            name: {
+                description: string;
+                unit: "label";
+                label: true;
+            };
+            count: {
+                description: string;
+                unit: "count";
+                measure: true;
+            };
+            sessions: {
+                description: string;
+                unit: "sessions";
+            };
+            props: {
+                description: string;
+                unit: "label";
+            };
+        };
+        limits: {
+            maxRows: number;
+            maxSummaryRows: number;
+        };
+        interpretation: string;
+        caveats: string[];
+        sourceChannels: "custom"[];
+        related: ("event_counts" | "funnel" | "variant_leaderboard")[];
+        category: "interaction";
+    };
     camera_gestures: {
         id: "camera_gestures";
         title: string;
@@ -2006,8 +2416,29 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "row";
-        dimensions: ("scene" | "session" | "name" | "source" | "cameraMode")[];
-        filters: ("scene" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "name" | "session" | "source" | "cameraMode" | "device.engine" | "device.renderer" | "device.browser" | "device.os")[];
+        grainDimensions: "name"[];
+        genericGroupBy: {
+            eventTypes: "camera_gesture"[];
+            measures: ({
+                column: string;
+                kind: "count";
+                of?: undefined;
+            } | {
+                column: string;
+                kind: "sum";
+                of: string;
+            } | {
+                column: string;
+                kind: "avg";
+                of: string;
+            } | {
+                column: string;
+                kind: "max";
+                of: string;
+            })[];
+        };
+        filters: ("scene" | "format" | "session" | "source" | "cameraMode" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             kind: z.ZodString;
             gestures: z.ZodNumber;
@@ -2065,7 +2496,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "limit" | "moveThreshold" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "limit" | "moveThreshold")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             segments: z.ZodNumber;
@@ -2124,7 +2556,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "scene";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "limit" | "cellSize" | "format")[];
+        grainDimensions: "scene"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             scene: z.ZodString;
             sessions: z.ZodNumber;
@@ -2183,7 +2616,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: "session"[];
-        filters: ("session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             samples: z.ZodNumber;
             avg_fps: z.ZodNullable<z.ZodNumber>;
@@ -2235,7 +2669,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: "session"[];
-        filters: ("session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             samples: z.ZodNumber;
             avg_fps: z.ZodNullable<z.ZodNumber>;
@@ -2303,7 +2738,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             sessions: z.ZodNumber;
             samples: z.ZodNullable<z.ZodNumber>;
@@ -2360,7 +2796,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "bucket" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit" | "bucket")[];
         row: z.ZodObject<{
             bucket: z.ZodNumber;
             sessions: z.ZodNumber;
@@ -2404,7 +2841,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             sessions: z.ZodNumber;
             samples: z.ZodNullable<z.ZodNumber>;
@@ -2456,7 +2894,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             sessions: z.ZodNumber;
             total_long_frames: z.ZodNullable<z.ZodNumber>;
@@ -2508,7 +2947,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "windowMs" | "fpsThreshold" | "stallMs" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit" | "windowMs" | "fpsThreshold" | "stallMs")[];
         row: z.ZodObject<{
             sessions: z.ZodNumber;
             churn_sessions: z.ZodNumber;
@@ -2561,7 +3001,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "session" | "device.engine" | "device.renderer" | "device.isMobile" | "device.browser" | "device.os")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: ("device.engine" | "device.renderer" | "device.isMobile" | "device.browser" | "device.os")[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             engine: z.ZodString;
             is_mobile: z.ZodString;
@@ -2634,7 +3075,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "scene";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: "scene"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             scene_id: z.ZodString;
             sessions: z.ZodNumber;
@@ -2687,7 +3129,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "voxel";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "limit" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             vx: z.ZodNumber;
             vy: z.ZodNumber;
@@ -2746,6 +3189,7 @@ export declare const METRIC_REGISTRY: {
         builder: "buildPerfDaily";
         grain: "bucket";
         dimensions: never[];
+        grainDimensions: never[];
         filters: never[];
         row: z.ZodObject<{
             day: z.ZodString;
@@ -2804,8 +3248,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "row";
-        dimensions: ("scene" | "session" | "name")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "name" | "session")[];
+        grainDimensions: "name"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             phase: z.ZodString;
             stalls: z.ZodNumber;
@@ -2863,7 +3308,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: "session"[];
-        filters: ("session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             samples: z.ZodNumber;
             avg_js_heap_bytes: z.ZodNullable<z.ZodNumber>;
@@ -2950,7 +3396,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             sessions: z.ZodNumber;
             samples: z.ZodNullable<z.ZodNumber>;
@@ -3022,7 +3469,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             context_losses: z.ZodNumber;
             compile_stalls: z.ZodNumber;
@@ -3069,7 +3517,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             severity: z.ZodString;
             category: z.ZodString;
@@ -3122,7 +3571,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "voxel";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "region" | "limit" | "cellSize" | "severity" | "category" | "errorKind" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "region" | "limit" | "cellSize" | "severity" | "category" | "errorKind")[];
         row: z.ZodObject<{
             vx: z.ZodNumber;
             vy: z.ZodNumber;
@@ -3175,7 +3625,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             api: z.ZodString;
             backend: z.ZodString;
@@ -3232,8 +3683,9 @@ export declare const METRIC_REGISTRY: {
             path: string;
         };
         grain: "row";
-        dimensions: ("scene" | "session" | "name")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        dimensions: ("scene" | "name" | "session")[];
+        grainDimensions: "name"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             kind: z.ZodString;
             from: z.ZodString;
@@ -3286,7 +3738,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "limit" | "rapidTurn" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "limit" | "rapidTurn")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             samples: z.ZodNumber;
@@ -3350,7 +3803,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "session" | "source")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: "source"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             source: z.ZodString;
             interactions: z.ZodNumber;
@@ -3398,7 +3852,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             events: z.ZodNumber;
@@ -3456,7 +3911,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             fly_gestures: z.ZodNumber;
@@ -3524,7 +3980,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: ("scene" | "session" | "source")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             degraded_ms: z.ZodNumber;
@@ -3592,7 +4049,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "voxel";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "region" | "limit" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "region" | "limit" | "cellSize")[];
         row: z.ZodObject<{
             vx: z.ZodNumber;
             vy: z.ZodNumber;
@@ -3645,7 +4103,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "project";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "region" | "cellSize" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "region" | "cellSize")[];
         row: z.ZodObject<{
             cells: z.ZodNumber;
             hits: z.ZodNumber;
@@ -3682,7 +4141,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "session";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: "session"[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             session_id: z.ZodString;
             contacts: z.ZodNumber;
@@ -3730,7 +4190,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "bucketMs" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit" | "bucketMs")[];
         row: z.ZodObject<{
             bucket: z.ZodNumber;
             placements: z.ZodNumber;
@@ -3774,7 +4235,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             attempts: z.ZodNumber;
             placements: z.ZodNumber;
@@ -3818,7 +4280,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "session")[];
-        filters: ("scene" | "session" | "since" | "until" | "bins" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "session" | "since" | "until" | "bins" | "limit")[];
         row: z.ZodObject<{
             surface: z.ZodString;
             placements: z.ZodNumber;
@@ -3866,7 +4329,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: ("scene" | "cameraMode")[];
-        filters: ("scene" | "cameraMode" | "since" | "until" | "steps" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "cameraMode" | "since" | "until" | "steps")[];
         row: z.ZodObject<{
             step: z.ZodNumber;
             sessions: z.ZodNumber;
@@ -3910,7 +4374,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: "scene"[];
-        filters: ("since" | "until" | "limit" | "format")[];
+        grainDimensions: never[];
+        filters: ("format" | "since" | "until" | "limit")[];
         row: z.ZodObject<{
             from_scene: z.ZodString;
             to_scene: z.ZodString;
@@ -3958,7 +4423,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "bucket";
         dimensions: "scene"[];
-        filters: ("scene" | "since" | "until" | "bands" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "since" | "until" | "bands")[];
         row: z.ZodObject<{
             band: z.ZodNumber;
             sessions: z.ZodNumber;
@@ -4008,7 +4474,8 @@ export declare const METRIC_REGISTRY: {
         };
         grain: "row";
         dimensions: ("scene" | "name" | "cameraMode")[];
-        filters: ("scene" | "cameraMode" | "since" | "until" | "limit" | "variant" | "conversion" | "format")[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "cameraMode" | "since" | "until" | "limit" | "variant" | "conversion")[];
         row: z.ZodObject<{
             variant: z.ZodString;
             views: z.ZodNumber;
@@ -4056,6 +4523,378 @@ export declare const METRIC_REGISTRY: {
         };
         category: "conversion";
     };
+    insight_baseline: {
+        id: "insight_baseline";
+        title: string;
+        description: string;
+        derived: "insight";
+        endpoint: {
+            method: "GET";
+            path: string;
+        };
+        grain: "project";
+        dimensions: "scene"[];
+        grainDimensions: "scene"[];
+        filters: ("scene" | "format" | "since" | "until" | "bucket" | "metric" | "window")[];
+        row: z.ZodObject<{
+            metric: z.ZodString;
+            scene: z.ZodString;
+            sampleSize: z.ZodNumber;
+            buckets: z.ZodNumber;
+            mean: z.ZodNullable<z.ZodNumber>;
+            median: z.ZodNullable<z.ZodNumber>;
+            mad: z.ZodNullable<z.ZodNumber>;
+            p10: z.ZodNullable<z.ZodNumber>;
+            p90: z.ZodNullable<z.ZodNumber>;
+            slope: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        columns: {
+            metric: {
+                description: string;
+                unit: "id";
+            };
+            scene: {
+                description: string;
+                unit: "id";
+            };
+            sampleSize: {
+                description: string;
+                unit: "count";
+            };
+            buckets: {
+                description: string;
+                unit: "count";
+            };
+            mean: {
+                description: string;
+            };
+            median: {
+                description: string;
+                measure: true;
+            };
+            mad: {
+                description: string;
+            };
+            p10: {
+                description: string;
+            };
+            p90: {
+                description: string;
+            };
+            slope: {
+                description: string;
+            };
+        };
+        limits: {
+            maxRows: number;
+            maxSummaryRows: number;
+        };
+        interpretation: string;
+        caveats: string[];
+        sourceChannels: never[];
+        related: ("perf_summary" | "timeseries" | "events_daily" | "insight_movers")[];
+        category: "insights";
+    };
+    insight_movers: {
+        id: "insight_movers";
+        title: string;
+        description: string;
+        derived: "insight";
+        endpoint: {
+            method: "GET";
+            path: string;
+        };
+        grain: "row";
+        dimensions: "scene"[];
+        grainDimensions: never[];
+        filters: ("scene" | "format" | "since" | "until" | "limit" | "bucket" | "metrics" | "refSince" | "refUntil")[];
+        row: z.ZodObject<{
+            metric: z.ZodString;
+            dimensionValue: z.ZodNullable<z.ZodString>;
+            current: z.ZodNullable<z.ZodNumber>;
+            previous: z.ZodNullable<z.ZodNumber>;
+            delta: z.ZodNullable<z.ZodNumber>;
+            deltaPct: z.ZodNullable<z.ZodNumber>;
+            z: z.ZodNullable<z.ZodNumber>;
+            direction: z.ZodString;
+            aboveMinSample: z.ZodBoolean;
+            sampleSize: z.ZodNumber;
+        }, z.core.$strip>;
+        columns: {
+            metric: {
+                description: string;
+                unit: "id";
+                label: true;
+            };
+            dimensionValue: {
+                description: string;
+                unit: "id";
+            };
+            current: {
+                description: string;
+            };
+            previous: {
+                description: string;
+            };
+            delta: {
+                description: string;
+            };
+            deltaPct: {
+                description: string;
+                unit: "ratio";
+            };
+            z: {
+                description: string;
+                unit: "ratio";
+                measure: true;
+            };
+            direction: {
+                description: string;
+                unit: "label";
+            };
+            aboveMinSample: {
+                description: string;
+            };
+            sampleSize: {
+                description: string;
+            };
+        };
+        limits: {
+            maxRows: number;
+            maxSummaryRows: number;
+        };
+        interpretation: string;
+        caveats: string[];
+        sourceChannels: never[];
+        related: ("event_counts" | "perf_daily" | "events_daily" | "insight_baseline")[];
+        category: "insights";
+    };
+    insight_anomalies: {
+        id: "insight_anomalies";
+        title: string;
+        description: string;
+        derived: "insight";
+        endpoint: {
+            method: "GET";
+            path: string;
+        };
+        grain: "row";
+        dimensions: "scene"[];
+        grainDimensions: "scene"[];
+        filters: ("scene" | "format" | "since" | "until" | "bucket" | "metric" | "window" | "sensitivity")[];
+        row: z.ZodObject<{
+            metric: z.ZodString;
+            scene: z.ZodString;
+            bucketStart: z.ZodNumber;
+            value: z.ZodNullable<z.ZodNumber>;
+            expected: z.ZodNullable<z.ZodNumber>;
+            z: z.ZodNullable<z.ZodNumber>;
+            kind: z.ZodString;
+            contributor: z.ZodNullable<z.ZodObject<{
+                dimension: z.ZodString;
+                value: z.ZodString;
+                share: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+            sampleSize: z.ZodNumber;
+        }, z.core.$strip>;
+        columns: {
+            metric: {
+                description: string;
+                unit: "id";
+                label: true;
+            };
+            scene: {
+                description: string;
+                unit: "id";
+            };
+            bucketStart: {
+                description: string;
+                unit: "timestamp";
+            };
+            value: {
+                description: string;
+            };
+            expected: {
+                description: string;
+            };
+            z: {
+                description: string;
+                unit: "ratio";
+                measure: true;
+            };
+            kind: {
+                description: string;
+                unit: "label";
+            };
+            contributor: {
+                description: string;
+            };
+            sampleSize: {
+                description: string;
+                unit: "count";
+            };
+        };
+        limits: {
+            maxRows: number;
+            maxSummaryRows: number;
+        };
+        interpretation: string;
+        caveats: string[];
+        sourceChannels: never[];
+        related: ("timeseries" | "error_heatmap" | "insight_baseline" | "insight_movers")[];
+        category: "insights";
+    };
+    insight_significance: {
+        id: "insight_significance";
+        title: string;
+        description: string;
+        derived: "insight";
+        endpoint: {
+            method: "GET";
+            path: string;
+        };
+        grain: "project";
+        dimensions: "scene"[];
+        grainDimensions: "scene"[];
+        filters: ("scene" | "format" | "since" | "until" | "bucket" | "metric" | "refSince" | "refUntil")[];
+        row: z.ZodObject<{
+            metric: z.ZodString;
+            scene: z.ZodString;
+            a: z.ZodObject<{
+                value: z.ZodNullable<z.ZodNumber>;
+                n: z.ZodNumber;
+            }, z.core.$strip>;
+            b: z.ZodObject<{
+                value: z.ZodNullable<z.ZodNumber>;
+                n: z.ZodNumber;
+            }, z.core.$strip>;
+            effect: z.ZodNullable<z.ZodNumber>;
+            ci95: z.ZodTuple<[z.ZodNullable<z.ZodNumber>, z.ZodNullable<z.ZodNumber>], null>;
+            p: z.ZodNullable<z.ZodNumber>;
+            test: z.ZodString;
+            effectUnit: z.ZodString;
+            significant: z.ZodBoolean;
+            powerNote: z.ZodString;
+        }, z.core.$strip>;
+        columns: {
+            metric: {
+                description: string;
+                unit: "id";
+                label: true;
+            };
+            scene: {
+                description: string;
+                unit: "id";
+            };
+            a: {
+                description: string;
+            };
+            b: {
+                description: string;
+            };
+            effect: {
+                description: string;
+                measure: true;
+            };
+            ci95: {
+                description: string;
+            };
+            p: {
+                description: string;
+                unit: "ratio";
+            };
+            test: {
+                description: string;
+                unit: "label";
+            };
+            effectUnit: {
+                description: string;
+                unit: "label";
+            };
+            significant: {
+                description: string;
+            };
+            powerNote: {
+                description: string;
+                unit: "label";
+            };
+        };
+        limits: {
+            maxRows: number;
+            maxSummaryRows: number;
+        };
+        interpretation: string;
+        caveats: string[];
+        sourceChannels: never[];
+        related: ("insight_baseline" | "insight_movers" | "insight_scene_health")[];
+        category: "insights";
+    };
+    insight_scene_health: {
+        id: "insight_scene_health";
+        title: string;
+        description: string;
+        derived: "insight";
+        endpoint: {
+            method: "GET";
+            path: string;
+        };
+        grain: "scene";
+        dimensions: "scene"[];
+        grainDimensions: "scene"[];
+        filters: ("scene" | "format" | "since" | "until" | "limit" | "bucket" | "window" | "weights")[];
+        row: z.ZodObject<{
+            scene: z.ZodString;
+            score: z.ZodNullable<z.ZodNumber>;
+            factors: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                metric: z.ZodString;
+                raw: z.ZodNullable<z.ZodNumber>;
+                baseline: z.ZodNullable<z.ZodNumber>;
+                score: z.ZodNullable<z.ZodNumber>;
+                weight: z.ZodNumber;
+                unit: z.ZodString;
+                note: z.ZodString;
+            }, z.core.$strip>>;
+            sampleSize: z.ZodNumber;
+            since: z.ZodNumber;
+            until: z.ZodNumber;
+        }, z.core.$strip>;
+        columns: {
+            scene: {
+                description: string;
+                unit: "id";
+                label: true;
+            };
+            score: {
+                description: string;
+                measure: true;
+            };
+            factors: {
+                description: string;
+            };
+            sampleSize: {
+                description: string;
+                unit: "sessions";
+            };
+            since: {
+                description: string;
+                unit: "epoch-ms";
+            };
+            until: {
+                description: string;
+                unit: "epoch-ms";
+            };
+        };
+        limits: {
+            maxRows: number;
+            maxSummaryRows: number;
+        };
+        interpretation: string;
+        caveats: string[];
+        sourceChannels: never[];
+        related: ("insight_baseline" | "insight_movers" | "insight_significance")[];
+        category: "insights";
+    };
 };
 /** The registry's own type, with each entry's literal `builder` preserved. */
 export type MetricRegistry = typeof METRIC_REGISTRY;
@@ -4115,5 +4954,16 @@ export declare function metricForBuilder(builder: AggregationBuilderName): Metri
  * catalog stays a superset of the hand-written one (design sketch §A.4).
  */
 export declare function isResourceMetric(metric: MetricDefinition): boolean;
+/**
+ * A **derived** entry is computed in TypeScript over another metric's data
+ * rather than by a `build*` aggregation (ADR 0051 §4): the insight primitives.
+ * It has no builder, but — unlike a {@link isResourceMetric resource} — it is a
+ * real aggregate with a querystring, a time range and the `format` envelope, so
+ * every consumer that treats `builder != null` as "is an aggregate" should ask
+ * this instead.
+ */
+export declare function isDerivedMetric(metric: MetricDefinition): boolean;
+/** Whether a metric is served as an aggregate over a querystring (not a resource read). */
+export declare function isAggregateMetric(metric: MetricDefinition): boolean;
 export {};
 //# sourceMappingURL=registry.d.ts.map