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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragon GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,88 @@
 # @miragon/pulse-analytics-connector
 
-Placeholder that sets up npm trusted publishing for @miragon/pulse-analytics-connector. The first real
-release is 0.21.0, published from [Miragon/pulse](https://github.com/Miragon/pulse) by
-GitHub Actions. Do not install this version.
+The **analytics module** for [Pulse](../../../../README.md): Prometheus-backed process analytics as
+`analytics_*` MCP tools, plus dashboard and comparison widgets. Built on
+[`@miragon/pulse-analytics-client`](../analytics-client) and the `@miragon/mcp-toolkit-*` packages.
+
+The server loads this module as `analytics` via `analyticsModule` (`src/module.ts`), which conforms
+structurally to the app's `ModuleDefinition` port. The package is published to npm in lockstep with
+the other `@miragon/pulse-*` packages (pin them all to one version); the
+[pulse-starter](https://github.com/Miragon/pulse-starter) template shows how to compose it
+into your own MCP server.
+
+The consumer-shared libraries are ranged **peer dependencies** so they dedupe against your app's
+copy: `react`/`react-dom` `^19.2.0`, `zod` `^4.4.0`, `@miragon/mcp-toolkit-*` `~2.8.1`,
+`lucide-react` `^0.562.0 || ^1.0.0` (the widgets' icons; add it to your `dedupe` list like the
+widget-shell kit asks, and pin 1.47.0 or newer: the toolkit's chrome (2.7 and later) imports `LucideProvider`,
+which 0.x lacks, so a deduped 0.x copy fails the bundle build). **`mcp-use` is exactly pinned**:
+pin it to `mcp-use@2.7.3` in your app. A duplicate `mcp-use` instance breaks the React context and
+hangs every in-widget query on "Loading…".
+
+## What it provides
+
+- **Analytics tools** (`src/tools/`): `analyze_process_performance`, `compare_execution_periods`,
+  `element_bottleneck`, `find_failed_instances`, `cluster_compare`, `version_compare`,
+  `engine_landscape`, `engine_compare`, and `engine_health` (a live WIP / incidents / backlog /
+  alerts snapshot). All carry the `analytics` category and run PromQL through
+  [`@miragon/pulse-analytics-client`](../analytics-client).
+- **Widgets** (`src/widgets/`): `show_dashboard`, `show_failure_dashboard`, `show_cluster_compare`,
+  `show_version_compare`, `show_engine_landscape`, `show_engine_compare`, `show_bpmn_heatmap`.
+- **Configured engines only:** analytics reads exactly the server's configured engine ids:
+  `createPlugin({ engineIds })` (a composed server injects camunda7's engines through
+  `analyticsModule`'s shared `engineIds`), else `ANALYTICS_ENGINE_IDS` for a standalone boot.
+  Without either, every analytics tool refuses (fail-closed) instead of reading every `engine_id`
+  a shared Prometheus holds. Every tool takes an optional `engine` filter (one configured id or a
+  list); omitted, it covers all configured engines and the result's `engines` names them; any
+  other id is refused. Analytics are session-independent.
+- **Toolsets** (`src/toolsets.ts`, declared as the module's `toolsets` vocabulary): `read-only`
+  (every analytics tool and widget, no settings save) and `standard` (adds
+  `analytics_save_settings`). With no `analytics:<toolset>` suffix the module runs `read-only` on an
+  unauthenticated server and `standard` under OAuth; an empty or unknown suffix falls back to
+  `read-only`.
+
+### Cross-engine: overview, not scoreboard
+
+Engines host different process definitions, so a failure rate, incident rate or duration aggregated
+per engine describes that engine's **process mix**, not the engine. The same aggregation can even
+invert the per-process truth. Two consequences run through the module:
+
+- `engine_landscape` is the cross-engine view. It reports the process × engine inventory, absolute
+  counts (running instances, open incidents, failed jobs) and the engine-owned job backlog
+  (`jobs_executable`, `jobs_suspended`, `jobs_due_future`, `external_tasks_open`), the one metric
+  family whose contract labels are `engine_id` only, so no process mix can confound it. It covers
+  every configured engine, so one that reports nothing still gets a row (`reporting: false`).
+- `engine_compare` **requires** a `processDefinitionKey`. Holding the process fixed on both sides is
+  what makes a delta attributable to the engine; `engine_landscape.sharedProcessKeys` lists the
+  definitions that qualify.
+
+These tools read the `camunda_*` series emitted by the
+[engine metrics plugin](../../../../engine-plugins). Per-instance drill-down (search by variable) is **not**
+metric-backed: use the `camunda7_query_historic_*` tools in the [camunda7 module](../../camunda/camunda7-connector).
+
+The BPMN heatmap gets its diagram XML via an injected `fetchBpmnXml` shared resource (wired by the
+host app from the camunda7 module), and the dashboards, the failure dashboard and the landscape read
+the process and activity names behind their ids through the same lookup (`bpmn-name-lookup.ts`).
+This package has **no** engine-SDK dependency: the heatmap
+degrades gracefully without it and the views show ids. `fetchBpmnXml(key, engineId?)` reads on the
+named engine (the default one without), resolves `null` for a key not deployed there and rejects a
+failed read; the views ask the engines their rows come from, and the names are cached per caller
+(under passthrough auth the engine answers with each caller's own permissions).
+
+## Adding an analytics capability
+
+Read the [`add-analytics-feature`](../../../../.claude/skills/add-analytics-feature) skill first. The house
+pattern: add a PromQL query function in [`@miragon/pulse-analytics-client`](../analytics-client) (using
+`METRIC_NAMES`, never raw metric strings), then a tool here, then optionally a widget. Metric names
+and labels are governed by the
+[metrics contract](../analytics-client/metrics-contract.json). Change it there first.
+
+## Layout
+
+| Path                  | Contents                                                    |
+| --------------------- | ----------------------------------------------------------- |
+| `src/tools/`          | Analytics tools (`index.ts` wires them)                     |
+| `src/widget-tools.ts` | `show_*` dashboard/comparison widget tools                  |
+| `src/widgets/`        | React dashboard + comparison widgets                        |
+| `src/definition.ts`   | Widget metadata                                             |
+| `src/module.ts`       | `analyticsModule` (env mapping, `PROMETHEUS_URL` boot hint) |
+| `src/steps/`          | Pipeline steps contributed to the server                    |

package/dist/bpmn-name-lookup.d.ts

@@ -0,0 +1,72 @@
+import type { NameIndex } 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 declare const NO_NAMES: NameLookup;
+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;
+}
+/**
+ * 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 declare function createNameLookup(fetchBpmnXml: FetchBpmnXml | undefined, options?: NameLookupOptions): NameLookup;
+//# sourceMappingURL=bpmn-name-lookup.d.ts.map

package/dist/bpmn-name-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bpmn-name-lookup.d.ts","sourceRoot":"","sources":["../src/bpmn-name-lookup.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAA;AAE9D;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,oBAAoB,EAAE,MAAM,EAC5B,QAAQ,CAAC,EAAE,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;AAE3B,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,iGAAiG;IACjG,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IACxD;;;OAGG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IAC1D;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS,CAAC,CAAA;AAE9F,mFAAmF;AACnF,eAAO,MAAM,QAAQ,EAAE,UAAsC,CAAA;AAE7D,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mGAAmG;IACnG,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;IACrB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAUD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CAqEZ"}

package/dist/bpmn-name-lookup.js

@@ -0,0 +1,123 @@
+import { callerCacheKey, parseBpmnNames } from "@miragon/pulse-widget-shell/server";
+/** A lookup that knows no names: what a server without the camunda7 module has. */
+export const NO_NAMES = () => Promise.resolve({});
+const DEFAULT_TIMEOUT_MS = 2_000;
+const DEFAULT_TTL_MS = 5 * 60_000;
+const DEFAULT_MAX_KEYS = 40;
+const DEFAULT_MAX_ENTRIES = 2_000;
+/**
+ * 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, options = {}) {
+    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();
+    function remember(id, names) {
+        // 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, engine, key) {
+        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) {
+            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)]));
+            const index = {};
+            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(record, key) {
+    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, request) {
+    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, ids) {
+    const out = {};
+    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) {
+    let timer;
+    let expired = false;
+    const passed = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            expired = true;
+            resolve(undefined);
+        }, ms);
+    });
+    return { passed, expired: () => expired, clear: () => clearTimeout(timer) };
+}
+//# sourceMappingURL=bpmn-name-lookup.js.map

package/dist/bpmn-name-lookup.js.map

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

package/dist/bpmn-name-lookup.test.d.ts

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

package/dist/bpmn-name-lookup.test.d.ts.map

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

package/dist/bpmn-name-lookup.test.js

@@ -0,0 +1,287 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getMcpRequestInfo, runWithMcpRequestInfo } from "@miragon/pulse-widget-shell/server";
+import { NO_NAMES, createNameLookup } 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) => 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) => 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) => key === "slow"
+            ? new Promise(() => { })
+            : 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) => 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(() => 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 = () => { };
+        const fetchBpmnXml = vi.fn(() => new Promise((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(() => 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(() => 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(() => 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(() => 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, down = []) {
+        return vi.fn((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((_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(() => 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(() => 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);
+    });
+});
+//# sourceMappingURL=bpmn-name-lookup.test.js.map