@uptimizr/db 2.0.1 → 2.1.0

package/dist/query/dsl/generic.js

@@ -0,0 +1,323 @@
+/**
+ * **The generic group-by compiler** (ADR 0051 §3, design sketch §C.2, tier 2).
+ *
+ * The delegated tier (`compile.ts`) can run any metric, but only at the grain
+ * its builder renders: `top_meshes` is one row per mesh and nothing else. That
+ * is right for a spatial binning or a percentile — those measures *are* their
+ * grain — but wrong for a count. "How many mesh interactions per input source"
+ * and "…per scene" are the same question about the same events, and the only
+ * reason they needed two endpoints is that somebody wrote two `GROUP BY`s.
+ *
+ * So a metric that declares `genericGroupBy` in the registry (a portable
+ * `count` / `count(DISTINCT session_id)` / `sum` / `avg` / `max` over promoted
+ * columns) gets one shared, dialect-authored builder that renders
+ *
+ * ```sql
+ * SELECT <dimensions>, <measures>
+ *   FROM events [LEFT JOIN session_attrs …]
+ *  WHERE project_id = ? AND <event types> AND <scope> AND <range> AND <filters>
+ *  GROUP BY <dimensions>
+ *  ORDER BY <measure> DESC, <dimensions>
+ *  LIMIT ?
+ * ```
+ *
+ * for **any** subset of the dimensions that metric declares.
+ *
+ * ## Why this is still only one SQL path
+ *
+ * Everything variable in the SQL above comes from **registry data**, never from
+ * the request: the event types and the scope predicate are the metric's
+ * `genericGroupBy`, the measures are its declared columns, and each dimension's
+ * expression is chosen from a closed table keyed by `DimensionId`. Every value a
+ * caller supplies — a scene id, a mesh name, an event predicate — reaches the
+ * SQL as a bound parameter through the same {@link ParamBag} the canned
+ * aggregations use. There is no string interpolation of caller input anywhere in
+ * this file, which is what makes a grammar with a `GROUP BY` in it still a
+ * closed grammar.
+ *
+ * ## Portability
+ *
+ * The promoted dimensions (`scene_id`, `session_id`, `mesh`, `name`, `source`,
+ * `event_type`) are plain columns on every engine. The session attributes
+ * (`cameraMode`, `device.*`) live in the `session_start` payload, so they are
+ * read through `Dialect.jsonText` in one CTE and `LEFT JOIN`ed on `session_id`
+ * — the same shape `buildPerfByDevice` has always used. `GROUP BY` repeats the
+ * expressions rather than naming the output aliases, because T-SQL rejects the
+ * latter (the mssql dialect rewrites it, but not relying on the rewrite is
+ * cheaper than relying on it).
+ *
+ * ## Why it is not called `build*`
+ *
+ * Every `build*` export of this package is a dialect-agnostic aggregation with
+ * the signature `(projectId, opts, dialect)`, and the optional stores' suites
+ * enumerate them by that prefix to run each one against DuckDB. This one takes a
+ * `MetricDefinition` first, because the metric *is* its configuration — so it is
+ * a `compile*`, next to `compileMetric` and `compileQuery`, and the prefix keeps
+ * meaning what it has always meant.
+ *
+ * The one session attribute deliberately left out is `device.isMobile`: it is a
+ * boolean, and a group-by on it would key rows by `"true"` on one engine and `1`
+ * on another. `GENERIC_DIMENSIONS` in the registry says so, and `validateQuery`
+ * refuses it by name.
+ */
+import { dimensionColumn, } from "@uptimizr/metrics";
+import { ParamBag, cameraModeClause, rangeClause } from "../dialect.js";
+/** The default row cap when a caller names none. */
+const DEFAULT_GENERIC_LIMIT = 200;
+/** Session attributes read out of the `session_start` payload, by dimension. */
+const SESSION_ATTRIBUTE_PATHS = {
+    cameraMode: ["scene", "cameraType"],
+    "device.engine": ["device", "engine"],
+    "device.renderer": ["device", "renderer"],
+    "device.browser": ["device", "browser"],
+    "device.os": ["device", "os"],
+};
+/** Promoted `events` columns, by dimension. The rest come from the CTE. */
+const PROMOTED_COLUMNS = {
+    scene: "scene_id",
+    session: "session_id",
+    mesh: "mesh",
+    name: "name",
+    source: "source",
+    event_type: "event_type",
+};
+/** The CTE the session-attribute dimensions are read from. */
+const SESSION_CTE = "session_attrs";
+/** Whether a dimension is read from the joined `session_start` attributes. */
+function isSessionAttribute(dimension) {
+    return dimension in SESSION_ATTRIBUTE_PATHS;
+}
+/** Sanitised alias for a session attribute inside the CTE (`device.os` → `sa_os`). */
+function attributeAlias(dimension) {
+    return `sa_${dimension
+        .replace(/^device\./, "")
+        .replace(/[^A-Za-z0-9]/g, "_")
+        .toLowerCase()}`;
+}
+/** Resolve every asked-for dimension to its output column and SQL expression. */
+function resolveDimensions(metric, dimensions) {
+    return dimensions.map((id) => ({
+        id,
+        column: dimensionColumn(metric, id),
+        expression: isSessionAttribute(id)
+            ? `${SESSION_CTE}.${attributeAlias(id)}`
+            : `events.${PROMOTED_COLUMNS[id] ?? id}`,
+    }));
+}
+/** Render one measure column. */
+function renderMeasure(measure) {
+    switch (measure.kind) {
+        case "count":
+            return `count(*) AS ${measure.column}`;
+        case "sessions":
+            return `count(DISTINCT events.session_id) AS ${measure.column}`;
+        case "sum":
+            return `sum(events.${measure.of}) AS ${measure.column}`;
+        case "avg":
+            return `avg(events.${measure.of}) AS ${measure.column}`;
+        case "max":
+            return `max(events.${measure.of}) AS ${measure.column}`;
+    }
+}
+/**
+ * `event_type IN (…)`, every type a bound parameter. Empty for a metric whose
+ * subject is the whole stream (`event_counts`).
+ */
+function eventTypeClause(bag, types) {
+    if (types.length === 0)
+        return "";
+    const bound = types.map((type, index) => bag.add(`gType${index}`, "string", type));
+    return ` AND events.event_type IN (${bound.join(", ")})`;
+}
+/**
+ * The metric's own scope predicate, so a regrouped result counts the same
+ * population its builder counts. Closed: each value is one non-empty test on a
+ * promoted column, named by the registry, never by the caller.
+ */
+function scopeClause(scope) {
+    const parts = (scope ?? []).map((rule) => rule === "hasMesh" ? "events.mesh != ''" : "events.name != ''");
+    return parts.length === 0 ? "" : ` AND ${parts.join(" AND ")}`;
+}
+/** An equality predicate on a promoted column, or `""` when the value is absent. */
+function equality(bag, column, param, value) {
+    if (value == null || value.length === 0)
+        return "";
+    return ` AND events.${column} = ${bag.add(param, "string", value)}`;
+}
+/**
+ * `session_id IN (SELECT … FROM session_start WHERE <attribute> = ?)` — the
+ * device filter, rendered exactly like the camera-mode filter it sits next to so
+ * it composes with every other clause and needs no join.
+ */
+function deviceClause(bag, d, projectId, device) {
+    const tests = [];
+    if (device?.os != null && device.os.length > 0) {
+        tests.push(`${d.jsonText("payload", "device", "os")} = ${bag.add("devOs", "string", device.os)}`);
+    }
+    if (device?.browser != null && device.browser.length > 0) {
+        tests.push(`${d.jsonText("payload", "device", "browser")} = ` +
+            `${bag.add("devBrowser", "string", device.browser)}`);
+    }
+    if (tests.length === 0)
+        return "";
+    const pid = bag.add("devProjectId", "string", projectId);
+    return ` AND events.session_id IN (
+        SELECT session_id FROM events
+        WHERE project_id = ${pid} AND event_type = 'session_start' AND ${tests.join(" AND ")}
+      )`;
+}
+/**
+ * `session_id IN (SELECT … WHERE <the step predicate>)` — the ADR 0038 event
+ * filter.
+ *
+ * It is a **cohort** predicate, not a row predicate: it keeps the sessions in
+ * which the event happened at least once, and the metric then counts its own
+ * events within them. That is the useful question ("what did the people who
+ * reached checkout look at") and the one the funnel grammar already answers;
+ * narrowing the counted rows themselves is what `filters.event_type`-style
+ * dimensions and `eventTypes` already do.
+ */
+function eventPredicateClause(bag, projectId, event) {
+    if (event == null)
+        return "";
+    const parts = [`event_type = ${bag.add("evType", "string", event.type)}`];
+    if (event.name != null && event.name.length > 0) {
+        parts.push(`name = ${bag.add("evName", "string", event.name)}`);
+    }
+    if (event.mesh != null && event.mesh.length > 0) {
+        parts.push(`mesh = ${bag.add("evMesh", "string", event.mesh)}`);
+    }
+    const pid = bag.add("evProjectId", "string", projectId);
+    return ` AND events.session_id IN (
+        SELECT session_id FROM events
+        WHERE project_id = ${pid} AND ${parts.join(" AND ")}
+      )`;
+}
+/**
+ * Equality predicates for the dimensions a `segment` holds fixed. Only the
+ * dimensions the delegated filters cannot express reach here — the rest arrive
+ * as ordinary filter options.
+ */
+function segmentClauses(bag, d, projectId, segment) {
+    if (segment == null)
+        return "";
+    const parts = [];
+    let index = 0;
+    for (const [dimension, value] of Object.entries(segment)) {
+        if (value == null || value.length === 0)
+            continue;
+        const param = `seg${index++}`;
+        const path = SESSION_ATTRIBUTE_PATHS[dimension];
+        if (path != null) {
+            const pid = bag.add(`${param}ProjectId`, "string", projectId);
+            parts.push(`events.session_id IN (
+        SELECT session_id FROM events
+        WHERE project_id = ${pid} AND event_type = 'session_start'
+          AND ${d.jsonText("payload", ...path)} = ${bag.add(param, "string", value)}
+      )`);
+            continue;
+        }
+        const column = PROMOTED_COLUMNS[dimension];
+        if (column == null)
+            continue;
+        parts.push(`events.${column} = ${bag.add(param, "string", value)}`);
+    }
+    return parts.length === 0 ? "" : ` AND ${parts.join(" AND ")}`;
+}
+/**
+ * The `session_start` attribute CTE and its join, rendered only when a session
+ * attribute is actually one of the grouping dimensions. A device or camera-mode
+ * *filter* never needs it — those are sub-selects.
+ */
+function sessionAttributes(bag, d, projectId, dimensions) {
+    const attributes = dimensions.filter((dimension) => isSessionAttribute(dimension.id));
+    if (attributes.length === 0)
+        return { cte: "", join: "" };
+    const pid = bag.add("saProjectId", "string", projectId);
+    const projections = attributes.map((dimension) => `${d.jsonText("payload", ...(SESSION_ATTRIBUTE_PATHS[dimension.id] ?? []))} AS ` +
+        `${attributeAlias(dimension.id)}`);
+    return {
+        cte: `WITH ${SESSION_CTE} AS (
+        SELECT session_id AS sa_session, ${projections.join(", ")}
+        FROM events
+        WHERE project_id = ${pid} AND event_type = 'session_start'
+      )
+      `,
+        join: `
+      LEFT JOIN ${SESSION_CTE} ON ${SESSION_CTE}.sa_session = events.session_id`,
+    };
+}
+/**
+ * Compile a generic group-by query for one metric.
+ *
+ * `metric` must declare `genericGroupBy` — the caller (`compileMetric`) has
+ * already checked that, and `validateQuery` before it, so the throw below guards
+ * a programming error rather than a client one.
+ */
+export function compileGenericGroupBy(metric, projectId, opts, d) {
+    const spec = metric.genericGroupBy;
+    if (spec == null) {
+        throw new Error(`metric '${metric.id}' declares no genericGroupBy and cannot be grouped by an arbitrary grain`);
+    }
+    const bag = new ParamBag(d);
+    const dimensions = resolveDimensions(metric, opts.dimensions ?? metric.grainDimensions);
+    // The attribute CTE binds its own project id, and must be rendered before the
+    // outer clauses so the parameters read in source order.
+    const attributes = sessionAttributes(bag, d, projectId, dimensions);
+    const pid = bag.add("projectId", "string", projectId);
+    const where = [
+        eventTypeClause(bag, spec.eventTypes),
+        scopeClause(spec.scope),
+        rangeClause(bag, opts),
+        equality(bag, "scene_id", "scene", opts.scene),
+        equality(bag, "session_id", "session", opts.session),
+        equality(bag, "source", "source", opts.source),
+        equality(bag, "mesh", "mesh", opts.mesh),
+        cameraModeClause(bag, d, projectId, opts),
+        deviceClause(bag, d, projectId, opts.device),
+        eventPredicateClause(bag, projectId, opts.event),
+        segmentClauses(bag, d, projectId, opts.segment),
+    ].join("");
+    const measures = spec.measures.map(renderMeasure);
+    const selected = [
+        ...dimensions.map((dimension) => `${dimension.expression} AS ${dimension.column}`),
+        ...measures,
+    ];
+    // Order by the asked-for measure, then by every dimension, so the row set a
+    // `LIMIT` keeps is a function of the data rather than of the engine's
+    // scan order — the same reason the summariser breaks ties on the label.
+    const primary = opts.order?.by ?? spec.measures[0]?.column ?? "1";
+    const direction = opts.order?.dir === "asc" ? "ASC" : "DESC";
+    const order = [
+        `${primary} ${direction}`,
+        ...dimensions.map((dimension) => `${dimension.expression} ASC`),
+    ].join(", ");
+    const limit = bag.add("limit", "u32", opts.limit ?? DEFAULT_GENERIC_LIMIT);
+    const groupBy = dimensions.length === 0
+        ? ""
+        : `
+      GROUP BY ${dimensions.map((dimension) => dimension.expression).join(", ")}`;
+    return {
+        query: `
+      ${attributes.cte}SELECT ${selected.join(", ")}
+      FROM events${attributes.join}
+      WHERE events.project_id = ${pid}${where}${groupBy}
+      ORDER BY ${order}
+      LIMIT ${limit}
+    `,
+        metric: metric.id,
+        query_params: bag.values,
+    };
+}
+/**
+ * The columns a generic group-by result carries, in order: the grouping
+ * dimensions, then the metric's measures. Used by the explain plan and by the
+ * tests that assert a generic row is self-describing.
+ */
+export function genericResultColumns(metric, dimensions) {
+    return [
+        ...dimensions.map((dimension) => dimensionColumn(metric, dimension)),
+        ...(metric.genericGroupBy?.measures ?? []).map((measure) => measure.column),
+    ];
+}
+//# sourceMappingURL=generic.js.map

