@uptimizr/db 2.0.1 → 2.1.0

package/dist/metadata.js

@@ -7,6 +7,7 @@
  * once and OSS carries no Postgres dependency.
  */
 import { createHash, randomBytes } from "node:crypto";
+import { LIMITS } from "@uptimizr/schema";
 // --- API keys (pure crypto) ---
 /** SHA-256 hash of an API key. Only the hash is ever stored (never plaintext). */
 export function hashApiKey(plaintext) {
@@ -212,4 +213,83 @@ export function clampAuditTool(toolOrPath) {
         ? toolOrPath.slice(0, AUDIT_TOOL_MAX_LENGTH)
         : toolOrPath;
 }
+/**
+ * Per-project row caps (ADR 0051 §5). Metadata is a curated set of notes, so
+ * every store refuses the write that would exceed its table's cap rather than
+ * silently growing. The numbers live in `@uptimizr/schema`'s `LIMITS` with the
+ * rest of the wire bounds; this is the storage-side view of them.
+ */
+export const METADATA_LIMITS = {
+    annotations: LIMITS.maxProjectAnnotations,
+    glossary: LIMITS.maxProjectGlossaryEntries,
+    savedAnalyses: LIMITS.maxProjectSavedAnalyses,
+    panelSpecs: LIMITS.maxProjectPanelSpecs,
+};
+/**
+ * Thrown by a store when a write would take a project past the table's cap.
+ * The collector maps it to `409 Conflict` — the request was well-formed, the
+ * project is simply full, and the caller fixes it by deleting something.
+ */
+export class MetadataLimitError extends Error {
+    table;
+    limit;
+    constructor(table, limit) {
+        super(`project has reached its limit of ${limit} ${table} rows`);
+        this.table = table;
+        this.limit = limit;
+        this.name = "MetadataLimitError";
+    }
+}
+/**
+ * Clamp a caller-supplied `limit` into `[1, max]`, defaulting when absent.
+ * Shared by every store so one engine cannot quietly return more rows than
+ * another for the same request.
+ */
+export function clampMetadataLimit(limit, fallback = 100, max = 500) {
+    if (limit == null || !Number.isFinite(limit))
+        return fallback;
+    return Math.min(Math.max(Math.trunc(limit), 1), max);
+}
+/**
+ * Parse a stored `query` JSON column back into an object. A row written by this
+ * collector always parses; a hand-edited or truncated one degrades to `{}`
+ * rather than failing the whole listing.
+ */
+export function parseSavedAnalysisQuery(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return parsed != null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Parse a stored `spec` JSON column back into a document.
+ *
+ * Returns `null` rather than a partial object when the text is not a JSON
+ * object at all: unlike a saved analysis' opaque `query` — which degrades to
+ * `{}` because it is stored but never interpreted — a panel spec is *rendered*,
+ * so a row that cannot be one is better skipped than drawn. The listing drops
+ * it and the rest of the grid is unaffected, which is the same posture
+ * `loadSpecPanels` takes in `@uptimizr/react`.
+ *
+ * The result is typed as the wire shape but **not** re-validated here: a store
+ * is not the boundary, and re-running Zod on every row of every listing would
+ * pay the validation cost on the read path for a document the write path
+ * already checked. The renderer validates what it is about to draw.
+ */
+export function parsePanelSpec(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return parsed != null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}

package/dist/narrative/build.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `buildSessionNarrative` — the pure compaction behind
+ * `GET /api/v1/sessions/:id/narrative` (ADR 0051 §7, design sketch §G.2).
+ *
+ * It turns one session's raw event stream into an ordered, bounded account of
+ * what that session *did*: where it went, what held its attention, what it
+ * touched, what stuttered, what broke, and how it ended. Timestamps are relative
+ * to the session's first event, every line of prose is templated from the
+ * entry's own fields, and the whole thing is capped by `maxEntries`.
+ *
+ * **Pure.** It takes an `AnyEvent[]` and returns a plain object: no store, no
+ * request, no clock, no I/O. It lives in `@uptimizr/db` rather than in
+ * `@uptimizr/agent-core` because the collector is the only consumer and
+ * `agent-core` must stay browser-safe and driver-free; it is not in
+ * `@uptimizr/metrics` because that package is pure *data*.
+ *
+ * ## What it deliberately leaves out (ADR 0003)
+ *
+ * A narrative is derived from raw per-session data, so the route that serves it
+ * needs both `ENABLE_RAW_SESSION_RETENTION` and a `query:raw` key. The
+ * compaction is the second line of defence: it is an allow-list, not a redactor.
+ * It reads only the fields named below, so nothing else can leak even if a
+ * future event type carries it —
+ *
+ * - **never** `visitorId`, `url` or `pageMeta` (title, referrer, language, …);
+ * - **never** a position, hit point, ray, UV or screen coordinate;
+ * - from `device`/`graphics`, only the rendering `engine` and graphics `api` —
+ *   no renderer string, no vendor, no OS, no browser, no memory or core count;
+ * - from `session_start.user`, nothing at all;
+ * - custom-event property **keys** (developer-chosen field names), never their
+ *   values, unless the caller explicitly passes `includeCustomProps`;
+ * - `runtime_error.message` truncated, and never its `source` (a URL) or
+ *   `stack`;
+ * - `graphics_diagnostic` by `category`/`severity` only — never its message.
+ *
+ * `src/__tests__/narrative.test.ts` asserts the exclusions against a synthetic
+ * session whose every event carries a visitor hash, a URL and page metadata.
+ */
+import { type SessionNarrativeEntry, type SessionNarrativeTotals } from "@uptimizr/metrics";
+import type { AnyEvent } from "@uptimizr/schema";
+/** How to compact a session. Every field has a registry-declared default. */
+export interface SessionNarrativeOptions {
+    /** Dwell floor in ms; a mesh below it is a glance, not attention. */
+    minDwellMs?: number;
+    /** A `frame_perf` sample below this FPS counts towards a dip. */
+    fpsThreshold?: number;
+    /** Hard cap on entries, closing `summary` entry included. */
+    maxEntries?: number;
+    /**
+     * Include custom-event property **values** as well as their keys. Off by
+     * default: a property value is app-supplied and may carry anything, so it is
+     * outside the privacy allow-list unless the operator opts in.
+     */
+    includeCustomProps?: boolean;
+}
+/** An ordered, bounded account of one session. */
+export interface SessionNarrative {
+    /** The session the narrative describes. */
+    sessionId: string;
+    /** Wall-clock start of the session (epoch ms) — the origin `tMs` counts from. */
+    startedAt: number;
+    /** The entries, oldest first, ending with the `summary` entry. */
+    entries: SessionNarrativeEntry[];
+    /** Whether entries were dropped to honour `maxEntries`. */
+    truncated: boolean;
+    /** Session-wide totals, also carried on the closing `summary` entry. */
+    totals: SessionNarrativeTotals;
+}
+/**
+ * Compact one session's events into a narrative.
+ *
+ * `events` may arrive in any order (they are sorted here, stably, so events
+ * sharing a timestamp keep their stream order) and may be empty — an empty
+ * session yields an empty narrative with zeroed totals, which the collector
+ * turns into a 404.
+ */
+export declare function buildSessionNarrative(events: readonly AnyEvent[], options?: SessionNarrativeOptions): SessionNarrative;
+//# sourceMappingURL=build.d.ts.map

package/dist/narrative/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/narrative/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,MAAM,EAAE,sBAAsB,CAAC;CAChC;AA0ED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAsYlB"}

package/dist/narrative/build.js

@@ -0,0 +1,437 @@
+/**
+ * `buildSessionNarrative` — the pure compaction behind
+ * `GET /api/v1/sessions/:id/narrative` (ADR 0051 §7, design sketch §G.2).
+ *
+ * It turns one session's raw event stream into an ordered, bounded account of
+ * what that session *did*: where it went, what held its attention, what it
+ * touched, what stuttered, what broke, and how it ended. Timestamps are relative
+ * to the session's first event, every line of prose is templated from the
+ * entry's own fields, and the whole thing is capped by `maxEntries`.
+ *
+ * **Pure.** It takes an `AnyEvent[]` and returns a plain object: no store, no
+ * request, no clock, no I/O. It lives in `@uptimizr/db` rather than in
+ * `@uptimizr/agent-core` because the collector is the only consumer and
+ * `agent-core` must stay browser-safe and driver-free; it is not in
+ * `@uptimizr/metrics` because that package is pure *data*.
+ *
+ * ## What it deliberately leaves out (ADR 0003)
+ *
+ * A narrative is derived from raw per-session data, so the route that serves it
+ * needs both `ENABLE_RAW_SESSION_RETENTION` and a `query:raw` key. The
+ * compaction is the second line of defence: it is an allow-list, not a redactor.
+ * It reads only the fields named below, so nothing else can leak even if a
+ * future event type carries it —
+ *
+ * - **never** `visitorId`, `url` or `pageMeta` (title, referrer, language, …);
+ * - **never** a position, hit point, ray, UV or screen coordinate;
+ * - from `device`/`graphics`, only the rendering `engine` and graphics `api` —
+ *   no renderer string, no vendor, no OS, no browser, no memory or core count;
+ * - from `session_start.user`, nothing at all;
+ * - custom-event property **keys** (developer-chosen field names), never their
+ *   values, unless the caller explicitly passes `includeCustomProps`;
+ * - `runtime_error.message` truncated, and never its `source` (a URL) or
+ *   `stack`;
+ * - `graphics_diagnostic` by `category`/`severity` only — never its message.
+ *
+ * `src/__tests__/narrative.test.ts` asserts the exclusions against a synthetic
+ * session whose every event carries a visitor hash, a URL and page metadata.
+ */
+import { NARRATIVE_LIMITS, } from "@uptimizr/metrics";
+/** Input sources that mean "this was an immersive XR session" (ADR 0011). */
+const XR_SOURCES = new Set(["xr-controller", "hand", "gaze", "transient"]);
+/** Clamp `value` into `[min, max]`, falling back to `fallback` when absent. */
+function clamp(value, fallback, min, max) {
+    if (value == null || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, value));
+}
+/** Collapse whitespace and cut to `max` characters, marking the cut with `…`. */
+function truncate(text, max = NARRATIVE_LIMITS.maxMessageLength) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+/** `3400` → `"3.4s"`, `900` → `"900ms"` — durations a reader can skim. */
+function humanMs(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const minutes = Math.floor(ms / 60_000);
+    const seconds = Math.round((ms % 60_000) / 1000);
+    return `${minutes}m ${seconds}s`;
+}
+/** A number rendered for prose: one decimal place, no trailing `.0`. */
+function humanNumber(value) {
+    return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+/** `via mouse` / `` — the input source clause, when the event carried one. */
+function sourceClause(source) {
+    return typeof source === "string" && source.length > 0 ? ` via ${source}` : "";
+}
+/** Drop the `undefined` keys so `refs` serialises as only what it really has. */
+function refsOf(refs) {
+    const out = {};
+    if (refs.mesh)
+        out.mesh = refs.mesh;
+    if (refs.scene)
+        out.scene = refs.scene;
+    if (refs.name)
+        out.name = refs.name;
+    return out;
+}
+/**
+ * Compact one session's events into a narrative.
+ *
+ * `events` may arrive in any order (they are sorted here, stably, so events
+ * sharing a timestamp keep their stream order) and may be empty — an empty
+ * session yields an empty narrative with zeroed totals, which the collector
+ * turns into a 404.
+ */
+export function buildSessionNarrative(events, options = {}) {
+    const minDwellMs = clamp(options.minDwellMs, NARRATIVE_LIMITS.defaultMinDwellMs, 0, NARRATIVE_LIMITS.maxMinDwellMs);
+    const fpsThreshold = clamp(options.fpsThreshold, NARRATIVE_LIMITS.defaultFpsThreshold, 1, NARRATIVE_LIMITS.maxFpsThreshold);
+    const maxEntries = Math.round(clamp(options.maxEntries, NARRATIVE_LIMITS.defaultMaxEntries, 1, NARRATIVE_LIMITS.maxMaxEntries));
+    const ordered = [...events]
+        .map((event, index) => ({ event, index }))
+        .sort((a, b) => a.event.ts - b.event.ts || a.index - b.index)
+        .map((entry) => entry.event);
+    const empty = {
+        events: 0,
+        durationMs: 0,
+        scenes: 0,
+        meshes: 0,
+        interactions: 0,
+        dips: 0,
+        errors: 0,
+    };
+    const first = ordered[0];
+    if (!first) {
+        return { sessionId: "", startedAt: 0, entries: [], truncated: false, totals: empty };
+    }
+    const t0 = first.ts;
+    const rel = (ts) => Math.max(0, Math.round(ts - t0));
+    const entries = [];
+    const push = (entry) => {
+        entries.push(entry);
+    };
+    const dwell = new Map();
+    const scenes = new Set();
+    const meshes = new Set();
+    let interactions = 0;
+    let dips = 0;
+    let errors = 0;
+    let dip = null;
+    let xrFirstTMs = null;
+    let xrLastTMs = null;
+    let xrSource = "";
+    let boundaryCount = 0;
+    let boundaryMs = 0;
+    let boundaryTMs = 0;
+    let lastTs = first.ts;
+    /** Fold a dwell contribution for `mesh` into the accumulator. */
+    const addDwell = (mesh, tMs, scene, visibleMs, hoverMs) => {
+        meshes.add(mesh);
+        const existing = dwell.get(mesh);
+        if (existing) {
+            existing.visibleMs += visibleMs;
+            existing.hoverMs += hoverMs;
+            existing.count += 1;
+            if (tMs < existing.tMs)
+                existing.tMs = tMs;
+            return;
+        }
+        dwell.set(mesh, { mesh, scene, tMs, visibleMs, hoverMs, count: 1 });
+    };
+    /** Close the open perf dip, emitting an entry when it is long enough. */
+    const closeDip = () => {
+        if (!dip)
+            return;
+        if (dip.samples >= NARRATIVE_LIMITS.dipMinSamples) {
+            const durationMs = Math.max(0, dip.endTMs - dip.tMs);
+            dips += 1;
+            push({
+                tMs: dip.tMs,
+                kind: "perf_dip",
+                summary: `Frame rate dipped to ${humanNumber(dip.minFps)} fps ` +
+                    `(mean ${humanNumber(dip.totalFps / dip.samples)}) across ${dip.samples} samples` +
+                    (durationMs > 0 ? ` over ${humanMs(durationMs)}.` : "."),
+                refs: refsOf({ scene: dip.scene }),
+                ...(durationMs > 0 ? { durationMs } : {}),
+                count: dip.samples,
+            });
+        }
+        dip = null;
+    };
+    for (const event of ordered) {
+        lastTs = event.ts;
+        const tMs = rel(event.ts);
+        const scene = typeof event.sceneId === "string" ? event.sceneId : undefined;
+        if (scene)
+            scenes.add(scene);
+        // Anything with an XR input source marks the immersive stretch of the
+        // session. There is no explicit "entered XR" event (ADR 0011 models XR as an
+        // input source, not a mode), so the span is derived from the first and last
+        // XR-sourced event.
+        const source = event.source;
+        if (typeof source === "string" && XR_SOURCES.has(source)) {
+            if (xrFirstTMs == null) {
+                xrFirstTMs = tMs;
+                xrSource = source;
+            }
+            xrLastTMs = tMs;
+        }
+        switch (event.type) {
+            case "session_start": {
+                const engine = event.device?.engine;
+                const api = event.graphics?.api;
+                const renderer = engine ?? api;
+                push({
+                    tMs,
+                    kind: "scene",
+                    summary: (scene ? `Session started in scene "${scene}"` : "Session started") +
+                        (renderer ? ` on ${renderer}.` : "."),
+                    refs: refsOf({ scene }),
+                });
+                break;
+            }
+            case "scene_change": {
+                push({
+                    tMs,
+                    kind: "scene",
+                    summary: scene ? `Moved to scene "${scene}".` : "Moved to another scene.",
+                    refs: refsOf({ scene }),
+                });
+                break;
+            }
+            case "mesh_visibility": {
+                addDwell(event.mesh, tMs, scene, event.visibleMs, 0);
+                break;
+            }
+            case "hover_dwell": {
+                addDwell(event.mesh, tMs, scene, 0, event.dwellMs);
+                break;
+            }
+            case "mesh_interaction": {
+                meshes.add(event.mesh);
+                interactions += 1;
+                push({
+                    tMs,
+                    kind: "interaction",
+                    summary: `${event.kind} on "${event.mesh}"${sourceClause(event.source)}.`,
+                    refs: refsOf({ mesh: event.mesh, scene }),
+                });
+                break;
+            }
+            case "pointer_click": {
+                // Only a click that hit something is a story. A click into empty space
+                // carries nothing but coordinates, which a narrative never reports —
+                // `dead_clicks` is the aggregate metric for those.
+                if (!event.hitMesh)
+                    break;
+                meshes.add(event.hitMesh);
+                interactions += 1;
+                push({
+                    tMs,
+                    kind: "interaction",
+                    summary: `Clicked "${event.hitMesh}"${sourceClause(event.source)}.`,
+                    refs: refsOf({ mesh: event.hitMesh, scene }),
+                });
+                break;
+            }
+            case "input_action": {
+                interactions += 1;
+                const state = event.pressed === false ? " released" : "";
+                push({
+                    tMs,
+                    kind: "interaction",
+                    summary: `Input action "${event.action}"${event.code ? ` (${event.code})` : ""}` +
+                        `${state}${sourceClause(event.source)}.`,
+                    refs: refsOf({ name: event.action, scene }),
+                });
+                break;
+            }
+            case "custom": {
+                interactions += 1;
+                const props = event.props ?? {};
+                const keys = Object.keys(props).sort().slice(0, NARRATIVE_LIMITS.maxCustomPropKeys);
+                // Keys are developer-chosen field names and are always safe to name;
+                // values are app data and are opt-in only (see the module comment).
+                const detail = options.includeCustomProps
+                    ? keys.map((key) => `${key}=${truncate(String(props[key]), 40)}`).join(", ")
+                    : keys.join(", ");
+                push({
+                    tMs,
+                    kind: "interaction",
+                    summary: `Custom event "${event.name}"${detail ? ` (${detail})` : ""}.`,
+                    refs: refsOf({ name: event.name, scene }),
+                });
+                break;
+            }
+            case "frame_perf": {
+                if (event.fps < fpsThreshold) {
+                    if (dip == null) {
+                        dip = {
+                            tMs,
+                            endTMs: tMs,
+                            samples: 1,
+                            minFps: event.fps,
+                            scene,
+                            totalFps: event.fps,
+                        };
+                    }
+                    else {
+                        dip.endTMs = tMs;
+                        dip.samples += 1;
+                        dip.totalFps += event.fps;
+                        if (event.fps < dip.minFps)
+                            dip.minFps = event.fps;
+                    }
+                }
+                else {
+                    closeDip();
+                }
+                break;
+            }
+            case "runtime_error": {
+                errors += 1;
+                // The message only — never `source` (a URL) or `stack`.
+                push({
+                    tMs,
+                    kind: "error",
+                    summary: `Runtime ${event.kind}: ${truncate(event.message)}`,
+                    refs: refsOf({ scene }),
+                });
+                break;
+            }
+            case "graphics_diagnostic": {
+                if (event.severity === "error" || event.severity === "fatal")
+                    errors += 1;
+                // Category and severity are closed enums; the engine's own message is
+                // not reported.
+                push({
+                    tMs,
+                    kind: "diagnostic",
+                    summary: `Graphics diagnostic: ${event.category} (${event.severity}).`,
+                    refs: refsOf({ scene }),
+                    ...(event.count != null ? { count: event.count } : {}),
+                });
+                break;
+            }
+            case "capability_change": {
+                const from = event.from ? truncate(event.from, 64) : undefined;
+                const to = event.to ? truncate(event.to, 64) : undefined;
+                const transition = from && to ? `: ${from} → ${to}` : to ? `: → ${to}` : "";
+                const durationMs = event.durationMs != null ? Math.round(event.durationMs) : undefined;
+                push({
+                    tMs,
+                    kind: "capability",
+                    summary: `Capability change (${event.kind})${transition}` +
+                        (durationMs != null ? ` for ${humanMs(durationMs)}.` : "."),
+                    refs: refsOf({ scene }),
+                    ...(durationMs != null ? { durationMs } : {}),
+                });
+                break;
+            }
+            case "xr_boundary_proximity": {
+                // Folded into one summary entry rather than one per contact: a guardian
+                // approach fires repeatedly and would otherwise flood the narrative.
+                if (boundaryCount === 0)
+                    boundaryTMs = tMs;
+                boundaryCount += 1;
+                boundaryMs += event.durationMs;
+                break;
+            }
+            case "session_end": {
+                closeDip();
+                const durationMs = event.durationMs != null ? Math.round(event.durationMs) : Math.max(0, tMs);
+                push({
+                    tMs,
+                    kind: "end",
+                    summary: `Session ended${event.reason ? ` (${event.reason})` : ""} after ${humanMs(durationMs)}.`,
+                    refs: refsOf({ scene }),
+                    durationMs,
+                });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    closeDip();
+    // --- deferred, session-wide entries -------------------------------------
+    for (const accumulator of dwell.values()) {
+        const totalMs = Math.round(accumulator.visibleMs + accumulator.hoverMs);
+        if (totalMs < minDwellMs)
+            continue;
+        const hover = accumulator.hoverMs > 0 ? ` (${humanMs(Math.round(accumulator.hoverMs))} hovered)` : "";
+        push({
+            tMs: accumulator.tMs,
+            kind: "dwell",
+            summary: `Dwelled on "${accumulator.mesh}" for ${humanMs(totalMs)}${hover}.`,
+            refs: refsOf({ mesh: accumulator.mesh, scene: accumulator.scene }),
+            durationMs: totalMs,
+            count: accumulator.count,
+        });
+    }
+    if (xrFirstTMs != null) {
+        push({
+            tMs: xrFirstTMs,
+            kind: "xr",
+            summary: `Entered immersive XR input (${xrSource}).`,
+            refs: {},
+        });
+        if (xrLastTMs != null && xrLastTMs > xrFirstTMs) {
+            push({
+                tMs: xrLastTMs,
+                kind: "xr",
+                summary: `Last immersive XR input, ${humanMs(xrLastTMs - xrFirstTMs)} after the first.`,
+                refs: {},
+                durationMs: xrLastTMs - xrFirstTMs,
+            });
+        }
+    }
+    if (boundaryCount > 0) {
+        push({
+            tMs: boundaryTMs,
+            kind: "xr",
+            summary: `Approached the play-area boundary ${boundaryCount} time(s) for ${humanMs(Math.round(boundaryMs))} in total.`,
+            refs: {},
+            durationMs: Math.round(boundaryMs),
+            count: boundaryCount,
+        });
+    }
+    // --- order, bound, summarise --------------------------------------------
+    const sorted = entries
+        .map((entry, index) => ({ entry, index }))
+        .sort((a, b) => a.entry.tMs - b.entry.tMs || a.index - b.index)
+        .map((item) => item.entry);
+    // The closing `summary` entry always survives, so the bound the caller asked
+    // for is the bound on the whole answer — never `maxEntries + 1`.
+    const room = Math.max(0, maxEntries - 1);
+    const truncated = sorted.length > room;
+    const kept = truncated ? sorted.slice(0, room) : sorted;
+    const totals = {
+        events: ordered.length,
+        durationMs: Math.max(0, Math.round(lastTs - t0)),
+        scenes: scenes.size,
+        meshes: meshes.size,
+        interactions,
+        dips,
+        errors,
+    };
+    kept.push({
+        tMs: totals.durationMs,
+        kind: "summary",
+        summary: `${totals.events} events over ${humanMs(totals.durationMs)}: ${totals.scenes} scene(s), ` +
+            `${totals.meshes} mesh(es), ${totals.interactions} interaction(s), ${totals.dips} perf dip(s), ` +
+            `${totals.errors} error(s).` +
+            (truncated
+                ? ` ${sorted.length - room} later entr(ies) were dropped to honour maxEntries.`
+                : ""),
+        refs: {},
+        totals,
+        truncated,
+    });
+    return { sessionId: first.sessionId, startedAt: t0, entries: kept, truncated, totals };
+}
+//# sourceMappingURL=build.js.map