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

package/dist/queries/element.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+import { elementBottleneck } from "./element.js";
+/** Mock Prometheus client that dispatches canned samples by the PromQL it sees. */
+function mockClient() {
+    const instant = vi.fn(async (q) => {
+        if (q.includes("activity_type")) {
+            return [
+                { metric: { activity_id: "A", activity_type: "serviceTask" }, value: 10 },
+                { metric: { activity_id: "B", activity_type: "userTask" }, value: 5 },
+            ];
+        }
+        // Durations in ms, the histogram's unit.
+        if (q.includes("histogram_quantile")) {
+            return [
+                { metric: { activity_id: "A" }, value: 15_000 },
+                { metric: { activity_id: "B" }, value: 6_000 },
+            ];
+        }
+        if (q.includes("duration_milliseconds_sum")) {
+            return [
+                { metric: { activity_id: "A" }, value: 100_000 },
+                { metric: { activity_id: "B" }, value: 20_000 },
+            ];
+        }
+        if (q.includes("incident_created")) {
+            return [{ metric: { activity_id: "A" }, value: 2 }];
+        }
+        // counts: activity_ended_total grouped by activity_id only
+        return [
+            { metric: { activity_id: "A" }, value: 10 },
+            { metric: { activity_id: "B" }, value: 5 },
+        ];
+    });
+    const ch = { instant };
+    return { ch, instant };
+}
+describe("elementBottleneck", () => {
+    it("ranks activities by time contribution and maps incident rate; wait time is null on metrics", async () => {
+        const { ch } = mockClient();
+        const res = await elementBottleneck(ch, {
+            processDefinitionKey: "miraveloLeasing",
+            period: "7d",
+            minBucketSize: 1,
+            maxResults: 10,
+        });
+        expect(res.activities).toHaveLength(2);
+        const [a, b] = res.activities;
+        expect(a).toMatchObject({
+            activity_id: "A",
+            activity_type: "serviceTask",
+            execution_count: 10,
+            avg_duration_sec: 10,
+            p95_duration_sec: 15,
+            total_time_sec: 100,
+            incident_count: 2,
+            incident_rate_pct: 20,
+            bottleneck_score_sec: 100,
+            avg_wait_sec: null,
+            total_wait_sec: null,
+        });
+        // B has fewer/shorter executions → ranked below A
+        expect(b.activity_id).toBe("B");
+        expect(b.incident_count).toBe(0);
+        expect(res.suppressedActivities).toBe(0);
+    });
+    it("suppresses activities below minBucketSize", async () => {
+        const { ch } = mockClient();
+        const res = await elementBottleneck(ch, {
+            processDefinitionKey: "miraveloLeasing",
+            period: "7d",
+            minBucketSize: 8,
+            maxResults: 10,
+        });
+        // only A (count 10) clears the threshold; B (count 5) is suppressed
+        expect(res.activities.map((r) => r.activity_id)).toEqual(["A"]);
+        expect(res.suppressedActivities).toBe(1);
+    });
+    it("reports a missing histogram sample as an unmeasured p95, never 0 s", async () => {
+        const instant = vi.fn(async (q) => q.includes("histogram_quantile") ||
+            q.includes("duration_milliseconds_sum") ||
+            q.includes("incident")
+            ? []
+            : [{ metric: { activity_id: "A", activity_type: "serviceTask" }, value: 4 }]);
+        const res = await elementBottleneck({ instant }, { processDefinitionKey: "k", period: "7d", minBucketSize: 1, maxResults: 5 });
+        expect(res.activities[0]).toMatchObject({
+            execution_count: 4,
+            avg_duration_sec: null,
+            p95_duration_sec: null,
+            incident_rate_pct: 0,
+        });
+    });
+    it("scopes every query to the process definition key and period", async () => {
+        const { ch, instant } = mockClient();
+        await elementBottleneck(ch, {
+            processDefinitionKey: "myKey",
+            period: "30d",
+            minBucketSize: 1,
+            maxResults: 5,
+        });
+        const queries = instant.mock.calls.map((c) => c[0]);
+        expect(queries.every((q) => q.includes('process_definition_key="myKey"'))).toBe(true);
+        expect(queries.every((q) => q.includes("[30d]"))).toBe(true);
+    });
+});
+//# sourceMappingURL=element.test.js.map

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

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

