@uptimizr/collector-server 1.1.1 → 2.0.1

package/dist/routes/query.js

@@ -1,7 +1,9 @@
 import { Readable } from "node:stream";
 import { z } from "zod";
-import { sceneProxySchema, funnelStepsSchema, funnelStepSchema } from "@uptimizr/schema";
-import { defaultCellSizeForBounds } from "@uptimizr/db";
+import { sceneProxySchema, sceneRegionsSchema, regionIdSchema, funnelStepsSchema, funnelStepSchema, } from "@uptimizr/schema";
+import { defaultCellSizeForBounds, resultEnvelopeSchema, resultFormatSchema, summarizeRows, tableResult, } from "@uptimizr/db";
+import { allMetrics } from "@uptimizr/metrics";
+import { requireCapability } from "../auth.js";
 /** Developer-assigned scene/area filter (ADR 0010). */
 const sceneFilter = z
     .string()
@@ -20,6 +22,19 @@ const sessionFilter = z.string().min(1).max(128).optional();
  * {@link cameraTypeForMode} before it reaches the aggregation layer.
  */
 const cameraModeFilter = z.enum(["viewer", "first-person"]).optional();
+/**
+ * Result envelope (ADR 0051 §2, design sketch §B.1). Accepted by every
+ * registry-served aggregate endpoint, and declared as the `format` filter on
+ * each of their registry entries — the registry-route contract test asserts the
+ * two stay in step.
+ *
+ * Omitted or `full` means the response is the bare rows, byte-for-byte what the
+ * endpoint has always returned: the dashboard never sends `format`, so it cannot
+ * be affected by this. `table` and `summary` are shaped by a single
+ * `preSerialization` hook at the bottom of this plugin, so no handler has to
+ * know the envelope exists.
+ */
+const formatFilter = resultFormatSchema.optional();
 /** Map the dashboard camera-mode toggle to the stored `cameraType` value. */
 function cameraTypeForMode(mode) {
     if (mode === "first-person")
@@ -29,10 +44,19 @@ function cameraTypeForMode(mode) {
     return undefined;
 }
 /**
- * World-space region filter (ADR 0040 §4): a `minX,minY,minZ,maxX,maxY,maxZ`
- * comma list naming an axis-aligned box to drill into. Validated to six finite
- * numbers with `max >= min` on every axis, then handed to the aggregation layer
- * as a {@link WorldAabb}. Omit for the whole scene.
+ * World-space region filter (ADR 0040 §4, extended by ADR 0051 §2). Accepts
+ * either form:
+ *
+ * - a `minX,minY,minZ,maxX,maxY,maxZ` comma list naming an ad-hoc axis-aligned
+ *   box to drill into (validated to six finite numbers with `max >= min` on
+ *   every axis) — the original drill-down the dashboard sends; or
+ * - the **id of a registered scene region** (`region=checkout-counter`), the
+ *   shared vocabulary humans and agents use to talk about places. It is
+ *   resolved server-side to the stored bounds by {@link resolveRegionFilter},
+ *   so the aggregation layer only ever sees a {@link WorldAabb}.
+ *
+ * The two are unambiguous: a box always contains commas, a region id never can.
+ * Omit for the whole scene.
  */
 const regionFilter = z
     .string()
@@ -40,6 +64,18 @@ const regionFilter = z
     .transform((val, ctx) => {
     if (val == null)
         return undefined;
+    if (!val.includes(",")) {
+        const id = regionIdSchema.safeParse(val);
+        if (!id.success) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "region must be a registered region id (1-64 chars of [A-Za-z0-9._:-]) " +
+                    "or 6 comma-separated finite numbers: minX,minY,minZ,maxX,maxY,maxZ",
+            });
+            return z.NEVER;
+        }
+        return { kind: "id", id: id.data };
+    }
     const parts = val.split(",").map((s) => Number(s.trim()));
     if (parts.length !== 6 || parts.some((n) => !Number.isFinite(n))) {
         ctx.addIssue({
@@ -56,8 +92,38 @@ const regionFilter = z
         });
         return z.NEVER;
     }
-    return [minX, minY, minZ, maxX, maxY, maxZ];
+    return { kind: "box", bounds: [minX, minY, minZ, maxX, maxY, maxZ] };
 });
+function isRegionError(value) {
+    return typeof value === "object" && value !== null && "error" in value;
+}
+/**
+ * Resolve a parsed `region` filter to the world box the aggregations take.
+ *
+ * A box passes straight through. A **region id** is looked up in the scene
+ * registry: regions are keyed by `(project, scene, region)`, so the request must
+ * also name the `scene` the region belongs to, and an id the project has never
+ * registered is a client error (`400`) rather than a silently unfiltered query —
+ * an agent must never be told "no hits in the entrance" when it merely misspelt
+ * the region. Returns the box, `undefined` when no filter was given, or an error
+ * object the caller turns into a `400`.
+ */
+async function resolveRegionFilter(store, projectId, scene, filter) {
+    if (filter == null)
+        return undefined;
+    if (filter.kind === "box")
+        return filter.bounds;
+    if (scene == null) {
+        return {
+            error: "region names a registered region, so the request must also pass a scene",
+        };
+    }
+    const regions = await store.getSceneRegions(projectId, scene);
+    const match = regions.find((r) => r.regionId === filter.id);
+    if (!match)
+        return { error: `unknown region "${filter.id}" in scene "${scene}"` };
+    return match.bounds;
+}
 /**
  * Resolve the effective voxel `cellSize` for a spatial heatmap (ADR 0040 §1).
  * When the caller pins a `cellSize` it wins. Otherwise the resolution is driven
@@ -66,7 +132,26 @@ const regionFilter = z
  * legible instead of dissolving into a few coarse blocks. Returns `undefined`
  * when no extent is known, letting the aggregation fall back to its fixed default.
  */