package/dist/query/dsl/generic.js.map

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

package/dist/query/dsl/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The query DSL's compilation tiers (ADR 0051 §3, design sketch §C.2), and the
+ * four pure layers that sit on top of them.
+ *
+ * - **delegated** (`compile.ts`) — a validated `queryV1` document is mapped onto
+ *   the metric's existing aggregation builder, so every metric is reachable at
+ *   exactly the power its canned endpoint has.
+ * - **generic** (`generic.ts`) — a metric that declares `genericGroupBy` is
+ *   recomputed at any grain it declares, by one shared dialect-authored builder.
+ *
+ * On top: `compare.ts` joins two runs of the same spec, `significance.ts` says
+ * whether the difference is real, `explain.ts` renders the plan and the reasons
+ * not to trust it, and `order.ts` re-sorts a delegated result honestly. All four
+ * are pure — rows in, rows out — and none of them runs a query.
+ */
+export { builderFor } from "./builders.js";
+export type { AggregationBuilder } from "./builders.js";
+export { cameraTypeForMode, compileMetric, compileQuery, toBuilderOptions } from "./compile.js";
+export type { MetricQueryOptions, QueryResolution } from "./compile.js";
+export { compileGenericGroupBy, genericResultColumns } from "./generic.js";
+export type { GenericDeviceFilter, GenericEventPredicate, GenericQueryOptions } from "./generic.js";
+export { compareRows, comparisonKeys, summarizeComparison } from "./compare.js";
+export type { ComparisonBasis, ComparisonContext, ComparisonMeta, ComparisonResult, ComparisonRow, ComparisonSide, MoversSummary, } from "./compare.js";
+export { DEFAULT_ALPHA, normalCdf, sampleOf, studentTTwoSided, twoProportionZ, welchT, wilsonScoreInterval, } from "./significance.js";
+export type { MeanSignificance, Proportion, ProportionSignificance, Sample, ScoreInterval, Significance, } from "./significance.js";
+export { channelRows, explainQuery, explainSpec, planWarnings, silentChannels } from "./explain.js";
+export type { ExplainParam, ExplainParamType, PlanContext, QueryPlan } from "./explain.js";
+export { ORDER_AFTER_CAP_CAVEAT, applyOrder, reordersCappedResult } from "./order.js";
+export type { ResultOrder } from "./order.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/query/dsl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/query/dsl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChG,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACpG,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,MAAM,EACN,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,MAAM,EACN,aAAa,EACb,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpG,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACtF,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/query/dsl/index.js

