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

package/src/steps/failure-dashboard.ts

@@ -0,0 +1,38 @@
+import type { PipelineStepDefinition } from "@miragon/mcp-toolkit-core"
+import { queries } from "@miragon/pulse-analytics-client"
+import { ENGINE_KEY_DECLARATION, stepEngines, type AnalyticsAppConfig } from "./app-config.js"
+import { builderText } from "../builder-texts.js"
+import { NO_NAMES } from "../bpmn-name-lookup.js"
+import { namedFailureDashboard } from "../named-views.js"
+
+/**
+ * Loads current failure / incident state from Prometheus for the
+ * failure-dashboard widgets. Point-in-time (live state gauges), so there is no
+ * time-window input. Reads the optional `analytics:engine` key (configured
+ * engine id(s); omitted = all of them).
+ */
+export const loadFailureDashboardStep: PipelineStepDefinition<AnalyticsAppConfig> = {
+  id: "analytics:load-failure-dashboard",
+  ...builderText("step.load-failure-dashboard"),
+  description:
+    "The incidents open right now, grouped by incident type and process definition, plus each affected process's running instances and dead jobs. Powers the failure widgets (failure-summary-kpi, failure-rate-table, error-patterns-table).",
+  dataType: "analytics:failureDashboard",
+  requires: [],
+  optionalKeys: [ENGINE_KEY_DECLARATION],
+  produces: ["analytics:failureDashboardData"],
+  execute: async (context, appConfig) => {
+    const data = await namedFailureDashboard(
+      await queries.failureDashboardData(appConfig.client, {
+        engine: stepEngines(context.keys, appConfig.engineScope),
+      }),
+      appConfig.namesFor ?? NO_NAMES,
+    )
+
+    return {
+      data,
+      keys: { "analytics:failureDashboardData": data },
+      _app: "analytics",
+      _step: "load-failure-dashboard",
+    }
+  },
+}

package/src/steps/index.ts

@@ -0,0 +1,2 @@
+export { loadDashboardStep } from "./dashboard.js"
+export { loadFailureDashboardStep } from "./failure-dashboard.js"

