@uptimizr/db 1.0.1 → 2.0.0

package/dist/query/summary/cluster.d.ts

@@ -0,0 +1,78 @@
+/**
+ * **Deterministic greedy cluster merge** for binned and voxelised metrics
+ * (design sketch §B.2).
+ *
+ * A 500-bin heatmap or a voxel cloud is the wrong shape for a language model:
+ * every cell is individually meaningless and collectively unaffordable. This
+ * module collapses the grid into a handful of *hotspots* — connected runs of
+ * adjacent occupied cells whose weight clears a density threshold — each
+ * reporting where it is, how big it is and how much of the total it holds.
+ *
+ * ## Why not k-means
+ *
+ * A summary has to be reproducible: the same rows must produce the same words,
+ * whatever order the store returned them in and however many times it is asked.
+ * k-means needs seeds, so it is neither. What is implemented here is a plain
+ * connected-components merge over the grid:
+ *
+ * 1. duplicate coordinates are summed, so a metric with extra dimensions (a
+ *    per-mesh flow link, say) collapses onto its grid first;
+ * 2. cells with weight at or above `densityThreshold` qualify — by default the
+ *    mean weight per occupied cell, which keeps the busy cells and drops the
+ *    long thin tail that would otherwise fuse every hotspot into one blob;
+ * 3. qualifying cells are merged with their neighbours — the 8-neighbourhood
+ *    for a 2D grid, the 26-neighbourhood for a 3D one (every cell whose indices
+ *    differ by at most one on each axis);
+ * 4. clusters are ranked by summed weight, and the rest is reported in bulk.
+ *
+ * Connected components do not depend on iteration order, and every accumulation
+ * (centroid, weight) is done over the component's cells in **sorted coordinate
+ * order**, so even floating-point summation is bit-identical when the input is
+ * shuffled. `__tests__/summary.test.ts` asserts exactly that.
+ *
+ * Pure and browser-safe: no I/O, no `node:` import, no store reference.
+ */
+import type { SpatialCluster } from "./types.js";
+/** One occupied grid cell: its integer indices on each axis, and its weight. */
+export interface GridCell {
+    coords: readonly number[];
+    weight: number;
+}
+/** Knobs for {@link clusterCells}. */
+export interface ClusterOptions {
+    /**
+     * Minimum weight a cell needs to take part in the merge. Defaults to the mean
+     * weight per occupied cell. Pass `0` to cluster every occupied cell.
+     */
+    densityThreshold?: number;
+    /** Maximum clusters to report individually; the remainder goes to `rest`. */
+    maxClusters?: number;
+}
+/** What {@link clusterCells} found. */
+export interface ClusterResult {
+    clusters: SpatialCluster[];
+    /** Distinct occupied cells, after duplicate coordinates were summed. */
+    occupiedCells: number;
+    /** Summed weight of every occupied cell (clustered or not). */
+    totalWeight: number;
+    /** The threshold that was actually applied. */
+    densityThreshold: number;
+    /** Clusters, cells and weight not reported individually. */
+    rest: {
+        clusters: number;
+        cells: number;
+        weight: number;
+    };
+}
+/**
+ * Merge adjacent occupied cells into ranked hotspots.
+ *
+ * Cells with a non-finite or non-positive weight are ignored (an empty bin is
+ * not a hotspot), as are cells whose coordinate arity does not match the first
+ * cell's — a malformed row must not silently shift the grid.
+ *
+ * Returns clusters ordered by weight descending, ties broken by their lowest
+ * corner then by cell count, so the output is a pure function of the cell *set*.
+ */
+export declare function clusterCells(cells: readonly GridCell[], options?: ClusterOptions): ClusterResult;
+//# sourceMappingURL=cluster.d.ts.map

package/dist/query/summary/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../../src/query/summary/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAwCD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAiHf"}

package/dist/query/summary/cluster.js

