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

package/package.json

@@ -1,8 +1,94 @@
 {
   "name": "@miragon/pulse-analytics-connector",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder that sets up trusted publishing. The first release of @miragon/pulse-analytics-connector is 0.21.0.",
+  "version": "0.21.0",
+  "description": "Prometheus-backed process-analytics MCP module: tools, dashboards, and comparison widgets.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/Miragon/pulse.git" },
-  "homepage": "https://github.com/Miragon/pulse#readme"
-}
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "camunda",
+    "process-analytics",
+    "prometheus",
+    "widgets"
+  ],
+  "homepage": "https://github.com/Miragon/pulse/tree/main/packages/connectors/analytics/analytics-connector#readme",
+  "bugs": "https://github.com/Miragon/pulse/issues",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Miragon/pulse.git",
+    "directory": "packages/connectors/analytics/analytics-connector"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./widgets": "./src/widgets/index.ts",
+    "./definition": "./src/definition.ts"
+  },
+  "dependencies": {
+    "@miragon/pulse-analytics-client": "0.21.0",
+    "@miragon/pulse-widget-shell": "0.21.0"
+  },
+  "peerDependencies": {
+    "@miragon/mcp-toolkit-core": "~2.8.1",
+    "@miragon/mcp-toolkit-ui": "~2.8.1",
+    "lucide-react": "^0.562.0 || ^1.0.0",
+    "mcp-use": "2.7.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "zod": "^4.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@miragon/mcp-toolkit-ui": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@miragon/mcp-toolkit-core": "2.8.1",
+    "@miragon/mcp-toolkit-ui": "2.8.1",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "bpmn-js": "18.30.1",
+    "happy-dom": "20.14.5",
+    "lucide-react": "0.562.0",
+    "mcp-use": "2.7.3",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11",
+    "zod": "4.6.5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.widgets.json",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test:mutation": "stryker run"
+  }
+}

package/src/bpmn-name-lookup.test.ts