package/src/steps/steps.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from "vitest"
+import type { MCPServer } from "mcp-use"
+import type { PipelineContext } from "@miragon/mcp-toolkit-core"
+import { runWithMcpRequestInfo } from "@miragon/pulse-widget-shell/server"
+import type { PrometheusClient, PromSample } from "@miragon/pulse-analytics-client"
+import { createEngineScope } from "../engine-ids.js"
+import { analyticsModule } from "../module.js"
+import type { ProfileSource } from "../server-locale.js"
+import type { AnalyticsAppConfig } from "./app-config.js"
+import { loadDashboardStep, loadFailureDashboardStep } from "./index.js"
+
+/**
+ * The analytics pipeline steps run under render-view / the dashboard builder,
+ * whose step keys are free-form (`z.record(z.string(), z.unknown())`) — no
+ * schema checks them before the step does. So the steps hold the line the
+ * tools' strict inputs hold: a malformed key is refused naming the key, never
+ * read as "omitted" (which for `analytics:engine` would silently widen one
+ * engine's view to the whole fleet).
+ */
+
+function recordingClient() {
+  const sent: string[] = []
+  const ch: PrometheusClient = {
+    instant: (q) => {
+      sent.push(q)
+      return Promise.resolve<PromSample[]>([])
+    },
+  }
+  return { ch, sent }
+}
+
+/** A profile store holding one signed-in user's saved analytics period. */
+const profileStore: ProfileSource = {
+  get: (key) =>
+    Promise.resolve(
+      key === "user-7" ? { modules: { analytics: { defaultPeriod: "30d" } } } : undefined,
+    ),
+}
+
+function setup(withProfileStore = false) {
+  const { ch, sent } = recordingClient()
+  const appConfig: AnalyticsAppConfig = {
+    client: ch,
+    engineScope: createEngineScope(["prod-a", "prod-b"]),
+    ...(withProfileStore ? { profileStore } : {}),
+  }
+  return { appConfig, sent }
+}
+
+const context = (keys: Record<string, unknown>): PipelineContext => ({
+  steps: {},
+  keys,
+  errors: [],
+})
+
+const STEPS = [
+  ["analytics:load-dashboard", loadDashboardStep],
+  ["analytics:load-failure-dashboard", loadFailureDashboardStep],
+] as const
+
+/** Every engine id the `engine_id` matchers of `promql` admit. */
+const enginesRead = (sent: string[]) =>
+  new Set(
+    sent.flatMap((q) =>
+      [...q.matchAll(/engine_id(=~?)"([^"]*)"/g)].flatMap((m) =>
+        m[1] === "=~" ? m[2].split("|") : [m[2]],
+      ),
+    ),
+  )
+
+describe.each(STEPS)("%s — analytics:engine", (_id, step) => {
+  it("reads the whole configured fleet when the key is omitted", async () => {
+    const { appConfig, sent } = setup()
+    const out = await step.execute(context({}), appConfig)
+
+    expect((out.data as { engines: string[] }).engines).toEqual(["prod-a", "prod-b"])
+    expect([...enginesRead(sent)].sort()).toEqual(["prod-a", "prod-b"])
+  })
+
+  it("reads exactly the configured engine(s) the key names", async () => {
+    const { appConfig, sent } = setup()
+    const out = await step.execute(context({ "analytics:engine": "prod-b" }), appConfig)
+
+    expect((out.data as { engines: string[] }).engines).toEqual(["prod-b"])
+    expect([...enginesRead(sent)]).toEqual(["prod-b"])
+  })
+
+  it("refuses an engine this server is not configured for, before any query", async () => {
+    const { appConfig, sent } = setup()
+    await expect(
+      step.execute(context({ "analytics:engine": "tenant-x" }), appConfig),
+    ).rejects.toThrow('Unknown engine "tenant-x"')
+    expect(sent).toEqual([])
+  })
+
+  it.each([
+    ["a number", 7],
+    ["a list with a non-string id", ["prod-a", 7]],
+    ["null", null],
+    ["an object", { id: "prod-a" }],
+  ])("refuses %s instead of widening to the fleet", async (_label, raw) => {
+    const { appConfig, sent } = setup()
+    await expect(step.execute(context({ "analytics:engine": raw }), appConfig)).rejects.toThrow(
+      /analytics:engine must be an engine id or a list of engine ids/,
+    )
+    expect(sent).toEqual([])
+  })
+})
+
+describe("the plugin wires the steps' caller lookup", () => {
+  it("hands the steps the profile store and installs the ambient request info they read", () => {
+    const patterns: string[] = []
+    const server = {
+      tool: () => {},
+      use: (pattern: string) => {
+        patterns.push(pattern)
+      },
+    } as unknown as MCPServer
+    const plugin = analyticsModule.createPlugin(
+      { url: "http://prometheus.invalid" },
+      { profileStore, engineIds: ["prod-a"] },
+    )
+    plugin.registerTools?.(server)
+
+    expect((plugin.appConfig as unknown as AnalyticsAppConfig).profileStore).toBe(profileStore)
+    // A step gets no handler ctx: without this middleware its caller lookup
+    // finds no identity and every saved period silently reads as the default.
+    expect(patterns).toEqual(["mcp:*"])
+  })
+
+  it("hands the steps the name lookup over the injected BPMN lookup", async () => {
+    const xml = '<definitions><process id="order" name="Order fulfillment"/></definitions>'
+    const plugin = analyticsModule.createPlugin(
+      { url: "http://prometheus.invalid" },
+      { profileStore, engineIds: ["prod-a"], fetchBpmnXml: () => Promise.resolve(xml) },
+    )
+    const { namesFor } = plugin.appConfig as unknown as AnalyticsAppConfig
+    expect(await namesFor!(["order"])).toEqual({
+      order: { name: "Order fulfillment", elements: {} },
+    })
+  })
+})
+
+describe.each(STEPS)("%s — the names behind the ids", (_id, step) => {
+  it("passes its figures through the view's name lookup", async () => {
+    const names = { order: { name: "Order fulfillment", elements: {} } }
+    const { appConfig } = setup()
+    const out = await step.execute(context({}), {
+      ...appConfig,
+      namesFor: () => Promise.resolve(names),
+    })
+    expect((out.data as { names: unknown }).names).toEqual(names)
+  })
+
+  it("shows ids when the server has no lookup", async () => {
+    const out = await step.execute(context({}), setup().appConfig)
+    expect((out.data as { names: unknown }).names).toEqual({})
+  })
+})
+
+describe("analytics:load-dashboard — analytics:period", () => {
+  // The windows read — not the hour the born-series check looks at (`[1h] offset …`).
+  const windows = (sent: string[]) =>
+    new Set(
+      sent.flatMap((q) => [...q.matchAll(/\[(\w+)\](?!(?: @ \d+)? offset)/g)].map((m) => m[1])),
+    )
+
+  it("takes the caller's SAVED period when the key is omitted (N83/N116)", async () => {
+    const { appConfig, sent } = setup(true)
+    const out = await runWithMcpRequestInfo({ authUserId: "user-7" }, () =>
+      loadDashboardStep.execute(context({}), appConfig),
+    )
+
+    expect((out.data as { period: string }).period).toBe("30d")
+    expect([...windows(sent)]).toEqual(["30d"])
+  })
+
+  it("falls back to the module default without a caller or a saved period", async () => {
+    const { appConfig } = setup(true)
+    const anonymous = await runWithMcpRequestInfo({}, () =>
+      loadDashboardStep.execute(context({}), appConfig),
+    )
+    const storeless = await loadDashboardStep.execute(context({}), setup().appConfig)
+
+    expect((anonymous.data as { period: string }).period).toBe("7d")
+    expect((storeless.data as { period: string }).period).toBe("7d")
+  })
+
+  it("lets an explicit period win over the saved one", async () => {
+    const { appConfig } = setup(true)
+    const out = await runWithMcpRequestInfo({ authUserId: "user-7" }, () =>
+      loadDashboardStep.execute(context({ "analytics:period": "1d" }), appConfig),
+    )
+    expect((out.data as { period: string }).period).toBe("1d")
+  })
+
+  it.each([
+    ["an unknown period", "90d"],
+    ["a number", 7],
+    ["null", null],
+  ])("refuses %s instead of substituting a default", async (_label, raw) => {
+    const { appConfig, sent } = setup()
+    await expect(
+      loadDashboardStep.execute(context({ "analytics:period": raw }), appConfig),
+    ).rejects.toThrow(/analytics:period must be one of 1d, 3d, 7d, 14d, 30d/)
+    expect(sent).toEqual([])
+  })
+
+  it("refuses a non-string process key, naming the key", async () => {
+    const { appConfig, sent } = setup()
+    await expect(
+      loadDashboardStep.execute(context({ "analytics:processDefinitionKey": 7 }), appConfig),
+    ).rejects.toThrow(/analytics:processDefinitionKey must be a process definition key/)
+    expect(sent).toEqual([])
+  })
+})

