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

package/src/widgets/model-descriptions.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest"
+import {
+  describeEngineLandscape,
+  describeErrorPatterns,
+  describeFailureRates,
+  describeFailureSummary,
+  describeVersionCompare,
+} from "./model-descriptions.js"
+import type {
+  EngineLandscapeEngine,
+  EngineLandscapeResult,
+  FailureDashboardData,
+  VersionCompareKpi,
+  VersionCompareResult,
+} from "@miragon/pulse-analytics-client"
+
+// The dashboard, comparison and heatmap descriptions: model-descriptions.dashboard.test.ts.
+
+const engine = (
+  engineId: string,
+  over: Partial<EngineLandscapeEngine> = {},
+): EngineLandscapeEngine => ({
+  engineId,
+  reporting: true,
+  runningInstances: 0,
+  openIncidents: 0,
+  failedJobs: 0,
+  executableJobs: 0,
+  suspendedJobs: 0,
+  jobsDueFuture: 0,
+  openExternalTasks: 0,
+  deployedDefinitionKeys: 0,
+  exclusiveDefinitionKeys: 0,
+  ...over,
+})
+
+const landscape = (over: Partial<EngineLandscapeResult> = {}): EngineLandscapeResult => ({
+  engines: [
+    engine("prod-a", { runningInstances: 12, executableJobs: 3, deployedDefinitionKeys: 2 }),
+    engine("prod-b", { runningInstances: 4, executableJobs: 90, deployedDefinitionKeys: 1 }),
+  ],
+  processes: [],
+  sharedProcessKeys: ["order"],
+  totals: {
+    engineCount: 2,
+    reportingEngineCount: 2,
+    processKeyCount: 3,
+    sharedProcessKeyCount: 1,
+    runningInstances: 16,
+    openIncidents: 2,
+    failedJobs: 0,
+  },
+  ...over,
+})
+
+describe("describeEngineLandscape", () => {
+  it("names the busiest engine, the largest backlog and the comparable process", () => {
+    const text = describeEngineLandscape(landscape(), {})
+
+    expect(text).toContain('busiestEngine="prod-a", busiestRunningInstances=12')
+    expect(text).toContain('largestBacklogEngine="prod-b", largestBacklogExecutableJobs=90')
+    expect(text).toContain('sharedProcessKeys=["order"]')
+    expect(text).toContain("Tools: analytics_engine_compare, analytics_engine_health")
+  })
+
+  it("tells the model why per-engine rates are absent", () => {
+    // The whole point of the view: without this line a model would happily
+    // divide the counts into per-engine rates and compare them again.
+    expect(describeEngineLandscape(landscape(), {})).toContain("different process mixes")
+  })
+
+  it("states that no valid engine comparison exists when nothing is shared", () => {
+    const text = describeEngineLandscape(landscape({ sharedProcessKeys: [] }), {})
+
+    expect(text).toContain("No definition runs on more than one engine")
+    // Without a shared definition there is nothing to compare: no compare tool.
+    expect(text).not.toContain("analytics_engine_compare")
+    expect(text).toContain("Tools: analytics_engine_health")
+  })
+
+  it("calls out engines that report no metrics at all", () => {
+    const text = describeEngineLandscape(
+      landscape({
+        engines: [
+          engine("prod-a", { runningInstances: 1 }),
+          engine("prod-c", { reporting: false }),
+        ],
+      }),
+      {},
+    )
+
+    expect(text).toContain('enginesReportingNoMetrics=["prod-c"]')
+  })
+})
+
+const versionKpi = (version: number, over: Partial<VersionCompareKpi> = {}): VersionCompareKpi => ({
+  version,
+  bucket: version === 1 ? "versionA" : "versionB",
+  instance_count: 100,
+  completed_count: 90,
+  incident_count: 2,
+  incident_rate_pct: 2,
+  element_incident_count: null,
+  element_incident_rate_pct: null,
+  avg_duration_sec: 10,
+  p95_duration_sec: 20,
+  ...over,
+})
+
+const versionCompare = (
+  kpis: VersionCompareKpi[],
+  engines: string[] | null = ["prod-a"],
+): VersionCompareResult => ({
+  engines,
+  processDefinitionKey: "order",
+  versionA: 1,
+  versionB: 2,
+  windowDays: 14,
+  minBucketSize: 10,
+  suppressed: false,
+  kpis,
+  delta: {
+    started_per_day_delta_pct: 0,
+    incident_rate_delta_pp: 0,
+    element_incident_rate_delta_pp: null,
+    avg_duration_delta_pct: 25,
+    p95_duration_delta_pct: null,
+  },
+})
+
+describe("describeVersionCompare", () => {
+  it("names the measured deltas, the incident rate per version included", () => {
+    const text = describeVersionCompare(versionCompare([versionKpi(1), versionKpi(2)]), {})
+
+    expect(text).toContain("avgDurationDeltaPct=25")
+    expect(text).toContain("incidentRateDeltaPp=0")
+    expect(text).toContain('largestDelta="avgDurationDeltaPct"')
+    // An unmeasured delta is left out — never sent as 0.
+    expect(text).not.toContain("p95DurationDeltaPct")
+    expect(text).not.toMatch(/failure/i)
+  })
+
+  // The tool takes no element scope (#336): the comparison is process-wide,
+  // on the engines it read.
+  it("re-runs the process-wide comparison on the engines on screen", () => {
+    const text = describeVersionCompare(versionCompare([versionKpi(1), versionKpi(2)]), {})
+    expect(text).toContain(
+      'Ids: engine="prod-a", processDefinitionKey="order", versionA=1, versionB=2, windowDays=14\n',
+    )
+    expect(text).toContain("every figure covers the whole process")
+    expect(text).not.toContain("activityId")
+  })
+
+  it("names every engine of a fleet comparison (K33)", () => {
+    const text = describeVersionCompare(
+      versionCompare([versionKpi(1), versionKpi(2)], ["prod-a", "prod-b"]),
+      {},
+    )
+    expect(text).toContain('Ids: engine=["prod-a","prod-b"]')
+    expect(text).toContain("(aggregated)")
+  })
+})
+
+const failures = (engines: string[] | null): FailureDashboardData => ({
+  engines,
+  totalIncidents: 6,
+  uniqueErrorPatterns: 1,
+  mostAffectedProcess: "order",
+  errorPatterns: [{ incidentType: "failedJob", processDefinitionKey: "order", incidentCount: 6 }],
+  processBreakdown: [
+    {
+      processDefinitionKey: "order",
+      runningNow: 50,
+      deadJobs: 3,
+      openIncidents: 6,
+      incidentRatePct: 12,
+    },
+  ],
+})
+
+describe("describeFailureRates", () => {
+  it("states live open incidents per running instance and routes the regression check (#327)", () => {
+    const text = describeFailureRates(failures(["prod-a"]), {})
+
+    expect(text).toContain('Ids: engine="prod-a"\n')
+    expect(text).toContain(
+      'highestRateProcessDefinitionKey="order", highestOpenIncidentsNow=6, highestRunningNow=50, highestIncidentRatePct=12, highestDeadJobs=3',
+    )
+    expect(text).toContain("Tools: analytics_compare_execution_periods, analytics_cluster_compare")
+    // Its incident rates are null per version — a wasted call for this question.
+    expect(text).not.toContain("analytics_version_compare")
+    // Incidents, not failed instances (N85).
+    expect(text).not.toMatch(/failed|failure/i)
+  })
+
+  it("leaves an unmeasured rate out instead of sending it as 0", () => {
+    const idle = failures(["prod-a"])
+    idle.processBreakdown = [{ ...idle.processBreakdown[0], runningNow: 0, incidentRatePct: null }]
+    expect(describeFailureRates(idle, {})).not.toContain("highestIncidentRatePct")
+  })
+})
+
+describe("failure-dashboard scope (N83/N116)", () => {
+  it("names the engines from the data, not from cell props — a self-fetch keeps its label", () => {
+    for (const describeCell of [
+      describeFailureSummary,
+      describeErrorPatterns,
+      describeFailureRates,
+    ]) {
+      const fleet = describeCell(failures(["prod-a", "prod-b"]), {})
+      expect(fleet).toContain('Ids: engine=["prod-a","prod-b"]')
+      expect(fleet).toContain("(aggregated)")
+      // Props claiming another engine never override what the data covers.
+      const scoped = describeCell(failures(["prod-a"]), { engine: "prod-b" })
+      expect(scoped).toContain('Ids: engine="prod-a"')
+      expect(scoped).not.toContain("prod-b")
+      // An unscoped library result names no engine — never a placeholder.
+      expect(describeCell(failures(null), {})).not.toContain("engine=")
+    }
+  })
+
+  it("presents only fields the open-incident metric fills (N117)", () => {
+    const text = describeErrorPatterns(failures(["prod-a"]), {})
+    expect(text).toContain(
+      'On screen: groups=1, largestGroupProcessDefinitionKey="order", largestGroupIncidentType="failedJob", largestGroupIncidents=6',
+    )
+    expect(text).toContain("no message, activity or timestamps")
+  })
+
+  // The view spans every process: the largest group's key is a fact, never
+  // the scope the model passes on; the list is capped at 50, the totals not.
+  it("scopes the view by engine only and states the exact group count of a capped list", () => {
+    const capped: FailureDashboardData = {
+      ...failures(["prod-a", "prod-b"]),
+      uniqueErrorPatterns: 73,
+      errorPatterns: Array.from({ length: 50 }, (_, i) => ({
+        incidentType: "failedJob",
+        processDefinitionKey: i === 0 ? "order" : `process_${i}`,
+        incidentCount: 100 - i,
+      })),
+    }
+    const text = describeErrorPatterns(capped, {})
+    expect(text).toContain('Ids: engine=["prod-a","prod-b"]\n')
+    expect(text).not.toMatch(/[,\s]processDefinitionKey=/)
+    expect(text).toContain(
+      'On screen: groups=73, listedGroups=50, largestGroupProcessDefinitionKey="order", largestGroupIncidentType="failedJob", largestGroupIncidents=100',
+    )
+    // An uncapped list is the whole set — no listed count beside it.
+    expect(describeErrorPatterns(failures(["prod-a"]), {})).not.toContain("listedGroups")
+  })
+})