@@ -0,0 +1,23 @@
+/**
+ * The query DSL's compilation tiers (ADR 0051 §3, design sketch §C.2), and the
+ * four pure layers that sit on top of them.
+ *
+ * - **delegated** (`compile.ts`) — a validated `queryV1` document is mapped onto
+ *   the metric's existing aggregation builder, so every metric is reachable at
+ *   exactly the power its canned endpoint has.
+ * - **generic** (`generic.ts`) — a metric that declares `genericGroupBy` is
+ *   recomputed at any grain it declares, by one shared dialect-authored builder.
+ *
+ * On top: `compare.ts` joins two runs of the same spec, `significance.ts` says
+ * whether the difference is real, `explain.ts` renders the plan and the reasons
+ * not to trust it, and `order.ts` re-sorts a delegated result honestly. All four
+ * are pure — rows in, rows out — and none of them runs a query.
+ */
+export { builderFor } from "./builders.js";
+export { cameraTypeForMode, compileMetric, compileQuery, toBuilderOptions } from "./compile.js";
+export { compileGenericGroupBy, genericResultColumns } from "./generic.js";
+export { compareRows, comparisonKeys, summarizeComparison } from "./compare.js";
+export { DEFAULT_ALPHA, normalCdf, sampleOf, studentTTwoSided, twoProportionZ, welchT, wilsonScoreInterval, } from "./significance.js";
+export { channelRows, explainQuery, explainSpec, planWarnings, silentChannels } from "./explain.js";
+export { ORDER_AFTER_CAP_CAVEAT, applyOrder, reordersCappedResult } from "./order.js";
+//# sourceMappingURL=index.js.map