package/src/tool-names.ts

@@ -0,0 +1,26 @@
+/**
+ * Names of the analytics widget tools referenced from widget code, so a tool
+ * rename in `widget-tools.ts` trips a TS error at every call site (same rule
+ * as the camunda7 module's tool-names.ts).
+ */
+// Per-view data-only feeds (no UI, app-only via `visibility: "app"`) backing
+// each widget's own self-fetch. A widget tool (view-bound) can't be used for
+// this: the host renders it instead of returning data to the in-widget
+// callTool().
+export const ANALYTICS_DASHBOARD_DATA = "analytics_dashboard_data"
+export const ANALYTICS_FAILURE_DASHBOARD_DATA = "analytics_failure_dashboard_data"
+// Cross-module consumers (camunda7's process-incidents flow) reference this
+// feed by raw string with graceful degradation — keep the name stable.
+export const ANALYTICS_BPMN_HEATMAP_DATA = "analytics_bpmn_heatmap_data"
+// The latest deployed diagram of a process key, for the heatmap view: never
+// inside the heat payload, so the model never reads the XML and the heat
+// values refresh without it.
+export const ANALYTICS_BPMN_XML_DATA = "analytics_bpmn_xml_data"
+// Backs the cross-engine landscape widget's self-fetch. Also referenced by
+// camunda7's cross-engine cockpit mode through the widget id (tier-2), so the
+// section disappears with the module instead of erroring.
+export const ANALYTICS_ENGINE_LANDSCAPE_DATA = "analytics_engine_landscape_data"
+// Settings section: the widget self-fetches the feed and writes via the save
+// tool; both live in settings-tools.ts.
+export const ANALYTICS_SETTINGS_DATA = "analytics_settings_data"
+export const ANALYTICS_SAVE_SETTINGS = "analytics_save_settings"