package/dist/queries/engine-compare.d.ts

@@ -0,0 +1,52 @@
+import { type PrometheusClient } from "../prometheus.js";
+import { type CompareKpiDelta, type CompareKpis } from "./helpers.js";
+export interface EngineCompareKpi extends CompareKpis {
+    engineId: string;
+    bucket: "engineA" | "engineB";
+}
+export type EngineCompareDelta = CompareKpiDelta;
+export interface EngineCompareResult {
+    engineA: string;
+    engineB: string;
+    processDefinitionKey: string;
+    windowDays: number;
+    activityId: string | null;
+    minBucketSize: number;
+    suppressed: boolean;
+    kpis: EngineCompareKpi[];
+    delta: EngineCompareDelta;
+    /**
+     * When the figures were read from Prometheus (ISO timestamp): the "Stand"
+     * a view shows. Optional only for payloads recorded before it existed.
+     */
+    asOf?: string;
+}
+/**
+ * Side-by-side comparison of ONE process definition as it runs on two engines,
+ * over a shared rolling window. The engine is a metric label (`engine_id`) and
+ * all engines write to one Prometheus, so the partition is exact with no
+ * per-engine DB fan-out.
+ *
+ * `processDefinitionKey` is required by design. Comparing two engines' entire
+ * workloads would compare their PROCESS MIXES: engines host different
+ * processes, so an engine running an inherently error-prone process reads
+ * "worse" no matter how healthy it is — a textbook confound (the same
+ * aggregation can even invert the per-process truth, Simpson's paradox).
+ * Holding the process fixed is what makes a delta attributable to the engine.
+ * The cross-engine picture without that scope is `engineLandscape`, which
+ * reports mix-independent signals instead (absolute load, engine-owned job
+ * backlog) and names the keys deployed on several engines — the valid inputs
+ * here.
+ *
+ * `incident_count`/`incident_rate_pct` cover every activity; with `activityId`
+ * the `element_incident_*` fields add the count at that element.
+ */
+export declare function engineCompare(ch: PrometheusClient, params: {
+    processDefinitionKey: string;
+    engineA: string;
+    engineB: string;
+    windowDays: number;
+    activityId?: string;
+    minBucketSize: number;
+}): Promise<EngineCompareResult>;
+//# sourceMappingURL=engine-compare.d.ts.map

package/dist/queries/engine-compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-compare.d.ts","sourceRoot":"","sources":["../../src/queries/engine-compare.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACpF,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAA;AAErB,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAC9B;AAED,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAA;AAEhD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,oBAAoB,EAAE,MAAM,CAAA;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,OAAO,CAAA;IACnB,IAAI,EAAE,gBAAgB,EAAE,CAAA;IACxB,KAAK,EAAE,kBAAkB,CAAA;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE;IACN,oBAAoB,EAAE,MAAM,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;CACtB,GACA,OAAO,CAAC,mBAAmB,CAAC,CAuB9B"}

package/dist/queries/engine-compare.js

