@miragon/pulse-analytics-client 0.0.0-bootstrap.0 → 0.21.0

package/dist/queries/health.js

@@ -0,0 +1,126 @@
+import { engineIdsOf, engineMatcher, selector, } from "../prometheus.js";
+import { METRIC_NAMES as M } from "../metric-names.js";
+import { engineState, reportingEnginesQuery } from "./helpers.js";
+/**
+ * Name pattern (RE2) of the alert rules this module ships
+ * (`playground/docker/prometheus/alerts.yml`). An alert WITHOUT an
+ * `engine_id` label — a pipeline-level rule such as `CibSevenEngineNoMetrics`
+ * — only counts when it matches this pattern: in a shared Prometheus every
+ * other engine-less alert belongs to somebody else.
+ */
+export const ENGINE_ALERT_NAME_PATTERN = "CibSeven.+";
+/**
+ * How {@link engineHealth} decides `status`, in words — carried in every
+ * result (`statusRule`) and the tool description, so no reader mistakes this
+ * alert-based verdict for camunda7_show_engine_health's incident-count one:
+ * the two judge different data by different rules and may disagree for the
+ * same engine (500 open incidents without a firing critical alert stay
+ * "degraded" here).
+ */
+export const ENGINE_HEALTH_STATUS_RULE = "From Prometheus, over the engines in scope: unknown when none of them reports metrics; critical only while a severity=critical alert fires for them (fleet-wide also an engine-less CibSeven* alert); degraded with any such firing alert, dead job, open incident or an engine in scope that reports nothing; else healthy.";
+const first = (s) => (s.length ? Math.round(s[0].value) : 0);
+const total = (s) => Math.round(s.reduce((sum, x) => sum + x.value, 0));
+function counts(samples, label) {
+    return samples
+        .map((s) => ({ label: s.metric[label] ?? "", count: Math.round(s.value) }))
+        .filter((c) => c.count !== 0)
+        .sort((a, b) => b.count - a.count);
+}
+function alerts(samples) {
+    return samples.map((s) => ({
+        name: s.metric.alertname ?? "",
+        severity: s.metric.severity ?? "",
+        scope: s.metric.process_definition_key ?? s.metric.incident_type ?? s.metric.engine_id ?? "",
+    }));
+}
+/**
+ * The `ALERTS` selection for one alert state. With an engine scope: the
+ * alerts carrying one of its `engine_id`s, plus — only for a fleet-wide
+ * verdict — this module's engine-less rules. Without one: this module's
+ * rules only.
+ */
+function alertsQuery(state, engine, includeFleetAlerts) {
+    const own = `alertname=~"${ENGINE_ALERT_NAME_PATTERN}"`;
+    const stateMatcher = `alertstate="${state}"`;
+    const engineSel = engineMatcher(engine);
+    if (!engineSel)
+        return `ALERTS${selector(stateMatcher, own)}`;
+    const scoped = `ALERTS${selector(stateMatcher, engineSel)}`;
+    return includeFleetAlerts
+        ? `${scoped} or ALERTS${selector(stateMatcher, own, `engine_id=""`)}`
+        : scoped;
+}
+/**
+ * Live operational health of the engine(s), from the point-in-time gauges plus
+ * Prometheus' own `ALERTS` series. A one-call ops snapshot: running WIP, open
+ * incidents, dead jobs, job/task/external-task backlog, and which alert rules
+ * are firing/pending.
+ *
+ * Absence is not health: the engine-only gauges (`jobs_executable`,
+ * `external_tasks_open`) double as the presence probe, so an engine that
+ * sends nothing — or an id that matches no series — reads `unknown` (none in
+ * scope reports) or lands in `silentEngines` (degrading the verdict), never
+ * `healthy`. `includeFleetAlerts` (default: exactly when `engine` is
+ * omitted) adds the module's engine-less alerts — set it when `engine` lists
+ * the whole configured fleet.
+ */
+export async function engineHealth(ch, params) {
+    const sel = selector(engineMatcher(params.engine));
+    const fleet = params.includeFleetAlerts ?? engineIdsOf(params.engine) === null;
+    const [runningByDef, incidentsByType, deadJobs, executableByEngine, suspendedJobs, openTasks, unassignedTasks, externalByEngine, deployedKeys, firing, pending,] = await Promise.all([
+        ch.instant(`sum by (process_definition_key)(${engineState(M.processInstancesRunning, sel)})`),
+        ch.instant(`sum by (incident_type)(${engineState(M.incidentsOpen, sel)})`),
+        ch.instant(`sum(${engineState(M.jobsFailed, sel)})`),
+        ch.instant(reportingEnginesQuery(sel)),
+        ch.instant(`sum(${engineState(M.jobsSuspended, sel)})`),
+        ch.instant(`sum(${engineState(M.userTasksOpen, selector(`status="total"`, engineMatcher(params.engine)))})`),
+        ch.instant(`sum(${engineState(M.userTasksOpen, selector(`status="unassigned"`, engineMatcher(params.engine)))})`),
+        ch.instant(engineState(M.externalTasksOpen, sel)),
+        // Distinct keys, not series: a key deployed on two engines counts once.
+        ch.instant(`count(count by (process_definition_key)(${engineState(M.processDefinitionsDeployed, sel)}))`),
+        ch.instant(alertsQuery("firing", params.engine, fleet)),
+        ch.instant(alertsQuery("pending", params.engine, fleet)),
+    ]);
+    const runningByDefinition = counts(runningByDef, "process_definition_key");
+    const openIncidentsByType = counts(incidentsByType, "incident_type");
+    const firingAlerts = alerts(firing);
+    const pendingAlerts = alerts(pending);
+    const openIncidents = openIncidentsByType.reduce((s, c) => s + c.count, 0);
+    const runningInstances = runningByDefinition.reduce((s, c) => s + c.count, 0);
+    const dead = first(deadJobs);
+    const engines = engineIdsOf(params.engine);
+    const reportingEngines = [
+        ...new Set([...executableByEngine, ...externalByEngine]
+            .map((s) => s.metric.engine_id)
+            .filter((id) => !!id)),
+    ].sort();
+    const silentEngines = (engines ?? []).filter((id) => !reportingEngines.includes(id));
+    const status = reportingEngines.length === 0
+        ? "unknown"
+        : firingAlerts.some((a) => a.severity === "critical")
+            ? "critical"
+            : firingAlerts.length > 0 || dead > 0 || openIncidents > 0 || silentEngines.length > 0
+                ? "degraded"
+                : "healthy";
+    return {
+        status,
+        statusRule: ENGINE_HEALTH_STATUS_RULE,
+        engines,
+        reportingEngines,
+        silentEngines,
+        runningInstances,
+        runningByDefinition,
+        openIncidents,
+        openIncidentsByType,
+        deadJobs: dead,
+        executableJobs: total(executableByEngine),
+        suspendedJobs: first(suspendedJobs),
+        openUserTasks: first(openTasks),
+        unassignedUserTasks: first(unassignedTasks),
+        openExternalTasks: total(externalByEngine),
+        deployedDefinitionKeys: first(deployedKeys),
+        firingAlerts,
+        pendingAlerts,
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/queries/health.js.map

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

package/dist/queries/health.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=health.test.d.ts.map

package/dist/queries/health.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.test.d.ts","sourceRoot":"","sources":["../../src/queries/health.test.ts"],"names":[],"mappings":""}

package/dist/queries/health.test.js

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from "vitest";
+import { ENGINE_HEALTH_STATUS_RULE, engineHealth } from "./health.js";
+const sample = (metric, value) => ({ metric, value });
+/** Answers each gauge by its metric name; ALERTS by its alertstate. */
+function mockClient(fixture = {}) {
+    const scalar = (value) => (value === undefined ? [] : [sample({}, value)]);
+    const perEngine = (value) => (fixture.reporting ?? ["prod-a"]).map((engine_id) => sample({ engine_id }, value));
+    const instant = vi.fn(async (q) => {
+        if (q.startsWith("ALERTS")) {
+            return (q.includes('"firing"') ? fixture.firing : fixture.pending) ?? [];
+        }
+        if (q.includes("process_instances_running"))
+            return fixture.running ?? [];
+        if (q.includes("incidents_open"))
+            return fixture.incidents ?? [];
+        if (q.includes("jobs_failed"))
+            return scalar(fixture.dead);
+        if (q.includes("jobs_executable"))
+            return perEngine(6.2);
+        if (q.includes("jobs_suspended"))
+            return scalar(2);
+        if (q.includes('status="total"'))
+            return scalar(9);
+        if (q.includes('status="unassigned"'))
+            return scalar(4);
+        if (q.includes("external_tasks_open"))
+            return perEngine(3.3);
+        if (q.includes("process_definitions_deployed"))
+            return scalar(3);
+        return [];
+    });
+    const ch = { instant };
+    return { ch, instant };
+}
+const alert = (alertname, severity, scope = {}) => sample({ alertname, severity, ...scope }, 1);
+describe("engineHealth snapshot", () => {
+    it("reports every gauge, rounded, with breakdowns sorted and zero rows dropped", async () => {
+        const { ch } = mockClient({
+            reporting: ["prod-a", "prod-b"],
+            running: [
+                sample({ process_definition_key: "invoice" }, 2),
+                sample({ process_definition_key: "order" }, 7.4),
+                sample({ process_definition_key: "idle" }, 0.2),
+                sample({}, 1),
+            ],
+            incidents: [sample({ incident_type: "failedJob" }, 3)],
+            dead: 1.6,
+        });
+        const result = await engineHealth(ch, {});
+        expect(result).toMatchObject({
+            engines: null,
+            reportingEngines: ["prod-a", "prod-b"],
+            silentEngines: [],
+            runningInstances: 10,
+            runningByDefinition: [
+                { label: "order", count: 7 },
+                { label: "invoice", count: 2 },
+                { label: "", count: 1 },
+            ],
+            openIncidents: 3,
+            openIncidentsByType: [{ label: "failedJob", count: 3 }],
+            deadJobs: 2,
+            // Summed across the reporting engines.
+            executableJobs: 12,
+            suspendedJobs: 2,
+            openUserTasks: 9,
+            unassignedUserTasks: 4,
+            openExternalTasks: 7,
+            deployedDefinitionKeys: 3,
+        });
+    });
+    it("names each alert's scope by process, else incident type, else engine", async () => {
+        const { ch } = mockClient({
+            firing: [
+                alert("A", "warning", { process_definition_key: "order", incident_type: "x" }),
+                alert("B", "warning", { incident_type: "failedJob", engine_id: "prod-a" }),
+                alert("C", "warning", { engine_id: "prod-a" }),
+                sample({}, 1),
+            ],
+            pending: [alert("D", "info")],
+        });
+        const result = await engineHealth(ch, {});
+        expect(result.firingAlerts).toEqual([
+            { name: "A", severity: "warning", scope: "order" },
+            { name: "B", severity: "warning", scope: "failedJob" },
+            { name: "C", severity: "warning", scope: "prod-a" },
+            { name: "", severity: "", scope: "" },
+        ]);
+        expect(result.pendingAlerts).toEqual([{ name: "D", severity: "info", scope: "" }]);
+    });
+});
+/**
+ * #340: the verdict is alert-based and says so — the same engine may be
+ * "critical" in camunda7_show_engine_health (incident counts) and only
+ * "degraded" here. #336: silence is not health.
+ */
+describe("engineHealth verdict", () => {
+    it.each([
+        ["a reporting engine without any signal", {}, "healthy"],
+        ["one open incident", { incidents: [sample({ incident_type: "failedJob" }, 1)] }, "degraded"],
+        ["one dead job", { dead: 1 }, "degraded"],
+        ["a firing warning", { firing: [alert("Slow", "warning")] }, "degraded"],
+        ["a firing critical alert", { firing: [alert("NoMetrics", "critical")] }, "critical"],
+        ["a merely PENDING critical alert", { pending: [alert("NoMetrics", "critical")] }, "healthy"],
+        [
+            "500 open incidents without a critical alert",
+            { incidents: [sample({ incident_type: "failedJob" }, 500)] },
+            "degraded",
+        ],
+        ["no engine reporting any metric", { reporting: [] }, "unknown"],
+        [
+            "no engine reporting, even with a critical alert firing",
+            { reporting: [], firing: [alert("CibSevenEngineNoMetrics", "critical")] },
+            "unknown",
+        ],
+    ])("%s → %s", async (_label, fixture, status) => {
+        const result = await engineHealth(mockClient(fixture).ch, {});
+        expect(result.status).toBe(status);
+        expect(result.statusRule).toBe(ENGINE_HEALTH_STATUS_RULE);
+    });
+    it("reads an engine that sends nothing — or a mistyped id — as unknown, never healthy (N76)", async () => {
+        const { ch } = mockClient({ reporting: [] });
+        const result = await engineHealth(ch, { engine: "prod-b" });
+        expect(result).toMatchObject({
+            status: "unknown",
+            engines: ["prod-b"],
+            reportingEngines: [],
+            silentEngines: ["prod-b"],
+        });
+    });
+    it("degrades a scope in which one engine is silent", async () => {
+        const { ch } = mockClient({ reporting: ["prod-a"] });
+        const result = await engineHealth(ch, { engine: ["prod-a", "prod-b"] });
+        expect(result).toMatchObject({
+            status: "degraded",
+            reportingEngines: ["prod-a"],
+            silentEngines: ["prod-b"],
+        });
+    });
+    it("states its rule in words", () => {
+        expect(ENGINE_HEALTH_STATUS_RULE).toBe("From Prometheus, over the engines in scope: unknown when none of them reports metrics; critical only while a severity=critical alert fires for them (fleet-wide also an engine-less CibSeven* alert); degraded with any such firing alert, dead job, open incident or an engine in scope that reports nothing; else healthy.");
+    });
+});
+describe("engineHealth PromQL", () => {
+    it("scopes every gauge and the ALERTS series to the engine filter", async () => {
+        const { ch, instant } = mockClient();
+        await engineHealth(ch, { engine: "prod-a" });
+        const sel = '{engine_id="prod-a"}';
+        // Every gauge folded over its own labels first: a clustered engine's nodes
+        // report the same engine-wide rows.
+        const perKey = "max by (process_definition_key, engine_id)";
+        expect(instant.mock.calls.map(([q]) => q)).toEqual([
+            `sum by (process_definition_key)(${perKey}(camunda_process_instances_running${sel}))`,
+            `sum by (incident_type)(max by (process_definition_key, incident_type, engine_id)(camunda_incidents_open${sel}))`,
+            `sum(${perKey}(camunda_jobs_failed${sel}))`,
+            `max by (engine_id)(camunda_jobs_executable${sel})`,
+            `sum(max by (engine_id)(camunda_jobs_suspended${sel}))`,
+            `sum(max by (status, engine_id)(camunda_usertasks_open{status="total",engine_id="prod-a"}))`,
+            `sum(max by (status, engine_id)(camunda_usertasks_open{status="unassigned",engine_id="prod-a"}))`,
+            `max by (engine_id)(camunda_external_tasks_open${sel})`,
+            `count(count by (process_definition_key)(${perKey}(camunda_process_definitions_deployed${sel})))`,
+            // One engine named: only alerts carrying its engine_id — an unrelated
+            // alert in a shared Prometheus cannot turn its verdict critical.
+            `ALERTS{alertstate="firing",engine_id="prod-a"}`,
+            `ALERTS{alertstate="pending",engine_id="prod-a"}`,
+        ]);
+    });
+    it("adds the module's engine-less alerts only for the whole fleet", async () => {
+        const { ch, instant } = mockClient();
+        await engineHealth(ch, { engine: ["prod-a", "prod-b"], includeFleetAlerts: true });
+        const alertQueries = instant.mock.calls.map(([q]) => q).filter((q) => q.startsWith("ALERTS"));
+        expect(alertQueries).toEqual([
+            'ALERTS{alertstate="firing",engine_id=~"prod-a|prod-b"} or ALERTS{alertstate="firing",alertname=~"CibSeven.+",engine_id=""}',
+            'ALERTS{alertstate="pending",engine_id=~"prod-a|prod-b"} or ALERTS{alertstate="pending",alertname=~"CibSeven.+",engine_id=""}',
+        ]);
+    });
+    it("reads only the module's own rules when unscoped — never a shared Prometheus' foreign alerts", async () => {
+        const { ch, instant } = mockClient();
+        await engineHealth(ch, {});
+        const alertQueries = instant.mock.calls.map(([q]) => q).filter((q) => q.startsWith("ALERTS"));
+        expect(alertQueries).toEqual([
+            'ALERTS{alertstate="firing",alertname=~"CibSeven.+"}',
+            'ALERTS{alertstate="pending",alertname=~"CibSeven.+"}',
+        ]);
+    });
+});
+//# sourceMappingURL=health.test.js.map

package/dist/queries/health.test.js.map

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

package/dist/queries/helpers.d.ts

@@ -0,0 +1,184 @@
+import type { PrometheusClient, PromSample } from "../prometheus.js";
+import { type GaugeName } from "../metric-names.js";
+import { type CountWindow } from "./windows.js";
+/** Round to one decimal place (KPI seconds / percentages). */
+export declare const round1: (n: number) => number;
+/** Milliseconds (the duration histograms' unit) as seconds, one decimal. */
+export declare const secondsOf: (ms: number) => number;
+/** {@link secondsOf} that passes `null` (not measured) through. */
+export declare const secondsOrNull: (ms: number | null) => number | null;
+/**
+ * What a counter or histogram series recorded inside `w`, per series — the
+ * ONE way every query reads a counter (contract rule 2). The plugin creates a
+ * series on its first event, and `increase()` never counts a series' first
+ * sample: a rare event such as the first incident of a type at an activity
+ * would read 0. So a series that existed before the window counts its
+ * `increase()`, and a series born inside it counts its whole value.
+ * `series` is a metric name plus its selector, e.g. `camunda_x{engine_id="a"}`.
+ *
+ * The check looks at the hour before the window. Where that hour lies past
+ * the retention (the 30-day period), Prometheus has deleted it and every
+ * series would pass for new, counting its whole history; there it looks at
+ * the window's own first hour instead: a series silent then was born later.
+ * Only a window of an hour or less at the retention edge has no hour to look
+ * at and reads plain `increase()`, which can miss a series' first sample but
+ * never counts what happened before the window.
+ */
+export declare function increaseIn(series: string, w: CountWindow): string;
+/**
+ * An engine-state gauge with one row per engine-wide figure (contract rule 3):
+ * every node of a clustered engine reports the same rows, so the nodes are
+ * folded with `max` over the gauge's contract labels before anything sums them.
+ */
+export declare const engineState: (gauge: GaugeName, sel: string) => string;
+/**
+ * Parse an ISO datetime into epoch seconds. Throws a caller-readable error
+ * instead of letting a NaN reach PromQL as `[NaNs] @ NaN` (Prometheus would
+ * answer with an opaque parse error).
+ */
+export declare function parseIsoSeconds(value: string, field: string): number;
+/**
+ * Value of the first sample, or 0 when the query returned no series — for
+ * COUNTS (`sum(increase(…))`), where "no series in the window" means nothing
+ * happened. Never use it for a duration or a gauge: there a missing series is
+ * "not measured", see {@link firstOrNull}.
+ */
+export declare const first: (s: PromSample[]) => number;
+/**
+ * Value of the first sample, or `null` when the query returned none — for
+ * durations and live gauges. A duration over an empty window is NaN
+ * (`0 / 0`, `histogram_quantile` over all-zero buckets), which the client
+ * drops, so "nothing ended in the window" lands here as `null`, never as a
+ * plausible 0 s. A per-key gauge without a series is 0 while the engines
+ * report and "not reported" only while they do not — decide that with
+ * {@link reportingEnginesQuery}, never from the gauge's own series.
+ */
+export declare const firstOrNull: (s: PromSample[]) => number | null;
+/**
+ * The engine-state presence probe — one series per engine in scope that
+ * reports its state gauges. `camunda_jobs_executable` carries `engine_id`
+ * only and is registered on every tick, 0 included; the per-key gauges are
+ * not: the metrics plugin registers a row only for what exists (no incident
+ * open → no `camunda_incidents_open` series at all). So a per-key gauge
+ * without a series is a measured 0 while this probe answers, and "not
+ * reported" only while it does not. `engineSel` must hold the engine matcher
+ * alone — the gauge has no other label to match.
+ */
+export declare const reportingEnginesQuery: (engineSel: string) => string;
+/** The engine ids the {@link reportingEnginesQuery} probe answered for, ascending. */
+export declare const reportingEngineIds: (samples: PromSample[]) => string[];
+/** The as-of stamp of a result: now, as an ISO timestamp (the instant queries evaluate at now). */
+export declare const asOfNow: () => string;
+/**
+ * Index sample values by one label, dropping samples that miss the label.
+ * The last sample wins on duplicate label values.
+ */
+export declare function byLabel(samples: PromSample[], label: string): Record<string, number>;
+/**
+ * `part` per 100 of `base`, one decimal — `null` when `base` is 0 (a rate of
+ * nothing is undefined, not 0 %). Incident rates divide incidents by
+ * instances; one instance can carry several incidents, so they may exceed 100.
+ */
+export declare function ratePct(part: number, base: number): number | null;
+/**
+ * Percentage change from `before` to `after`, rounded to two decimals. `null`
+ * when either side is not measured or the baseline is 0 — never a −100 % from
+ * a missing value or a division by zero.
+ */
+export declare function pctChange(before: number | null, after: number | null): number | null;
+/** Percentage-point difference of two rates; `null` when either is not measured. */
+export declare function ppDelta(before: number | null, after: number | null): number | null;
+/** Label selectors scoping one KPI partition (a window, an engine, a version …). */
+export interface KpiScope {
+    /** Base selector: instance starts, incidents and durations. */
+    sel: string;
+    /** Base selector additionally matching `state="COMPLETED"` (completed count). */
+    completedSel: string;
+    /**
+     * Selector for the element-scoped incident count — the base selector
+     * narrowed to one `activity_id`. Absent: no element scope, no element query.
+     */
+    elementIncidentSel?: string;
+}
+/**
+ * The shared instance-KPI PromQL block used by the dashboard, performance and
+ * compare modules: counts via {@link increaseIn} over the window, durations
+ * from the histogram (`histogram_quantile` for p50/p95, sum/count for the
+ * mean), in MILLISECONDS — the histogram's unit; callers convert. Callers pick
+ * the strings they need.
+ *
+ * The duration histogram is recorded when an instance ENDS (any end state), so
+ * every duration covers the instances that ended inside the window only —
+ * still-running long instances are not in it (survivorship), and an empty
+ * window yields no value at all.
+ */
+export declare function kpiQueries(scope: KpiScope, w: CountWindow): {
+    started: string;
+    completed: string;
+    incidents: string;
+    avgDuration: string;
+    medianDuration: string;
+    p95Duration: string;
+};
+/** The KPI core every compare module reports per partition. */
+export interface CompareKpis {
+    /** Process instances STARTED in the window. */
+    instance_count: number;
+    /** Instances that ended with state COMPLETED in the window. */
+    completed_count: number;
+    /** Incidents CREATED in the window (every activity of the scope). */
+    incident_count: number;
+    /**
+     * `incident_count` per 100 started instances — `null` when nothing started.
+     * Several incidents per instance are possible, so it may exceed 100.
+     */
+    incident_rate_pct: number | null;
+    /** Incidents created at the `activityId` element — `null` without one. */
+    element_incident_count: number | null;
+    /** `element_incident_count` per 100 started instances — `null` without an element or starts. */
+    element_incident_rate_pct: number | null;
+    /** Mean duration of the instances that ENDED in the window — `null` when none did. */
+    avg_duration_sec: number | null;
+    /** p95 duration of the instances that ENDED in the window — `null` when none did. */
+    p95_duration_sec: number | null;
+}
+/**
+ * Runs the KPI block shared by the compare modules (cluster / engine /
+ * version) for one partition: five queries, plus the element-scoped incident
+ * count when `scope.elementIncidentSel` is set.
+ */
+export declare function queryCompareKpis(ch: PrometheusClient, scope: KpiScope, w: CountWindow): Promise<CompareKpis>;
+/**
+ * Deltas of `other` vs `baseline`: percentage points for rates, percent
+ * otherwise. Every delta is `null` when either side is not measured or the
+ * baseline is 0.
+ */
+export interface CompareKpiDelta {
+    /**
+     * Change in instances started PER DAY — equal windows make it the plain
+     * count change; windows of different length (a clamped post-deploy window)
+     * still compare fairly.
+     */
+    started_per_day_delta_pct: number | null;
+    incident_rate_delta_pp: number | null;
+    element_incident_rate_delta_pp: number | null;
+    avg_duration_delta_pct: number | null;
+    p95_duration_delta_pct: number | null;
+}
+type DeltaInput = Pick<CompareKpis, "instance_count" | "incident_rate_pct" | "element_incident_rate_pct" | "avg_duration_sec" | "p95_duration_sec">;
+/**
+ * Shared delta block of the compare modules. `days` are the two windows'
+ * actual lengths; the start counts are compared per day.
+ */
+export declare function compareKpiDelta(baseline: DeltaInput, other: DeltaInput, days: {
+    baseline: number;
+    other: number;
+}): CompareKpiDelta;
+/**
+ * Whether a comparison is below the trust threshold: a partition with fewer
+ * than `minBucketSize` started instances (the rates' base) OR fewer completed
+ * ones (the durations' sample) is noise, not a signal.
+ */
+export declare function belowMinBucket(partitions: ReadonlyArray<Pick<CompareKpis, "instance_count" | "completed_count">>, minBucketSize: number): boolean;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/queries/helpers.d.ts.map

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