@@ -0,0 +1,200 @@
+/**
+ * **Deterministic greedy cluster merge** for binned and voxelised metrics
+ * (design sketch §B.2).
+ *
+ * A 500-bin heatmap or a voxel cloud is the wrong shape for a language model:
+ * every cell is individually meaningless and collectively unaffordable. This
+ * module collapses the grid into a handful of *hotspots* — connected runs of
+ * adjacent occupied cells whose weight clears a density threshold — each
+ * reporting where it is, how big it is and how much of the total it holds.
+ *
+ * ## Why not k-means
+ *
+ * A summary has to be reproducible: the same rows must produce the same words,
+ * whatever order the store returned them in and however many times it is asked.
+ * k-means needs seeds, so it is neither. What is implemented here is a plain
+ * connected-components merge over the grid:
+ *
+ * 1. duplicate coordinates are summed, so a metric with extra dimensions (a
+ *    per-mesh flow link, say) collapses onto its grid first;
+ * 2. cells with weight at or above `densityThreshold` qualify — by default the
+ *    mean weight per occupied cell, which keeps the busy cells and drops the
+ *    long thin tail that would otherwise fuse every hotspot into one blob;
+ * 3. qualifying cells are merged with their neighbours — the 8-neighbourhood
+ *    for a 2D grid, the 26-neighbourhood for a 3D one (every cell whose indices
+ *    differ by at most one on each axis);
+ * 4. clusters are ranked by summed weight, and the rest is reported in bulk.
+ *
+ * Connected components do not depend on iteration order, and every accumulation
+ * (centroid, weight) is done over the component's cells in **sorted coordinate
+ * order**, so even floating-point summation is bit-identical when the input is
+ * shuffled. `__tests__/summary.test.ts` asserts exactly that.
+ *
+ * Pure and browser-safe: no I/O, no `node:` import, no store reference.
+ */
+/** Compare two coordinate tuples lexicographically (ascending). */
+function compareCoords(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        const left = a[i] ?? 0;
+        const right = b[i] ?? 0;
+        if (left !== right)
+            return left - right;
+    }
+    return 0;
+}
+/**
+ * Every neighbour offset for a grid of `axes` dimensions: all combinations of
+ * `-1 | 0 | +1` per axis, minus the all-zero one. Eight offsets in 2D, twenty-six
+ * in 3D — the neighbourhoods the sketch specifies, derived rather than typed out.
+ */
+function neighbourOffsets(axes) {
+    let offsets = [[]];
+    for (let axis = 0; axis < axes; axis++) {
+        const next = [];
+        for (const prefix of offsets) {
+            for (const delta of [-1, 0, 1])
+                next.push([...prefix, delta]);
+        }
+        offsets = next;
+    }
+    return offsets.filter((offset) => offset.some((delta) => delta !== 0));
+}
+/** Cached offsets — the only two shapes that occur are 2D and 3D. */
+const OFFSETS = new Map();
+function offsetsFor(axes) {
+    let cached = OFFSETS.get(axes);
+    if (cached == null) {
+        cached = neighbourOffsets(axes);
+        OFFSETS.set(axes, cached);
+    }
+    return cached;
+}
+/**
+ * Merge adjacent occupied cells into ranked hotspots.
+ *
+ * Cells with a non-finite or non-positive weight are ignored (an empty bin is
+ * not a hotspot), as are cells whose coordinate arity does not match the first
+ * cell's — a malformed row must not silently shift the grid.
+ *
+ * Returns clusters ordered by weight descending, ties broken by their lowest
+ * corner then by cell count, so the output is a pure function of the cell *set*.
+ */
+export function clusterCells(cells, options = {}) {
+    const axes = cells[0]?.coords.length ?? 0;
+    const empty = {
+        clusters: [],
+        occupiedCells: 0,
+        totalWeight: 0,
+        densityThreshold: options.densityThreshold ?? 0,
+        rest: { clusters: 0, cells: 0, weight: 0 },
+    };
+    if (axes === 0)
+        return empty;
+    // 1. Collapse duplicate coordinates onto the grid.
+    const grid = new Map();
+    let totalWeight = 0;
+    for (const cell of cells) {
+        if (cell.coords.length !== axes)
+            continue;
+        if (!Number.isFinite(cell.weight) || cell.weight <= 0)
+            continue;
+        if (!cell.coords.every((coordinate) => Number.isFinite(coordinate)))
+            continue;
+        const coords = cell.coords.map((coordinate) => Math.trunc(coordinate));
+        const key = coords.join(",");
+        const existing = grid.get(key);
+        if (existing)
+            existing.weight += cell.weight;
+        else
+            grid.set(key, { coords, weight: cell.weight });
+        totalWeight += cell.weight;
+    }
+    if (grid.size === 0)
+        return empty;
+    // 2. Qualify cells against the density threshold (mean weight by default).
+    const densityThreshold = options.densityThreshold ?? totalWeight / grid.size;
+    const qualifying = new Map();
+    for (const [key, cell] of grid) {
+        if (cell.weight >= densityThreshold)
+            qualifying.set(key, cell);
+    }
+    // 3. Connected components over the qualifying cells (8- or 26-neighbourhood).
+    const offsets = offsetsFor(axes);
+    const seen = new Set();
+    const components = [];
+    // Seed order only affects which component is discovered first, never their
+    // membership — but iterate the grid in sorted order anyway so a debugger shows
+    // the same thing twice.
+    const seeds = [...qualifying.keys()].sort();
+    for (const seed of seeds) {
+        if (seen.has(seed))
+            continue;
+        const component = [];
+        const stack = [seed];
+        seen.add(seed);
+        while (stack.length > 0) {
+            const key = stack.pop();
+            const cell = qualifying.get(key);
+            if (cell == null)
+                continue;
+            component.push(cell);
+            for (const offset of offsets) {
+                const neighbourKey = cell.coords
+                    .map((value, axis) => value + (offset[axis] ?? 0))
+                    .join(",");
+                if (seen.has(neighbourKey) || !qualifying.has(neighbourKey))
+                    continue;
+                seen.add(neighbourKey);
+                stack.push(neighbourKey);
+            }
+        }
+        components.push(component);
+    }
+    // 4. Describe each component. Accumulating in sorted coordinate order makes
+    //    the floating-point sums independent of the input's row order.
+    const described = components.map((component) => {
+        const ordered = [...component].sort((a, b) => compareCoords(a.coords, b.coords));
+        const min = [...ordered[0].coords];
+        const max = [...min];
+        const weighted = new Array(axes).fill(0);
+        let weight = 0;
+        for (const cell of ordered) {
+            weight += cell.weight;
+            for (let axis = 0; axis < axes; axis++) {
+                const value = cell.coords[axis];
+                if (value < min[axis])
+                    min[axis] = value;
+                if (value > max[axis])
+                    max[axis] = value;
+                weighted[axis] = weighted[axis] + value * cell.weight;
+            }
+        }
+        return {
+            centroid: weighted.map((sum) => (weight > 0 ? sum / weight : 0)),
+            extent: { min, max },
+            cells: ordered.length,
+            weight,
+            share: totalWeight > 0 ? weight / totalWeight : null,
+        };
+    });
+    described.sort((a, b) => b.weight - a.weight || compareCoords(a.extent.min, b.extent.min) || b.cells - a.cells);
+    const cap = Math.max(0, options.maxClusters ?? described.length);
+    const clusters = described.slice(0, cap);
+    const dropped = described.slice(cap);
+    const clusteredCells = described.reduce((sum, cluster) => sum + cluster.cells, 0);
+    const reportedWeight = clusters.reduce((sum, cluster) => sum + cluster.weight, 0);
+    return {
+        clusters,
+        occupiedCells: grid.size,
+        totalWeight,
+        densityThreshold,
+        rest: {
+            clusters: dropped.length,
+            // Everything not listed individually: the dropped clusters' cells plus
+            // every occupied cell that never cleared the threshold.
+            cells: grid.size - clusteredCells + dropped.reduce((sum, cluster) => sum + cluster.cells, 0),
+            weight: totalWeight - reportedWeight,
+        },
+    };
+}
+//# sourceMappingURL=cluster.js.map