@@ -0,0 +1,57 @@
+import { escapeLabelValue, selector } from "../prometheus.js";
+import { asOfNow, belowMinBucket, compareKpiDelta, queryCompareKpis, } from "./helpers.js";
+/**
+ * Side-by-side comparison of ONE process definition as it runs on two engines,
+ * over a shared rolling window. The engine is a metric label (`engine_id`) and
+ * all engines write to one Prometheus, so the partition is exact with no
+ * per-engine DB fan-out.
+ *
+ * `processDefinitionKey` is required by design. Comparing two engines' entire
+ * workloads would compare their PROCESS MIXES: engines host different
+ * processes, so an engine running an inherently error-prone process reads
+ * "worse" no matter how healthy it is — a textbook confound (the same
+ * aggregation can even invert the per-process truth, Simpson's paradox).
+ * Holding the process fixed is what makes a delta attributable to the engine.
+ * The cross-engine picture without that scope is `engineLandscape`, which
+ * reports mix-independent signals instead (absolute load, engine-owned job
+ * backlog) and names the keys deployed on several engines — the valid inputs
+ * here.
+ *
+ * `incident_count`/`incident_rate_pct` cover every activity; with `activityId`
+ * the `element_incident_*` fields add the count at that element.
+ */
+export async function engineCompare(ch, params) {
+    const minBucket = Math.max(1, Math.floor(params.minBucketSize));
+    const windowDays = Math.max(1, Math.floor(params.windowDays));
+    const range = `${windowDays}d`;
+    const asOf = asOfNow();
+    const [a, b] = await Promise.all([
+        engineKpi(ch, params, "engineA", params.engineA, range),
+        engineKpi(ch, params, "engineB", params.engineB, range),
+    ]);
+    return {
+        asOf,
+        engineA: params.engineA,
+        engineB: params.engineB,
+        processDefinitionKey: params.processDefinitionKey,
+        windowDays,
+        activityId: params.activityId ?? null,
+        minBucketSize: minBucket,
+        suppressed: belowMinBucket([a, b], minBucket),
+        kpis: [a, b],
+        delta: compareKpiDelta(a, b, { baseline: windowDays, other: windowDays }),
+    };
+}
+async function engineKpi(ch, params, bucket, engineId, range) {
+    const engine = `engine_id="${escapeLabelValue(engineId)}"`;
+    const keyMatcher = `process_definition_key="${escapeLabelValue(params.processDefinitionKey)}"`;
+    const kpis = await queryCompareKpis(ch, {
+        sel: selector(keyMatcher, engine),
+        completedSel: selector(keyMatcher, `state="COMPLETED"`, engine),
+        elementIncidentSel: params.activityId
+            ? selector(keyMatcher, `activity_id="${escapeLabelValue(params.activityId)}"`, engine)
+            : undefined,
+    }, { range });
+    return { engineId, bucket, ...kpis };
+}
+//# sourceMappingURL=engine-compare.js.map

package/dist/queries/engine-compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-compare.js","sourceRoot":"","sources":["../../src/queries/engine-compare.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAyB,MAAM,kBAAkB,CAAA;AACpF,OAAO,EACL,OAAO,EACP,cAAc,EACd,eAAe,EACf,gBAAgB,GAGjB,MAAM,cAAc,CAAA;AA0BrB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAoB,EACpB,MAOC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAA;IAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAA;IAC7D,MAAM,KAAK,GAAG,GAAG,UAAU,GAAG,CAAA;IAC9B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAA;IAEtB,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC/B,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC;QACvD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC;KACxD,CAAC,CAAA;IAEF,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;QACjD,UAAU;QACV,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;QACrC,aAAa,EAAE,SAAS;QACxB,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC;QAC7C,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACZ,KAAK,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;KAC1E,CAAA;AACH,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,EAAoB,EACpB,MAA6D,EAC7D,MAA6B,EAC7B,QAAgB,EAChB,KAAa;IAEb,MAAM,MAAM,GAAG,cAAc,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAA;IAC1D,MAAM,UAAU,GAAG,2BAA2B,gBAAgB,CAAC,MAAM,CAAC,oBAAoB,CAAC,GAAG,CAAA;IAC9F,MAAM,IAAI,GAAG,MAAM,gBAAgB,CACjC,EAAE,EACF;QACE,GAAG,EAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QACjC,YAAY,EAAE,QAAQ,CAAC,UAAU,EAAE,mBAAmB,EAAE,MAAM,CAAC;QAC/D,kBAAkB,EAAE,MAAM,CAAC,UAAU;YACnC,CAAC,CAAC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;YACtF,CAAC,CAAC,SAAS;KACd,EACD,EAAE,KAAK,EAAE,CACV,CAAA;IACD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAA;AACtC,CAAC"}

package/dist/queries/engine-compare.test.d.ts

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

package/dist/queries/engine-compare.test.d.ts.map

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