-async function resolveSpatialCellSize(store, projectId, opts) {
+async function resolveSpatialCellSize(store, projectId, opts, request) {
+    const resolved = await computeSpatialCellSize(store, projectId, opts);
+    if (request != null && resolved != null)
+        resolvedCellSizes.set(request, resolved);
+    return resolved;
+}
+/**
+ * Cell sizes a spatial route resolved for the request in flight.
+ *
+ * The `format=summary` hook runs after the handler and needs the **effective**
+ * cell size to turn a cluster's grid extent into a world-space `region` drill
+ * hint (ADR 0040 §1/§4). The handler is the only place that knows it — it may
+ * have been derived from the scene's registered bounds — so it is recorded here
+ * on the way past. A `WeakMap` rather than a request decorator keeps this an
+ * implementation detail of this plugin and cannot leak: the entry dies with the
+ * request object.
+ */
+const resolvedCellSizes = new WeakMap();
+/** The resolution rule itself; see {@link resolveSpatialCellSize}. */
+async function computeSpatialCellSize(store, projectId, opts) {
     if (opts.cellSize != null)
         return opts.cellSize;
     if (opts.region != null)
@@ -84,6 +169,7 @@ const rangeQuery = z.object({
     until: z.coerce.number().int().optional(),
     bins: z.coerce.number().int().positive().max(500).optional(),
     limit: z.coerce.number().int().positive().max(1000).optional(),
+    format: formatFilter,
 });
 /** Sessions-list params: a time range, result cap, and camera-mode filter. */
 const sessionsQueryParams = rangeQuery.extend({ cameraMode: cameraModeFilter });
@@ -153,6 +239,7 @@ const worldHeatmapQueryParams = z.object({
     source: sourceFilter,
     cameraMode: cameraModeFilter,
     region: regionFilter,
+    format: formatFilter,
 });
 /** World heatmap totals params (ADR 0040 §3): same filters as the world heatmap, no `limit`. */
 const worldStatsQueryParams = z.object({
@@ -163,6 +250,7 @@ const worldStatsQueryParams = z.object({
     source: sourceFilter,
     cameraMode: cameraModeFilter,
     region: regionFilter,
+    format: formatFilter,
 });
 /**
  * Boundary-touch heatmap params (#157, ADR 0048): a positive voxel `cellSize`
@@ -178,6 +266,7 @@ const boundaryHeatmapQueryParams = z.object({
     scene: sceneFilter,
     session: sessionFilter,
     region: regionFilter,
+    format: formatFilter,
 });
 /** Boundary-touch heatmap totals params (ADR 0040 §3): boundary filters, no `limit`. */
 const boundaryStatsQueryParams = z.object({
@@ -187,6 +276,7 @@ const boundaryStatsQueryParams = z.object({
     scene: sceneFilter,
     session: sessionFilter,
     region: regionFilter,
+    format: formatFilter,
 });
 /**
  * Gaze heatmap params (ADR 0030): a positive voxel `cellSize` plus scene/session
@@ -202,6 +292,7 @@ const gazeHeatmapQueryParams = z.object({
     session: sessionFilter,
     cameraMode: cameraModeFilter,
     region: regionFilter,
+    format: formatFilter,
 });
 /** Gaze heatmap totals params (ADR 0040 §3): same filters as the gaze heatmap, no `limit`. */
 const gazeStatsQueryParams = z.object({
@@ -212,6 +303,7 @@ const gazeStatsQueryParams = z.object({
     session: sessionFilter,
     cameraMode: cameraModeFilter,
     region: regionFilter,
+    format: formatFilter,
 });
 /**
  * Floor-plan camera-position heatmap params (ADR 0026): a ground-plane bin
@@ -226,6 +318,7 @@ const cameraPositionQueryParams = z.object({
     session: sessionFilter,
     cameraMode: cameraModeFilter,
     region: regionFilter,
+    format: formatFilter,
 });
 /**
  * Aggregate desire-line params (#73, ADR 0037): a ground-bin `cellSize` plus
@@ -239,6 +332,7 @@ const aggregatePathQueryParams = z.object({
     limit: z.coerce.number().int().positive().max(50000).optional(),
     scene: sceneFilter,
     cameraMode: cameraModeFilter,
+    format: formatFilter,
 });
 /** Session-trajectory params: a time range, scene filter, and point cap. */
 const trajectoryQueryParams = z.object({
@@ -246,6 +340,7 @@ const trajectoryQueryParams = z.object({
     until: z.coerce.number().int().optional(),
     limit: z.coerce.number().int().positive().max(10000).optional(),
     scene: sceneFilter,
+    format: formatFilter,
 });
 /** Path param for a single session's trajectory. */
 const sessionPathParams = z.object({
@@ -260,6 +355,7 @@ const clickRayQueryParams = z.object({
     scene: sceneFilter,
     source: sourceFilter,
     session: sessionFilter,
+    format: formatFilter,
 });
 /**
  * Flow params: camera-direction bins joined to clicked meshes (§7.5), plus the
@@ -281,6 +377,7 @@ const scenesQueryParams = z.object({
     since: z.coerce.number().int().optional(),
     until: z.coerce.number().int().optional(),
     limit: z.coerce.number().int().positive().max(1000).optional(),
+    format: formatFilter,
 });
 /** Time-series params: range + scene + optional event-type filter + bucket interval (seconds). */
 const timeseriesQueryParams = z.object({
@@ -292,12 +389,14 @@ const timeseriesQueryParams = z.object({
         .string()
         .regex(/^[a-z_]{1,40}$/)
         .optional(),
+    format: formatFilter,
 });
 /** Event-type-counts params: range + optional scene filter. */
 const eventCountsQueryParams = z.object({
     since: z.coerce.number().int().optional(),
     until: z.coerce.number().int().optional(),
     scene: sceneFilter,
+    format: formatFilter,
 });
 /**
  * Funnel params (#78, ADR 0038): a time range, optional scene/camera-mode scope,
@@ -312,6 +411,7 @@ const funnelQueryParams = z.object({
     scene: sceneFilter,
     cameraMode: cameraModeFilter,
     steps: z.string().min(1).max(8192),
+    format: formatFilter,
 });
 /**
  * Scene-retention params (#147): a time range plus an optional result cap. No
@@ -322,6 +422,7 @@ const sceneRetentionQueryParams = z.object({
     since: z.coerce.number().int().optional(),
     until: z.coerce.number().int().optional(),
     limit: z.coerce.number().int().positive().max(10000).optional(),
+    format: formatFilter,
 });
 /**
  * Load → bounce funnel params (#152): a time range, optional scene scope, and
@@ -353,6 +454,7 @@ const loadBounceQueryParams = z.object({
         }
         return parts;
     }),
+    format: formatFilter,
 });
 /**
  * Variant-leaderboard params (#150): a time range, optional scene/camera-mode
@@ -370,6 +472,7 @@ const variantLeaderboardQueryParams = z.object({
     variant: z.string().min(1).max(2048).optional(),
     conversion: z.string().min(1).max(2048).optional(),
     limit: z.coerce.number().int().positive().max(500).optional(),
+    format: formatFilter,
 });
 /** Scene-coverage params: voxel `cellSize` + scene/session filters + result cap. */
 const coverageQueryParams = z.object({
@@ -379,6 +482,7 @@ const coverageQueryParams = z.object({
     limit: z.coerce.number().int().positive().max(10000).optional(),
     scene: sceneFilter,
     session: sessionFilter,
+    format: formatFilter,
 });
 /**
  * Spatial FPS heatmap params (#145): voxel `cellSize` + scene/session filters + a
@@ -402,6 +506,7 @@ const errorHeatmapQueryParams = z.object({
     severity: z.string().min(1).max(64).optional(),
     category: z.string().min(1).max(64).optional(),
     errorKind: z.string().min(1).max(64).optional(),
+    format: formatFilter,
 });
 /** Camera-distance params: reference `center` (3 coords) + `bucketSize` + filters. */
 const cameraDistanceQueryParams = z.object({
@@ -414,6 +519,7 @@ const cameraDistanceQueryParams = z.object({
     limit: z.coerce.number().int().positive().max(1000).optional(),
     scene: sceneFilter,
     session: sessionFilter,
+    format: formatFilter,
 });
 /** Navigation-stats params: idle/active `moveThreshold` + scene/session filters. */
 const navigationQueryParams = z.object({
@@ -423,6 +529,7 @@ const navigationQueryParams = z.object({
     limit: z.coerce.number().int().positive().max(1000).optional(),
     scene: sceneFilter,
     session: sessionFilter,
+    format: formatFilter,
 });
 /** Backtrack-ratio params: coarse-grid `cellSize` + scene/session filters. */
 const backtrackQueryParams = z.object({
@@ -432,6 +539,7 @@ const backtrackQueryParams = z.object({
     limit: z.coerce.number().int().positive().max(1000).optional(),
     scene: sceneFilter,
     session: sessionFilter,
+    format: formatFilter,
 });
 /** XR rotation-rate params: `rapidTurn` (rad) threshold + scene/session filters. */
 const xrRotationQueryParams = z.object({
@@ -441,6 +549,7 @@ const xrRotationQueryParams = z.object({
     limit: z.coerce.number().int().positive().max(1000).optional(),
     scene: sceneFilter,
     session: sessionFilter,
+    format: formatFilter,
 });
 /** Path param for a single scene's representation. */
 const sceneParams = z.object({
@@ -451,43 +560,251 @@ const putRepresentationBody = z.object({
     proxy: sceneProxySchema,
     label: z.string().max(200).optional(),
 });
+// --- Response schemas, from the metric registry ---------------------------
+//
+// Every canned read endpoint is a registry metric (ADR 0051 §1), and the registry
+// already declares its output `row` — the same schema the agent tool catalog and
+// the generated OpenAPI document are derived from. Attaching it here as the 200
+// response schema makes the Zod type provider serialise through it, so the shape
+// the docs promise and the shape the wire carries cannot drift apart.
+//
+// Two consequences worth knowing before adding a route:
+//
+// - `z.object()` **strips** keys it does not declare, so a column a handler
+//   returns but the registry does not describe would vanish. The test
+//   `__tests__/queryResponseSchemas.test.ts` calls every one of these endpoints
+//   against a seeded DuckDB store and asserts the serialised body is deep-equal
+//   to what the store produced, so a missing declaration fails the build rather
+//   than a dashboard panel.
+// - Serialisation is strict, so a `null` in a column the registry declares
+//   non-nullable is a 500. The same test also runs every endpoint against an
+//   **empty** project, which is where SQL's "aggregate over no rows is NULL"
+//   shows up.
+//
+// Since ADR 0051 §2 each schema is the **union** of the three `format` envelopes
+// (`resultEnvelopeSchema`), with the untouched `full` shape first — so a request
+// that does not ask for an envelope is parsed by exactly the schema it was
+// parsed by before, and its bytes cannot drift.
+/** Registry metrics indexed by the collector path that serves them. */
+const METRIC_BY_PATH = new Map(allMetrics()
+    .filter((metric) => Boolean(metric.endpoint))
+    .map((metric) => [metric.endpoint.path, metric]));
+/** The registry row schema for the metric served on `path`. */
+function rowFor(path) {
+    const metric = METRIC_BY_PATH.get(path);
+    if (!metric) {
+        // Startup-time failure: a route claiming to serve a metric must have one.
+        throw new Error(`no registry metric is registered for ${path}`);
+    }
+    return metric.row;
+}
+/**
+ * 200 response schema for a metric that returns a list of rows.
+ *
+ * Typed as `z.ZodType<unknown[]>` rather than `z.ZodArray<z.ZodObject>`: a bare
+ * `ZodObject` infers `Record<string, unknown>`, and the hand-written row
+ * *interfaces* in `@uptimizr/db` (`MeshCountRow`, …) have no index signature, so
+ * the provider would reject every handler that returns one. Widening keeps the
+ * runtime schema — which is what serialises — exactly as declared; the
+ * handler-shape check is done for real, against real rows, by
+ * `__tests__/queryResponseSchemas.test.ts`.
+ */
+function rowsFor(path) {
+    const row = rowFor(path);
+    return resultEnvelopeSchema(z.array(row), row);
+}
+/**
+ * 200 response schema for the three spatial `stats` routes, which return the metric's
+ * single row plus the **effective** `cellSize` the collector resolved for the
+ * request (ADR 0040 §1) so the caller can label its own grid. The echo is a
+ * property of the route, not of the aggregation, so it is added here rather than
+ * put in the registry row.
+ */
+function statsRowFor(path) {
+    const row = rowFor(path).extend({ cellSize: z.number() });
+    return resultEnvelopeSchema(row, row);
+}
+/**
+ * 200 response schema for the two **resource** metrics, which return a single
+ * record rather than a list of aggregate rows. Widened for the same reason as
+ * {@link rowsFor}: `SessionMeta` / `SceneRepresentation` are declared interfaces
+ * with no index signature.
+ */
+function singleRowFor(path) {
+    return rowFor(path);
+}
+/**
+ * Filters carried in the path rather than the querystring, keyed by the filter
+ * ids the registry declares for them (`endpoint.pathParams`, in `:` order) — so
+ * a session trajectory's `:sessionId` is echoed back as `session`, the name the
+ * rest of the query surface uses.
+ */
+function pathFilters(metric, request) {
+    const params = (request.params ?? {});
+    const segments = (metric.endpoint?.path ?? "")
+        .split("/")
+        .filter((segment) => segment.startsWith(":"))
+        .map((segment) => segment.slice(1));
+    const ids = metric.endpoint?.pathParams ?? [];
+    const filters = {};
+    segments.forEach((segment, index) => {
+        const id = ids[index];
+        const value = params[segment];
+        if (id != null && value != null)
+            filters[id] = value;
+    });
+    return filters;
+}
+/**
+ * Everything the summariser needs to know about the request that produced the
+ * rows: the window and filters to echo, the row cap that was in force (so
+ * `truncated` is honest), and the effective spatial `cellSize` — the resolved
+ * one where a handler derived it from the scene bounds, else whatever the caller
+ * pinned.
+ */
+function summaryContextFor(metric, request) {
+    const query = (request.query ?? {});
+    const cellSize = resolvedCellSizes.get(request) ?? query.cellSize;
+    return {
+        range: {
+            since: typeof query.since === "number" ? query.since : null,
+            until: typeof query.until === "number" ? query.until : null,
+        },
+        filters: { ...query, ...pathFilters(metric, request) },
+        limit: typeof query.limit === "number" ? query.limit : undefined,
+        cellSize: typeof cellSize === "number" ? cellSize : undefined,
+    };
+}
+/** `{ error }` body the read routes send for a miss. Declared so `reply.code(404)` stays typed. */
+const notFoundResponse = z.object({ error: z.string() });
+/**
+ * `{ error, details? }` body sent when a JSON-encoded query parameter (a funnel
+ * or variant predicate) fails its schema. Declared alongside the 200 so
+ * `reply.code(400)` stays typed once a route has a response schema.
+ */
+const badRequestResponse = z.object({ error: z.string(), details: z.unknown().optional() });
+/**
+ * Body for declaring a scene's regions (ADR 0051 §2): the scene's whole set.
+ * The write replaces what is stored, so an empty array clears the scene — the
+ * caller declares what the regions *are* rather than patching them one by one.
+ * `sceneRegionsSchema` bounds the count, the label/description lengths, the box
+ * shape, and rejects duplicate ids at the edge.
+ */
+const putRegionsBody = z.object({
+    regions: sceneRegionsSchema,
+});
 /**
  * Authenticate a read request with a project API key (`x-api-key`). Returns the
- * resolved project id, or sends a 401 and returns `null`. Reads are always scoped
- * to the authenticated project — any client-supplied project id is ignored.
+ * resolved project id, or sends a 401/403 and returns `null`. Reads are always
+ * scoped to the authenticated project — any client-supplied project id is
+ * ignored — and require a `query`-capable key.
  */
 async function authProject(request, reply, store) {
-    const key = request.headers["x-api-key"];
-    if (typeof key !== "string" || key.length === 0) {
-        await reply.code(401).send({ error: "missing api key" });
-        return null;
-    }
-    const projectId = await store.resolveApiKey(key);
-    if (!projectId) {
-        await reply.code(401).send({ error: "invalid api key" });
-        return null;
-    }
-    // Read endpoints require a `query`-capable key (ingest-only keys cannot read).
-    if (projectId.capability !== "query") {
-        await reply.code(403).send({ error: "api key not permitted to read" });
-        return null;
-    }
-    return projectId.projectId;
+    const resolved = await requireCapability(request, reply, store, "query");
+    return resolved?.projectId ?? null;
 }
+/**
+ * Audit-log query params: an optional epoch-ms range and a bounded row cap.
+ */
+const auditQueryParams = z.object({
+    since: z.coerce.number().int().optional(),
+    until: z.coerce.number().int().optional(),
+    limit: z.coerce.number().int().positive().max(1000).optional(),
+});
 /**
  * Query API. All aggregations are computed at query time (v1). Every route is
  * scoped to the authenticated project.
  */
 export const queryRoutes = async (app, { store, config }) => {
     const r = app.withTypeProvider();
-    r.get("/api/v1/sessions", { schema: { querystring: sessionsQueryParams } }, async (req, reply) => {
+    // --- format=table | summary (ADR 0051 §2, design sketch §B.1) ------------
+    //
+    // The whole envelope feature lives in this one hook. It runs after a handler
+    // has produced its rows and before the response schema serialises them, which
+    // is the only place that can see *every* registry endpoint's result without
+    // any of the 67 handlers knowing the feature exists — exactly the "keep the
+    // Fastify layer thin" rule (ADR 0005). The shaping itself is
+    // `@uptimizr/db`'s: `tableResult` / `summarizeRows` are pure, registry-driven
+    // functions with no store or request in sight.
+    //
+    // Four conditions have to hold before anything is touched, and the first of
+    // them is the promise that this feature is invisible by default: no `format`,
+    // or `format=full`, returns the payload untouched, so the dashboard — which
+    // never sends the parameter — cannot be affected. The non-metric routes below
+    // (`/whoami`, `/audit`) describe the *calling key* rather than project
+    // telemetry; they are not in `METRIC_BY_PATH`, so the hook passes their
+    // payloads straight through (asserted in `resultFormat.test.ts`).
+    app.addHook("preSerialization", async (request, reply, payload) => {
+        if (reply.statusCode !== 200)
+            return payload;
+        const format = request.query?.format;
+        if (format == null || format === "full")
+            return payload;
+        const metric = METRIC_BY_PATH.get(request.routeOptions.url ?? "");
+        // Not a registry metric (the raw event stream, which has carried its own
+        // `format=json|ndjson` since long before this; `/whoami`; `/audit`), or one
+        // of the two **resource** reads. A resource is a single stored record rather
+        // than an aggregation: it declares no filters, no querystring schema — so a
+        // stray `?format=` would arrive unvalidated — and has nothing to summarise.
+        if (metric == null || metric.builder == null)
+            return payload;
+        // A single-row endpoint (the spatial `stats` routes) still summarises as a
+        // one-row result; `null` never happens on a 200 but costs nothing to guard.
+        const rows = (Array.isArray(payload) ? payload : payload == null ? [] : [payload]);
+        const context = summaryContextFor(metric, request);
+        const shaped = format === "table"
+            ? tableResult(metric, rows, context)
+            : summarizeRows(metric, rows, context);
+        // `null` only comes back for an unknown metric, which `METRIC_BY_PATH`
+        // already excluded — fall back to the raw rows rather than fail the request.
+        return shaped ?? payload;
+    });
+    // --- Key identity + audit (#309, ADR 0051 §7) ----------------------------
+    // What is this key allowed to do? Agent clients (and the MCP server) call it
+    // first so they can register only the tools their capabilities permit. It
+    // reports the key's *id*, never the key itself.
+    r.get("/api/v1/whoami", async (req, reply) => {
+        const resolved = await requireCapability(req, reply, store, "query");
+        if (!resolved)
+            return reply;
+        return {
+            projectId: resolved.projectId,
+            keyId: resolved.keyId,
+            capabilities: resolved.capabilities,
+            label: resolved.label,
+            rateLimit: resolved.rateLimit ?? {
+                max: config.rateLimitMax,
+                windowMs: config.rateLimitWindowMs,
+            },
+            /** Whether {@link rateLimit} is the key's own budget or the collector default. */
+            rateLimitSource: resolved.rateLimit ? "key" : "default",
+        };
+    });
+    // The project's agent-audit trail, newest first. Reading it needs the ordinary
+    // `query` capability — it is the project owner's window onto what every agent
+    // key has asked for. Rows carry no key material and bounded, redacted params.
+    r.get("/api/v1/audit", { schema: { querystring: auditQueryParams } }, async (req, reply) => {
+        const projectId = await authProject(req, reply, store);
+        if (!projectId)
+            return reply;
+        const rows = await store.listAudit(projectId, req.query);
+        return rows.map((row) => ({ ...row, at: row.at.toISOString() }));
+    });
+    r.get("/api/v1/sessions", {
+        schema: { querystring: sessionsQueryParams, response: { 200: rowsFor("/api/v1/sessions") } },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
         const { cameraMode, ...rest } = req.query;
         return store.listSessions(projectId, { ...rest, cameraType: cameraTypeForMode(cameraMode) });
     });
-    r.get("/api/v1/heatmaps/pointer", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/pointer", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/pointer") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -503,16 +820,24 @@ export const queryRoutes = async (app, { store, config }) => {
             return reply;
         return store.meshUvHeatmap(projectId, req.query);
     });
-    r.get("/api/v1/heatmaps/world", { schema: { querystring: worldHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/world", {
+        schema: {
+            querystring: worldHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/world"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        const { cameraMode, region, cellSize, ...rest } = req.query;
+        const { cameraMode, region: regionParam, cellSize, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
         const resolved = await resolveSpatialCellSize(store, projectId, {
             cellSize,
             scene: rest.scene,
             region,
-        });
+        }, req);
         return store.worldHeatmap(projectId, {
             ...rest,
             region,
@@ -524,16 +849,24 @@ export const queryRoutes = async (app, { store, config }) => {
     // the truncated top-N voxels, so the viewer can report coverage/cold-spots and
     // "showing top N of M cells". Echoes the effective (possibly bounds-derived)
     // cellSize so the caller can label its own grid.
-    r.get("/api/v1/heatmaps/world/stats", { schema: { querystring: worldStatsQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/world/stats", {
+        schema: {
+            querystring: worldStatsQueryParams,
+            response: { 200: statsRowFor("/api/v1/heatmaps/world/stats"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        const { cameraMode, region, cellSize, ...rest } = req.query;
+        const { cameraMode, region: regionParam, cellSize, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
         const resolved = await resolveSpatialCellSize(store, projectId, {
             cellSize,
             scene: rest.scene,
             region,
-        });
+        }, req);
         const stats = await store.worldHeatmapStats(projectId, {
             ...rest,
             region,
@@ -544,16 +877,24 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // World-space gaze heatmap (ADR 0030) — the "what did people actually look at"
     // sibling of the world (click) heatmap: voxel-binned `camera_sample` gaze hits.
-    r.get("/api/v1/heatmaps/gaze", { schema: { querystring: gazeHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/gaze", {
+        schema: {
+            querystring: gazeHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/gaze"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        const { cameraMode, region, cellSize, ...rest } = req.query;
+        const { cameraMode, region: regionParam, cellSize, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
         const resolved = await resolveSpatialCellSize(store, projectId, {
             cellSize,
             scene: rest.scene,
             region,
-        });
+        }, req);
         return store.gazeHeatmap(projectId, {
             ...rest,
             region,
@@ -562,16 +903,24 @@ export const queryRoutes = async (app, { store, config }) => {
         });
     });
     // Gaze heatmap totals (ADR 0040 §3) — gaze sibling of the world stats route.
-    r.get("/api/v1/heatmaps/gaze/stats", { schema: { querystring: gazeStatsQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/gaze/stats", {
+        schema: {
+            querystring: gazeStatsQueryParams,
+            response: { 200: statsRowFor("/api/v1/heatmaps/gaze/stats"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        const { cameraMode, region, cellSize, ...rest } = req.query;
+        const { cameraMode, region: regionParam, cellSize, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
         const resolved = await resolveSpatialCellSize(store, projectId, {
             cellSize,
             scene: rest.scene,
             region,
-        });
+        }, req);
         const stats = await store.gazeHeatmapStats(projectId, {
             ...rest,
             region,
@@ -580,7 +929,12 @@ export const queryRoutes = async (app, { store, config }) => {
         });
         return { cellSize: resolved ?? 0.5, cells: stats.cells, hits: stats.hits };
     });
-    r.get("/api/v1/heatmaps/camera", { schema: { querystring: cameraHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/camera", {
+        schema: {
+            querystring: cameraHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/camera") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -591,7 +945,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // saw, bucketed across sessions (0–25 / 25–50 / 50–75 / 75–100%). Derived from
     // the same `camera_sample` direction grid as the view-direction dome; no schema
     // change. Shares the camera-heatmap params (bins + scene/session + cameraMode).
-    r.get("/api/v1/coverage/view-histogram", { schema: { querystring: cameraHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/coverage/view-histogram", {
+        schema: {
+            querystring: cameraHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/coverage/view-histogram") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -603,18 +962,33 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Floor-plan camera-position heatmap (ADR 0026) — the first-person analog of
     // the 2D pointer heatmap: where visitors stand/dwell on the X/Z ground plane.
-    r.get("/api/v1/heatmaps/position", { schema: { querystring: cameraPositionQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/position", {
+        schema: {
+            querystring: cameraPositionQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/position"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        const { cameraMode, ...rest } = req.query;
+        const { cameraMode, region: regionParam, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
         return store.cameraPositionHeatmap(projectId, {
             ...rest,
+            region,
             cameraType: cameraTypeForMode(cameraMode),
         });
     });
     // One session's ordered walked path (ADR 0026) — camera positions, oldest first.
-    r.get("/api/v1/sessions/:sessionId/trajectory", { schema: { params: sessionPathParams, querystring: trajectoryQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/sessions/:sessionId/trajectory", {
+        schema: {
+            params: sessionPathParams,
+            querystring: trajectoryQueryParams,
+            response: { 200: rowsFor("/api/v1/sessions/:sessionId/trajectory") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -623,7 +997,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Aggregate desire lines (#73, ADR 0037) — every session's camera path binned
     // onto the ground grid and returned as ordered, session-keyed points; the
     // dashboard overlays many low-opacity poly-lines into a crowd-level route map.
-    r.get("/api/v1/paths", { schema: { querystring: aggregatePathQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/paths", {
+        schema: {
+            querystring: aggregatePathQueryParams,
+            response: { 200: rowsFor("/api/v1/paths") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -634,7 +1013,12 @@ export const queryRoutes = async (app, { store, config }) => {
         });
     });
     // View-gated click rays (design §7.2/§7.3) — camera-origin → hit rays per voxel/mesh.
-    r.get("/api/v1/heatmaps/click-rays", { schema: { querystring: clickRayQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/click-rays", {
+        schema: {
+            querystring: clickRayQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/click-rays") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -642,7 +1026,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Aggregate gaze→mesh flow links (design §7.5): direction bins → clicked meshes.
     // Position-aware mode (§7.8): a standpoint voxel dimension for walkable scenes.
-    r.get("/api/v1/heatmaps/flow", { schema: { querystring: flowHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/flow", {
+        schema: {
+            querystring: flowHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/flow") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -656,7 +1045,12 @@ export const queryRoutes = async (app, { store, config }) => {
                 : undefined,
         });
     });
-    r.get("/api/v1/meshes/top", { schema: { querystring: sessionScopedRangeQuery } }, async (req, reply) => {
+    r.get("/api/v1/meshes/top", {
+        schema: {
+            querystring: sessionScopedRangeQuery,
+            response: { 200: rowsFor("/api/v1/meshes/top") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -665,7 +1059,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Per-mesh source split (#74) — the most-interacted-mesh tally broken out by
     // the input `source` that drove each interaction; the leaderboard reads both
     // rank (sum across sources) and the per-row breakdown from this one query.
-    r.get("/api/v1/meshes/sources", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/meshes/sources", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/meshes/sources") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -674,7 +1073,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Per-mesh interaction trend (#74) — the most-interacted-mesh tally bucketed
     // into fixed `interval`-second windows so the leaderboard can draw a per-mesh
     // sparkline and a rising/falling delta over the active range.
-    r.get("/api/v1/meshes/trend", { schema: { querystring: meshTrendQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/meshes/trend", {
+        schema: {
+            querystring: meshTrendQueryParams,
+            response: { 200: rowsFor("/api/v1/meshes/trend") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -682,7 +1086,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Object dwell ranking (#37) — per-mesh attention from `mesh_visibility`
     // summaries (total visible/centered time, peak screen fraction).
-    r.get("/api/v1/meshes/dwell", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/meshes/dwell", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/meshes/dwell") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -692,7 +1101,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // cross-referenced against `mesh_interaction` + `hover_dwell` engagement.
     // Surfaces objects that render but are never noticed (the inverse of the
     // most-interacted / part-popularity leaderboards).
-    r.get("/api/v1/meshes/blind-spots", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/meshes/blind-spots", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/meshes/blind-spots") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -701,7 +1115,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Interaction-kind breakdown (#72, ADR 0023) — per-mesh counts of each
     // interaction kind (hover / pick / click / drag / …) from `mesh_interaction`
     // events; how an audience acts on objects, not just which ones draw attention.
-    r.get("/api/v1/meshes/kinds", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/meshes/kinds", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/meshes/kinds") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -710,7 +1129,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Reachability report (#151) — per-mesh histogram of the standpoint→interaction
     // distance (ASOF-joins `mesh_interaction` world points to the nearest preceding
     // `camera_sample`). Far bands flag meshes/UI reached from an uncomfortable range.
-    r.get("/api/v1/meshes/reachability", { schema: { querystring: reachabilityQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/meshes/reachability", {
+        schema: {
+            querystring: reachabilityQueryParams,
+            response: { 200: rowsFor("/api/v1/meshes/reachability") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -718,7 +1142,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Dead-click rate (#46) — total clicks vs. clicks that hit empty space; a 3D
     // discoverability signal. The consumer derives the rate from the two counts.
-    r.get("/api/v1/clicks/dead", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/clicks/dead", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/clicks/dead") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -726,7 +1155,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Rage clicks (#47) — rapid repeated clicks on the same mesh within a short
     // window; a frustration signal derived from the click stream.
-    r.get("/api/v1/clicks/rage", { schema: { querystring: rageClickQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/clicks/rage", {
+        schema: {
+            querystring: rageClickQueryParams,
+            response: { 200: rowsFor("/api/v1/clicks/rage") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -734,7 +1168,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Hover hesitation (#48) — per-mesh dwell spent hovering an object without
     // clicking it; flags things that look interactive but aren't.
-    r.get("/api/v1/hover/dwell", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/hover/dwell", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/hover/dwell") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -742,7 +1181,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Compile stalls (#42) — per-phase shader/pipeline compilation hitches; the
     // felt first-interaction jank that `frame_perf` averages away.
-    r.get("/api/v1/perf/compile-stalls", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/compile-stalls", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/compile-stalls") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -757,7 +1201,12 @@ export const queryRoutes = async (app, { store, config }) => {
             return reply;
         return store.arPlacementTimeToPlace(projectId, req.query);
     });
-    r.get("/api/v1/ar/placement/attempts", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/ar/placement/attempts", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/ar/placement/attempts") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -769,7 +1218,9 @@ export const queryRoutes = async (app, { store, config }) => {
             return reply;
         return store.arPlacementSurfaces(projectId, req.query);
     });
-    r.get("/api/v1/perf", { schema: { querystring: sessionScopedRangeQuery } }, async (req, reply) => {
+    r.get("/api/v1/perf", {
+        schema: { querystring: sessionScopedRangeQuery, response: { 200: rowsFor("/api/v1/perf") } },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -778,7 +1229,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Render-scale truth (#71, ADR 0021) — the FPS headline paired with the
     // resolution the engine actually rendered at, so "good FPS" can be read against
     // the render scale an adaptive renderer bought it with.
-    r.get("/api/v1/perf/render-scale", { schema: { querystring: sessionScopedRangeQuery } }, async (req, reply) => {
+    r.get("/api/v1/perf/render-scale", {
+        schema: {
+            querystring: sessionScopedRangeQuery,
+            response: { 200: rowsFor("/api/v1/perf/render-scale") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -786,7 +1242,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Resource footprint (#44) — GPU / memory cost summary (avg + peak texture/
     // geometry bytes, triangles/vertices, JS heap) the scene asked of the device.
-    r.get("/api/v1/perf/resources", { schema: { querystring: sessionScopedRangeQuery } }, async (req, reply) => {
+    r.get("/api/v1/perf/resources", {
+        schema: {
+            querystring: sessionScopedRangeQuery,
+            response: { 200: rowsFor("/api/v1/perf/resources") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -795,7 +1256,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // FPS distribution (#81, ADR 0028 §1) — per-session p05/p50/p95 FPS summarized
     // across sessions (median-of-medians); the distribution-honest headline that
     // replaces the volume-chart mean.
-    r.get("/api/v1/perf/distribution", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/distribution", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/distribution") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -803,7 +1269,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // FPS histogram (#81, ADR 0028 §1) — per-session median FPS bucketed into
     // `bucket`-wide bins; one session = one data point.
-    r.get("/api/v1/perf/fps-histogram", { schema: { querystring: fpsHistogramQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/fps-histogram", {
+        schema: {
+            querystring: fpsHistogramQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/fps-histogram") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -811,7 +1282,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Frame-time percentiles (#81, ADR 0028 §1) — per-session median frame time and
     // worst-window p95 (ms), summarized across sessions.
-    r.get("/api/v1/perf/frame-time", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/frame-time", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/frame-time") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -819,7 +1295,9 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Jank rate (#81, ADR 0028 §1) — per-session long-frames-per-window rate,
     // reported as the median and worst-decile session.
-    r.get("/api/v1/perf/jank", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/jank", {
+        schema: { querystring: heatmapQueryParams, response: { 200: rowsFor("/api/v1/perf/jank") } },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -828,7 +1306,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Perf-correlated churn (#144) — of the sessions that ended in range, how many
     // ended within `windowMs` of an FPS dip or a compile_stall, with the cause
     // attributed. Does a stutter actually cost sessions?
-    r.get("/api/v1/perf/churn", { schema: { querystring: perfChurnQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/churn", {
+        schema: {
+            querystring: perfChurnQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/churn") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -837,14 +1320,24 @@ export const queryRoutes = async (app, { store, config }) => {
     // FPS by device class (#82, ADR 0028 §2; #11, ADR 0041) — per-session median FPS
     // attributed to the `session_start.device` block (backend / mobile / GPU
     // renderer) plus the coarse browser/OS derived from the User-Agent at ingestion.
-    r.get("/api/v1/perf/by-device", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/by-device", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/by-device") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
         return store.perfByDevice(projectId, req.query);
     });
     // FPS by scene (#82, ADR 0028 §1) — per-session median FPS grouped by scene.
-    r.get("/api/v1/perf/by-scene", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/by-scene", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/by-scene") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -852,7 +1345,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Resource-footprint percentiles (#83, ADR 0028 §1) — per-session p50/p95 of JS
     // heap, texture bytes, and triangle count, summarized across sessions.
-    r.get("/api/v1/perf/resource-percentiles", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/resource-percentiles", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/resource-percentiles") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -860,7 +1358,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Stability incidents (#83) — context-loss and compile-stall counts over the
     // range; the hard failures `frame_perf` cannot show.
-    r.get("/api/v1/perf/stability", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/perf/stability", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/perf/stability") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -870,7 +1373,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // incident counts crossed by (severity, category, backend) over the range,
     // folding discrete markers and per-session rollups into the same counters.
     // Capture is off by default, so an empty result is the common (clean) case.
-    r.get("/api/v1/graphics-diagnostics", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/graphics-diagnostics", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/graphics-diagnostics") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -881,11 +1389,20 @@ export const queryRoutes = async (app, { store, config }) => {
     // things break (clustering around geometry, shader-heavy areas, a level
     // region). severity/category narrow to engine diagnostics, errorKind to JS
     // errors. Only events carrying a best-effort position participate.
-    r.get("/api/v1/heatmaps/errors", { schema: { querystring: errorHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/errors", {
+        schema: {
+            querystring: errorHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/errors"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        return store.errorHeatmap(projectId, req.query);
+        const { region: regionParam, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
+        return store.errorHeatmap(projectId, { ...rest, region });
     });
     // Guardian/boundary-touch heatmap (#157, ADR 0048) — voxel-binned world
     // `position` of `xr_boundary_proximity` events: *where* in the play space the
@@ -894,30 +1411,46 @@ export const queryRoutes = async (app, { store, config }) => {
     // position + duration each approach carries participate (ADR 0003 / ADR 0048).
     // Reuses the world-heatmap voxel path; cellSize resolves from scene/region
     // bounds when unset so the stats endpoint can echo it.
-    r.get("/api/v1/heatmaps/boundary", { schema: { querystring: boundaryHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/boundary", {
+        schema: {
+            querystring: boundaryHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/boundary"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        const { region, cellSize, ...rest } = req.query;
+        const { region: regionParam, cellSize, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
         const resolved = await resolveSpatialCellSize(store, projectId, {
             cellSize,
             scene: rest.scene,
             region,
-        });
+        }, req);
         return store.boundaryHeatmap(projectId, { ...rest, region, cellSize: resolved });
     });
     // Boundary-touch heatmap totals (ADR 0040 §3) — true occupied-cell + contact
     // counts behind the truncated top-N voxels, echoing the effective cellSize.
-    r.get("/api/v1/heatmaps/boundary/stats", { schema: { querystring: boundaryStatsQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/boundary/stats", {
+        schema: {
+            querystring: boundaryStatsQueryParams,
+            response: { 200: statsRowFor("/api/v1/heatmaps/boundary/stats"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
-        const { region, cellSize, ...rest } = req.query;
+        const { region: regionParam, cellSize, ...rest } = req.query;
+        const region = await resolveRegionFilter(store, projectId, rest.scene, regionParam);
+        if (isRegionError(region))
+            return reply.code(400).send(region);
         const resolved = await resolveSpatialCellSize(store, projectId, {
             cellSize,
             scene: rest.scene,
             region,
-        });
+        }, req);
         const stats = await store.boundaryHeatmapStats(projectId, {
             ...rest,
             region,
@@ -929,7 +1462,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // crossed by (api, backend, api_version, shading_language) from
     // `session_start.graphics`. Always-on (unlike diagnostics), so a populated
     // result is the common case.
-    r.get("/api/v1/rendering-technology", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/rendering-technology", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/rendering-technology") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -938,7 +1476,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Capability changes (#49) — per-transition fallback/recovery counts (e.g. how
     // many sessions fell back WebGPU→WebGL2); explains perf / visual-fidelity
     // variance across the user base. App-reported via reportCapabilityChange.
-    r.get("/api/v1/capabilities", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/capabilities", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/capabilities") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -947,7 +1490,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Camera gestures (ADR 0025) — per-kind navigation breakdown (orbit / pan /
     // dolly / zoom / roll / fly) separating deliberate viewpoint movement from
     // object selection; reveals how an audience explores the scene.
-    r.get("/api/v1/camera-gestures", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/camera-gestures", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/camera-gestures") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -955,7 +1503,9 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Scene coverage / dead zones (derived, scene-metrics §B) — occupied
     // camera-position voxels; coverage % is layered in against the scene AABB.
-    r.get("/api/v1/coverage", { schema: { querystring: coverageQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/coverage", {
+        schema: { querystring: coverageQueryParams, response: { 200: rowsFor("/api/v1/coverage") } },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -963,7 +1513,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Spatial FPS heatmap (#145) — where FPS is bad in world space: frame_perf
     // samples voxel-binned by their captured camera position (avg/min FPS per cell).
-    r.get("/api/v1/heatmaps/perf", { schema: { querystring: perfHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/heatmaps/perf", {
+        schema: {
+            querystring: perfHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/heatmaps/perf") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -971,7 +1526,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Camera distance / zoom distribution (derived, scene-metrics §B) — histogram of
     // camera-to-center distance. The center defaults to the origin when omitted.
-    r.get("/api/v1/camera/distance", { schema: { querystring: cameraDistanceQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/camera/distance", {
+        schema: {
+            querystring: cameraDistanceQueryParams,
+            response: { 200: rowsFor("/api/v1/camera/distance") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -983,7 +1543,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Navigation effort / friction (derived, scene-metrics §B) — per-session travel
     // distance with active-vs-idle segmentation.
-    r.get("/api/v1/navigation", { schema: { querystring: navigationQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/navigation", {
+        schema: {
+            querystring: navigationQueryParams,
+            response: { 200: rowsFor("/api/v1/navigation") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -992,7 +1557,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Path-retrace / backtracking ratio (#153) — per-scene leaderboard of how often
     // visitors re-walk a coarse grid cell (the confusion / unclear-signage signal),
     // derived from the same camera-position stream as desire lines.
-    r.get("/api/v1/backtrack", { schema: { querystring: backtrackQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/backtrack", {
+        schema: {
+            querystring: backtrackQueryParams,
+            response: { 200: rowsFor("/api/v1/backtrack") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1000,7 +1570,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // XR motion-sickness proxy (#50, scene-metrics §F) — per-session head/view
     // rotation rate over the camera pose stream; rapid rotation flags discomfort.
-    r.get("/api/v1/xr/rotation", { schema: { querystring: xrRotationQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/xr/rotation", {
+        schema: {
+            querystring: xrRotationQueryParams,
+            response: { 200: rowsFor("/api/v1/xr/rotation") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1008,7 +1583,9 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // XR input-source usage (#50, scene-metrics §F) — hand vs. controller (vs.
     // gaze) split read from `source` on the interaction events.
-    r.get("/api/v1/xr/sources", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/xr/sources", {
+        schema: { querystring: heatmapQueryParams, response: { 200: rowsFor("/api/v1/xr/sources") } },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1016,7 +1593,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // XR session abandonment (#50, scene-metrics §F) — per XR session, its time
     // bounds and event/interaction counts; a short span signals headset drop-off.
-    r.get("/api/v1/xr/abandonment", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/xr/abandonment", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/xr/abandonment") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1025,7 +1607,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // XR locomotion & comfort (#148) — per XR session, its locomotion-style mix
     // (fly / navigate / teleport + duration) and wall-clock span, so heavy
     // locomotion can be correlated with early exits (a discomfort proxy).
-    r.get("/api/v1/xr/locomotion", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/xr/locomotion", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/xr/locomotion") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1036,7 +1623,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // the near-boundary zone. A room-scale comfort signal beside VR locomotion;
     // frequent contact means the physical space didn't fit the experience. Built
     // from `xr_boundary_proximity` (one event per approach) — no room geometry.
-    r.get("/api/v1/xr/boundary-contacts", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/xr/boundary-contacts", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/xr/boundary-contacts") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1045,7 +1637,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // XR tracking quality (#155, ADR 0048) — per XR session that reported a
     // tracking transition, how much of the session ran with degraded / lost
     // spatial tracking, split by hand vs. controller (a tracking-quality timeline).
-    r.get("/api/v1/xr/tracking", { schema: { querystring: heatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/xr/tracking", {
+        schema: {
+            querystring: heatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/xr/tracking") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1054,7 +1651,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Input-source breakdown (ADR 0011) — per (event_type, source), how many
     // interactions came from each input source (mouse / touch / xr-controller /
     // hand / …) and across how many sessions. Turns `source` into an insight.
-    r.get("/api/v1/interactions/sources", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/interactions/sources", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/interactions/sources") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1063,7 +1665,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Most-used shortcuts / actions (#75, ADR 0023) — rank `input_action` events by
     // their app-level `action` label, split by `source` (keyboard / gamepad / …).
     // Pairs with the input-source breakdown for the input-modality panel.
-    r.get("/api/v1/input-actions/top", { schema: { querystring: pointerHeatmapQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/input-actions/top", {
+        schema: {
+            querystring: pointerHeatmapQueryParams,
+            response: { 200: rowsFor("/api/v1/input-actions/top") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1077,14 +1684,24 @@ export const queryRoutes = async (app, { store, config }) => {
         return store.scenes(projectId, req.query);
     });
     // Event-volume time-series (the 4th dimension) — bucketed event counts + FPS.
-    r.get("/api/v1/timeseries", { schema: { querystring: timeseriesQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/timeseries", {
+        schema: {
+            querystring: timeseriesQueryParams,
+            response: { 200: rowsFor("/api/v1/timeseries") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
         return store.timeseries(projectId, req.query);
     });
     // Per-event-type counts over the range — powers the scene health panel.
-    r.get("/api/v1/event-counts", { schema: { querystring: eventCountsQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/event-counts", {
+        schema: {
+            querystring: eventCountsQueryParams,
+            response: { 200: rowsFor("/api/v1/event-counts") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1095,7 +1712,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // of step predicates, validated against the shared `funnelStepsSchema`; the
     // OSS dashboard is a passive viewer, so steps are supplied by the caller
     // (CLI / hosted), never authored or persisted here.
-    r.get("/api/v1/funnel", { schema: { querystring: funnelQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/funnel", {
+        schema: {
+            querystring: funnelQueryParams,
+            response: { 200: rowsFor("/api/v1/funnel"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1108,7 +1730,9 @@ export const queryRoutes = async (app, { store, config }) => {
         }
         const result = funnelStepsSchema.safeParse(parsed);
         if (!result.success) {
-            return reply.code(400).send({ error: "invalid funnel steps", details: result.error.issues });
+            return reply
+                .code(400)
+                .send({ error: "invalid funnel steps", details: result.error.issues });
         }
         const { since, until, scene, cameraMode } = req.query;
         return store.funnel(projectId, {
@@ -1122,7 +1746,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // Canned scene/level retention funnel (#147) — session counts flowing scene →
     // scene in observed order, built directly from `scene_change` markers with no
     // caller-authored steps (the zero-config complement to `/api/v1/funnel`).
-    r.get("/api/v1/scene-retention", { schema: { querystring: sceneRetentionQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/scene-retention", {
+        schema: {
+            querystring: sceneRetentionQueryParams,
+            response: { 200: rowsFor("/api/v1/scene-retention") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1134,7 +1763,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // `bands` are optional caller-supplied ascending ms boundaries; the store
     // applies a sensible default when omitted. Derived from existing events — no
     // schema change.
-    r.get("/api/v1/load-bounce", { schema: { querystring: loadBounceQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/load-bounce", {
+        schema: {
+            querystring: loadBounceQueryParams,
+            response: { 200: rowsFor("/api/v1/load-bounce") },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1147,7 +1781,12 @@ export const queryRoutes = async (app, { store, config }) => {
     // the next switch/conversion. `variant`/`conversion` are JSON-encoded step
     // predicates validated against the shared `funnelStepSchema`; like the funnel,
     // OSS is a passive viewer and the caller supplies them (ADR 0038).
-    r.get("/api/v1/variant-leaderboard", { schema: { querystring: variantLeaderboardQueryParams } }, async (req, reply) => {
+    r.get("/api/v1/variant-leaderboard", {
+        schema: {
+            querystring: variantLeaderboardQueryParams,
+            response: { 200: rowsFor("/api/v1/variant-leaderboard"), 400: badRequestResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1200,12 +1839,20 @@ export const queryRoutes = async (app, { store, config }) => {
             querystring: z.object({ format: z.enum(["json", "ndjson"]).optional() }),
         },
     }, async (req, reply) => {
-        const projectId = await authProject(req, reply, store);
-        if (!projectId)
+        // Raw per-session data needs BOTH halves of the gate (ADR 0051 §7):
+        // retention enabled on the collector AND `query:raw` on the key. A plain
+        // `query` key is authenticated (so an unknown key still gets a 401) but
+        // refused the raw stream even when retention is on.
+        const resolved = await requireCapability(req, reply, store, "query");
+        if (!resolved)
             return reply;
         if (!config.enableRawSessionRetention) {
             return reply.code(403).send({ error: "raw session retention is disabled" });
         }
+        if (!resolved.capabilities.includes("query:raw")) {
+            return reply.code(403).send({ error: "api key not permitted to read raw session data" });
+        }
+        const projectId = resolved.projectId;
         const accept = req.headers.accept ?? "";
         const wantsNdjson = req.query.format === "ndjson" || accept.includes("application/x-ndjson");
         if (!wantsNdjson) {
@@ -1223,7 +1870,12 @@ export const queryRoutes = async (app, { store, config }) => {
     });
     // Coarse session descriptor (device/scene/anonymized user). Not raw data, so it
     // is not gated by raw-session retention.
-    r.get("/api/v1/sessions/:id/meta", { schema: { params: z.object({ id: z.string().min(1) }) } }, async (req, reply) => {
+    r.get("/api/v1/sessions/:id/meta", {
+        schema: {
+            params: z.object({ id: z.string().min(1) }),
+            response: { 200: singleRowFor("/api/v1/sessions/:id/meta"), 404: notFoundResponse },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1252,7 +1904,15 @@ export const queryRoutes = async (app, { store, config }) => {
         return store.putSceneProxy(projectId, req.body.proxy, req.body.label);
     });
     // Fetch one scene's representation (including the proxy blob), or 404.
-    r.get("/api/v1/scenes/:sceneId/representation", { schema: { params: sceneParams } }, async (req, reply) => {
+    r.get("/api/v1/scenes/:sceneId/representation", {
+        schema: {
+            params: sceneParams,
+            response: {
+                200: singleRowFor("/api/v1/scenes/:sceneId/representation"),
+                404: notFoundResponse,
+            },
+        },
+    }, async (req, reply) => {
         const projectId = await authProject(req, reply, store);
         if (!projectId)
             return reply;
@@ -1261,5 +1921,42 @@ export const queryRoutes = async (app, { store, config }) => {
             return reply.code(404).send({ error: "scene representation not found" });
         return representation;
     });
+    // --- Scene regions (ADR 0051 §2 / sketch §B.2) ---------------------------
+    //
+    // Named, labelled boxes that give a scene a vocabulary for *where* — so a
+    // spatial answer can say "the checkout counter" instead of a voxel centre, and
+    // `?region=<id>` can drill a heatmap into that place by name.
+    //
+    // AUTH: the two **reads** take a `query`-capable key, like every other read.
+    // The **write** takes an `annotate`-capable key (#309, ADR 0051 §5/§7) — the
+    // dedicated metadata-write capability, so a read-only key handed to an agent
+    // cannot redraw the project's spatial vocabulary. `annotate` is a write
+    // capability only: mint `query,annotate` for a client that both declares
+    // regions and reads them back.
+    // List every region the project has declared, across all scenes (names only,
+    // no boxes) — the whole spatial vocabulary in one read, for a region picker or
+    // an agent's project context. The sibling of `/scene-representations`.
+    r.get("/api/v1/scene-regions", async (req, reply) => {
+        const projectId = await authProject(req, reply, store);
+        if (!projectId)
+            return reply;
+        return store.listSceneRegions(projectId);
+    });
+    // Declare a scene's regions, replacing whatever was stored for that scene.
+    r.put("/api/v1/scenes/:sceneId/regions", { schema: { params: sceneParams, body: putRegionsBody } }, async (req, reply) => {
+        const resolved = await requireCapability(req, reply, store, "annotate");
+        if (!resolved)
+            return reply;
+        return store.putSceneRegions(resolved.projectId, req.params.sceneId, req.body.regions);
+    });
+    // Read one scene's regions. An unregistered scene is an empty set, not a 404 —
+    // "this scene has no regions" is a normal answer, and the caller need not know
+    // whether the scene was ever registered.
+    r.get("/api/v1/scenes/:sceneId/regions", { schema: { params: sceneParams } }, async (req, reply) => {
+        const projectId = await authProject(req, reply, store);
+        if (!projectId)
+            return reply;
+        return store.getSceneRegions(projectId, req.params.sceneId);
+    });
 };
 //# sourceMappingURL=query.js.map