package/src/widgets/model-descriptions.ts

@@ -0,0 +1,428 @@
+import type {
+  AnalyticsDashboardData,
+  CompareKpiDelta,
+  FailureDashboardData,
+} from "@miragon/pulse-analytics-client"
+import { modelContextText, type ModelContextSpec } from "@miragon/pulse-widget-shell/widgets"
+import type { DescribeForModel } from "@miragon/pulse-widget-shell/ui"
+import { ANALYTICS_ONLY_SURFACE, engineIdsOf, isAggregate } from "./hand-off.js"
+import type { ClusterCompareData } from "./cluster-compare.js"
+import type { VersionCompareData } from "./version-compare.js"
+import type { EngineCompareData } from "./engine-compare.js"
+import type { EngineLandscapeData } from "./engine-landscape.js"
+import type { AnalyticsSettingsViewData } from "./settings-section.js"
+import type { AnalyticsBpmnHeatmapData } from "./bpmn-heatmap.js"
+import { deltaFacts } from "./comparison-shared.js"
+
+/**
+ * Model-context descriptions for every analytics widget, attached centrally via
+ * `adaptDataWidget(..., describe)` in `widgets/index.ts`. Each one is built by
+ * `modelContextText` (#338, CLAUDE.md invariant 6) — a static summary of the
+ * view, the ids the follow-up tools take, the headline numbers as facts, and
+ * the natural follow-up tools — never a hand-written template: a value is
+ * inlined only when id-shaped, and a tool is only ever named in `tools`.
+ *
+ * The scope comes from the DATA, never from the cell props (#336): every
+ * analytics result echoes what it covers (process key, period, `engines`), so
+ * a widget that self-fetched, was saved or composed by render-view describes
+ * exactly the numbers on screen — including which engines a fleet aggregate
+ * adds up. A figure that was not measured is null and left out, never a 0.
+ *
+ * A pure description cannot query the camunda7 surface, so these name
+ * analytics tools only (`ANALYTICS_ONLY_SURFACE`); the Ask-AI hand-offs (live
+ * surface) add the camunda7 ones where the deployment has them.
+ */
+
+/** Said whenever a figure adds up several engines (the deliberate fleet aggregate). */
+const AGGREGATED = " The figures add up every engine listed (aggregated)."
+
+/**
+ * Said for an incident rate over several processes: a total over their mix,
+ * so the screen judges no change of it (`incidentRateTrend`).
+ */
+const MIXED_RATE =
+  " The incident rate totals several processes, so its change against the previous period reflects their mix and is not judged; compare per process."
+
+/** How many definitions an unscoped dashboard covers (none when scoped to one). */
+function definitionCount(data: AnalyticsDashboardData) {
+  return data.processDefinitionKey ? undefined : data.definitionBreakdown.length
+}
+
+/**
+ * The execution summary: flows within the period (`…InWindow` — incidents,
+ * not failed instances) kept apart from the live gauges (`…Now`), which do
+ * not depend on the period (#336).
+ */
+export const describeExecutionSummary: DescribeForModel<AnalyticsDashboardData> = (data) =>
+  modelContextText({
+    summary:
+      "The operator is viewing the execution summary of the process analytics: flows within the period (incidents, not failed instances) apart from the live state right now, which does not depend on the period." +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: {
+      engine: engineIdsOf(data.engines),
+      processDefinitionKey: data.processDefinitionKey ?? undefined,
+      period: data.period,
+    },
+    facts: {
+      processDefinitions: definitionCount(data),
+      startedInWindow: data.totalCount,
+      completedInWindow: data.completedCount,
+      incidentsCreatedInWindow: data.incidentsCreated,
+      incidentsResolvedInWindow: data.incidentsResolved,
+      runningNow: data.runningNow,
+      openIncidentsNow: data.openIncidentsNow,
+    },
+    tools: ["analytics_analyze_process_performance", "analytics_find_failed_instances"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+
+/** The performance KPIs: durations of the instances that ENDED in the period (null when none did). */
+export const describeExecutionPerformance: DescribeForModel<AnalyticsDashboardData> = (data) =>
+  modelContextText({
+    summary:
+      "The operator is viewing the performance KPIs of the process analytics: durations of the instances that ended in the period, and incidents per 100 started instances." +
+      (data.avgDurationMs === null
+        ? " No instance ended in the period, so there are no durations."
+        : "") +
+      (data.processDefinitionKey ? "" : MIXED_RATE) +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: {
+      engine: engineIdsOf(data.engines),
+      processDefinitionKey: data.processDefinitionKey ?? undefined,
+      period: data.period,
+    },
+    facts: {
+      processDefinitions: definitionCount(data),
+      avgDurationMs: data.avgDurationMs,
+      medianDurationMs: data.medianDurationMs,
+      p95DurationMs: data.p95DurationMs,
+      incidentRatePct: data.incidentRatePct,
+      // The reference the rate is judged against on screen (one process
+      // only): the period before.
+      previousPeriodIncidentRatePct: data.previous?.incidentRatePct,
+      previousPeriodComparisonNotReliable:
+        (data.processDefinitionKey && data.previous?.suppressed) || undefined,
+    },
+    tools: ["analytics_element_bottleneck"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+
+export const describeDefinitionBreakdown: DescribeForModel<AnalyticsDashboardData> = (data) => {
+  const top = [...data.definitionBreakdown].sort((a, b) => b.totalInstances - a.totalInstances)[0]
+  return modelContextText({
+    summary:
+      "The operator is viewing the per-definition breakdown of the process analytics; " +
+      "the dashboard scopes to one process by its processDefinitionKey." +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: {
+      engine: engineIdsOf(data.engines),
+      processDefinitionKey: data.processDefinitionKey ?? undefined,
+      period: data.period,
+    },
+    facts: {
+      processDefinitions: data.definitionBreakdown.length,
+      busiestProcessDefinitionKey: top?.processDefinitionKey,
+      busiestStartedInWindow: top?.totalInstances,
+      busiestIncidentsCreatedInWindow: top?.incidentsCreated,
+      busiestRunningNow: top?.runningNow,
+    },
+    tools: ["analytics_show_dashboard"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+}
+
+/**
+ * The bottleneck table: one row per (process, activity) — BPMN ids are only
+ * unique within one model, so the top row names its process too.
+ */
+export const describeActivityBottlenecks: DescribeForModel<AnalyticsDashboardData> = (data) => {
+  const top = [...data.activityBreakdown].sort((a, b) => b.totalTimeMs - a.totalTimeMs)[0]
+  return modelContextText({
+    summary:
+      "The operator is viewing the activity-bottleneck table of the process analytics: one row per (process, activity)." +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: {
+      engine: engineIdsOf(data.engines),
+      processDefinitionKey: data.processDefinitionKey ?? undefined,
+      period: data.period,
+    },
+    facts: {
+      rows: data.activityBreakdown.length,
+      // The list is the top of the breakdown by total time: how many there were in all.
+      activitiesInAll:
+        data.activityCount > data.activityBreakdown.length ? data.activityCount : undefined,
+      topProcessDefinitionKey: top?.processDefinitionKey,
+      topActivityId: top?.activityId,
+      topExecutions: top?.executionCount,
+      topTotalTimeMs: top?.totalTimeMs,
+      topP95DurationMs: top?.p95DurationMs,
+    },
+    tools: ["analytics_element_bottleneck"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+}
+
+/**
+ * The failure summary (point-in-time). A pure description cannot query the
+ * camunda7 surface, so it names analytics tools only; the Ask-AI hand-off
+ * (live surface) adds the camunda7 ones where the deployment has them.
+ */
+export const describeFailureSummary: DescribeForModel<FailureDashboardData> = (data) =>
+  modelContextText({
+    summary:
+      "The operator is viewing the failure dashboard: the incidents open right now (point-in-time, no period), grouped by incident type and process." +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: { engine: engineIdsOf(data.engines) },
+    facts: {
+      openIncidents: data.totalIncidents,
+      incidentGroups: data.uniqueErrorPatterns,
+      mostAffectedProcess: data.mostAffectedProcess,
+    },
+    tools: ["analytics_find_failed_instances"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+
+/**
+ * The open-incident groups. The gauge carries only incident type, process and
+ * count — no message, activity or timestamps. A custom incident type is any
+ * string: unless id-shaped it is quoted as untrusted data (#338). The view
+ * spans every process, so the largest group's key is a fact, never a scope;
+ * the group count is the exact one, and a capped list says how much it shows.
+ */
+export const describeErrorPatterns: DescribeForModel<FailureDashboardData> = (data) => {
+  const top = [...data.errorPatterns].sort((a, b) => b.incidentCount - a.incidentCount)[0]
+  const listed = data.errorPatterns.length
+  return modelContextText({
+    summary:
+      "The operator is viewing the incidents open right now (point-in-time), grouped by incident type and process; the metric carries no message, activity or timestamps." +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: { engine: engineIdsOf(data.engines) },
+    // A value that is not id-shaped moves into the untrusted fence by itself.
+    facts: {
+      groups: data.uniqueErrorPatterns,
+      listedGroups: listed < data.uniqueErrorPatterns ? listed : undefined,
+      largestGroupProcessDefinitionKey: top?.processDefinitionKey,
+      largestGroupIncidentType: top?.incidentType,
+      largestGroupIncidents: top?.incidentCount,
+    },
+    tools: ["analytics_find_failed_instances"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+}
+
+/**
+ * Open incidents by process (point-in-time live gauges): open incidents per
+ * 100 running instances and dead jobs — incidents, not failed instances
+ * (#336). The regression check goes to the tools that measure incident rates
+ * over time — not analytics_version_compare: it cannot split incidents by
+ * version, so its incident rates are null (#327).
+ */
+export const describeFailureRates: DescribeForModel<FailureDashboardData> = (data) => {
+  const top = [...data.processBreakdown].sort(
+    (a, b) => (b.incidentRatePct ?? -1) - (a.incidentRatePct ?? -1),
+  )[0]
+  return modelContextText({
+    summary:
+      "The operator is viewing the incidents open right now by process (point-in-time): open " +
+      "incidents per 100 running instances and dead jobs. A regression shows period over " +
+      "period or around a deployment." +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: { engine: engineIdsOf(data.engines) },
+    facts: {
+      processes: data.processBreakdown.length,
+      highestRateProcessDefinitionKey: top?.processDefinitionKey,
+      highestOpenIncidentsNow: top?.openIncidents,
+      highestRunningNow: top?.runningNow,
+      highestIncidentRatePct: top?.incidentRatePct,
+      highestDeadJobs: top?.deadJobs,
+    },
+    tools: ["analytics_compare_execution_periods", "analytics_cluster_compare"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+}
+
+/**
+ * The deltas on screen plus the single largest one — the number a user asks
+ * about first. The candidates are the {@link deltaFacts} keys: a new
+ * `CompareKpiDelta` field must be added there.
+ */
+function comparisonFacts(delta: CompareKpiDelta, suppressed: boolean) {
+  const facts = deltaFacts(delta, suppressed)
+  const moved = Object.entries(facts).filter(
+    (entry): entry is [string, number] => typeof entry[1] === "number" && entry[1] !== 0,
+  )
+  const largest = moved.reduce<[string, number] | null>(
+    (max, entry) => (max === null || Math.abs(entry[1]) > Math.abs(max[1]) ? entry : max),
+    null,
+  )
+  return { ...facts, largestDelta: largest?.[0] ?? "none" }
+}
+
+const SUPPRESSED = " The sample is below minBucketSize (suppressed): treat the deltas as noise."
+
+/**
+ * Before/after a deployment. The ids re-run the comparison as asked (the
+ * requested whole-day windows); the windows actually measured — cut short at
+ * now or the retention — are facts (#336).
+ */
+export const describeClusterCompare: DescribeForModel<ClusterCompareData> = (data) =>
+  modelContextText({
+    summary:
+      "The operator is comparing KPIs before vs after a deployment (cluster-wide unless a " +
+      "processDefinitionKey scopes it); durations cover only the instances that ended in a window." +
+      (data.partial
+        ? " A window was cut short at now or the retention (partial): starts compare per day."
+        : "") +
+      (data.suppressed ? SUPPRESSED : "") +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: {
+      engine: engineIdsOf(data.engines),
+      deploymentTimestamp: data.deploymentTimestamp,
+      windowBeforeDays: data.requestedWindowDays.before,
+      windowAfterDays: data.requestedWindowDays.after,
+      processDefinitionKey: data.processDefinitionKey,
+      activityId: data.activityId,
+    },
+    facts: {
+      measuredBeforeDays: data.windowDays.before,
+      measuredAfterDays: data.windowDays.after,
+      ...comparisonFacts(data.delta, data.suppressed),
+    },
+    tools: ["analytics_cluster_compare", "analytics_element_bottleneck"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+
+/** Version compare: process-wide (the tool takes no element scope, #336). */
+export const describeVersionCompare: DescribeForModel<VersionCompareData> = (data) =>
+  modelContextText({
+    summary:
+      "The operator is comparing two versions of one process (versionA is the baseline); every " +
+      "figure covers the whole process." +
+      (data.suppressed ? SUPPRESSED : "") +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: {
+      engine: engineIdsOf(data.engines),
+      processDefinitionKey: data.processDefinitionKey,
+      versionA: data.versionA,
+      versionB: data.versionB,
+      windowDays: data.windowDays,
+    },
+    facts: comparisonFacts(data.delta, data.suppressed),
+    tools: ["analytics_version_compare", "analytics_element_bottleneck"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+
+export const describeEngineCompare: DescribeForModel<EngineCompareData> = (data) =>
+  modelContextText({
+    summary:
+      "The operator is comparing one process on two engines (engineA is the baseline). The " +
+      "process is held fixed, so a delta is attributable to the engine rather than to a " +
+      "different workload." +
+      (data.suppressed ? SUPPRESSED : ""),
+    ids: {
+      processDefinitionKey: data.processDefinitionKey,
+      engineA: data.engineA,
+      engineB: data.engineB,
+      windowDays: data.windowDays,
+      activityId: data.activityId,
+    },
+    facts: comparisonFacts(data.delta, data.suppressed),
+    tools: ["analytics_engine_compare", "analytics_engine_health", "analytics_engine_landscape"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+
+export const describeEngineLandscape: DescribeForModel<EngineLandscapeData> = (data) => {
+  const { totals } = data
+  const silent = data.engines.filter((e) => !e.reporting).map((e) => e.engineId)
+  // Ranked among the engines that report: a silent engine's counts are unknown (null).
+  const measured = data.engines.flatMap((e) =>
+    e.reporting
+      ? [{ ...e, running: e.runningInstances ?? 0, executable: e.executableJobs ?? 0 }]
+      : [],
+  )
+  const busiest = [...measured].sort((a, b) => b.running - a.running)[0]
+  const backlog = [...measured].sort((a, b) => b.executable - a.executable)[0]
+  const shared = data.sharedProcessKeys.length > 0
+  return modelContextText({
+    summary:
+      "The operator is viewing the cross-engine landscape: absolute counts and the " +
+      "process-independent job backlog on purpose — engines run different process mixes, so " +
+      "per-engine failure rates or durations would describe the mix, not the engine." +
+      (shared
+        ? " A KPI comparison is only sound for a definition deployed on several engines " +
+          "(sharedProcessKeys), compared by its processDefinitionKey."
+        : " No definition runs on more than one engine, so there is no valid engine-vs-engine " +
+          "KPI comparison here."),
+    facts: {
+      engines: totals.engineCount,
+      processDefinitions: totals.processKeyCount,
+      runningInstances: totals.runningInstances,
+      openIncidents: totals.openIncidents,
+      enginesReportingNoMetrics: silent.length > 0 ? silent : undefined,
+      busiestEngine: busiest?.engineId,
+      busiestRunningInstances: busiest?.running,
+      largestBacklogEngine: backlog && backlog.executable > 0 ? backlog.engineId : undefined,
+      largestBacklogExecutableJobs:
+        backlog && backlog.executable > 0 ? backlog.executable : undefined,
+      sharedProcessKeys: shared ? data.sharedProcessKeys : undefined,
+    },
+    tools: ["analytics_engine_compare", "analytics_engine_health"].filter(
+      (tool) => shared || tool !== "analytics_engine_compare",
+    ),
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+}
+
+function maxEntry(values: Record<string, number>): [string, number] | null {
+  let best: [string, number] | null = null
+  for (const [key, value] of Object.entries(values)) {
+    if (!best || value > best[1]) best = [key, value]
+  }
+  return best
+}
+
+/**
+ * The settings section. Its save tool is named only while the section can
+ * save (`canSave`: the toolset registers the write AND the caller has an
+ * identity to save under) — the model is never told about a write that fails.
+ * Rendered in-component (the section self-fetches), hence a spec, not a text.
+ */
+export function describeAnalyticsSettings(data: AnalyticsSettingsViewData): ModelContextSpec {
+  return {
+    summary:
+      "The operator is viewing the analytics settings: the defaults every analytics call uses when it omits period or minBucketSize.",
+    facts: {
+      defaultPeriod: data.settings.defaultPeriod,
+      minBucketSize: data.settings.minBucketSize,
+      editable: data.canSave,
+    },
+    tools: ["analytics_save_settings"],
+    surface: { has: (tool) => tool === "analytics_save_settings" && data.canSave },
+  }
+}
+
+/** The BPMN heatmap — over the engines its heat adds up (the `engines` echo, #336). */
+export const describeBpmnHeatmap: DescribeForModel<AnalyticsBpmnHeatmapData> = (data) => {
+  const hottest = maxEntry(data.frequency)
+  const slowest = maxEntry(data.durationSec)
+  return modelContextText({
+    summary:
+      "The operator is viewing the BPMN heatmap of one process (the frequency ↔ duration toggle " +
+      "is client-side)." +
+      (isAggregate(data.engines) ? AGGREGATED : ""),
+    ids: {
+      engine: engineIdsOf(data.engines),
+      processDefinitionKey: data.processDefinitionKey,
+      period: data.period,
+    },
+    facts: {
+      elementsWithHeat: Object.keys(data.frequency).length,
+      hottestActivityId: hottest?.[0],
+      hottestExecutions: hottest?.[1],
+      slowestActivityId: slowest?.[0],
+      slowestAvgSec: slowest ? Math.round(slowest[1] * 10) / 10 : undefined,
+    },
+    tools: ["analytics_element_bottleneck"],
+    surface: ANALYTICS_ONLY_SURFACE,
+  })
+}