@uptimizr/metrics 0.1.0 → 0.2.0

package/dist/registry.js

@@ -35,6 +35,7 @@
  * the Zod querystring that actually serves it.
  */
 import { z } from "zod";
+import { NARRATIVE_LIMITS, sessionNarrativeEntrySchema } from "./narrative.js";
 /**
  * Every exported `build*` aggregation name in `@uptimizr/db`'s
  * `query/aggregations.ts`. The registry must cover them all.
@@ -64,6 +65,7 @@ export const AGGREGATION_BUILDER_NAMES = [
     "buildCapabilityChanges",
     "buildClickGazeRay",
     "buildCompileStalls",
+    "buildCustomEventVocabulary",
     "buildDeadClicks",
     "buildDistinctScenes",
     "buildErrorHeatmap",
@@ -134,6 +136,65 @@ export const DIMENSION_COLUMNS = {
     "device.browser": "session_start.payload.device.browser (derived from the UA, ADR 0042)",
     "device.os": "session_start.payload.device.os (derived from the UA, ADR 0042)",
 };
+/**
+ * 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 const DIMENSION_ROW_COLUMNS = {
+    scene: ["scene_id", "scene"],
+    session: ["session_id"],
+    mesh: ["mesh"],
+    name: ["name", "kind", "action", "phase"],
+    source: ["source"],
+    event_type: ["event_type"],
+    cameraMode: [],
+    "device.engine": ["engine"],
+    "device.renderer": ["renderer"],
+    "device.isMobile": ["is_mobile"],
+    "device.browser": ["browser"],
+    "device.os": ["os"],
+};
+/**
+ * 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 const GENERIC_DIMENSIONS = [
+    "scene",
+    "session",
+    "mesh",
+    "name",
+    "source",
+    "event_type",
+    "cameraMode",
+    "device.engine",
+    "device.renderer",
+    "device.browser",
+    "device.os",
+];
 /**
  * The single mapping from a request parameter to the option field it drives.
  * Consumers (docs generator, OpenAPI, the DSL) read filter semantics here rather
@@ -208,7 +269,8 @@ export const FILTER_TARGETS = {
     bucket: {
         option: "BuilderOptions",
         field: "bucket",
-        description: "Histogram bin width in FPS.",
+        description: "Bucket width. On `fps_histogram` a histogram bin width in FPS; on the insight " +
+            "primitives the time grain of the series, `day` or `hour`.",
     },
     bucketMs: {
         option: "BuilderOptions",
@@ -310,6 +372,62 @@ export const FILTER_TARGETS = {
         field: "conversion",
         description: "JSON funnel-step predicate for the success event. Omit to report views only.",
     },
+    minDwellMs: {
+        option: "SessionNarrativeOptions",
+        field: "minDwellMs",
+        description: "Session narrative only: a mesh must hold attention for at least this many milliseconds " +
+            "before it earns a `dwell` entry. Raise it to keep only the meshes that were really looked at.",
+    },
+    maxEntries: {
+        option: "SessionNarrativeOptions",
+        field: "maxEntries",
+        description: "Session narrative only: the maximum number of entries, oldest first. The closing `summary` " +
+            "entry always survives and reports whether anything was dropped.",
+    },
+    metric: {
+        option: "InsightOptions",
+        field: "metric",
+        description: "The registry metric the insight is computed over. Must be a `comparable` metric that has a " +
+            "portable bucket series; a metric without one is rejected with the list of ids that do.",
+    },
+    metrics: {
+        option: "InsightOptions",
+        field: "metrics",
+        description: "Comma-separated allowlist of registry metric ids to scan instead of the curated default " +
+            "set. Bounded by the per-request metric cap the registry `limits` declare.",
+    },
+    window: {
+        option: "InsightOptions",
+        field: "windowDays",
+        description: "Length of the baseline window in days, counted back from `until`. Ignored when `since` is " +
+            "given explicitly.",
+    },
+    refSince: {
+        option: "InsightOptions",
+        field: "refSince",
+        description: "Inclusive lower bound of the reference window a change is measured against, epoch " +
+            "milliseconds. Defaults to the equal-length window immediately before the current range.",
+    },
+    refUntil: {
+        option: "InsightOptions",
+        field: "refUntil",
+        description: "Exclusive upper bound of the reference window, epoch milliseconds. Defaults to `since`.",
+    },
+    // --- anomalies (#306) ---
+    sensitivity: {
+        option: "InsightOptions",
+        field: "sensitivity",
+        description: "How far out of line a bucket must be before it is reported, in median-absolute-deviations " +
+            "of the trailing window. Higher means fewer, more extreme findings. 1-10, default 3.",
+    },
+    // --- significance / scene health (#307) ---
+    weights: {
+        option: "InsightOptions",
+        field: "weights",
+        description: "JSON object overriding the declared per-factor weights of a composite score, e.g. " +
+            '`{"error_rate":0.5}`. Factors the object does not name keep their declared weight; an ' +
+            "unknown factor id is rejected rather than ignored.",
+    },
     format: {
         option: "ResultEnvelope",
         field: "(response layer)",
@@ -318,6 +436,15 @@ export const FILTER_TARGETS = {
             "or a trend, with shares, a sample size, a templated reading and the caveats).",
     },
 };
+/**
+ * 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 function metricCapability(metric) {
+    return metric.endpoint?.capability ?? "query";
+}
 // --- Row-schema building blocks ------------------------------------------
 //
 // Numeric columns are **strict** `z.number()`: they describe what the collector
@@ -421,6 +548,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/sessions" },
         grain: "session",
         dimensions: ["session"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "bins", "limit", "cameraMode", "format"],
         row: z.object({
             session_id: text,
@@ -467,6 +595,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/sessions/:id/meta", pathParams: ["session"] },
         grain: "session",
         dimensions: ["session"],
+        grainDimensions: [],
         filters: [],
         row: z.object({
             sessionId: text,
@@ -500,6 +629,91 @@ export const METRIC_REGISTRY = {
         related: ["list_sessions", "perf_by_device"],
         category: "sessions",
     },
+    session_narrative: {
+        id: "session_narrative",
+        title: "Session narrative",
+        description: "An ordered, compacted account of what one session did — scene changes, the meshes it " +
+            "dwelled on, its interactions, performance dips, errors and how it ended — timestamps " +
+            "relative to its first event, plus a closing totals entry. A compaction of the raw " +
+            "per-session stream, gated on `query:raw` and raw-session retention (ADR 0003).",
+        endpoint: {
+            method: "GET",
+            path: "/api/v1/sessions/:id/narrative",
+            pathParams: ["session"],
+            capability: "query:raw",
+        },
+        grain: "row",
+        dimensions: ["session"],
+        // A narrative entry is not keyed by the session: the session is the *scope*,
+        // named in the path, and no row column projects it (cf. `session_meta`).
+        grainDimensions: [],
+        filters: ["minDwellMs", "fpsThreshold", "maxEntries", "format"],
+        row: sessionNarrativeEntrySchema,
+        columns: {
+            tMs: {
+                description: "Milliseconds since the session's first event. Relative by design — a narrative never carries a wall-clock time.",
+                unit: "ms",
+            },
+            kind: {
+                description: "What the entry is about: scene / dwell / interaction / perf_dip / error / diagnostic / capability / xr / end / summary.",
+                unit: "label",
+                label: true,
+            },
+            summary: {
+                description: "One templated line of prose, composed from the entry's own fields — never free text copied out of an event payload.",
+            },
+            refs: {
+                description: "The named things the entry points at: `mesh`, `scene` and `name` (a custom-event or input-action name). Nothing else is ever referenced.",
+            },
+            durationMs: {
+                description: "How long the entry spans, for the kinds that cover a stretch of time.",
+                unit: "ms",
+            },
+            count: {
+                description: "How many source events the entry collapses (dwell samples, dip frames, …).",
+                unit: "count",
+            },
+            totals: {
+                description: "Session totals (events, duration, scenes, meshes, interactions, dips, errors). Present on the closing `summary` entry only.",
+            },
+            truncated: {
+                description: "Whether entries were dropped to honour `maxEntries`. Present on the closing `summary` entry only.",
+            },
+        },
+        limits: {
+            maxRows: NARRATIVE_LIMITS.maxMaxEntries,
+            maxSummaryRows: NARRATIVE_LIMITS.defaultMaxEntries,
+        },
+        interpretation: "Read it top to bottom as a story: where the session went, what held its attention, what it " +
+            "touched, and what went wrong. The closing `summary` entry gives the totals and says whether " +
+            "anything was dropped — if `truncated` is true, raise `minDwellMs` or `maxEntries` rather " +
+            "than trusting the tail.",
+        caveats: [
+            "Refused with 403 unless the collector has `ENABLE_RAW_SESSION_RETENTION` enabled AND the key holds `query:raw` (ADR 0003).",
+            "Returns 404 when the session id is unknown to the project, or when retention was enabled only after it was recorded.",
+            "A projection, not the raw stream: no visitor hash, no URL or page metadata, no positions or rays, and no `device` detail. Custom-event property **keys** are listed; their values never are.",
+            "Dwell comes from the sampled `mesh_visibility` / `hover_dwell` channels (ADR 0012), so it ranks attention rather than measuring it exactly.",
+            "Not an aggregation — there is no `build*` builder, and it takes no time range.",
+        ],
+        sourceChannels: [
+            "session_start",
+            "session_end",
+            "scene_change",
+            "mesh_visibility",
+            "hover_dwell",
+            "mesh_interaction",
+            "pointer_click",
+            "input_action",
+            "custom",
+            "frame_perf",
+            "runtime_error",
+            "graphics_diagnostic",
+            "capability_change",
+            "xr_boundary_proximity",
+        ],
+        related: ["session_meta", "list_sessions", "session_trajectory"],
+        category: "sessions",
+    },
     scene_representation: {
         id: "scene_representation",
         title: "Scene representation",
@@ -513,6 +727,7 @@ export const METRIC_REGISTRY = {
         },
         grain: "scene",
         dimensions: ["scene"],
+        grainDimensions: [],
         filters: [],
         row: z.object({
             projectId: text,
@@ -578,6 +793,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/scenes" },
         grain: "scene",
         dimensions: ["scene"],
+        grainDimensions: ["scene"],
         filters: ["since", "until", "limit", "format"],
         row: z.object({ scene_id: text, events: int, last_seen: ts }),
         columns: {
@@ -611,8 +827,9 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/timeseries" },
         grain: "bucket",
         dimensions: ["scene", "event_type"],
+        grainDimensions: [],
         filters: ["since", "until", "interval", "scene", "type", "format"],
-        row: z.object({ bucket: int, events: int, avg_fps: num }),
+        row: z.object({ bucket: int, events: int, avg_fps: numOrNull }),
         columns: {
             bucket: {
                 description: "Bucket start as epoch milliseconds.",
@@ -622,13 +839,15 @@ export const METRIC_REGISTRY = {
             },
             events: { description: "Events in the bucket.", unit: "count", measure: true },
             avg_fps: {
-                description: "Mean FPS of the `frame_perf` samples in the bucket; `0` when there were none.",
+                description: "Mean FPS of the `frame_perf` samples in the bucket; `null` when the bucket had " +
+                    "none — an average over no samples is absent, never zero.",
                 unit: "fps",
             },
         },
         limits: { maxRows: 1000, maxSummaryRows: 8 },
-        interpretation: "Read it as a trend, not a level. A bucket with no `frame_perf` samples reports `avg_fps` 0, " +
-            "so treat a zero as 'no perf data', never as a stall.",
+        interpretation: "Read it as a trend, not a level. A bucket with no `frame_perf` samples reports `avg_fps` " +
+            "`null` — traffic the engine never sampled perf for, not a stall. A `0` means the samples " +
+            "really did average zero.",
         caveats: [
             "Buckets are fixed width; a range shorter than one `interval` collapses to a single bucket.",
             "Volume scales with the capture fidelity dial (ADR 0012) — a rise can be a sampling change rather than traffic.",
@@ -648,7 +867,26 @@ export const METRIC_REGISTRY = {
         builder: "buildEventTypeCounts",
         endpoint: { method: "GET", path: "/api/v1/event-counts" },
         grain: "row",
-        dimensions: ["event_type", "scene"],
+        dimensions: [
+            "event_type",
+            "scene",
+            "session",
+            "source",
+            "mesh",
+            "name",
+            "cameraMode",
+            "device.os",
+            "device.browser",
+            "device.engine",
+            "device.renderer",
+        ],
+        grainDimensions: ["event_type"],
+        genericGroupBy: {
+            // The whole stream: this metric's subject *is* every event, so no
+            // `eventTypes` narrowing and no scope predicate.
+            eventTypes: [],
+            measures: [{ column: "count", kind: "count" }],
+        },
         filters: ["since", "until", "scene", "format"],
         row: z.object({ event_type: text, count: int }),
         columns: {
@@ -681,6 +919,7 @@ export const METRIC_REGISTRY = {
         builder: "buildEventsDaily",
         grain: "bucket",
         dimensions: ["event_type"],
+        grainDimensions: ["event_type"],
         filters: [],
         row: z.object({ day: day, event_type: text, events: int }),
         columns: {
@@ -719,6 +958,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/pointer" },
         grain: "bin",
         dimensions: ["scene", "session", "source", "cameraMode"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -760,6 +1000,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/mesh-uv" },
         grain: "bin",
         dimensions: ["scene", "session", "source", "mesh"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "source", "mesh", "format"],
         row: heatmapBinRow,
         columns: {
@@ -790,6 +1031,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/world" },
         grain: "voxel",
         dimensions: ["scene", "source", "cameraMode"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -827,6 +1069,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/world/stats" },
         grain: "project",
         dimensions: ["scene", "source", "cameraMode"],
+        grainDimensions: [],
         filters: ["since", "until", "cellSize", "scene", "source", "cameraMode", "region", "format"],
         row: spatialStatsRow,
         columns: {
@@ -858,6 +1101,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/gaze" },
         grain: "voxel",
         dimensions: ["scene", "session", "cameraMode"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -900,6 +1144,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/gaze/stats" },
         grain: "project",
         dimensions: ["scene", "session", "cameraMode"],
+        grainDimensions: [],
         filters: ["since", "until", "cellSize", "scene", "session", "cameraMode", "region", "format"],
         row: spatialStatsRow,
         columns: {
@@ -931,6 +1176,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/camera" },
         grain: "bin",
         dimensions: ["scene", "session", "cameraMode"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "cameraMode", "format"],
         row: z.object({ azimuth_bin: int, elevation_bin: int, count: int }),
         columns: {
@@ -968,6 +1214,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/coverage/view-histogram" },
         grain: "bucket",
         dimensions: ["scene", "session", "cameraMode"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "cameraMode", "format"],
         row: z.object({ bucket: int, sessions: int }),
         columns: {
@@ -1007,6 +1254,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/position" },
         grain: "bin",
         dimensions: ["scene", "session", "cameraMode"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -1052,6 +1300,7 @@ export const METRIC_REGISTRY = {
         },
         grain: "row",
         dimensions: ["session", "scene"],
+        grainDimensions: [],
         filters: ["since", "until", "limit", "scene", "format"],
         row: z.object({ ts: int, x: num, y: num, z: num }),
         columns: {
@@ -1086,6 +1335,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/paths" },
         grain: "row",
         dimensions: ["session", "scene", "cameraMode"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "cellSize", "limit", "scene", "cameraMode", "format"],
         row: z.object({ session_id: text, ts: int, gx: int, gz: int }),
         columns: {
@@ -1120,6 +1370,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/coverage" },
         grain: "voxel",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "cellSize", "limit", "scene", "session", "format"],
         row: voxelCountRow,
         columns: {
@@ -1152,6 +1403,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/camera/distance" },
         grain: "bucket",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -1196,6 +1448,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/click-rays" },
         grain: "voxel",
         dimensions: ["scene", "session", "source", "mesh"],
+        grainDimensions: ["mesh"],
         filters: ["since", "until", "cellSize", "limit", "scene", "source", "session", "format"],
         row: z.object({
             cam_vx: int,
@@ -1254,6 +1507,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/flow" },
         grain: "bin",
         dimensions: ["scene", "session", "mesh", "cameraMode"],
+        grainDimensions: ["mesh"],
         filters: [
             "since",
             "until",
@@ -1334,7 +1588,26 @@ export const METRIC_REGISTRY = {
         builder: "buildTopMeshes",
         endpoint: { method: "GET", path: "/api/v1/meshes/top" },
         grain: "mesh",
-        dimensions: ["mesh", "session"],
+        dimensions: [
+            "mesh",
+            "session",
+            "scene",
+            "source",
+            "event_type",
+            "cameraMode",
+            "device.os",
+            "device.browser",
+            "device.engine",
+            "device.renderer",
+        ],
+        grainDimensions: ["mesh"],
+        genericGroupBy: {
+            // Every mesh-referencing event, gaze included — the same population the
+            // canned builder counts, which is why `hasMesh` is not optional here.
+            eventTypes: [],
+            scope: ["hasMesh"],
+            measures: [{ column: "count", kind: "count" }],
+        },
         filters: ["since", "until", "bins", "limit", "session", "format"],
         row: z.object({ mesh: text, count: int }),
         columns: {
@@ -1365,7 +1638,25 @@ export const METRIC_REGISTRY = {
         builder: "buildTopMeshesBySource",
         endpoint: { method: "GET", path: "/api/v1/meshes/sources" },
         grain: "mesh",
-        dimensions: ["mesh", "source", "scene", "session", "cameraMode"],
+        dimensions: [
+            "mesh",
+            "source",
+            "scene",
+            "session",
+            "cameraMode",
+            "name",
+            "event_type",
+            "device.os",
+            "device.browser",
+            "device.engine",
+            "device.renderer",
+        ],
+        grainDimensions: ["mesh", "source"],
+        genericGroupBy: {
+            eventTypes: ["mesh_interaction", "pointer_click"],
+            scope: ["hasMesh"],
+            measures: [{ column: "count", kind: "count" }],
+        },
         filters: [
             "since",
             "until",
@@ -1407,6 +1698,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/meshes/trend" },
         grain: "bucket",
         dimensions: ["mesh", "scene", "session", "source", "cameraMode"],
+        grainDimensions: ["mesh"],
         filters: [
             "since",
             "until",
@@ -1449,6 +1741,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/meshes/dwell" },
         grain: "mesh",
         dimensions: ["mesh", "scene", "session"],
+        grainDimensions: ["mesh"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             mesh: text,
@@ -1498,6 +1791,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/meshes/blind-spots" },
         grain: "mesh",
         dimensions: ["mesh", "scene", "session"],
+        grainDimensions: ["mesh"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             mesh: text,
@@ -1542,7 +1836,24 @@ export const METRIC_REGISTRY = {
         builder: "buildMeshInteractionKinds",
         endpoint: { method: "GET", path: "/api/v1/meshes/kinds" },
         grain: "mesh",
-        dimensions: ["mesh", "name", "scene", "session", "source", "cameraMode"],
+        dimensions: [
+            "mesh",
+            "name",
+            "scene",
+            "session",
+            "source",
+            "cameraMode",
+            "device.os",
+            "device.browser",
+            "device.engine",
+            "device.renderer",
+        ],
+        grainDimensions: ["mesh", "name"],
+        genericGroupBy: {
+            eventTypes: ["mesh_interaction"],
+            scope: ["hasMesh"],
+            measures: [{ column: "count", kind: "count" }],
+        },
         filters: [
             "since",
             "until",
@@ -1588,6 +1899,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/meshes/reachability" },
         grain: "mesh",
         dimensions: ["mesh", "scene", "session", "source", "cameraMode"],
+        grainDimensions: ["mesh"],
         filters: [
             "since",
             "until",
@@ -1637,6 +1949,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/clicks/dead" },
         grain: "project",
         dimensions: ["scene", "session", "source", "cameraMode"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -1683,6 +1996,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/clicks/rage" },
         grain: "row",
         dimensions: ["session", "mesh", "scene", "source", "cameraMode"],
+        grainDimensions: ["session", "mesh"],
         filters: [
             "since",
             "until",
@@ -1730,6 +2044,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/hover/dwell" },
         grain: "mesh",
         dimensions: ["mesh", "scene", "session", "source", "cameraMode"],
+        grainDimensions: ["mesh"],
         filters: [
             "since",
             "until",
@@ -1770,7 +2085,38 @@ export const METRIC_REGISTRY = {
         builder: "buildInteractionsBySource",
         endpoint: { method: "GET", path: "/api/v1/interactions/sources" },
         grain: "row",
-        dimensions: ["event_type", "source", "scene", "session", "cameraMode"],
+        dimensions: [
+            "event_type",
+            "source",
+            "scene",
+            "session",
+            "cameraMode",
+            "mesh",
+            "name",
+            "device.os",
+            "device.browser",
+            "device.engine",
+            "device.renderer",
+        ],
+        grainDimensions: ["event_type", "source"],
+        genericGroupBy: {
+            // Exactly the event types the canned builder lists — the events that
+            // carry an input source.
+            eventTypes: [
+                "pointer_move",
+                "pointer_click",
+                "pointer_down",
+                "pointer_up",
+                "mesh_interaction",
+                "hover_dwell",
+                "camera_gesture",
+                "input_action",
+            ],
+            measures: [
+                { column: "count", kind: "count" },
+                { column: "sessions", kind: "sessions" },
+            ],
+        },
         filters: [
             "since",
             "until",
@@ -1810,7 +2156,23 @@ export const METRIC_REGISTRY = {
         builder: "buildTopInputActions",
         endpoint: { method: "GET", path: "/api/v1/input-actions/top" },
         grain: "row",
-        dimensions: ["name", "source", "scene", "session", "cameraMode"],
+        dimensions: [
+            "name",
+            "source",
+            "scene",
+            "session",
+            "cameraMode",
+            "device.os",
+            "device.browser",
+            "device.engine",
+            "device.renderer",
+        ],
+        grainDimensions: ["name", "source"],
+        genericGroupBy: {
+            eventTypes: ["input_action"],
+            scope: ["hasName"],
+            measures: [{ column: "count", kind: "count" }],
+        },
         filters: [
             "since",
             "until",
@@ -1845,6 +2207,60 @@ export const METRIC_REGISTRY = {
         comparable: { primary: "count", direction: "neutral", minSample: 30 },
         category: "interaction",
     },
+    custom_event_vocabulary: {
+        id: "custom_event_vocabulary",
+        title: "Discovered custom-event vocabulary",
+        description: "Which developer-defined `custom` event names the project actually emits, how often, over " +
+            "how many distinct sessions, and the union of `props` keys observed on each name with a " +
+            "coarse type per key (ADR 0051 §5). One row per custom-event name. This is how an agent " +
+            "learns that `add_to_cart` exists and carries `sku` and `qty` — nothing else in the read " +
+            "surface enumerates an application's own event vocabulary.",
+        builder: "buildCustomEventVocabulary",
+        endpoint: { method: "GET", path: "/api/v1/vocabulary/custom-events" },
+        grain: "row",
+        dimensions: ["name", "scene"],
+        // One row per custom-event name; `scene` is a filter, never a key.
+        grainDimensions: ["name"],
+        filters: ["since", "until", "scene", "limit", "format"],
+        row: z.object({
+            name: text,
+            count: int,
+            sessions: int,
+            props: z.record(z.string(), z.enum(["string", "number", "boolean", "null", "mixed"])),
+        }),
+        columns: {
+            name: {
+                description: "Developer-chosen custom-event name, e.g. `add_to_cart`.",
+                unit: "label",
+                label: true,
+            },
+            count: { description: "Times the event fired over the range.", unit: "count", measure: true },
+            sessions: { description: "Distinct sessions that emitted it.", unit: "sessions" },
+            props: {
+                description: "Observed `props` keys mapped to a coarse JSON type (`string` / `number` / `boolean` / " +
+                    "`null` / `mixed`). `mixed` means the key arrived with more than one kind; `null` means " +
+                    "every sampled value was null.",
+                unit: "label",
+            },
+        },
+        limits: { maxRows: 200, maxSummaryRows: 20 },
+        interpretation: "A discovery read, not a KPI: use it to find the real event names and prop keys before " +
+            "filtering or funnelling on them. `count` and `sessions` are exact over the range; `props` " +
+            "is a sample.",
+        caveats: [
+            "`props` is discovered from the 20 most recent events per name, not from the whole range: a " +
+                "key that stopped being emitted long ago will be absent, and a rarely-sent optional key " +
+                "may be missed. Treat it as a vocabulary hint, never as a schema.",
+            "Only prop key names and value kinds are reported — never a prop value (ADR 0003).",
+            "Names are ranked by `count` and capped by `limit`, so a long tail of rare custom events may " +
+                "be truncated.",
+            "An empty result means the project emits no `custom` events over the range, not that custom " +
+                "events are unsupported.",
+        ],
+        sourceChannels: ["custom"],
+        related: ["variant_leaderboard", "funnel", "event_counts"],
+        category: "interaction",
+    },
     camera_gestures: {
         id: "camera_gestures",
         title: "Camera navigation gestures",
@@ -1854,7 +2270,30 @@ export const METRIC_REGISTRY = {
         builder: "buildCameraGestures",
         endpoint: { method: "GET", path: "/api/v1/camera-gestures" },
         grain: "row",
-        dimensions: ["name", "scene", "session", "source", "cameraMode"],
+        dimensions: [
+            "name",
+            "scene",
+            "session",
+            "source",
+            "cameraMode",
+            "device.os",
+            "device.browser",
+            "device.engine",
+            "device.renderer",
+        ],
+        grainDimensions: ["name"],
+        genericGroupBy: {
+            // The one generic metric whose measures are not all counts: gesture
+            // duration rides in the promoted `visible_ms` column, and sum / avg / max
+            // over a promoted column render the same on every engine.
+            eventTypes: ["camera_gesture"],
+            measures: [
+                { column: "gestures", kind: "count" },
+                { column: "total_ms", kind: "sum", of: "visible_ms" },
+                { column: "avg_ms", kind: "avg", of: "visible_ms" },
+                { column: "max_ms", kind: "max", of: "visible_ms" },
+            ],
+        },
         filters: [
             "since",
             "until",
@@ -1897,6 +2336,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/navigation" },
         grain: "session",
         dimensions: ["session", "scene"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "moveThreshold", "limit", "scene", "session", "format"],
         row: z.object({
             session_id: text,
@@ -1942,6 +2382,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/backtrack" },
         grain: "scene",
         dimensions: ["scene", "session"],
+        grainDimensions: ["scene"],
         filters: ["since", "until", "cellSize", "limit", "scene", "session", "format"],
         row: z.object({
             scene: text,
@@ -1999,6 +2440,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf" },
         grain: "project",
         dimensions: ["session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "session", "format"],
         row: z.object({ samples: int, avg_fps: numOrNull, min_fps: numOrNull, p50_fps: numOrNull }),
         columns: {
@@ -2033,6 +2475,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/render-scale" },
         grain: "project",
         dimensions: ["session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "session", "format"],
         row: z.object({
             samples: int,
@@ -2087,6 +2530,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/distribution" },
         grain: "project",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             sessions: int,
@@ -2132,6 +2576,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/fps-histogram" },
         grain: "bucket",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "bucket", "format"],
         row: z.object({ bucket: int, sessions: int }),
         columns: {
@@ -2170,6 +2615,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/frame-time" },
         grain: "project",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ sessions: int, samples: intOrNull, p50_ms: numOrNull, p95_ms: numOrNull }),
         columns: {
@@ -2209,6 +2655,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/jank" },
         grain: "project",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             sessions: int,
@@ -2256,6 +2703,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/churn" },
         grain: "project",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -2327,6 +2775,13 @@ export const METRIC_REGISTRY = {
             "scene",
             "session",
         ],
+        grainDimensions: [
+            "device.engine",
+            "device.isMobile",
+            "device.renderer",
+            "device.browser",
+            "device.os",
+        ],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             engine: text,
@@ -2382,6 +2837,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/by-scene" },
         grain: "scene",
         dimensions: ["scene", "session"],
+        grainDimensions: ["scene"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ scene_id: text, sessions: int, samples: int, p50_fps: num }),
         columns: {
@@ -2417,6 +2873,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/perf" },
         grain: "voxel",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "cellSize", "limit", "scene", "session", "format"],
         row: z.object({ vx: int, vy: int, vz: int, samples: int, avg_fps: num, min_fps: num }),
         columns: {
@@ -2449,6 +2906,7 @@ export const METRIC_REGISTRY = {
         builder: "buildPerfDaily",
         grain: "bucket",
         dimensions: [],
+        grainDimensions: [],
         filters: [],
         row: z.object({ day: day, samples: int, avg_fps: num, min_fps: num, p50_fps: num }),
         columns: {
@@ -2486,6 +2944,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/compile-stalls" },
         grain: "row",
         dimensions: ["name", "scene", "session"],
+        grainDimensions: ["name"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ phase: text, stalls: int, total_ms: num, avg_ms: num, max_ms: num }),
         columns: {
@@ -2526,6 +2985,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/resources" },
         grain: "project",
         dimensions: ["session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "session", "format"],
         row: z.object({
             samples: int,
@@ -2578,6 +3038,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/resource-percentiles" },
         grain: "project",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             sessions: int,
@@ -2634,6 +3095,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/perf/stability" },
         grain: "project",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ context_losses: int, compile_stalls: int, incidents: int }),
         columns: {
@@ -2664,6 +3126,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/graphics-diagnostics" },
         grain: "row",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ severity: text, category: text, backend: text, incidents: int }),
         columns: {
@@ -2710,6 +3173,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/errors" },
         grain: "voxel",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: [
             "since",
             "until",
@@ -2754,6 +3218,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/rendering-technology" },
         grain: "row",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             api: text,
@@ -2797,6 +3262,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/capabilities" },
         grain: "row",
         dimensions: ["name", "scene", "session"],
+        grainDimensions: ["name"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ kind: text, from: text, to: text, changes: int }),
         columns: {
@@ -2841,6 +3307,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/xr/rotation" },
         grain: "session",
         dimensions: ["session", "scene"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "rapidTurn", "limit", "scene", "session", "format"],
         row: z.object({
             session_id: text,
@@ -2893,6 +3360,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/xr/sources" },
         grain: "row",
         dimensions: ["source", "scene", "session"],
+        grainDimensions: ["source"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ source: text, interactions: int, sessions: int }),
         columns: {
@@ -2923,6 +3391,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/xr/abandonment" },
         grain: "session",
         dimensions: ["session", "scene"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             session_id: text,
@@ -2966,6 +3435,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/xr/locomotion" },
         grain: "session",
         dimensions: ["session", "scene"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             session_id: text,
@@ -3021,6 +3491,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/xr/tracking" },
         grain: "session",
         dimensions: ["session", "scene", "source"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({
             session_id: text,
@@ -3071,6 +3542,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/boundary" },
         grain: "voxel",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "cellSize", "limit", "scene", "session", "region", "format"],
         row: voxelCountRow,
         columns: {
@@ -3108,6 +3580,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/heatmaps/boundary/stats" },
         grain: "project",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "cellSize", "scene", "session", "region", "format"],
         row: spatialStatsRow,
         columns: {
@@ -3136,6 +3609,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/xr/boundary-contacts" },
         grain: "session",
         dimensions: ["session", "scene"],
+        grainDimensions: ["session"],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ session_id: text, contacts: int, near_ms: num }),
         columns: {
@@ -3170,6 +3644,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/ar/placement/time-to-place" },
         grain: "bucket",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "bucketMs", "format"],
         row: z.object({ bucket: int, placements: int }),
         columns: {
@@ -3204,6 +3679,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/ar/placement/attempts" },
         grain: "bucket",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ attempts: int, placements: int }),
         columns: {
@@ -3242,6 +3718,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/ar/placement/surfaces" },
         grain: "row",
         dimensions: ["scene", "session"],
+        grainDimensions: [],
         filters: ["since", "until", "bins", "limit", "scene", "session", "format"],
         row: z.object({ surface: text, placements: int, avg_scale: num }),
         columns: {
@@ -3282,6 +3759,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/funnel" },
         grain: "bucket",
         dimensions: ["scene", "cameraMode"],
+        grainDimensions: [],
         filters: ["since", "until", "scene", "cameraMode", "steps", "format"],
         row: z.object({ step: int, sessions: int }),
         columns: {
@@ -3321,6 +3799,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/scene-retention" },
         grain: "row",
         dimensions: ["scene"],
+        grainDimensions: [],
         filters: ["since", "until", "limit", "format"],
         row: z.object({ from_scene: text, to_scene: text, sessions: int }),
         columns: {
@@ -3356,6 +3835,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/load-bounce" },
         grain: "bucket",
         dimensions: ["scene"],
+        grainDimensions: [],
         filters: ["since", "until", "scene", "bands", "format"],
         row: z.object({ band: int, sessions: int, bounced: int }),
         columns: {
@@ -3397,6 +3877,7 @@ export const METRIC_REGISTRY = {
         endpoint: { method: "GET", path: "/api/v1/variant-leaderboard" },
         grain: "row",
         dimensions: ["name", "scene", "cameraMode"],
+        grainDimensions: [],
         filters: ["since", "until", "scene", "cameraMode", "variant", "conversion", "limit", "format"],
         row: z.object({
             variant: text,
@@ -3437,6 +3918,451 @@ export const METRIC_REGISTRY = {
         comparable: { primary: "conversions", direction: "up", minSample: 50 },
         category: "conversion",
     },
+    // =========================================================================
+    // Insights (ADR 0051 §4, design sketch §D)
+    //
+    // Derived metrics: computed in pure TypeScript over *another* metric's
+    // portable bucket series (`@uptimizr/db`'s `src/insights/`) rather than by a
+    // `build*` aggregation of their own. They are the answer to the two questions
+    // an agent otherwise re-derives from raw rows on every turn — "what is normal
+    // here" and "what changed" — computed once, the same way, on every engine.
+    // =========================================================================
+    insight_baseline: {
+        id: "insight_baseline",
+        title: "Metric baseline",
+        description: "What is normal for one metric in one scene. Buckets a comparable metric's headline column " +
+            "into days or hours over a trailing window and reduces the series to its centre (mean, " +
+            "median), its ordinary spread (MAD, p10, p90) and its drift (least-squares slope per " +
+            "bucket). One row per request: the reference distribution a single later observation should " +
+            "be judged against, so 'is 42 FPS bad here?' has an answer that does not depend on the " +
+            "reader's memory.",
+        derived: "insight",
+        endpoint: { method: "GET", path: "/api/v1/insights/baseline" },
+        grain: "project",
+        dimensions: ["scene"],
+        // One row per request; `scene` is both the filter and the key the row
+        // carries, so it is the grain (#304).
+        grainDimensions: ["scene"],
+        filters: ["metric", "scene", "window", "bucket", "since", "until", "format"],
+        row: z.object({
+            metric: text,
+            scene: text,
+            sampleSize: int,
+            buckets: int,
+            mean: numOrNull,
+            median: numOrNull,
+            mad: numOrNull,
+            p10: numOrNull,
+            p90: numOrNull,
+            slope: numOrNull,
+        }),
+        columns: {
+            metric: { description: "The registry metric the baseline is of.", unit: "id" },
+            scene: {
+                description: "The scene it was scoped to; empty when the baseline spans every scene.",
+                unit: "id",
+            },
+            sampleSize: {
+                description: "Events (or distinct sessions, for a session-valued metric) behind the whole series.",
+                unit: "count",
+            },
+            buckets: { description: "How many buckets carried a value.", unit: "count" },
+            mean: { description: "Arithmetic mean of the bucket values." },
+            median: { description: "Median bucket value — the headline 'normal'.", measure: true },
+            mad: {
+                description: "Median absolute deviation: the typical bucket-to-bucket swing, and the unit a robust " +
+                    "z-score is measured in.",
+            },
+            p10: { description: "10th percentile of the bucket values — the ordinary floor." },
+            p90: { description: "90th percentile of the bucket values — the ordinary ceiling." },
+            slope: {
+                description: "Least-squares slope against the bucket index: change per bucket over the window.",
+            },
+        },
+        limits: { maxRows: 1, maxSummaryRows: 1 },
+        interpretation: "Read `median` as the centre and `mad` as the tolerance: a later observation more than a few " +
+            "MADs from the median is unusual for this scene, one inside p10..p90 is ordinary. `slope` is " +
+            "the drift *within* the window — a baseline with a steep slope is not a stable reference and " +
+            "should be re-read over a shorter window before it is used to judge anything.",
+        caveats: [
+            "Only `comparable` metrics with a portable bucket series can be baselined; a metric whose value is defined by a join, a window function or a caller-supplied funnel predicate is rejected rather than approximated, and the error names every id that is available.",
+            "Window bounds are snapped down to whole buckets, so the current (incomplete) day or hour is excluded — otherwise every morning would look like a collapse. The snapped window is echoed in the `table` / `summary` envelopes.",
+            "Buckets with no matching events are absent from the series rather than zero: a metric that was silent for a week has a narrower baseline, not a lower one.",
+            "Every statistic is `null` when the window carried no values, and `slope` is `null` under two buckets. Read `null` as 'no data', never as 0.",
+            "The series reproduces the metric's headline column per bucket; where the metric's own endpoint aggregates per session first (ADR 0028 §1), a bucket value and that endpoint's headline can differ slightly.",
+        ],
+        sourceChannels: [],
+        related: ["insight_movers", "timeseries", "perf_summary", "events_daily"],
+        category: "insights",
+    },
+    insight_movers: {
+        id: "insight_movers",
+        title: "What changed",
+        description: "What moved, ranked. For every comparable metric in scope, compares the current range with a " +
+            "reference range (the previous equal window by default) and ranks the differences by a " +
+            "robust z-score — the change divided by how much that metric normally swings, so a metric " +
+            "that is always volatile has to move much further than a steady one before it is called a " +
+            "mover. One row per metric: the top risers, the top fallers, and the ones that did not move.",
+        derived: "insight",
+        endpoint: { method: "GET", path: "/api/v1/insights/movers" },
+        grain: "row",
+        dimensions: ["scene"],
+        // One row per metric. Its rows carry no registry dimension column at all —
+        // the key is the metric id, which is not one — so there is nothing for the
+        // generic group-by tier to regroup by (#304).
+        grainDimensions: [],
+        filters: [
+            "scene",
+            "metrics",
+            "bucket",
+            "limit",
+            "since",
+            "until",
+            "refSince",
+            "refUntil",
+            "format",
+        ],
+        row: z.object({
+            metric: text,
+            dimensionValue: z.string().nullable(),
+            current: numOrNull,
+            previous: numOrNull,
+            delta: numOrNull,
+            deltaPct: numOrNull,
+            z: numOrNull,
+            direction: text,
+            aboveMinSample: z.boolean(),
+            sampleSize: num,
+        }),
+        columns: {
+            metric: { description: "The registry metric that moved.", unit: "id", label: true },
+            dimensionValue: {
+                description: "The dimension value the move is attributed to. Always null in v1 — movers are computed " +
+                    "at the scene (or project) level; per-dimension attribution arrives with `anomalies`.",
+                unit: "id",
+            },
+            current: { description: "The metric's headline column over the current range." },
+            previous: { description: "The same over the reference range." },
+            delta: { description: "`current - previous`, in the metric's own unit." },
+            deltaPct: {
+                description: "Relative change; null when the reference value was zero or missing.",
+                unit: "ratio",
+            },
+            z: {
+                description: "Robust z-score: `delta` divided by the median absolute deviation of the reference " +
+                    "bucket series. The ranking key.",
+                unit: "ratio",
+                measure: true,
+            },
+            direction: {
+                description: "Whether a rise is good (`up`), bad (`down`) or merely a fact (`neutral`), from the " +
+                    "moved metric's own registry entry. It qualifies the sign of `delta`; it is not the " +
+                    "direction this metric actually moved in.",
+                unit: "label",
+            },
+            aboveMinSample: {
+                description: "Whether the current range cleared the metric's declared minimum denominator. False " +
+                    "means the delta is real arithmetic but not evidence.",
+            },
+            sampleSize: {
+                description: "The current range's denominator — events, or distinct sessions for a session-valued " +
+                    "metric — that `aboveMinSample` was decided on.",
+            },
+        },
+        limits: { maxRows: 150, maxSummaryRows: 10 },
+        interpretation: "Read the rows in order: risers first, then fallers, then the ones that did not move. |z| is " +
+            "'how many typical swings': under ~2 the move is inside this metric's ordinary noise, over " +
+            "~3 it is worth explaining. Combine `direction` with the sign of `delta` to know whether a " +
+            "move is good or bad — a rise in a `down` metric (errors, dead clicks, jank) is a " +
+            "regression. Rows with `aboveMinSample: false` are sorted last and must not be reported as " +
+            "findings.",
+        caveats: [
+            "Cost is bounded by a per-request cap on how many metrics are scanned (one grouped scan each); without a `metrics` allowlist a curated default set is used, so a move in a metric outside that set is not reported. Name it explicitly to include it.",
+            "Only metrics with a portable bucket series participate. Funnels, cohort metrics and anything defined by the relationship between consecutive events are outside the scan by construction.",
+            "`aboveMinSample: false` means the denominator is too small for the delta to be evidence — the row is kept rather than dropped so 'we cannot tell' stays distinguishable from 'nothing changed', but it must not be read as a finding.",
+            "The spread is taken over the *reference* window's buckets, floored at 1% of that window's level — so a one-bucket or perfectly flat reference cannot make every metric score in the billions and turn the ranking into a comparison of raw deltas across incompatible units. A reference that is flat *at zero* has no level to floor against, so the first data of its kind scores a very large |z|: correct (it is unprecedented) but only meaningful once `aboveMinSample` is true.",
+            "Window bounds are snapped down to whole buckets, so the current incomplete day or hour is excluded from both ranges and the two stay exactly comparable.",
+            "`deltaPct` is null when the reference value was zero: a percentage change from nothing is undefined. Read `delta` in that case.",
+            "A metric is compared with itself over time, never across projects or scenes: sampling rates (ADR 0012) make absolute counts incomparable between them.",
+        ],
+        sourceChannels: [],
+        related: ["insight_baseline", "events_daily", "perf_daily", "event_counts"],
+        category: "insights",
+    },
+    // =========================================================================
+    // --- anomalies (#306) ---
+    // =========================================================================
+    insight_anomalies: {
+        id: "insight_anomalies",
+        title: "Anomalous buckets",
+        description: "When one metric stopped behaving, and what inside it accounts for that. Walks a comparable " +
+            "metric's day or hour bucket series and returns only the buckets that do not belong in it: " +
+            "a `spike` or a `drop` when a single bucket sits more than `sensitivity` median absolute " +
+            "deviations from the buckets just before it, and a `shift` at the bucket where a CUSUM " +
+            "change-point says the level moved and stayed moved. Where the metric declares a dimension " +
+            "it can be split by, the row also names the dimension value holding the largest share of " +
+            "the excess — the difference between 'errors tripled on the 14th' and 'graphics " +
+            "diagnostics tripled on the 14th'.",
+        derived: "insight",
+        endpoint: { method: "GET", path: "/api/v1/insights/anomalies" },
+        grain: "row",
+        dimensions: ["scene"],
+        // One row per anomalous bucket; `scene` is the only registry dimension the
+        // row carries (the metric id and the bucket start are not) (#304).
+        grainDimensions: ["scene"],
+        filters: ["metric", "scene", "window", "bucket", "sensitivity", "since", "until", "format"],
+        row: z.object({
+            metric: text,
+            scene: text,
+            bucketStart: num,
+            value: numOrNull,
+            expected: numOrNull,
+            z: numOrNull,
+            kind: text,
+            contributor: z.object({ dimension: text, value: text, share: numOrNull }).nullable(),
+            sampleSize: num,
+        }),
+        columns: {
+            metric: { description: "The registry metric the series is of.", unit: "id", label: true },
+            scene: {
+                description: "The scene it was scoped to; empty when the series spans every scene.",
+                unit: "id",
+            },
+            bucketStart: {
+                description: "Start of the anomalous bucket, epoch milliseconds (UTC, aligned to the grain). For a " +
+                    "`shift` this is the bucket the level changed at, not the bucket the change was detected in.",
+                unit: "timestamp",
+            },
+            value: {
+                description: "The observed value. For a `shift`, the level that held after the change-point rather " +
+                    "than one bucket's reading.",
+            },
+            expected: {
+                description: "What the bucket should have read: the median of the trailing window, or for a " +
+                    "`shift` the level that held before the change-point.",
+            },
+            z: {
+                description: "Signed robust z-score: `(value - expected)` divided by the trailing window's median " +
+                    "absolute deviation rescaled to a standard deviation (x1.4826) and floored at 1% of the " +
+                    "level. It is measured in standard deviations, so `sensitivity: 3` means 'beyond three " +
+                    "sigma'. `insight_movers` reports the same ratio *unscaled* because it ranks rather " +
+                    "than thresholds, so the two columns differ by that constant factor.",
+                unit: "ratio",
+                measure: true,
+            },
+            kind: {
+                description: "`spike` (one bucket far above the trailing window), `drop` (far below) or `shift` (the " +
+                    "level moved and stayed moved).",
+                unit: "label",
+            },
+            contributor: {
+                description: "The dimension value accounting for the excess: `{ dimension, value, share }`, where " +
+                    "`share` is its fraction of the total same-signed excess. Null when the metric declares " +
+                    "no split dimension, when the split would be degenerate, or when no value moved with the " +
+                    "finding.",
+            },
+            sampleSize: {
+                description: "The anomalous bucket's own denominator — events, or distinct sessions for a " +
+                    "session-valued metric.",
+                unit: "count",
+            },
+        },
+        limits: { maxRows: 200, maxSummaryRows: 8 },
+        interpretation: "Rows are ordered by bucket, oldest first, so the result reads as a timeline. |z| is 'how " +
+            "many typical swings out': at the default `sensitivity` of 3 nothing under 3 appears at all, " +
+            "and a `shift` is usually the more important finding than a `spike` because it is still " +
+            "true today. Read `contributor.share`: above ~0.8 the anomaly *is* that dimension value and " +
+            "the investigation has one place to start; near the reciprocal of the number of values it is " +
+            "spread evenly and the cause is more likely to be global. An empty result means the series " +
+            "held together over the window, not that there was no data - check `insight_baseline`'s " +
+            "`buckets` for that.",
+        caveats: [
+            "Only `comparable` metrics with a portable bucket series can be scored; a metric whose value is defined by a join, a window function or a caller-supplied funnel predicate is rejected with the list of ids that are available, rather than approximated.",
+            "A bucket is judged against the buckets before it (14 at day grain, 168 at hour grain), never against itself, and a bucket with fewer than 5 buckets of history behind it is not judged at all. The first days of a project are therefore silent by construction rather than a wall of findings.",
+            "The spread is floored at 1% of the trailing level, so a perfectly flat metric does not report every subsequent bucket as an infinite z. A series that is flat at *zero* has no level to floor against, so the first data of its kind can read as a very large spike.",
+            "Buckets with no matching events are absent from the series rather than zero, so a gap in capture is not reported as a drop. A metric that genuinely fell to zero *did* record events, so it is.",
+            "Change-points are detected sequentially, so a shift is reported at the bucket the level moved at but can only be found once enough buckets after it have accumulated. The most recent few buckets of a window are therefore under-covered for `shift` - re-read after more data lands.",
+            "Contributor attribution costs at most 3 extra grouped scans per request whatever the data looks like: adjacent findings share one window, and only the three most extreme windows are re-read. Quieter findings carry `contributor: null` - narrow `since` / `until` around one to attribute it.",
+            "The contributor is one dimension, chosen per metric from the promoted columns (mesh, source, name, event type, scene). It is not a cause: it is where the excess sits. A metric whose real explanation is the device or the release has no column for it and reports null.",
+            "Window bounds are snapped down to whole buckets, so the incomplete day or hour in progress is never scored - otherwise every morning would report a drop.",
+            "A sustained level change is reported twice over: once as the `shift` at its change-point, and again as `drop`/`spike` rows for the buckets right after it, until the trailing window has caught up with the new level. Those are two true statements about one event ('it moved on the 14th' and 'the 15th was far below what the fortnight before it predicted'), not a duplicate row - read the `shift` as the finding and the points as its first days.",
+            "`z` is measured in standard deviations (the MAD rescaled by 1.4826), so it is directly comparable with a normal-distribution intuition but **not** byte-comparable with `insight_movers`' `z`, which is the same ratio unscaled.",
+        ],
+        sourceChannels: [],
+        related: ["insight_baseline", "insight_movers", "timeseries", "error_heatmap"],
+        category: "insights",
+    },
+    // --- significance / scene health (#307) ---------------------------------
+    //
+    // The other two §4 primitives. `insight_significance` answers the question a
+    // robust z deliberately does not — *could this difference be chance?* — and
+    // `insight_scene_health` collapses six of those readings into one comparable
+    // score per scene, with every factor traceable back to the metric behind it.
+    insight_significance: {
+        id: "insight_significance",
+        title: "Statistical significance",
+        description: "Is that difference real? Compares one comparable metric across two windows and reports the " +
+            "effect, its 95% confidence interval and a two-sided p-value, with the test chosen from what " +
+            "the measure *is*: a two-proportion z with Wilson intervals for a declared rate, Welch's t " +
+            "over the per-bucket values for a level, an exact Poisson rate test for a bare count. One " +
+            "row per request, and a `powerNote` saying what these sample sizes could and could not have " +
+            "detected.",
+        derived: "insight",
+        endpoint: { method: "GET", path: "/api/v1/insights/significance" },
+        grain: "project",
+        dimensions: ["scene"],
+        // One row per request; `scene` is the only registry dimension the row
+        // carries, so it is the grain (#304).
+        grainDimensions: ["scene"],
+        filters: ["metric", "scene", "bucket", "since", "until", "refSince", "refUntil", "format"],
+        row: z.object({
+            metric: text,
+            scene: text,
+            a: z.object({ value: numOrNull, n: num }),
+            b: z.object({ value: numOrNull, n: num }),
+            effect: numOrNull,
+            ci95: z.tuple([numOrNull, numOrNull]),
+            p: numOrNull,
+            test: text,
+            effectUnit: text,
+            significant: z.boolean(),
+            powerNote: text,
+        }),
+        columns: {
+            metric: { description: "The registry metric being compared.", unit: "id", label: true },
+            scene: {
+                description: "The scene it was scoped to; empty when the comparison spans every scene.",
+                unit: "id",
+            },
+            a: {
+                description: "The current window: `value` in the metric's own unit (a proportion for a rate, a " +
+                    "per-bucket rate for a count, a mean of bucket values for a level) and `n`, the " +
+                    "denominator it rests on — trials for a proportion, buckets otherwise. `value * n` " +
+                    "recovers the total the arm was computed from, whichever test ran.",
+            },
+            b: { description: "The reference window, in the same shape as `a`." },
+            effect: {
+                description: "`a.value - b.value`, in the unit named by `effectUnit`.",
+                measure: true,
+            },
+            ci95: {
+                description: "The 95% confidence interval for `effect`, as `[lo, hi]`. An interval that straddles 0 " +
+                    "is the finding, whatever `p` says.",
+            },
+            p: {
+                description: "Two-sided p-value for the null hypothesis of no difference.",
+                unit: "ratio",
+            },
+            test: {
+                description: "Which test produced the row: `two_proportion_z`, `welch_t` or `poisson_rate`.",
+                unit: "label",
+            },
+            effectUnit: { description: "What one unit of `effect` means.", unit: "label" },
+            significant: {
+                description: "Whether `p` cleared alpha = 0.05. A convenience, never a substitute for `ci95`.",
+            },
+            powerNote: {
+                description: "The smallest difference these sample sizes could have detected at 80% power, plus any " +
+                    "assumption the data strained (overdispersed counts, too few buckets).",
+                unit: "label",
+            },
+        },
+        limits: { maxRows: 1, maxSummaryRows: 1 },
+        interpretation: "Read `ci95` before `p`. A narrow interval around a small effect is evidence that nothing " +
+            "much changed; a wide interval containing 0 is evidence of nothing at all, and `powerNote` " +
+            "says which of the two you are looking at. `p` is two-sided throughout: it answers 'is there " +
+            "a difference', not 'is it an improvement' — combine it with the sign of `effect` and the " +
+            "compared metric's own `direction` for that.",
+        caveats: [
+            "v1 compares two **time windows**, not two segments. A variant-versus-variant or device-versus-device contrast needs the bucket series split by a promoted dimension, which is not available yet; asking for one is rejected rather than answered with the wrong contrast.",
+            "The test is chosen from the measure, not from the caller: a metric whose comparable primary declares a `rateOf` denominator gets the two-proportion z, a bare count gets the Poisson rate test, and everything else gets Welch's t. A caller cannot ask for a different one.",
+            "Welch's t treats each **bucket** as one observation, so `n` is the number of days or hours compared, never the number of events. Consecutive frame samples inside a day are not independent, and counting them would manufacture a p-value of 1e-40 for ordinary day-to-day drift.",
+            "For a Welch comparison `a.value` is the **mean** of the bucket values even where `movers` would report the window sum, so that `effect` and `value` can be read together; `n` is the bucket count, so the sum is one multiplication away.",
+            "The Poisson test assumes counts that do not vary more than a Poisson process would. When the buckets say otherwise, the p-value is optimistic and `powerNote` says so — treat it as an upper bound on the evidence.",
+            "The Poisson interval is the normal approximation on the rate difference (there is no closed-form exact one); only the p-value is exact.",
+            "The two-proportion p-value uses the pooled variance under the null while the interval is unpooled and Newcombe-hybrid. In a borderline case the two can disagree about whether 0 is excluded; that is the textbook procedure, and the interval is the one to believe.",
+            "Window bounds are snapped down to whole buckets, so the current incomplete day or hour is excluded from both windows and the two stay exactly comparable.",
+            "Statistical significance is not importance. A large enough sample makes a difference of no consequence significant; `effect` and `effectUnit` are what say whether it matters.",
+        ],
+        sourceChannels: [],
+        related: ["insight_movers", "insight_baseline", "insight_scene_health"],
+        category: "insights",
+    },
+    insight_scene_health: {
+        id: "insight_scene_health",
+        title: "Scene health score",
+        description: "Which scene is in trouble, and why. Scores each scene 0-100 over six weighted factors — " +
+            "perf stability, jank, errors, dead clicks, exploration coverage and XR abandonment — each " +
+            "normalised against the project's own baseline over the preceding equal window. One row per " +
+            "scene, least healthy first, and every factor carries the metric id, the raw value, the " +
+            "baseline it was compared with and the weight it contributed, so the score can always be " +
+            "taken apart.",
+        derived: "insight",
+        endpoint: { method: "GET", path: "/api/v1/insights/scene-health" },
+        grain: "scene",
+        dimensions: ["scene"],
+        // One row per scene — the grain is the scene itself (#304).
+        grainDimensions: ["scene"],
+        filters: ["scene", "window", "since", "until", "bucket", "limit", "weights", "format"],
+        row: z.object({
+            scene: text,
+            score: numOrNull,
+            factors: z.array(z.object({
+                id: text,
+                metric: text,
+                raw: numOrNull,
+                baseline: numOrNull,
+                score: numOrNull,
+                weight: num,
+                unit: text,
+                note: text,
+            })),
+            sampleSize: int,
+            since: int,
+            until: int,
+        }),
+        columns: {
+            scene: { description: "The scene scored.", unit: "id", label: true },
+            score: {
+                description: "Weighted mean of the available factors, 0-100. 50 is exactly the project norm for the " +
+                    "preceding window; higher is healthier. Null when no factor could be scored.",
+                measure: true,
+            },
+            factors: {
+                description: "One entry per factor: `id`, the `metric` behind it, its `raw` value in `unit`, the " +
+                    "project `baseline` it was compared with, its normalised `score`, the `weight` it " +
+                    "carried, and a `note` saying what the raw number measures (or why it was not scored).",
+            },
+            sampleSize: {
+                description: "Sessions started in the scene over the window — what the score rests on.",
+                unit: "sessions",
+            },
+            since: { description: "Start of the scored window, epoch ms.", unit: "epoch-ms" },
+            until: { description: "End of the scored window, epoch ms.", unit: "epoch-ms" },
+        },
+        limits: { maxRows: 10, maxSummaryRows: 10 },
+        interpretation: "The score is a **comparison, not a grade**: it says how this scene is doing against the " +
+            "rest of this project's recent past, so a project where everything is equally bad reads 50 " +
+            "everywhere. Read the lowest-scoring scene first, then the factor whose own score is " +
+            "furthest below 50 — that factor's `metric` is the endpoint to open next, and its `raw` " +
+            "versus `baseline` is the sentence to write. A factor with `score: null` was not counted; " +
+            "its `note` says why.",
+        caveats: [
+            "The default weights are a judgement, declared in this entry so they can be argued with: perf stability 0.25, error rate 0.25, jank rate 0.2, dead-click rate 0.15, coverage 0.1, XR abandonment 0.05. Pass `weights` as a JSON object to override any of them; unnamed factors keep their default.",
+            "Normalisation is against the **project as a whole** over the preceding equal window, not against an absolute target. A new project with one week of data has no baseline and scores null.",
+            "Unlike `insight_baseline` and `insight_movers`, the window **includes the bucket in progress** rather than snapping down to the last complete one: every factor is a rate or a percentile, neither of which a partial bucket distorts, and excluding today would make the score answer about yesterday. The window actually measured is echoed as `since` / `until` on every row.",
+            "A factor with no data in the window, or no project baseline to compare against, is reported with `score: null` and excluded from the weighted mean — the remaining weights are renormalised. The row still lists it, so a missing factor is visible rather than silently folded in.",
+            "XR abandonment is absent in a project with no XR traffic: a scene nobody visited in VR is not an unhealthy VR scene.",
+            "Coverage is positioned camera samples per session, not a voxel-coverage percentage: the true percentage needs the registered scene bounds and has no portable per-bucket form. It is only ever read against the project's own baseline.",
+            "The jank factor is the *pooled* long-frames-per-sampled-window rate, while the `jank_rate` metric's own endpoint reports a per-session median (ADR 0028 Section 1). They agree in direction, not in value.",
+            "Rage clicks are not folded into the dead-click factor: they are defined by the gap between consecutive clicks and have no portable per-bucket form.",
+            "Fewer than about 20 sessions makes a scene's score noise. The row is returned anyway, with its `sampleSize`, so 'we cannot tell' stays distinguishable from 'this scene is fine'.",
+            "Without a `scene` the scan is bounded to the busiest scenes by event volume, so a quiet scene can be missing from the list entirely. Name it explicitly to score it.",
+        ],
+        sourceChannels: [],
+        related: ["insight_movers", "insight_baseline", "insight_significance"],
+        category: "insights",
+    },
 };
 /** Every registry id, in declaration order. */
 export const METRIC_IDS = Object.keys(METRIC_REGISTRY);
@@ -3479,6 +4405,21 @@ export function metricForBuilder(builder) {
  * catalog stays a superset of the hand-written one (design sketch §A.4).
  */
 export function isResourceMetric(metric) {
-    return metric.builder === undefined;
+    return metric.builder === undefined && metric.derived === undefined;
+}
+/**
+ * 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 function isDerivedMetric(metric) {
+    return metric.derived !== undefined;
+}
+/** Whether a metric is served as an aggregate over a querystring (not a resource read). */
+export function isAggregateMetric(metric) {
+    return metric.builder !== undefined || metric.derived !== undefined;
 }
 //# sourceMappingURL=registry.js.map