@@ -0,0 +1,333 @@
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { getMcpRequestInfo, runWithMcpRequestInfo } from "@miragon/pulse-widget-shell/server"
+import { NO_NAMES, createNameLookup, type FetchBpmnXml } from "./bpmn-name-lookup.js"
+import { elementNameOf, processNameOf } from "./bpmn-names.js"
+
+/**
+ * The names behind the ids (U13): read on the server from the diagram the
+ * injected BPMN lookup returns, never a guess, never a failure. The reader
+ * itself is the kit's (`parseBpmnNames`, widget-shell's `bpmn-names.test.ts`):
+ * the one rule camunda7 names the same process and activities by.
+ */
+
+const LEASING = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" id="Defs_1">
+  <!-- <bpmn:userTask id="Task_Commented" name="Never shown" /> -->
+  <bpmn:process id="miraveloLeasing" name="Bike Leasing" isExecutable="true">
+    <bpmn:startEvent id="StartEvent_1" name="Application&#10;&#10; received" />
+    <bpmn:userTask id="Activity_Decide" name='Decide on "Leasing &amp; Co"'>
+      <bpmn:documentation><![CDATA[<bpmn:task id="Task_InCdata" name="Nope"/>]]></bpmn:documentation>
+    </bpmn:userTask>
+    <bpmn:exclusiveGateway id="Gateway_Amount" name="Amount &gt; 1000?" />
+    <bpmn:serviceTask id="Activity_Unnamed" />
+    <bpmn:serviceTask id="Activity_Blank" name="   " />
+    <bpmn:endEvent id="EndEvent_Done" name="Done &#x2713;"/>
+  </bpmn:process>
+</bpmn:definitions>`
+
+describe("createNameLookup", () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it("knows no names without a BPMN lookup (no camunda7 module)", async () => {
+    expect(createNameLookup(undefined)).toBe(NO_NAMES)
+    expect(await NO_NAMES(["a"])).toEqual({})
+  })
+
+  it("reads each key once and keeps only the elements a view asks for", async () => {
+    const fetchBpmnXml = vi.fn((key: string) =>
+      Promise.resolve(key === "miraveloLeasing" ? LEASING : null),
+    )
+    const namesFor = createNameLookup(fetchBpmnXml)
+    const index = await namesFor(["miraveloLeasing", "miraveloLeasing", "", "unknown"], {
+      elementIds: { miraveloLeasing: ["Activity_Decide", "Activity_Missing"], unknown: [] },
+    })
+    // Strictly: an element the model does not name is left out, never `undefined`.
+    expect(index).toStrictEqual({
+      miraveloLeasing: {
+        name: "Bike Leasing",
+        elements: { Activity_Decide: 'Decide on "Leasing & Co"' },
+      },
+    })
+    expect(fetchBpmnXml.mock.calls.map((c) => c[0])).toEqual(["miraveloLeasing", "unknown"])
+    expect(processNameOf(index, "miraveloLeasing")).toBe("Bike Leasing")
+    expect(processNameOf(index, "unknown")).toBeNull()
+    expect(elementNameOf(index, "miraveloLeasing", "Activity_Decide")).toBe(
+      'Decide on "Leasing & Co"',
+    )
+    expect(elementNameOf(index, "miraveloLeasing", "constructor")).toBeNull()
+    expect(elementNameOf(index, "unknown", "x")).toBeNull()
+    expect(elementNameOf(undefined, "a", "b")).toBeNull()
+    // Without an element list a key comes with every named element.
+    const all = await namesFor(["miraveloLeasing"])
+    expect(Object.keys(all.miraveloLeasing.elements)).toHaveLength(4)
+  })
+
+  it("reuses a read, an empty one too, until it is older than the ttl", async () => {
+    let now = 0
+    const fetchBpmnXml = vi.fn((key: string) => Promise.resolve(key === "a" ? LEASING : null))
+    const namesFor = createNameLookup(fetchBpmnXml, { ttlMs: 1000, now: () => now })
+    await namesFor(["a", "b"])
+    now = 999
+    await namesFor(["a", "b"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(2)
+    now = 1000
+    await namesFor(["a", "b"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(4)
+  })
+
+  it("goes on with the ids when a read fails or is slow, and asks again next time", async () => {
+    vi.useFakeTimers()
+    const fetchBpmnXml = vi.fn((key: string) =>
+      key === "slow"
+        ? new Promise<string | null>(() => {})
+        : Promise.reject(new Error("ECONNREFUSED")),
+    )
+    const namesFor = createNameLookup(fetchBpmnXml, { timeoutMs: 50 })
+    const pending = namesFor(["slow", "broken"])
+    await vi.advanceTimersByTimeAsync(50)
+    expect(await pending).toEqual({})
+    const again = namesFor(["slow", "broken"])
+    await vi.advanceTimersByTimeAsync(50)
+    await again
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(4)
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  // The injected fetcher (camunda7's createBpmnXmlFetcher) REJECTS a failed
+  // read (503, refused, 401) and resolves null only for "no such model": the
+  // engine's failure is no answer to keep for five minutes.
+  it("keeps a 'no such model' answer but never a failure", async () => {
+    let engineUp = false
+    const fetchBpmnXml = vi.fn((key: string) =>
+      engineUp
+        ? Promise.resolve(key === "miraveloLeasing" ? LEASING : null)
+        : Promise.reject(new Error("503 Service Unavailable")),
+    )
+    const namesFor = createNameLookup(fetchBpmnXml)
+    expect(await namesFor(["miraveloLeasing", "unknown"])).toEqual({})
+    engineUp = true
+    expect(processNameOf(await namesFor(["miraveloLeasing", "unknown"]), "miraveloLeasing")).toBe(
+      "Bike Leasing",
+    )
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(4)
+    // Now both are answers: the names and "no such model", both kept.
+    await namesFor(["miraveloLeasing", "unknown"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(4)
+  })
+
+  it("leaves no timer pending after a fast view", async () => {
+    vi.useFakeTimers()
+    const fetchBpmnXml = vi.fn<FetchBpmnXml>(() => Promise.resolve(LEASING))
+    const index = await createNameLookup(fetchBpmnXml)(["miraveloLeasing"])
+    expect(processNameOf(index, "miraveloLeasing")).toBe("Bike Leasing")
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  it("finishes a slow read for the next view", async () => {
+    vi.useFakeTimers()
+    let answer: (xml: string) => void = () => {}
+    const fetchBpmnXml = vi.fn(
+      () =>
+        new Promise<string | null>((resolve) => {
+          answer = resolve
+        }),
+    )
+    const namesFor = createNameLookup(fetchBpmnXml, { timeoutMs: 50 })
+    const first = namesFor(["miraveloLeasing"])
+    await vi.advanceTimersByTimeAsync(50)
+    expect(await first).toEqual({})
+    answer(LEASING)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(processNameOf(await namesFor(["miraveloLeasing"]), "miraveloLeasing")).toBe(
+      "Bike Leasing",
+    )
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(1)
+  })
+
+  it("looks up at most maxKeys keys for one view, in the order it names them", async () => {
+    const fetchBpmnXml = vi.fn<FetchBpmnXml>(() => Promise.resolve(null))
+    await createNameLookup(fetchBpmnXml, { maxKeys: 2 })(["a", "b", "c"])
+    expect(fetchBpmnXml.mock.calls.map((c) => c[0])).toEqual(["a", "b"])
+  })
+
+  it("keeps at most maxEntries answers, dropping the oldest first", async () => {
+    const fetchBpmnXml = vi.fn<FetchBpmnXml>(() => Promise.resolve(null))
+    const namesFor = createNameLookup(fetchBpmnXml, { maxEntries: 2 })
+    await namesFor(["a", "b", "c"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(3)
+    // "b" and "c" are still kept; "a" went first and is read again.
+    await namesFor(["b", "c"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(3)
+    await namesFor(["a"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(4)
+  })
+
+  it("keeps a re-read answer as the newest, so the next to go is the oldest read", async () => {
+    let now = 0
+    const fetchBpmnXml = vi.fn<FetchBpmnXml>(() => Promise.resolve(null))
+    const namesFor = createNameLookup(fetchBpmnXml, { maxEntries: 2, ttlMs: 1000, now: () => now })
+    await namesFor(["a", "b"])
+    now = 1000
+    // "a" expired and is read again: now the newest, "b" the oldest.
+    await namesFor(["a"])
+    await namesFor(["c"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(4)
+    // "b" went for "c"; "a" is still kept.
+    await namesFor(["a"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(4)
+    await namesFor(["b"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(5)
+  })
+
+  it("never reads an inherited entry for a key such as constructor", async () => {
+    const fetchBpmnXml = vi.fn<FetchBpmnXml>(() =>
+      Promise.resolve('<process id="constructor" name="Odd"><task id="T" name="Step"/></process>'),
+    )
+    const index = await createNameLookup(fetchBpmnXml)(["constructor"], {
+      elementIds: {},
+      enginesByKey: {},
+    })
+    expect(index.constructor).toEqual({ name: "Odd", elements: { T: "Step" } })
+    expect(fetchBpmnXml.mock.calls).toEqual([["constructor", undefined]])
+  })
+})
+
+/**
+ * A process may run on any configured engine, not only the default one
+ * (#322 review): each model is read on the engines the view's row comes
+ * from, in order, until one of them has it.
+ */
+describe("createNameLookup on several engines", () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  /** An engine fleet: which engine holds which model, and which engine is down. */
+  function fleet(models: Record<string, Record<string, string>>, down: string[] = []) {
+    return vi.fn<FetchBpmnXml>((key, engine) => {
+      if (engine && down.includes(engine)) return Promise.reject(new Error("503"))
+      return Promise.resolve(models[engine ?? "default"]?.[key] ?? null)
+    })
+  }
+
+  it("reads a key on the view's engines in order until one has its model", async () => {
+    const fetchBpmnXml = fleet({ "prod-c": { miraveloLeasing: LEASING } }, ["prod-a"])
+    const index = await createNameLookup(fetchBpmnXml)(["miraveloLeasing"], {
+      engines: ["prod-a", "prod-b", "prod-c", "prod-d"],
+    })
+    expect(processNameOf(index, "miraveloLeasing")).toBe("Bike Leasing")
+    expect(fetchBpmnXml.mock.calls.map((c) => c[1])).toEqual(["prod-a", "prod-b", "prod-c"])
+  })
+
+  it("prefers a key's own engines over the view's, and the default engine without either", async () => {
+    const fetchBpmnXml = fleet({
+      "prod-b": { miraveloLeasing: LEASING },
+      default: { other: '<process id="other" name="Other"/>' },
+    })
+    const namesFor = createNameLookup(fetchBpmnXml)
+    const index = await namesFor(["miraveloLeasing"], {
+      enginesByKey: { miraveloLeasing: ["prod-b"] },
+      engines: ["prod-a"],
+    })
+    expect(processNameOf(index, "miraveloLeasing")).toBe("Bike Leasing")
+    expect(processNameOf(await namesFor(["other"]), "other")).toBe("Other")
+    expect(fetchBpmnXml.mock.calls).toEqual([
+      ["miraveloLeasing", "prod-b"],
+      ["other", undefined],
+    ])
+  })
+
+  it("takes an empty engine list as none: the view's engines, else the default engine", async () => {
+    const fetchBpmnXml = fleet({ "prod-a": { miraveloLeasing: LEASING } })
+    const namesFor = createNameLookup(fetchBpmnXml)
+    const index = await namesFor(["miraveloLeasing"], {
+      enginesByKey: { miraveloLeasing: [] },
+      engines: ["prod-a"],
+    })
+    expect(processNameOf(index, "miraveloLeasing")).toBe("Bike Leasing")
+    expect(await namesFor(["other"], { engines: [] })).toEqual({})
+    expect(fetchBpmnXml.mock.calls).toEqual([
+      ["miraveloLeasing", "prod-a"],
+      ["other", undefined],
+    ])
+  })
+
+  it("keeps each engine's answer apart", async () => {
+    const fetchBpmnXml = fleet({ "prod-b": { miraveloLeasing: LEASING } })
+    const namesFor = createNameLookup(fetchBpmnXml)
+    // Not on prod-a: kept as "no such model" there, and prod-b still asked.
+    expect(await namesFor(["miraveloLeasing"], { engines: ["prod-a"] })).toEqual({})
+    const index = await namesFor(["miraveloLeasing"], { engines: ["prod-a", "prod-b"] })
+    expect(processNameOf(index, "miraveloLeasing")).toBe("Bike Leasing")
+    expect(fetchBpmnXml.mock.calls.map((c) => c[1])).toEqual(["prod-a", "prod-b"])
+  })
+
+  it("stops at the view's time budget, not one budget per engine", async () => {
+    vi.useFakeTimers()
+    const fetchBpmnXml = vi.fn<FetchBpmnXml>((_key, engine) =>
+      engine === "prod-a" ? new Promise(() => {}) : Promise.resolve(LEASING),
+    )
+    const pending = createNameLookup(fetchBpmnXml, { timeoutMs: 50 })(["miraveloLeasing"], {
+      engines: ["prod-a", "prod-b"],
+    })
+    await vi.advanceTimersByTimeAsync(50)
+    expect(await pending).toEqual({})
+    expect(fetchBpmnXml.mock.calls.map((c) => c[1])).toEqual(["prod-a"])
+    expect(vi.getTimerCount()).toBe(0)
+  })
+})
+
+/**
+ * With passthrough auth the engine answers each caller with that caller's
+ * own permissions (#322 review): a model one caller may read never reaches
+ * another through the cache, and one caller's refusal never hides the names
+ * from the others.
+ */
+describe("createNameLookup per caller", () => {
+  const ALICE = { authUserId: "alice", authorization: "Bearer token-alice" }
+  const BOB = { authUserId: "bob", authorization: "Bearer token-bob" }
+
+  /** A passthrough engine: only Alice's token may read the model. */
+  const passthrough = () =>
+    vi.fn<FetchBpmnXml>(() =>
+      Promise.resolve(getMcpRequestInfo()?.authorization === ALICE.authorization ? LEASING : null),
+    )
+
+  it("never hands one caller's names to another", async () => {
+    const fetchBpmnXml = passthrough()
+    const namesFor = createNameLookup(fetchBpmnXml)
+    const alice = await runWithMcpRequestInfo(ALICE, () => namesFor(["miraveloLeasing"]))
+    expect(processNameOf(alice, "miraveloLeasing")).toBe("Bike Leasing")
+    const bob = await runWithMcpRequestInfo(BOB, () => namesFor(["miraveloLeasing"]))
+    expect(bob).toEqual({})
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(2)
+  })
+
+  it("never hides the names from a caller because another was refused", async () => {
+    const fetchBpmnXml = passthrough()
+    const namesFor = createNameLookup(fetchBpmnXml)
+    expect(await runWithMcpRequestInfo(BOB, () => namesFor(["miraveloLeasing"]))).toEqual({})
+    // A request without a token is a caller of its own too.
+    expect(await namesFor(["miraveloLeasing"])).toEqual({})
+    const alice = await runWithMcpRequestInfo(ALICE, () => namesFor(["miraveloLeasing"]))
+    expect(processNameOf(alice, "miraveloLeasing")).toBe("Bike Leasing")
+    // Each caller's own answer is still kept.
+    await runWithMcpRequestInfo(ALICE, () => namesFor(["miraveloLeasing"]))
+    await runWithMcpRequestInfo(BOB, () => namesFor(["miraveloLeasing"]))
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(3)
+  })
+
+  it("takes the partition from the injected caller when one is given", async () => {
+    let caller = "a"
+    const fetchBpmnXml = vi.fn<FetchBpmnXml>(() => Promise.resolve(LEASING))
+    const namesFor = createNameLookup(fetchBpmnXml, { caller: () => caller })
+    await namesFor(["miraveloLeasing"])
+    await namesFor(["miraveloLeasing"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(1)
+    caller = "b"
+    await namesFor(["miraveloLeasing"])
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(2)
+  })
+})

package/src/bpmn-name-lookup.ts

@@ -0,0 +1,197 @@
+import { callerCacheKey, parseBpmnNames } from "@miragon/pulse-widget-shell/server"
+import type { NameIndex, ProcessNames } from "./bpmn-names.js"
+
+/**
+ * Engine-agnostic BPMN-XML lookup injected by the host app (which owns the
+ * engine clients) — this module never talks to an engine itself. Resolves the
+ * diagram XML of a process definition key's latest deployed version on the
+ * engine `engineId` names (omitted: the host's default engine). `null` is an
+ * answer: that engine has no such definition. A read that failed
+ * (unreachable, refused, timed out) REJECTS, so a consumer tells "not there"
+ * from "not now" and never remembers a failure as an answer.
+ */
+export type FetchBpmnXml = (
+  processDefinitionKey: string,
+  engineId?: string,
+) => Promise<string | null>
+
+/** What one view asks the lookup for, besides its keys. */
+export interface NameRequest {
+  /** Per key, the elements whose names the view shows; a key left out gets every named element. */
+  elementIds?: Readonly<Record<string, readonly string[]>>
+  /**
+   * Per key, the engines it runs on, in the order to read them (the
+   * landscape knows them per process). Preferred over {@link NameRequest.engines}.
+   */
+  enginesByKey?: Readonly<Record<string, readonly string[]>>
+  /**
+   * The view's engines, in the order to read them, for a key without a list
+   * of its own: the first whose model has the key names it. None: the host's
+   * default engine.
+   */
+  engines?: readonly string[] | null
+}
+
+/**
+ * Names for the process keys of one view: a {@link NameIndex} holding the keys
+ * whose model could be read on one of their engines, each with the elements
+ * the request asks for.
+ */
+export type NameLookup = (keys: Iterable<string>, request?: NameRequest) => Promise<NameIndex>
+
+/** A lookup that knows no names: what a server without the camunda7 module has. */
+export const NO_NAMES: NameLookup = () => Promise.resolve({})
+
+export interface NameLookupOptions {
+  /**
+   * How long one view waits for its names (ms), over every key and engine.
+   * Names are enrichment: a slow engine must not hold up the figures. A read
+   * still running then finishes for the next view.
+   */
+  timeoutMs?: number
+  /** How long an engine's answer is reused (ms): diagrams change with a deployment, not per call. */
+  ttlMs?: number
+  /** The most keys one view looks up, in the order it names them; the rest show their ids. */
+  maxKeys?: number
+  /** The most answers kept; the oldest go first. */
+  maxEntries?: number
+  /**
+   * Whose engine permissions a read runs under: the partition of the cache,
+   * so one caller's answer never serves another. Default: the request's
+   * caller and credential (`callerCacheKey`, widget-shell). With passthrough
+   * auth every engine read carries the caller's own token and the engine
+   * answers with THAT caller's permissions: a model one caller may read must
+   * never reach another through the cache, and a caller the engine refused
+   * must not hide the names from everyone else.
+   */
+  caller?: () => string
+  /** Clock, for tests. */
+  now?: () => number
+}
+
+const DEFAULT_TIMEOUT_MS = 2_000
+const DEFAULT_TTL_MS = 5 * 60_000
+const DEFAULT_MAX_KEYS = 40
+const DEFAULT_MAX_ENTRIES = 2_000
+
+/** One engine's answer: the names, `null` for "no such model", `undefined` for a failed read. */
+type Answer = ProcessNames | null | undefined
+
+/**
+ * The view's name lookup over the injected BPMN lookup, or {@link NO_NAMES}
+ * without one. Reads a key's model on its engines in order until one has it.
+ * Each engine's answer is kept per caller for `ttlMs` (a "no such model"
+ * too: a key an engine does not know stays unknown there that long); a failed
+ * read is not kept, so the next view asks again. Never waits longer than
+ * `timeoutMs` and never fails: a key without an answer is left out, and the
+ * view shows its id.
+ */
+export function createNameLookup(
+  fetchBpmnXml: FetchBpmnXml | undefined,
+  options: NameLookupOptions = {},
+): NameLookup {
+  if (!fetchBpmnXml) return NO_NAMES
+  const fetchXml = fetchBpmnXml
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+  const maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES
+  const now = options.now ?? Date.now
+  const callerOf = options.caller ?? callerCacheKey
+  /** (caller, engine, key) → that engine's answer for that caller, oldest first. */
+  const cache = new Map<string, { at: number; names: ProcessNames | null }>()
+
+  function remember(id: string, names: ProcessNames | null): void {
+    // Re-inserted at the end, so the map stays oldest first.
+    cache.delete(id)
+    cache.set(id, { at: now(), names })
+    for (const oldest of cache.keys()) {
+      if (cache.size <= maxEntries) break
+      cache.delete(oldest)
+    }
+  }
+
+  function readOn(caller: string, engine: string | undefined, key: string): Promise<Answer> {
+    const id = JSON.stringify([caller, engine ?? null, key])
+    const hit = cache.get(id)
+    if (hit && now() - hit.at < ttlMs) return Promise.resolve(hit.names)
+    return Promise.resolve()
+      .then(() => fetchXml(key, engine))
+      .then(
+        (xml) => {
+          const names = xml ? parseBpmnNames(xml, key) : null
+          remember(id, names)
+          return names
+        },
+        // A failed read is no answer: not kept, the next view asks again.
+        () => undefined,
+      )
+  }
+
+  return async (keys, request = {}) => {
+    const caller = callerOf()
+    const unique = [...new Set(keys)].filter((key) => key.length > 0).slice(0, maxKeys)
+    const deadline = startDeadline(timeoutMs)
+
+    async function namesOf(key: string): Promise<ProcessNames | null> {
+      for (const engine of enginesFor(key, request)) {
+        const names = await Promise.race([readOn(caller, engine, key), deadline.passed])
+        if (names) return names
+        if (deadline.expired()) break
+      }
+      return null
+    }
+
+    try {
+      const reads = await Promise.all(unique.map(async (key) => [key, await namesOf(key)] as const))
+      const index: NameIndex = {}
+      for (const [key, names] of reads) {
+        if (!names) continue
+        const wanted = own(request.elementIds, key)
+        index[key] = {
+          name: names.name,
+          elements: wanted ? pick(names.elements, wanted) : names.elements,
+        }
+      }
+      return index
+    } finally {
+      deadline.clear()
+    }
+  }
+}
+
+/** `record[key]` when the record itself holds it: a key such as `constructor` is no inherited lookup. */
+function own<T>(record: Readonly<Record<string, T>> | undefined, key: string): T | undefined {
+  return record && Object.hasOwn(record, key) ? record[key] : undefined
+}
+
+/** The engines to read `key`'s model on, in order: its own, else the view's, else the default engine. */
+function enginesFor(key: string, request: NameRequest): ReadonlyArray<string | undefined> {
+  const mine = own(request.enginesByKey, key)
+  if (mine && mine.length > 0) return mine
+  if (request.engines && request.engines.length > 0) return request.engines
+  return [undefined]
+}
+
+/** The entries of `elements` named in `ids` (what the view shows, nothing else). */
+function pick(elements: Record<string, string>, ids: readonly string[]): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const id of ids) if (Object.hasOwn(elements, id)) out[id] = elements[id]
+  return out
+}
+
+/**
+ * One view's time budget: `passed` resolves `undefined` once `ms` passed, and
+ * `clear` stops the timer, so a fast view leaves nothing pending.
+ */
+function startDeadline(ms: number) {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let expired = false
+  const passed = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => {
+      expired = true
+      resolve(undefined)
+    }, ms)
+  })
+  return { passed, expired: () => expired, clear: () => clearTimeout(timer) }
+}

package/src/bpmn-names.ts

@@ -0,0 +1,51 @@
+/**
+ * The names a BPMN model gives its process and elements, for views that would
+ * otherwise show bare ids (U13). Metrics carry ids only by contract (the
+ * labels are model-bounded); the names come from the diagram the server
+ * reads through the injected BPMN lookup (`bpmn-name-lookup.ts`) and travel in
+ * a view's payload as a {@link NameIndex}. Shared by the server and the widget
+ * bundle, so it holds types and pure helpers only.
+ */
+
+/**
+ * The names one model gives: its process and the elements that have one.
+ * The shape of the kit's `BpmnNames` (`parseBpmnNames`, widget-shell
+ * `/server`), the one rule camunda7 names the same model by.
+ */
+export interface ProcessNames {
+  /** The process's own name in its model (or its pool's); null when it has none. */
+  name: string | null
+  /** Element id → name, only for elements that carry a name. */
+  elements: Record<string, string>
+}
+
+/**
+ * Names per process definition key. A key is absent when its model could not
+ * be read (no camunda7 module, the engine was unreachable, not deployed on the
+ * engine the lookup reads): the view then shows the id, never a guess.
+ */
+export type NameIndex = Record<string, ProcessNames>
+
+/**
+ * A view payload with the names of the processes (and, for the activity
+ * breakdown, the elements) it lists. `names` is absent where no lookup ran
+ * (a payload built by a plain query call): the view shows ids.
+ */
+export type Named<T> = T & { names?: NameIndex }
+
+/** The process name for `key`, or null when the index does not know one. */
+export function processNameOf(names: NameIndex | undefined, key: string): string | null {
+  if (!names || !Object.hasOwn(names, key)) return null
+  return names[key].name
+}
+
+/** The name of element `id` in the model of `key`, or null when the index does not know one. */
+export function elementNameOf(
+  names: NameIndex | undefined,
+  key: string,
+  id: string,
+): string | null {
+  if (!names || !Object.hasOwn(names, key)) return null
+  const elements = names[key].elements
+  return Object.hasOwn(elements, id) ? elements[id] : null
+}