package/src/tools/cluster-compare.ts

@@ -0,0 +1,28 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { schemas, queries } from "@miragon/pulse-analytics-client"
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import type { ProfileSource } from "../server-locale.js"
+import { optionalMinBucketSize, settingsFor } from "../settings.js"
+import { withEngineScope, type AnalyticsEngineScope } from "../engine-ids.js"
+
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>
+
+export function registerClusterCompareTools(
+  register: Register,
+  engineScope: AnalyticsEngineScope,
+  profileStore?: ProfileSource,
+) {
+  register({
+    name: "analytics_cluster_compare",
+    category: "analytics",
+    description:
+      "Pre/Post deployment correlation from metrics. Given a deployment timestamp and windows before/after, compute instance KPIs per window and the delta, using PromQL historical windows. Windows are clamped to now and the 30-day retention and reported as measured (`windowDays`, `partial`) — right after a deploy the post window holds only the elapsed time; starts compare per day. Results are flagged `suppressed` if either window has fewer than minBucketSize started or completed instances. Typical flow: commit-hash → camunda7_get_deployment → deployment.timestamp → this tool.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: { ...schemas.clusterCompareInput.shape, minBucketSize: optionalMinBucketSize },
+    handler: async (ch, args, ctx) =>
+      queries.clusterCompare(ch, {
+        ...withEngineScope(engineScope, args),
+        minBucketSize: args.minBucketSize ?? (await settingsFor(profileStore, ctx)).minBucketSize,
+      }),
+  })
+}

package/src/tools/element.ts

@@ -0,0 +1,35 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { schemas, queries } from "@miragon/pulse-analytics-client"
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import type { ProfileSource } from "../server-locale.js"
+import { optionalMinBucketSize, optionalPeriod, settingsFor } from "../settings.js"
+import { withEngineScope, type AnalyticsEngineScope } from "../engine-ids.js"
+
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>
+
+export function registerElementTools(
+  register: Register,
+  engineScope: AnalyticsEngineScope,
+  profileStore?: ProfileSource,
+) {
+  register({
+    name: "analytics_element_bottleneck",
+    category: "analytics",
+    description:
+      "Rank activities by execution-time contribution and incident rate over a rolling window, from process metrics. Activities with fewer than `minBucketSize` executions are suppressed. Note: queue/wait time is not available from metrics.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: {
+      ...schemas.elementBottleneckInput.shape,
+      period: optionalPeriod,
+      minBucketSize: optionalMinBucketSize,
+    },
+    handler: async (ch, args, ctx) => {
+      const settings = await settingsFor(profileStore, ctx)
+      return queries.elementBottleneck(ch, {
+        ...withEngineScope(engineScope, args),
+        period: args.period ?? settings.defaultPeriod,
+        minBucketSize: args.minBucketSize ?? settings.minBucketSize,
+      })
+    },
+  })
+}