package/dist/query/summary/cluster.js.map

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

package/dist/query/summary/columns.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Registry column lookups shared by the summariser.
+ *
+ * Everything the summary does — what to rank by, what to call a row, which
+ * columns index a grid, how big the sample is — is read out of the metric's
+ * `columns` semantics rather than hard-coded per metric. That is the whole point
+ * of the registry: a new aggregation gets a usable summary for free the moment
+ * it declares what its columns mean.
+ */
+import type { ColumnSemantics, MetricDefinition } from "@uptimizr/metrics";
+import type { SampleSize } from "./types.js";
+/** A column name paired with its declared semantics. */
+export type Column = readonly [name: string, semantics: ColumnSemantics];
+/** Every declared column, in declaration order. */
+export declare function columnsOf(metric: MetricDefinition): Column[];
+/** The column a metric is ranked by (`measure: true`), if it declares one. */
+export declare function measureColumn(metric: MetricDefinition): Column | undefined;
+/** The column that names a row (`label: true`), if it declares one. */
+export declare function labelColumn(metric: MetricDefinition): Column | undefined;
+/**
+ * The ordered column of a `bucket`-grain metric (`axis: true`), falling back to
+ * the label column so a metric that has not declared an axis still summarises.
+ */
+export declare function axisColumn(metric: MetricDefinition): Column | undefined;
+/** The first column declared with a given unit, in declaration order. */
+export declare function firstColumnWithUnit(metric: MetricDefinition, unit: string): Column | undefined;
+/**
+ * The grid-index columns of a binned or voxelised metric: the first `axes`
+ * columns declared with `unit: "index"`, in declaration order.
+ *
+ * Declaration order is the rule, and it is what makes the choice explainable:
+ * `position_heatmap` indexes on `gx`/`gz` and skips its world-space `avg_y`,
+ * `flow_links` clusters on the view-direction grid it leads with, and
+ * `click_rays` clusters on the click-time standpoint voxel (`cam_v*`) it
+ * declares first. Returns `undefined` when the metric declares too few.
+ */
+export declare function gridColumns(metric: MetricDefinition, axes: number): Column[] | undefined;
+/**
+ * The column a spatial cluster weighs its cells by: the first `count` column if
+ * the metric declares one, else the measure. `perf_heatmap` measures `avg_fps`
+ * but counts `samples` — clustering by an average would weigh a one-sample
+ * voxel the same as a thousand-sample one.
+ */
+export declare function weightColumn(metric: MetricDefinition): Column | undefined;
+/** A row's value for a column, when it is a finite number; `null` otherwise. */
+export declare function numberAt(row: Readonly<Record<string, unknown>>, column: string): number | null;
+/**
+ * Sum a column across rows. `null` when the column is absent from every row or
+ * every value is null — a metric that reports nothing must not report `0`.
+ */
+export declare function sumColumn(rows: readonly Readonly<Record<string, unknown>>[], column: string | undefined): number | null;
+/**
+ * How much data is behind a result, derived entirely from column units.
+ *
+ * - `sessions` — the number of rows when one row *is* a session
+ *   (`grain: "session"`), otherwise the sum of the first column declared
+ *   `unit: "sessions"`. When rows can share a session (a per-mesh breakdown,
+ *   say) that sum is an upper bound, not a distinct count; the caveats say so.
+ * - `events` — the sum of the first column declared `unit: "count"`. Declaration
+ *   order matters: registry rows lead with the denominator (`total_clicks`
+ *   before `dead_clicks`, `samples` before the percentiles computed from them).
+ *
+ * `null` means the metric declares nothing that could answer the question.
+ */
+export declare function sampleSizeOf(metric: MetricDefinition, rows: readonly Readonly<Record<string, unknown>>[]): SampleSize;
+//# sourceMappingURL=columns.d.ts.map