package/dist/query/dsl/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/query/dsl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhG,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAUhF,OAAO,EACL,aAAa,EACb,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,MAAM,EACN,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAS3B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEpG,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/query/dsl/order.d.ts

@@ -0,0 +1,41 @@
+/**
+ * **`order`: on the delegated tier** (ADR 0051 §3).
+ *
+ * The generic builder puts the caller's `order` straight into its `ORDER BY`, so
+ * the row cap keeps the rows the caller asked for. A *delegated* metric cannot:
+ * its builder has one `ORDER BY` of its own, and it applied the `LIMIT` in that
+ * order before these rows existed.
+ *
+ * So a delegated re-order is exactly what it looks like — a re-sort of the rows
+ * that came back, done here rather than in the model's head. What it is **not**
+ * is a "bottom N": asking `top_meshes` for `count ASC` returns the *top* rows
+ * sorted ascending, because the store already discarded everything below the
+ * cap. {@link ORDER_AFTER_CAP_CAVEAT} says so, and the collector attaches it to
+ * the envelope whenever this function actually changed the order of a capped
+ * result — which is the only honest way to offer the feature at all.
+ */
+/** A row as it leaves a store. */
+type Row = Readonly<Record<string, unknown>>;
+/** What `order` asks for. */
+export interface ResultOrder {
+    by: string;
+    dir: "asc" | "desc";
+}
+/** Attached to a result whose delegated rows were re-ordered after the cap. */
+export declare const ORDER_AFTER_CAP_CAVEAT: string;
+/**
+ * Re-sort rows by a column, missing and non-numeric values last in either
+ * direction (a row with no value is not "the smallest"; it is unmeasured).
+ * Ties break on the remaining columns' rendered values so the order is a
+ * function of the row set rather than of the engine's scan order.
+ *
+ * Returns a new array; the input is never mutated.
+ */
+export declare function applyOrder<T extends Row>(rows: readonly T[], order: ResultOrder): T[];
+/**
+ * Whether re-ordering `rows` could misrepresent a capped result — the condition
+ * under which {@link ORDER_AFTER_CAP_CAVEAT} belongs on the envelope.
+ */
+export declare function reordersCappedResult(rows: readonly Row[], limit: number | undefined): boolean;
+export {};
+//# sourceMappingURL=order.d.ts.map