package/dist/queries/engine-compare.test.js

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from "vitest";
+import { engineCompare } from "./engine-compare.js";
+const v = (value) => ({ metric: {}, value });
+/** Mock Prometheus client with distinct canned KPIs per engine_id partition. */
+function mockClient(byEngine = {
+    "prod-a": { started: 100, completed: 80, incidents: 10, avg: 10, p95: 20 },
+    "prod-b": { started: 50, completed: 40, incidents: 10, avg: 12, p95: 30 },
+}) {
+    const instant = vi.fn(async (q) => {
+        const engine = q.includes('engine_id="prod-a"') ? byEngine["prod-a"] : byEngine["prod-b"];
+        const maybe = (value) => (value === null ? [] : [v(value)]);
+        // Canned durations are seconds; the histogram answers in ms.
+        const ms = (sec) => (sec === null ? null : sec * 1000);
+        if (q.includes("histogram_quantile"))
+            return maybe(ms(engine.p95));
+        if (q.includes("duration_milliseconds_sum"))
+            return maybe(ms(engine.avg));
+        if (q.includes("incident_created") && q.includes("activity_id")) {
+            return [v(engine.elementIncidents ?? 0)];
+        }
+        if (q.includes("incident_created"))
+            return [v(engine.incidents)];
+        if (q.includes('state="COMPLETED"'))
+            return [v(engine.completed)];
+        return [v(engine.started)];
+    });
+    const ch = { instant };
+    return { ch, instant };
+}
+const params = {
+    processDefinitionKey: "order",
+    engineA: "prod-a",
+    engineB: "prod-b",
+    windowDays: 14,
+    minBucketSize: 10,
+};
+describe("engineCompare", () => {
+    it("computes per-engine KPIs and the B-vs-A delta for one process", async () => {
+        const { ch } = mockClient();
+        const res = await engineCompare(ch, params);
+        expect(res).toMatchObject({
+            engineA: "prod-a",
+            engineB: "prod-b",
+            processDefinitionKey: "order",
+            windowDays: 14,
+            activityId: null,
+            minBucketSize: 10,
+            suppressed: false,
+        });
+        expect(res.kpis).toEqual([
+            {
+                engineId: "prod-a",
+                bucket: "engineA",
+                instance_count: 100,
+                completed_count: 80,
+                incident_count: 10,
+                incident_rate_pct: 10,
+                element_incident_count: null,
+                element_incident_rate_pct: null,
+                avg_duration_sec: 10,
+                p95_duration_sec: 20,
+            },
+            {
+                engineId: "prod-b",
+                bucket: "engineB",
+                instance_count: 50,
+                completed_count: 40,
+                incident_count: 10,
+                incident_rate_pct: 20,
+                element_incident_count: null,
+                element_incident_rate_pct: null,
+                avg_duration_sec: 12,
+                p95_duration_sec: 30,
+            },
+        ]);
+        expect(res.delta).toEqual({
+            started_per_day_delta_pct: -50,
+            incident_rate_delta_pp: 10,
+            element_incident_rate_delta_pp: null,
+            avg_duration_delta_pct: 20,
+            p95_duration_delta_pct: 50,
+        });
+    });
+    it("reports the element's incidents NEXT TO the process-wide ones, never instead", async () => {
+        const { ch, instant } = mockClient({
+            "prod-a": {
+                started: 100,
+                completed: 80,
+                incidents: 10,
+                elementIncidents: 4,
+                avg: 10,
+                p95: 20,
+            },
+            "prod-b": {
+                started: 50,
+                completed: 40,
+                incidents: 10,
+                elementIncidents: 1,
+                avg: 12,
+                p95: 30,
+            },
+        });
+        const res = await engineCompare(ch, { ...params, activityId: "Task_check" });
+        expect(res.kpis.map((k) => [k.incident_rate_pct, k.element_incident_rate_pct])).toEqual([
+            [10, 4],
+            [20, 2],
+        ]);
+        expect(res.delta.element_incident_rate_delta_pp).toBe(-2);
+        // One extra query per engine, only for the element count.
+        expect(instant.mock.calls.filter(([q]) => q.includes('activity_id="Task_check"'))).toHaveLength(2);
+    });
+    it("flags the comparison as suppressed when one engine misses minBucketSize", async () => {
+        const { ch } = mockClient();
+        // prod-b only has 50 instances
+        expect((await engineCompare(ch, { ...params, minBucketSize: 60 })).suppressed).toBe(true);
+    });
+    it("flags it suppressed when too few instances COMPLETED — the durations' sample", async () => {
+        const { ch } = mockClient({
+            "prod-a": { started: 100, completed: 80, incidents: 0, avg: 10, p95: 20 },
+            "prod-b": { started: 100, completed: 3, incidents: 0, avg: 1, p95: 2 },
+        });
+        expect((await engineCompare(ch, params)).suppressed).toBe(true);
+    });
+    it("reads 'nothing ended' as an unmeasured duration and suppresses its delta (N78)", async () => {
+        // prod-b started work but nothing ended yet: the duration ratio is NaN,
+        // which the client drops — formerly a 0 s duration and a −100 % delta.
+        const { ch } = mockClient({
+            "prod-a": { started: 100, completed: 80, incidents: 5, avg: 10, p95: 20 },
+            "prod-b": { started: 40, completed: 0, incidents: 0, avg: null, p95: null },
+        });
+        const res = await engineCompare(ch, params);
+        expect(res.kpis[1]).toMatchObject({ avg_duration_sec: null, p95_duration_sec: null });
+        expect(res.delta.avg_duration_delta_pct).toBeNull();
+        expect(res.delta.p95_duration_delta_pct).toBeNull();
+        expect(res.suppressed).toBe(true);
+    });
+    it("returns null deltas instead of dividing by a zero baseline", async () => {
+        const instant = vi.fn(async () => []);
+        const res = await engineCompare({ instant }, { ...params, windowDays: 7, minBucketSize: 1 });
+        expect(res.suppressed).toBe(true);
+        expect(Object.values(res.delta).every((d) => d === null)).toBe(true);
+        expect(res.kpis.every((k) => k.incident_rate_pct === null)).toBe(true);
+    });
+    it("partitions every query by exactly one engine_id and always holds the process fixed", async () => {
+        const { ch, instant } = mockClient();
+        await engineCompare(ch, params);
+        const queries = instant.mock.calls.map((c) => c[0]);
+        expect(queries).toHaveLength(10);
+        const aQueries = queries.filter((q) => q.includes('engine_id="prod-a"'));
+        const bQueries = queries.filter((q) => q.includes('engine_id="prod-b"'));
+        expect(aQueries).toHaveLength(5);
+        expect(bQueries).toHaveLength(5);
+        // The scope that makes the delta attributable to the engine rather than to
+        // a different process mix — never absent.
+        expect(queries.every((q) => q.includes('process_definition_key="order"'))).toBe(true);
+        expect(queries.every((q) => q.includes("[14d]"))).toBe(true);
+    });
+});
+//# sourceMappingURL=engine-compare.test.js.map