package/src/tools/engine-compare.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest"
+import { z } from "zod"
+import { increaseIn, type PrometheusClient } from "@miragon/pulse-analytics-client"
+import type { RegisteredToolMeta, ToolConfig } from "@miragon/mcp-toolkit-core/tools"
+import { createEngineScope } from "../engine-ids.js"
+import { registerEngineCompareTools } from "./engine-compare.js"
+
+const scope = createEngineScope(["prod-a", "prod-b"])
+const register = (r: never, store?: never) => registerEngineCompareTools(r, scope, store)
+
+type Config = ToolConfig<PrometheusClient>
+
+/** Registrar stand-in that captures each tool's full config instead of an MCPServer. */
+function captureConfigs(registerModule: (register: never) => void): Map<string, Config> {
+  const configs = new Map<string, Config>()
+  const register = Object.assign(
+    (config: Config) => {
+      configs.set(config.name, config)
+    },
+    { getRegisteredTools: (): RegisteredToolMeta[] => [] },
+  )
+  registerModule(register as never)
+  return configs
+}
+
+function captureHandlers(registerModule: (register: never) => void) {
+  const configs = captureConfigs(registerModule)
+  return new Map([...configs].map(([name, c]) => [name, c.handler]))
+}
+
+/** PrometheusClient that records every instant PromQL string and returns no samples. */
+function recordingClient(): { client: PrometheusClient; queries: string[] } {
+  const queries: string[] = []
+  return {
+    client: {
+      instant: (query: string) => {
+        queries.push(query)
+        return Promise.resolve([])
+      },
+    },
+    queries,
+  }
+}
+
+/** The five KPI queries per engine — no duplicate incident query without an element (N85). */
+function kpiQueries(sel: string, completedSel: string, range: string) {
+  const count = (series: string) => increaseIn(series, { range })
+  const duration = "camunda_process_instance_duration_milliseconds"
+  return [
+    `sum(${count(`camunda_process_instance_started_total${sel}`)})`,
+    `sum(${count(`camunda_process_instance_ended_total${completedSel}`)})`,
+    `sum(${count(`camunda_incident_created_total${sel}`)})`,
+    `sum(${count(`${duration}_sum${sel}`)}) / sum(${count(`${duration}_count${sel}`)})`,
+    `histogram_quantile(0.95, sum by (le)(${count(`${duration}_bucket${sel}`)}))`,
+  ]
+}
+
+describe("analytics_engine_compare PromQL", () => {
+  it("partitions every query by engine_id and applies the shared window", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+    const key = 'process_definition_key="order"'
+
+    await handlers.get("analytics_engine_compare")!(client, {
+      processDefinitionKey: "order",
+      engineA: "prod-a",
+      engineB: "prod-b",
+      windowDays: 14,
+      minBucketSize: 10,
+    })
+
+    expect(queries).toEqual([
+      ...kpiQueries(
+        `{${key},engine_id="prod-a"}`,
+        `{${key},state="COMPLETED",engine_id="prod-a"}`,
+        "14d",
+      ),
+      ...kpiQueries(
+        `{${key},engine_id="prod-b"}`,
+        `{${key},state="COMPLETED",engine_id="prod-b"}`,
+        "14d",
+      ),
+    ])
+  })
+
+  it("scopes to processDefinitionKey everywhere and activityId only on the incident query", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    await handlers.get("analytics_engine_compare")!(client, {
+      engineA: "prod-a",
+      engineB: "prod-b",
+      windowDays: 7,
+      processDefinitionKey: "order",
+      activityId: "Task_check",
+      minBucketSize: 1,
+    })
+
+    const key = 'process_definition_key="order"'
+    // Five KPI queries per engine plus the element-scoped incident count.
+    expect(queries).toHaveLength(12)
+    expect(queries.every((q) => q.includes(key))).toBe(true)
+    const elementScoped = queries.filter((q) => q.includes('activity_id="Task_check"'))
+    const incidents = (engine: string) =>
+      `sum(${increaseIn(`camunda_incident_created_total{${key},activity_id="Task_check",engine_id="${engine}"}`, { range: "7d" })})`
+    expect(elementScoped).toEqual([incidents("prod-a"), incidents("prod-b")])
+  })
+
+  it("refuses an engine this server is not configured for, before any query (N138)", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    await expect(
+      handlers.get("analytics_engine_compare")!(client, {
+        processDefinitionKey: "order",
+        engineA: "prod-a",
+        engineB: "tenant-x",
+        windowDays: 7,
+      }),
+    ).rejects.toThrow(/Unknown engine "tenant-x" in engineB/)
+    expect(queries).toEqual([])
+  })
+
+  it("reads 'nothing ended' as an unmeasured duration and suppresses its delta (N78)", async () => {
+    const handlers = captureHandlers(register)
+    // Both engines started 40 instances; only prod-a has completed any — prod-b
+    // has no duration sample at all.
+    const client: PrometheusClient = {
+      instant: (q) =>
+        Promise.resolve(
+          q.includes("duration_milliseconds") && q.includes("prod-b")
+            ? []
+            : [{ metric: {}, value: q.includes("duration_milliseconds") ? 30_000 : 40 }],
+        ),
+    }
+    const result = (await handlers.get("analytics_engine_compare")!(client, {
+      processDefinitionKey: "order",
+      engineA: "prod-a",
+      engineB: "prod-b",
+      windowDays: 7,
+      minBucketSize: 1,
+    })) as {
+      kpis: Array<{ avg_duration_sec: number | null; p95_duration_sec: number | null }>
+      delta: { avg_duration_delta_pct: number | null; p95_duration_delta_pct: number | null }
+    }
+
+    expect(result.kpis[1]).toMatchObject({ avg_duration_sec: null, p95_duration_sec: null })
+    // Never a −100 % from a missing value.
+    expect(result.delta).toMatchObject({
+      avg_duration_delta_pct: null,
+      p95_duration_delta_pct: null,
+    })
+  })
+
+  it("prefers an explicit minBucketSize over the resolved setting", async () => {
+    const handlers = captureHandlers(register)
+    const { client } = recordingClient()
+
+    const explicit = (await handlers.get("analytics_engine_compare")!(client, {
+      processDefinitionKey: "order",
+      engineA: "prod-a",
+      engineB: "prod-b",
+      windowDays: 7,
+      minBucketSize: 3,
+    })) as { minBucketSize: number }
+    const fallback = (await handlers.get("analytics_engine_compare")!(client, {
+      processDefinitionKey: "order",
+      engineA: "prod-a",
+      engineB: "prod-b",
+      windowDays: 7,
+    })) as { minBucketSize: number }
+
+    // "explicit arg > saved setting > schema default": without a store or a
+    // resolvable profile key the registrar path lands on the schema default.
+    expect(explicit.minBucketSize).toBe(3)
+    expect(fallback.minBucketSize).toBe(10)
+  })
+})
+
+describe("analytics_engine_compare registration", () => {
+  const config = captureConfigs(register).get("analytics_engine_compare")!
+
+  it("registers under the analytics category as a read-only external read", () => {
+    expect(config.category).toBe("analytics")
+    // toolsets.test.ts derives admin-only status from these; a read that lost
+    // `readOnlyHint` would silently change the toolset surface.
+    expect(config.annotations).toEqual({
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    })
+  })
+
+  it("tells the model why the process scope is mandatory", () => {
+    // The description is the only place a model learns that an unscoped
+    // engine-vs-engine comparison measures the process mix — losing it turns
+    // the tool back into the apples-to-oranges comparison it replaced.
+    expect(config.description).toContain("processDefinitionKey is required")
+    expect(config.description).toContain("process mixes")
+    expect(config.description).toContain("analytics_engine_landscape")
+  })
+
+  it("requires processDefinitionKey at the schema boundary", () => {
+    const parsed = z.object(config.inputSchema).safeParse({
+      engineA: "prod-a",
+      engineB: "prod-b",
+    })
+    expect(parsed.success).toBe(false)
+  })
+})