package/dist/query/summary/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../../src/query/summary/columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wDAAwD;AACxD,MAAM,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;AAEzE,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAE5D;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9F;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAGxF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9F;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,EAClD,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,GAAG,IAAI,CAWf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,GACjD,UAAU,CAMZ"}

package/dist/query/summary/columns.js

@@ -0,0 +1,98 @@
+/**
+ * Registry column lookups shared by the summariser.
+ *
+ * Everything the summary does — what to rank by, what to call a row, which
+ * columns index a grid, how big the sample is — is read out of the metric's
+ * `columns` semantics rather than hard-coded per metric. That is the whole point
+ * of the registry: a new aggregation gets a usable summary for free the moment
+ * it declares what its columns mean.
+ */
+/** Every declared column, in declaration order. */
+export function columnsOf(metric) {
+    return Object.entries(metric.columns);
+}
+/** The column a metric is ranked by (`measure: true`), if it declares one. */
+export function measureColumn(metric) {
+    return columnsOf(metric).find(([, semantics]) => semantics.measure);
+}
+/** The column that names a row (`label: true`), if it declares one. */
+export function labelColumn(metric) {
+    return columnsOf(metric).find(([, semantics]) => semantics.label);
+}
+/**
+ * The ordered column of a `bucket`-grain metric (`axis: true`), falling back to
+ * the label column so a metric that has not declared an axis still summarises.
+ */
+export function axisColumn(metric) {
+    return columnsOf(metric).find(([, semantics]) => semantics.axis) ?? labelColumn(metric);
+}
+/** The first column declared with a given unit, in declaration order. */
+export function firstColumnWithUnit(metric, unit) {
+    return columnsOf(metric).find(([, semantics]) => semantics.unit === unit);
+}
+/**
+ * The grid-index columns of a binned or voxelised metric: the first `axes`
+ * columns declared with `unit: "index"`, in declaration order.
+ *
+ * Declaration order is the rule, and it is what makes the choice explainable:
+ * `position_heatmap` indexes on `gx`/`gz` and skips its world-space `avg_y`,
+ * `flow_links` clusters on the view-direction grid it leads with, and
+ * `click_rays` clusters on the click-time standpoint voxel (`cam_v*`) it
+ * declares first. Returns `undefined` when the metric declares too few.
+ */
+export function gridColumns(metric, axes) {
+    const indexed = columnsOf(metric).filter(([, semantics]) => semantics.unit === "index");
+    return indexed.length >= axes ? indexed.slice(0, axes) : undefined;
+}
+/**
+ * The column a spatial cluster weighs its cells by: the first `count` column if
+ * the metric declares one, else the measure. `perf_heatmap` measures `avg_fps`
+ * but counts `samples` — clustering by an average would weigh a one-sample
+ * voxel the same as a thousand-sample one.
+ */
+export function weightColumn(metric) {
+    return firstColumnWithUnit(metric, "count") ?? measureColumn(metric);
+}
+/** A row's value for a column, when it is a finite number; `null` otherwise. */
+export function numberAt(row, column) {
+    const value = row[column];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Sum a column across rows. `null` when the column is absent from every row or
+ * every value is null — a metric that reports nothing must not report `0`.
+ */
+export function sumColumn(rows, column) {
+    if (column == null)
+        return null;
+    let total = 0;
+    let seen = false;
+    for (const row of rows) {
+        const value = numberAt(row, column);
+        if (value == null)
+            continue;
+        seen = true;
+        total += value;
+    }
+    return seen ? total : null;
+}
+/**
+ * How much data is behind a result, derived entirely from column units.
+ *
+ * - `sessions` — the number of rows when one row *is* a session
+ *   (`grain: "session"`), otherwise the sum of the first column declared
+ *   `unit: "sessions"`. When rows can share a session (a per-mesh breakdown,
+ *   say) that sum is an upper bound, not a distinct count; the caveats say so.
+ * - `events` — the sum of the first column declared `unit: "count"`. Declaration
+ *   order matters: registry rows lead with the denominator (`total_clicks`
+ *   before `dead_clicks`, `samples` before the percentiles computed from them).
+ *
+ * `null` means the metric declares nothing that could answer the question.
+ */
+export function sampleSizeOf(metric, rows) {
+    const sessions = metric.grain === "session"
+        ? rows.length
+        : sumColumn(rows, firstColumnWithUnit(metric, "sessions")?.[0]);
+    return { sessions, events: sumColumn(rows, firstColumnWithUnit(metric, "count")?.[0]) };
+}
+//# sourceMappingURL=columns.js.map

package/dist/query/summary/columns.js.map

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

package/dist/query/summary/format.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Deterministic, locale-independent number and unit rendering for the `reading`
+ * sentence (design sketch §B.1).
+ *
+ * `toLocaleString` is deliberately avoided: a summary is read by an agent and
+ * compared in tests, so "1,234" must not become "1.234" because the collector
+ * happens to run in a different locale. Every helper here also has to be
+ * **total** — a `reading` may never contain `undefined` or `NaN`, so a missing
+ * or non-finite value renders as `n/a` rather than leaking through.
+ */
+import type { ColumnUnit } from "@uptimizr/metrics";
+/** Whether values in a column with this unit may be added together. */
+export declare function isAdditiveUnit(unit: ColumnUnit | null | undefined): boolean;
+/**
+ * Render a number for prose: thousands-grouped, with at most two decimals and
+ * only when they carry information. Non-finite and missing values become `n/a`.
+ */
+export declare function formatNumber(value: number | null | undefined): string;
+/** Render a 0..1 share as a percentage with one decimal; `n/a` when unknown. */
+export declare function formatShare(share: number | null | undefined): string;
+/** The suffix that turns a bare number into a quantity, e.g. `450` → `450 ms`. */
+export declare function unitSuffix(unit: ColumnUnit | null | undefined): string;
+/** A number rendered with its unit, e.g. `2,210` or `450 ms`. */
+export declare function formatQuantity(value: number | null | undefined, unit: ColumnUnit | null | undefined): string;
+/** The plural noun for one row of a metric, used in prose. */
+export declare function grainNoun(grain: string, count: number): string;
+/** Turn a column name into readable prose (`avg_js_heap_bytes` → `avg js heap bytes`). */
+export declare function humanizeColumn(column: string): string;
+/** Render a cell value for prose; objects and nullish values become `n/a`. */
+export declare function formatLabel(value: unknown): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/query/summary/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/query/summary/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAkBpD,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE3E;AAOD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CASrE;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGpE;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAsBtE;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAClC,MAAM,CAGR;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB9D;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMlD"}

package/dist/query/summary/format.js

@@ -0,0 +1,119 @@
+/**
+ * Deterministic, locale-independent number and unit rendering for the `reading`
+ * sentence (design sketch §B.1).
+ *
+ * `toLocaleString` is deliberately avoided: a summary is read by an agent and
+ * compared in tests, so "1,234" must not become "1.234" because the collector
+ * happens to run in a different locale. Every helper here also has to be
+ * **total** — a `reading` may never contain `undefined` or `NaN`, so a missing
+ * or non-finite value renders as `n/a` rather than leaking through.
+ */
+/**
+ * Units whose values may be summed across rows. Shares, `total` and the cluster
+ * weights are only reported for these: adding FPS, a ratio or a bin index
+ * together produces a number that means nothing, and a `share` derived from it
+ * would be actively misleading.
+ */
+const ADDITIVE_UNITS = new Set([
+    "count",
+    "sessions",
+    "ms",
+    "s",
+    "bytes",
+    "world-units",
+    "radians",
+]);
+/** Whether values in a column with this unit may be added together. */
+export function isAdditiveUnit(unit) {
+    return unit != null && ADDITIVE_UNITS.has(unit);
+}
+/** Insert thousands separators into the integer part of a rendered number. */
+function group(digits) {
+    return digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+/**
+ * Render a number for prose: thousands-grouped, with at most two decimals and
+ * only when they carry information. Non-finite and missing values become `n/a`.
+ */
+export function formatNumber(value) {
+    if (value == null || !Number.isFinite(value))
+        return "n/a";
+    const rounded = Math.abs(value) >= 1000 ? Math.round(value) : Math.round(value * 100) / 100;
+    const sign = rounded < 0 ? "-" : "";
+    const text = Math.abs(rounded).toFixed(Number.isInteger(rounded) ? 0 : 2);
+    const [whole = "0", fraction] = text.split(".");
+    // Trim a trailing zero decimal ("1.50" → "1.5"), but never the whole part.
+    const trimmed = fraction == null ? "" : `.${fraction.replace(/0$/, "")}`;
+    return `${sign}${group(whole)}${trimmed === "." ? "" : trimmed}`;
+}
+/** Render a 0..1 share as a percentage with one decimal; `n/a` when unknown. */
+export function formatShare(share) {
+    if (share == null || !Number.isFinite(share))
+        return "n/a";
+    return `${formatNumber(Math.round(share * 1000) / 10)}%`;
+}
+/** The suffix that turns a bare number into a quantity, e.g. `450` → `450 ms`. */
+export function unitSuffix(unit) {
+    switch (unit) {
+        case "sessions":
+            return " sessions";
+        case "ms":
+            return " ms";
+        case "s":
+            return " s";
+        case "fps":
+            return " FPS";
+        case "percent":
+            return "%";
+        case "world-units":
+            return " units";
+        case "radians":
+            return " rad";
+        case "bytes":
+            return " bytes";
+        default:
+            // count / ratio / index / epoch-ms / id / label / timestamp read better bare.
+            return "";
+    }
+}
+/** A number rendered with its unit, e.g. `2,210` or `450 ms`. */
+export function formatQuantity(value, unit) {
+    const rendered = formatNumber(value);
+    return rendered === "n/a" ? rendered : `${rendered}${unitSuffix(unit)}`;
+}
+/** The plural noun for one row of a metric, used in prose. */
+export function grainNoun(grain, count) {
+    const singular = grain === "mesh"
+        ? "mesh"
+        : grain === "scene"
+            ? "scene"
+            : grain === "session"
+                ? "session"
+                : grain === "bucket"
+                    ? "bucket"
+                    : grain === "bin"
+                        ? "bin"
+                        : grain === "voxel"
+                            ? "voxel"
+                            : "row";
+    if (count === 1)
+        return singular;
+    return singular === "mesh" ? "meshes" : `${singular}s`;
+}
+/** Turn a column name into readable prose (`avg_js_heap_bytes` → `avg js heap bytes`). */
+export function humanizeColumn(column) {
+    return column.replace(/_/g, " ");
+}
+/** Render a cell value for prose; objects and nullish values become `n/a`. */
+export function formatLabel(value) {
+    if (value == null)
+        return "(unattributed)";
+    if (typeof value === "number")
+        return formatNumber(value);
+    if (typeof value === "string")
+        return value.length === 0 ? "(unattributed)" : value;
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return "n/a";
+}
+//# sourceMappingURL=format.js.map

package/dist/query/summary/format.js.map

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