package/dist/queries/engine-compare.test.js.map

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

package/dist/queries/engine-landscape.d.ts

@@ -0,0 +1,92 @@
+import { type EngineFilterInput, type PrometheusClient } from "../prometheus.js";
+/**
+ * Per-engine row of the landscape. Absolute counts only — see the module note.
+ * Every count is `null` for an engine that reports nothing (`reporting:
+ * false`): its figures are unknown, never a plausible 0.
+ */
+export interface EngineLandscapeEngine {
+    engineId: string;
+    /**
+     * `false` when the engine contributed no series at all: the plugin is down,
+     * the engine is unreachable, or it was never scraped. Only reachable when the
+     * caller passes the expected engine ids — an engine that reports nothing is
+     * otherwise indistinguishable from one that does not exist.
+     */
+    reporting: boolean;
+    runningInstances: number | null;
+    openIncidents: number | null;
+    failedJobs: number | null;
+    executableJobs: number | null;
+    suspendedJobs: number | null;
+    jobsDueFuture: number | null;
+    openExternalTasks: number | null;
+    deployedDefinitionKeys: number | null;
+    /** Keys present on this engine only — the load no other engine shares. */
+    exclusiveDefinitionKeys: number | null;
+}
+/** One row of the process × engine inventory matrix. */
+export interface EngineLandscapeProcess {
+    processDefinitionKey: string;
+    /** Engines this key is deployed on (or reports live state for), ascending. */
+    engineIds: string[];
+    /** Present on ≥2 engines — the only case where an A/B engine compare holds. */
+    shared: boolean;
+    /** Running instances per engine id; engines without running work are absent. */
+    runningByEngine: Record<string, number>;
+    runningTotal: number;
+    openIncidentsTotal: number;
+    failedJobsTotal: number;
+}
+export interface EngineLandscapeResult {
+    /** Ascending by engine id — deliberately not a ranking (see the module note). */
+    engines: EngineLandscapeEngine[];
+    /** Shared keys first, then by running instances descending, then by key. */
+    processes: EngineLandscapeProcess[];
+    /** Keys present on ≥2 engines — the valid drill-down targets for engineCompare. */
+    sharedProcessKeys: string[];
+    totals: {
+        engineCount: number;
+        reportingEngineCount: number;
+        processKeyCount: number;
+        sharedProcessKeyCount: number;
+        /** The sums over the reporting engines; `null` while no engine reports (unknown, not 0). */
+        runningInstances: number | null;
+        openIncidents: number | null;
+        failedJobs: number | null;
+    };
+    /**
+     * When the figures were read from Prometheus (ISO timestamp): the "Stand"
+     * a view shows. Optional only for payloads recorded before it existed.
+     */
+    asOf?: string;
+}
+/**
+ * Cross-engine landscape: what runs where, how much of it, and which engines
+ * carry a backlog.
+ *
+ * Deliberately NOT an engine-vs-engine scoreboard. Rates (failure rate,
+ * incident rate, duration) aggregated per engine measure that engine's PROCESS
+ * MIX, not the engine: an engine hosting an inherently error-prone process
+ * reads "unhealthy" while running perfectly. So this query reports the two
+ * things that survive a different mix per engine:
+ *
+ *  1. Absolute counts (running instances, open incidents, failed jobs) — they
+ *     say where work and trouble physically sit, which is what an operator
+ *     acts on, and they stay additive across engines.
+ *  2. The engine-owned backlog gauges (`jobs_executable`, `jobs_suspended`,
+ *     `jobs_due_future`, `external_tasks_open`), whose contract labels are
+ *     `engine_id` ONLY. With no process dimension there is no mix to confound
+ *     them, so these genuinely do rank engines against each other.
+ *
+ * The inventory matrix then names the one place a KPI comparison IS sound: a
+ * process definition key present on two or more engines (`sharedProcessKeys`)
+ * — the drill-down {@link engineCompare} requires.
+ *
+ * Pass `engine` as the array of CONFIGURED engine ids to also surface engines
+ * that report nothing (`reporting: false`); without it the landscape can only
+ * show engines Prometheus has series for.
+ */
+export declare function engineLandscape(ch: PrometheusClient, params?: {
+    engine?: EngineFilterInput;
+}): Promise<EngineLandscapeResult>;
+//# sourceMappingURL=engine-landscape.d.ts.map

package/dist/queries/engine-landscape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-landscape.d.ts","sourceRoot":"","sources":["../../src/queries/engine-landscape.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAEtB,MAAM,kBAAkB,CAAA;AAQzB;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAA;IAIlB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAIzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,0EAA0E;IAC1E,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,oBAAoB,EAAE,MAAM,CAAA;IAC5B,8EAA8E;IAC9E,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,+EAA+E;IAC/E,MAAM,EAAE,OAAO,CAAA;IACf,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,OAAO,EAAE,qBAAqB,EAAE,CAAA;IAChC,4EAA4E;IAC5E,SAAS,EAAE,sBAAsB,EAAE,CAAA;IACnC,mFAAmF;IACnF,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAA;QACnB,oBAAoB,EAAE,MAAM,CAAA;QAC5B,eAAe,EAAE,MAAM,CAAA;QACvB,qBAAqB,EAAE,MAAM,CAAA;QAC7B,4FAA4F;QAC5F,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;QAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;QAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAC1B,CAAA;IACD;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AASD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,gBAAgB,EACpB,MAAM,GAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAO,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CA4HhC"}