package/dist/query/dsl/order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../../src/query/dsl/order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kCAAkC;AAClC,KAAK,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE7C,6BAA6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,KAAK,GAAG,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,QAGiD,CAAC;AAErF;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,CAAC,EAAE,CAgBrF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE7F"}

package/dist/query/dsl/order.js

@@ -0,0 +1,55 @@
+/**
+ * **`order`: on the delegated tier** (ADR 0051 §3).
+ *
+ * The generic builder puts the caller's `order` straight into its `ORDER BY`, so
+ * the row cap keeps the rows the caller asked for. A *delegated* metric cannot:
+ * its builder has one `ORDER BY` of its own, and it applied the `LIMIT` in that
+ * order before these rows existed.
+ *
+ * So a delegated re-order is exactly what it looks like — a re-sort of the rows
+ * that came back, done here rather than in the model's head. What it is **not**
+ * is a "bottom N": asking `top_meshes` for `count ASC` returns the *top* rows
+ * sorted ascending, because the store already discarded everything below the
+ * cap. {@link ORDER_AFTER_CAP_CAVEAT} says so, and the collector attaches it to
+ * the envelope whenever this function actually changed the order of a capped
+ * result — which is the only honest way to offer the feature at all.
+ */
+/** Attached to a result whose delegated rows were re-ordered after the cap. */
+export const ORDER_AFTER_CAP_CAVEAT = "`order` was applied to the rows this metric returned, which its own builder had already " +
+    "capped in its own order — so an ascending sort shows the smallest of the top rows, not the " +
+    "smallest overall. Raise `limit`, or group by the dimension you want the tail of.";
+/**
+ * Re-sort rows by a column, missing and non-numeric values last in either
+ * direction (a row with no value is not "the smallest"; it is unmeasured).
+ * Ties break on the remaining columns' rendered values so the order is a
+ * function of the row set rather than of the engine's scan order.
+ *
+ * Returns a new array; the input is never mutated.
+ */
+export function applyOrder(rows, order) {
+    const sign = order.dir === "asc" ? 1 : -1;
+    return [...rows].sort((a, b) => {
+        const left = a[order.by];
+        const right = b[order.by];
+        const leftNumber = typeof left === "number" && Number.isFinite(left) ? left : null;
+        const rightNumber = typeof right === "number" && Number.isFinite(right) ? right : null;
+        if (leftNumber == null || rightNumber == null) {
+            if (leftNumber !== rightNumber)
+                return leftNumber == null ? 1 : -1;
+        }
+        else if (leftNumber !== rightNumber) {
+            return sign * (leftNumber - rightNumber);
+        }
+        const leftKey = JSON.stringify(a);
+        const rightKey = JSON.stringify(b);
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+    });
+}
+/**
+ * Whether re-ordering `rows` could misrepresent a capped result — the condition
+ * under which {@link ORDER_AFTER_CAP_CAVEAT} belongs on the envelope.
+ */
+export function reordersCappedResult(rows, limit) {
+    return limit != null && Number.isFinite(limit) && rows.length >= limit;
+}
+//# sourceMappingURL=order.js.map