package/src/tools/engine-compare.ts

@@ -0,0 +1,30 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { schemas, queries } from "@miragon/pulse-analytics-client"
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import type { ProfileSource } from "../server-locale.js"
+import { optionalMinBucketSize, settingsFor } from "../settings.js"
+import type { AnalyticsEngineScope } from "../engine-ids.js"
+
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>
+
+export function registerEngineCompareTools(
+  register: Register,
+  engineScope: AnalyticsEngineScope,
+  profileStore?: ProfileSource,
+) {
+  register({
+    name: "analytics_engine_compare",
+    category: "analytics",
+    description:
+      "Compare ONE process definition as it runs on two configured CIB Seven engines (e.g. prod-a vs prod-b) over a shared rolling window, from metrics. processDefinitionKey is required: engines host different process mixes, so comparing their whole workloads would measure the mix rather than the engines — holding the process fixed is what makes the delta attributable. Returns per engine starts, completions, incidents per 100 starts (with activityId also at that element) and avg/p95 duration of the instances that ENDED, plus the deltas. Flagged `suppressed` when either engine has fewer than minBucketSize started or completed instances. For the unscoped cross-engine picture (what runs where, load, job backlog, which keys are deployed on several engines) use analytics_engine_landscape first; its `sharedProcessKeys` are the valid inputs here.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: { ...schemas.engineCompareInput.shape, minBucketSize: optionalMinBucketSize },
+    handler: async (ch, args, ctx) =>
+      queries.engineCompare(ch, {
+        ...args,
+        engineA: engineScope.require(args.engineA, "engineA"),
+        engineB: engineScope.require(args.engineB, "engineB"),
+        minBucketSize: args.minBucketSize ?? (await settingsFor(profileStore, ctx)).minBucketSize,
+      }),
+  })
+}