package/dist/query/dsl/order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.js","sourceRoot":"","sources":["../../../src/query/dsl/order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GACjC,0FAA0F;IAC1F,6FAA6F;IAC7F,kFAAkF,CAAC;AAErF;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAgB,IAAkB,EAAE,KAAkB;IAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,UAAU,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACnF,MAAM,WAAW,GAAG,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACvF,IAAI,UAAU,IAAI,IAAI,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;YAC9C,IAAI,UAAU,KAAK,WAAW;gBAAE,OAAO,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,CAAC;aAAM,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;YACtC,OAAO,IAAI,GAAG,CAAC,UAAU,GAAG,WAAW,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACnC,OAAO,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAoB,EAAE,KAAyB;IAClF,OAAO,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;AACzE,CAAC"}

package/dist/query/dsl/significance.d.ts

@@ -0,0 +1,130 @@
+/**
+ * **Is this change real?** — the two significance tests `compare` can justify
+ * (ADR 0051 §4, design sketch §C.2).
+ *
+ * Pure functions over numbers: no registry, no store, no I/O. They exist here
+ * rather than inline in `compare.ts` so they can be unit-tested against
+ * textbook worked examples, which is the only way to be sure a statistic is
+ * right — a plausible-looking number is exactly the failure mode this file is
+ * meant to prevent, since a model will quote whatever it is handed.
+ *
+ * Two tests, because analytics produces two shapes of measure:
+ *
+ * - {@link twoProportionZ} — a **count or rate**. "Was 40/1000 this week
+ *   different from 25/900 last week?" Pooled two-proportion z, two-sided normal
+ *   p-value, plus a Wilson score interval on each proportion (which, unlike the
+ *   Wald interval, stays inside 0..1 at the small counts a long tail produces —
+ *   the same reason the summariser already uses it).
+ * - {@link welchT} — a **mean** over two samples of unequal size and variance.
+ *   Welch's unequal-variance t-test with the Welch–Satterthwaite degrees of
+ *   freedom. It applies where the two ranges really do give two *samples*: a
+ *   `bucket`-grain metric compared range-over-range hands us one value per
+ *   bucket on each side.
+ *
+ * Neither is applied speculatively. `compare.ts` computes a significance only
+ * when the registry says the measure supports it (`unit: count | sessions`, or a
+ * `rateOf` denominator) and the denominator clears the metric's
+ * `comparable.minSample`; otherwise the field is simply absent, because
+ * "no p-value" is a far better answer than a p-value computed from a
+ * denominator that cannot support one.
+ *
+ * ## Accuracy
+ *
+ * The normal CDF uses the Abramowitz & Stegun 7.1.26 rational approximation of
+ * `erf` (|error| < 1.5e-7). The Student-t CDF uses the regularised incomplete
+ * beta function via the Lentz continued fraction (Numerical Recipes §6.4),
+ * converged to 3e-16 or 300 iterations. Both are far tighter than the third
+ * significant figure anyone reads off a p-value.
+ */
+/** A 95% (by default) score interval on a proportion. */
+export interface ScoreInterval {
+    low: number;
+    high: number;
+}
+/** One side of a proportion comparison. */
+export interface Proportion {
+    /** Events (or sessions) in this group. */
+    successes: number;
+    /** Events (or sessions) in the population the group is part of. */
+    trials: number;
+}
+/** The result of a two-proportion z test. */
+export interface ProportionSignificance {
+    test: "two-proportion-z";
+    /** Share of the current population. */
+    current: number;
+    /** Share of the previous population. */
+    previous: number;
+    /** `current - previous`, in share points. */
+    diff: number;
+    /** The test statistic. */
+    z: number;
+    /** Two-sided p-value under the normal approximation. */
+    pValue: number;
+    /** Whether `pValue` clears the level the caller asked for. */
+    significant: boolean;
+    /** 95% Wilson score interval on the current share. */
+    currentInterval: ScoreInterval;
+    /** 95% Wilson score interval on the previous share. */
+    previousInterval: ScoreInterval;
+}
+/** The result of Welch's unequal-variance t test. */
+export interface MeanSignificance {
+    test: "welch-t";
+    current: number;
+    previous: number;
+    diff: number;
+    /** The test statistic. */
+    t: number;
+    /** Welch–Satterthwaite degrees of freedom. */
+    df: number;
+    pValue: number;
+    significant: boolean;
+    /** Samples behind each mean — a t-test on two points is not evidence. */
+    currentSamples: number;
+    previousSamples: number;
+}
+/** Either shape of significance a comparison row can carry. */
+export type Significance = ProportionSignificance | MeanSignificance;
+/** The default two-sided level. */
+export declare const DEFAULT_ALPHA = 0.05;
+/** The standard normal CDF, Φ(x). */
+export declare function normalCdf(x: number): number;
+/** The two-sided p-value of a Student-t statistic with `df` degrees of freedom. */
+export declare function studentTTwoSided(t: number, df: number): number;
+/**
+ * A Wilson score interval on `successes / trials`.
+ *
+ * The same interval the summary envelope reports, restated here so this module
+ * stays free of the summariser (and vice versa): both need it, neither should
+ * import the other.
+ */
+export declare function wilsonScoreInterval(successes: number, trials: number, z?: number): ScoreInterval;
+/**
+ * Pooled two-proportion z test: is `current.successes / current.trials`
+ * different from `previous.successes / previous.trials`?
+ *
+ * Returns `null` when either side has no trials — a proportion of nothing is not
+ * a proportion, and reporting `z = 0` for it would read as "no change" when the
+ * truth is "no data".
+ */
+export declare function twoProportionZ(current: Proportion, previous: Proportion, alpha?: number): ProportionSignificance | null;
+/** One sample, described by the three numbers Welch's test needs. */
+export interface Sample {
+    mean: number;
+    /** Unbiased (n − 1) sample variance. */
+    variance: number;
+    /** Number of observations. */
+    n: number;
+}
+/** Mean and unbiased variance of a list of observations; `null` below two. */
+export declare function sampleOf(values: readonly number[]): Sample | null;
+/**
+ * Welch's unequal-variance t test with the Welch–Satterthwaite degrees of
+ * freedom.
+ *
+ * Returns `null` when either sample has fewer than two observations (there is no
+ * variance to test) or when both variances are zero and the means are equal.
+ */
+export declare function welchT(current: Sample, previous: Sample, alpha?: number): MeanSignificance | null;
+//# sourceMappingURL=significance.d.ts.map

package/dist/query/dsl/significance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"significance.d.ts","sourceRoot":"","sources":["../../../src/query/dsl/significance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,kBAAkB,CAAC;IACzB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,WAAW,EAAE,OAAO,CAAC;IACrB,sDAAsD;IACtD,eAAe,EAAE,aAAa,CAAC;IAC/B,uDAAuD;IACvD,gBAAgB,EAAE,aAAa,CAAC;CACjC;AAED,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,sBAAsB,GAAG,gBAAgB,CAAC;AAErE,mCAAmC;AACnC,eAAO,MAAM,aAAa,OAAO,CAAC;AAmBlC,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAiED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,CAAC,GAAE,MAAa,GACf,aAAa,CAUf;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,UAAU,EACpB,KAAK,GAAE,MAAsB,GAC5B,sBAAsB,GAAG,IAAI,CAwB/B;AAED,qEAAqE;AACrE,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,CAAC,EAAE,MAAM,CAAC;CACX;AAED,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAOjE;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAsB,GAC5B,gBAAgB,GAAG,IAAI,CAqBzB"}