@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/tools/registry-names.js

@@ -0,0 +1,54 @@
+/**
+ * Canonical list of MCP tool names exposed by createMcpServer().
+ *
+ * Used by:
+ *   - the Product validator (typo guard): a Product's `tools` allow-
+ *     list must reference names that actually register, otherwise a
+ *     bound credential opens an /mcp session with an empty tool set
+ *     and the agent silently fails.
+ *   - the keystone integration test in registry-names.test.ts that
+ *     reads index.ts and asserts the registerTool() call sites match
+ *     this list 1:1 — a missing entry or an extra one trips the test.
+ *
+ * Keep this list and the registerTool("name", ...) calls in
+ * createMcpServer in sync. The test enforces it.
+ */
+export const REGISTERED_TOOL_NAMES = [
+    "list_sources",
+    "list_services",
+    "query_metrics",
+    "query_logs",
+    "query_traces",
+    "get_service_health",
+    "detect_anomalies",
+    "get_anomaly_history",
+    "generate_postmortem",
+    "get_topology",
+    "get_blast_radius",
+];
+export const REGISTERED_TOOLS = [
+    { name: "list_sources", category: "discovery", summary: "List configured observability backends + reachability." },
+    { name: "list_services", category: "discovery", summary: "Discover service names across every connected backend." },
+    { name: "query_metrics", category: "query", summary: "Fetch the raw time-series for one metric of one service over a window." },
+    { name: "query_logs", category: "query", summary: "Fetch matching log lines for one service over a window." },
+    { name: "query_traces", category: "query", summary: "Fetch ranked trace summaries for one service over a window." },
+    { name: "get_service_health", category: "diagnose", summary: "Aggregated health verdict for one service (metrics + logs)." },
+    { name: "detect_anomalies", category: "diagnose", summary: "Scan for anomalous services using z-score / heuristics." },
+    { name: "get_anomaly_history", category: "diagnose", summary: "Replay historical anomaly scores for a service (post-mortem context)." },
+    { name: "generate_postmortem", category: "diagnose", summary: "One-shot markdown post-mortem stitching anomaly history + traces + blast-radius + logs for a service." },
+    { name: "get_topology", category: "topology", summary: "Return the infrastructure topology graph (resources + edges)." },
+    { name: "get_blast_radius", category: "topology", summary: "Given a resource, return the impact set if its host(s) fail." },
+];
+/** Validate a candidate Product tools[] array. Returns the unknown
+ *  names (empty array = all OK). Pure helper — the caller decides
+ *  how to surface the rejection (the API handler emits a 422 with a
+ *  hint of valid names; the YAML loader could decide to warn). */
+export function unknownToolNames(tools) {
+    const known = new Set(REGISTERED_TOOL_NAMES);
+    const out = [];
+    for (const t of tools) {
+        if (!known.has(t))
+            out.push(t);
+    }
+    return out;
+}

package/dist/tools/registry-names.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/registry-names.test.js

@@ -0,0 +1,61 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { REGISTERED_TOOL_NAMES, REGISTERED_TOOLS, unknownToolNames } from "./registry-names.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = join(here, "..", "index.ts");
+test("REGISTERED_TOOL_NAMES — 1:1 with createMcpServer's registerTool() calls", () => {
+    // This is the integration-test-shaped guard: if a future PR adds
+    // or removes a tool registration in index.ts without updating
+    // REGISTERED_TOOL_NAMES, the Product validator will silently
+    // accept or reject the wrong names. We parse index.ts as text and
+    // assert the registered set matches the constant exactly.
+    const src = readFileSync(INDEX_TS, "utf8");
+    // registerTool("name", → captures the first argument of every call site.
+    const re = /\bregisterTool\(\s*"([a-z_][a-z0-9_]*)"/g;
+    const found = [];
+    for (const m of src.matchAll(re))
+        found.push(m[1]);
+    found.sort();
+    const expected = [...REGISTERED_TOOL_NAMES].sort();
+    assert.deepEqual(found, expected, `registerTool() call sites in index.ts don't match REGISTERED_TOOL_NAMES. ` +
+        `Add or remove names in src/tools/registry-names.ts to match the actual ` +
+        `registrations.\n  found: ${JSON.stringify(found)}\n  expected: ${JSON.stringify(expected)}`);
+});
+test("unknownToolNames — empty input → no unknowns", () => {
+    assert.deepEqual(unknownToolNames([]), []);
+});
+test("unknownToolNames — every registered name is accepted", () => {
+    assert.deepEqual(unknownToolNames([...REGISTERED_TOOL_NAMES]), []);
+});
+test("unknownToolNames — surfaces typos and unknown names verbatim", () => {
+    const r = unknownToolNames(["list_sources", "query_logz", "get_topologyy"]);
+    assert.deepEqual(r, ["query_logz", "get_topologyy"]);
+});
+test("unknownToolNames — case-sensitive (MCP spec)", () => {
+    // The spec requires exact name match; "List_Sources" is not the
+    // same tool as "list_sources" and silently accepting it would be a
+    // worse failure mode than rejecting (mismatched casing wouldn't
+    // route to a real tool).
+    assert.deepEqual(unknownToolNames(["List_Sources"]), ["List_Sources"]);
+});
+test("REGISTERED_TOOLS — every name has a category + summary", () => {
+    for (const t of REGISTERED_TOOLS) {
+        assert.ok(t.name, "name required");
+        assert.ok(t.category, `category required on ${t.name}`);
+        assert.ok(t.summary && t.summary.length > 10, `summary required on ${t.name}`);
+    }
+});
+test("REGISTERED_TOOLS — matches REGISTERED_TOOL_NAMES 1:1 (no drift)", () => {
+    const a = REGISTERED_TOOLS.map((t) => t.name).sort();
+    const b = [...REGISTERED_TOOL_NAMES].sort();
+    assert.deepEqual(a, b, "REGISTERED_TOOLS and REGISTERED_TOOL_NAMES must agree");
+});
+test("REGISTERED_TOOLS — every category is one of the four valid values", () => {
+    const valid = new Set(["discovery", "query", "diagnose", "topology"]);
+    for (const t of REGISTERED_TOOLS) {
+        assert.ok(valid.has(t.category), `unknown category '${t.category}' on ${t.name}`);
+    }
+});

package/dist/tools/topology.d.ts

@@ -12,7 +12,7 @@ interface AggregatedTopology {
     resources: Resource[];
     edges: Edge[];
 }
-export declare function aggregateTopology(registry: ConnectorRegistry): Promise<AggregatedTopology>;
+export declare function aggregateTopology(registry: ConnectorRegistry, tenant?: string): Promise<AggregatedTopology>;
 /**
  * Resolve a caller-supplied identifier to a Resource. Accepts:
  *   - exact canonical id (e.g. "k8s:pod:default/checkout-7f89d")
@@ -35,7 +35,7 @@ export interface GetTopologyArgs {
     scope?: string;
     limit?: number;
 }
-export declare function getTopologyHandler(registry: ConnectorRegistry, args?: GetTopologyArgs, _ctx?: RequestContext): Promise<{
+export declare function getTopologyHandler(registry: ConnectorRegistry, args?: GetTopologyArgs, ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;
@@ -48,7 +48,7 @@ export declare const getBlastRadiusDefinition: {
 export interface GetBlastRadiusArgs {
     resource: string;
 }
-export declare function getBlastRadiusHandler(registry: ConnectorRegistry, args: GetBlastRadiusArgs, _ctx?: RequestContext): Promise<{
+export declare function getBlastRadiusHandler(registry: ConnectorRegistry, args: GetBlastRadiusArgs, ctx?: RequestContext): Promise<{
     isError: boolean;
     content: {
         type: "text";

package/dist/tools/topology.js

@@ -14,11 +14,15 @@
 // connector later requires zero changes here.
 import { isTopologyProvider } from "../connectors/interface.js";
 import { defaultContext } from "../context.js";
-export async function aggregateTopology(registry) {
+import { mergeTopologies } from "../topology/merge.js";
+export async function aggregateTopology(registry, tenant) {
     const sources = [];
-    const resources = [];
-    const edges = [];
-    for (const c of registry.getAll()) {
+    const snapshots = [];
+    // Tenant-scoped when a tenant is supplied (call sites at the MCP
+    // tool layer pass ctx.tenant); undefined preserves the original
+    // global behaviour for internal / non-request callers.
+    const connectors = tenant ? registry.getByTenant(tenant) : registry.getAll();
+    for (const c of connectors) {
         if (!isTopologyProvider(c))
             continue;
         try {
@@ -30,14 +34,32 @@ export async function aggregateTopology(registry) {
                 resources: snap.resources.length,
                 edges: snap.edges.length,
             });
-            resources.push(...snap.resources);
-            edges.push(...snap.edges);
+            snapshots.push(snap);
         }
         catch {
             // A misbehaving connector must not poison the agent's view of the graph.
         }
     }
-    return { sources, resources, edges };
+    // P1: run the snapshots through mergeTopologies so workloads
+    // surfaced by more than one provider (e.g. the same Deployment
+    // observed by both Kubernetes + a service-mesh connector) collapse
+    // into a single canonical node and edges are rewritten to match.
+    //
+    // ONLY engages for multi-source topologies — with a single snapshot
+    // the merger would mis-group intra-source siblings that happen to
+    // share a canonical label (e.g. two pod replicas with
+    // `app.kubernetes.io/name=api`). The merger is designed for
+    // cross-provider de-duplication, not intra-provider.
+    if (snapshots.length <= 1) {
+        const only = snapshots[0];
+        return {
+            sources,
+            resources: only?.resources ?? [],
+            edges: only?.edges ?? [],
+        };
+    }
+    const merged = mergeTopologies(snapshots);
+    return { sources, resources: merged.resources, edges: merged.edges };
 }
 /**
  * Resolve a caller-supplied identifier to a Resource. Accepts:
@@ -79,8 +101,8 @@ export const getTopologyDefinition = {
     name: "get_topology",
     description: "Return the infrastructure topology graph as Resources and Edges. Use this when an agent needs to reason about which workload runs where, who owns whom, or which scope (namespace/project/folder) a resource belongs to.",
 };
-export async function getTopologyHandler(registry, args = {}, _ctx = defaultContext()) {
-    const agg = await aggregateTopology(registry);
+export async function getTopologyHandler(registry, args = {}, ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry, ctx.tenant);
     // Filtering — all optional. Filters compose conjunctively.
     let resources = agg.resources;
     let edges = agg.edges;
@@ -133,8 +155,8 @@ export const getBlastRadiusDefinition = {
     name: "get_blast_radius",
     description: "Given a resource, return the impact set if its underlying host(s) fail. Pivots on the generic RUNS_ON relation, so it works for pod→node, vm→hypervisor, container→host alike. Use this for cross-cutting RCA when several services degrade together.",
 };
-export async function getBlastRadiusHandler(registry, args, _ctx = defaultContext()) {
-    const agg = await aggregateTopology(registry);
+export async function getBlastRadiusHandler(registry, args, ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry, ctx.tenant);
     const found = resolveResource(args.resource, agg.resources);
     if ("error" in found) {
         return {

package/dist/tools/topology.test.js

@@ -208,3 +208,48 @@ describe("get_blast_radius tool", () => {
         assert.equal(apiBucket.ownershipRootKind, "deployment");
     });
 });
+// --- Multi-source merge (Phase P1 wiring) ----------------------------
+// `aggregateTopology` now delegates to `mergeTopologies` when 2+
+// snapshots are present so the same logical workload reported by
+// e.g. Kubernetes + a cloud connector collapses into one node.
+// Single-snapshot calls pass through unchanged (guarded so we don't
+// mis-merge intra-source siblings that share an `app:` label).
+describe("aggregateTopology — multi-source merger (P1 wire)", () => {
+    it("collapses cross-source duplicates that share a canonical label", async () => {
+        // Source A (k8s): one Deployment "checkout" in prod
+        const aRes = [
+            { id: "k8s:deployment:prod/checkout", kind: "deployment", name: "checkout", source: "k8s",
+                labels: { "app.kubernetes.io/name": "checkout" } },
+        ];
+        // Source B (trace provider): the same logical service
+        const bRes = [
+            { id: "tempo:service:checkout", kind: "trace_service", name: "checkout", source: "tempo",
+                labels: { "service.name": "checkout" } },
+        ];
+        const loader = new PluginLoader();
+        const reg = new ConnectorRegistry(loader);
+        const connA = new FakeTopologyConnector(aRes, []);
+        const connB = new FakeTopologyConnector(bRes, []);
+        await connA.connect({ name: "k8s", type: "fake", url: "", enabled: true });
+        await connB.connect({ name: "tempo", type: "fake", url: "", enabled: true });
+        const loaderInternal = loader;
+        loaderInternal.connectors.set("fake-a", { name: "fake-a", source: "builtin", factory: () => connA });
+        loaderInternal.connectors.set("fake-b", { name: "fake-b", source: "builtin", factory: () => connB });
+        await reg.addSource({ name: "k8s", type: "fake-a", url: "", enabled: true });
+        await reg.addSource({ name: "tempo", type: "fake-b", url: "", enabled: true });
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        // 2 sources reported in summary
+        assert.equal(out.sources.length, 2);
+        // But ONE resource after merge (deployment + trace_service of the
+        // same canonical name collapse via MERGEABLE_KIND_PAIRS).
+        assert.equal(out.resources.length, 1);
+        assert.equal(out.resources[0].name, "checkout");
+    });
+    it("single-source passes through unchanged (no intra-source merging)", async () => {
+        // The existing 4-pod fixture has two pods sharing `app: api`.
+        // With a single snapshot the merger must NOT collapse them.
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        assert.equal(out.resources.length, fixture().resources.length);
+    });
+});

package/dist/topology/merge.d.ts

@@ -0,0 +1,22 @@
+import type { Resource, Edge, TopologySnapshot } from "../types.js";
+/** Labels we treat as canonical-name carriers. First-match wins. */
+export declare const CANONICAL_LABEL_KEYS: readonly ["app.kubernetes.io/name", "app.kubernetes.io/instance", "app", "service", "service.name", "k8s-app"];
+/** Lower-cased label-key lookup; first match in CANONICAL_LABEL_KEYS
+ *  ordering wins so two providers with different label conventions
+ *  still converge if they both ship a known label. */
+export declare function canonicalNameFor(r: Resource): string | undefined;
+export interface MergeResult {
+    resources: Resource[];
+    edges: Edge[];
+    /** Map from original (source-scoped) id → merged canonical id. Used
+     *  to rewrite edges that referenced one of the collapsed nodes. */
+    idMap: Map<string, string>;
+}
+/**
+ * Merge a set of provider snapshots into one unified graph. The
+ * input is the flat union of every provider's resources+edges; the
+ * output collapses every group of nodes that share a canonical name
+ * (and a compatible kind) into a single node, then rewrites the
+ * edge endpoints accordingly.
+ */
+export declare function mergeTopologies(snapshots: TopologySnapshot[]): MergeResult;

package/dist/topology/merge.js

@@ -0,0 +1,178 @@
+// Topology merger — collapses Resources/Edges that come from
+// multiple providers into a single deduped graph.
+//
+// The default unified-view is the union of every provider's
+// snapshot, with no dedup. That's fine for unrelated providers
+// (k8s + AWS in different accounts) but breaks down once two
+// providers describe the same logical service (k8s `payment`
+// Deployment + ECS `payment-service` + Tempo `trace_service`
+// `payment`). Without a merger, get_blast_radius walks them as
+// three independent nodes and the LLM sees ghost relationships
+// instead of one real chain.
+//
+// Reconciliation rules, in priority order:
+//   1. Explicit override via attributes.canonicalName
+//   2. Match on any CANONICAL_LABEL_KEYS entry (case-insensitive)
+//   3. Name + kind-compatibility table
+//
+// See docs/topology-vocabulary.md for the rationale.
+/** Labels we treat as canonical-name carriers. First-match wins. */
+export const CANONICAL_LABEL_KEYS = [
+    "app.kubernetes.io/name",
+    "app.kubernetes.io/instance",
+    "app",
+    "service",
+    "service.name",
+    "k8s-app",
+];
+/** Pairs of kinds that are allowed to merge when their canonical
+ *  names match. Order doesn't matter (we normalise to sorted pair). */
+const MERGEABLE_KIND_PAIRS = new Set([
+    ["deployment", "cloud_service"],
+    ["deployment", "trace_service"],
+    ["cloud_service", "trace_service"],
+    ["pod", "container"],
+].map((p) => p.slice().sort().join("|")));
+function kindsMergeable(a, b) {
+    if (a === b)
+        return true;
+    return MERGEABLE_KIND_PAIRS.has([a, b].sort().join("|"));
+}
+/** Lower-cased label-key lookup; first match in CANONICAL_LABEL_KEYS
+ *  ordering wins so two providers with different label conventions
+ *  still converge if they both ship a known label. */
+export function canonicalNameFor(r) {
+    const override = typeof r.attributes?.canonicalName === "string"
+        ? r.attributes.canonicalName
+        : undefined;
+    if (override)
+        return override.toLowerCase();
+    if (!r.labels)
+        return undefined;
+    const lower = new Map();
+    for (const [k, v] of Object.entries(r.labels)) {
+        lower.set(k.toLowerCase(), v);
+    }
+    for (const key of CANONICAL_LABEL_KEYS) {
+        const v = lower.get(key.toLowerCase());
+        if (typeof v === "string" && v.length > 0)
+            return v.toLowerCase();
+    }
+    return undefined;
+}
+/**
+ * Merge a set of provider snapshots into one unified graph. The
+ * input is the flat union of every provider's resources+edges; the
+ * output collapses every group of nodes that share a canonical name
+ * (and a compatible kind) into a single node, then rewrites the
+ * edge endpoints accordingly.
+ */
+export function mergeTopologies(snapshots) {
+    const allResources = [];
+    const allEdges = [];
+    for (const s of snapshots) {
+        allResources.push(...s.resources);
+        allEdges.push(...s.edges);
+    }
+    // Group by (canonical-name + kind-bucket). Resources without a
+    // canonical name are passed through unchanged (one bucket each).
+    const groups = new Map();
+    const passthrough = [];
+    for (const r of allResources) {
+        const canonical = canonicalNameFor(r);
+        if (!canonical) {
+            passthrough.push(r);
+            continue;
+        }
+        // Bucket key tries to merge across compatible kinds: we group on
+        // canonical-name alone, then verify pairwise compatibility when
+        // collapsing.
+        const key = canonical;
+        const existing = groups.get(key);
+        if (existing)
+            existing.push(r);
+        else
+            groups.set(key, [r]);
+    }
+    const merged = [...passthrough];
+    const idMap = new Map();
+    for (const bucket of groups.values()) {
+        if (bucket.length === 1) {
+            merged.push(bucket[0]);
+            continue;
+        }
+        // Verify all kinds in the bucket are pairwise mergeable. If any
+        // pair isn't, fall back to passing every member through
+        // unchanged — better a slightly verbose graph than a wrong join.
+        let allCompatible = true;
+        for (let i = 0; i < bucket.length && allCompatible; i++) {
+            for (let j = i + 1; j < bucket.length && allCompatible; j++) {
+                if (!kindsMergeable(bucket[i].kind, bucket[j].kind)) {
+                    allCompatible = false;
+                }
+            }
+        }
+        if (!allCompatible) {
+            merged.push(...bucket);
+            continue;
+        }
+        const collapsed = collapseBucket(bucket);
+        merged.push(collapsed);
+        for (const r of bucket) {
+            if (r.id !== collapsed.id)
+                idMap.set(r.id, collapsed.id);
+        }
+    }
+    // Rewrite edge endpoints + dedupe identical (from,to,relation)
+    // tuples that arose from the collapse.
+    const seen = new Set();
+    const edges = [];
+    for (const e of allEdges) {
+        const from = idMap.get(e.from) ?? e.from;
+        const to = idMap.get(e.to) ?? e.to;
+        if (from === to)
+            continue; // self-loop after collapse → drop
+        const key = `${from}->${to}|${e.relation}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edges.push({ ...e, from, to });
+    }
+    return { resources: merged, edges, idMap };
+}
+function collapseBucket(bucket) {
+    // Stable choice for the canonical id: pick the first resource
+    // sorted lexicographically by source then id. Source rather than
+    // alphabetical so the choice doesn't flip when a label changes.
+    const sorted = [...bucket].sort((a, b) => {
+        const s = a.source.localeCompare(b.source);
+        return s !== 0 ? s : a.id.localeCompare(b.id);
+    });
+    const primary = sorted[0];
+    const labels = { ...primary.labels };
+    const attributes = { ...(primary.attributes ?? {}) };
+    const mergedFrom = [];
+    for (const r of sorted) {
+        if (r.labels)
+            for (const [k, v] of Object.entries(r.labels))
+                labels[k] = v;
+        if (r.attributes)
+            for (const [k, v] of Object.entries(r.attributes))
+                attributes[k] = v;
+        mergedFrom.push(`${r.source}:${r.id}`);
+    }
+    attributes.mergedFrom = mergedFrom;
+    // Pick the most-specific kind for the merged node: cloud_service
+    // > deployment > pod > trace_service > anything else. The merge
+    // rules above already capped the bucket to compatible kinds.
+    const kindPriority = ["cloud_service", "deployment", "pod", "trace_service", "container"];
+    const kind = kindPriority.find((k) => sorted.some((r) => r.kind === k)) ?? primary.kind;
+    return {
+        id: primary.id,
+        kind,
+        name: primary.name,
+        source: primary.source,
+        labels,
+        attributes,
+    };
+}

package/dist/topology/merge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/topology/merge.test.js

@@ -0,0 +1,110 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mergeTopologies, canonicalNameFor } from "./merge.js";
+function r(id, kind, opts = {}) {
+    return {
+        id,
+        kind,
+        name: opts.name ?? id,
+        source: opts.source ?? "test",
+        labels: opts.labels ?? {},
+        attributes: opts.canonical ? { canonicalName: opts.canonical } : undefined,
+    };
+}
+function e(from, to, relation = "RUNS_ON", source = "test") {
+    return { from, to, relation, source, confidence: 1.0 };
+}
+function snap(resources, edges = []) {
+    return { source: "test", resources, edges, revision: 1 };
+}
+test("canonicalNameFor: attributes.canonicalName wins, lowercased", () => {
+    const got = canonicalNameFor(r("x", "deployment", { canonical: "Payment-Service" }));
+    assert.equal(got, "payment-service");
+});
+test("canonicalNameFor: first matching CANONICAL_LABEL_KEYS entry wins", () => {
+    // app.kubernetes.io/name beats app
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { "app.kubernetes.io/name": "wins", app: "loses" } })), "wins");
+    // app beats service when app.kubernetes.io/name absent
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { app: "wins", service: "loses" } })), "wins");
+});
+test("canonicalNameFor: case-insensitive label-key match", () => {
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { "App": "Yes" } })), "yes");
+});
+test("canonicalNameFor: returns undefined when no canonical signal present", () => {
+    assert.equal(canonicalNameFor(r("x", "deployment")), undefined);
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { tier: "frontend" } })), undefined);
+});
+test("mergeTopologies: empty input returns empty result", () => {
+    const m = mergeTopologies([]);
+    assert.deepEqual(m.resources, []);
+    assert.deepEqual(m.edges, []);
+    assert.equal(m.idMap.size, 0);
+});
+test("mergeTopologies: passes resources without canonical name unchanged", () => {
+    const s = snap([r("a", "node", { source: "k8s" }), r("b", "namespace", { source: "k8s" })]);
+    const m = mergeTopologies([s]);
+    assert.equal(m.resources.length, 2);
+    assert.equal(m.idMap.size, 0);
+});
+test("mergeTopologies: collapses k8s Deployment + cloud_service with same canonical name", () => {
+    const k8s = snap([r("dep-payment", "deployment", { source: "k8s", labels: { app: "payment" } })]);
+    const aws = snap([r("ecs-payment", "cloud_service", { source: "aws", canonical: "payment" })]);
+    const m = mergeTopologies([k8s, aws]);
+    assert.equal(m.resources.length, 1, "two providers, one canonical service");
+    const merged = m.resources[0];
+    // Higher-priority kind wins (cloud_service > deployment)
+    assert.equal(merged.kind, "cloud_service");
+    assert.deepEqual((merged.attributes?.mergedFrom).sort(), [
+        "aws:ecs-payment",
+        "k8s:dep-payment",
+    ]);
+    // idMap maps the non-canonical id to the canonical one (first by
+    // source asc, then id asc: aws < k8s, so aws's id wins).
+    assert.equal(merged.id, "ecs-payment");
+    assert.equal(m.idMap.get("dep-payment"), "ecs-payment");
+});
+test("mergeTopologies: incompatible kinds in the bucket → no merge (graph stays verbose)", () => {
+    // `pod` and `function` are not in MERGEABLE_KIND_PAIRS — even if
+    // the names collide we keep both.
+    const k8s = snap([r("p1", "pod", { source: "k8s", labels: { app: "payment" } })]);
+    const aws = snap([r("fn1", "function", { source: "aws", canonical: "payment" })]);
+    const m = mergeTopologies([k8s, aws]);
+    assert.equal(m.resources.length, 2);
+    assert.equal(m.idMap.size, 0);
+});
+test("mergeTopologies: rewrites edges that referenced a collapsed id", () => {
+    const k8s = snap([r("dep-payment", "deployment", { source: "k8s", labels: { app: "payment" } })], [e("pod-1", "dep-payment", "RUNS_AS", "k8s")]);
+    const aws = snap([r("ecs-payment", "cloud_service", { source: "aws", canonical: "payment" })], [e("ecs-payment", "rds-1", "READS_FROM", "aws")]);
+    const m = mergeTopologies([k8s, aws]);
+    // dep-payment was collapsed into ecs-payment
+    const edges = m.edges;
+    // The k8s edge's TO endpoint must be rewritten to ecs-payment.
+    assert.ok(edges.some((x) => x.from === "pod-1" && x.to === "ecs-payment"));
+    // The aws edge stays put.
+    assert.ok(edges.some((x) => x.from === "ecs-payment" && x.to === "rds-1"));
+});
+test("mergeTopologies: self-loops created by the collapse are dropped", () => {
+    // Two resources merge into one. An edge that pointed from A to B
+    // becomes A→A after rewrite; drop it.
+    const k8s = snap([
+        r("dep-payment", "deployment", { source: "k8s", labels: { app: "payment" } }),
+        r("ecs-payment", "cloud_service", { source: "aws", canonical: "payment" }),
+    ], [e("dep-payment", "ecs-payment", "ALIAS_OF", "synthetic")]);
+    const m = mergeTopologies([k8s]);
+    assert.equal(m.resources.length, 1);
+    assert.equal(m.edges.filter((x) => x.from === x.to).length, 0, "self-loops after collapse must be removed");
+});
+test("mergeTopologies: duplicate (from,to,relation) tuples deduped after rewrite", () => {
+    const k8s = snap([
+        r("a", "deployment", { source: "k8s", labels: { app: "payment" } }),
+        r("b", "cloud_service", { source: "aws", canonical: "payment" }),
+        r("client", "deployment", { source: "k8s" }),
+    ], [
+        e("client", "a", "CALLS", "k8s"),
+        e("client", "b", "CALLS", "aws"),
+    ]);
+    const m = mergeTopologies([k8s]);
+    // After collapse, both edges become client→b CALLS — dedup to one.
+    const callEdges = m.edges.filter((x) => x.relation === "CALLS");
+    assert.equal(callEdges.length, 1);
+});

package/dist/transport/sessionStore.d.ts

@@ -0,0 +1,66 @@
+export interface SessionStore {
+    /** Stable backend identifier (used in /api/info diagnostics). */
+    readonly backend: string;
+    /** Get a JSON-serialisable value by key. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Set a value with no expiry. */
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    /** Set a value that auto-expires after `ttlSeconds`. */
+    setEx<T = unknown>(key: string, ttlSeconds: number, value: T): Promise<void>;
+    /** Remove a key. No-op if missing. */
+    del(key: string): Promise<void>;
+    /** List all keys matching a glob-style prefix (used by SCIM /
+     *  DCR enumeration). Not required to be efficient; backends MAY
+     *  impose a soft cap (and document it). */
+    keys(prefix: string): Promise<string[]>;
+    /** Best-effort shutdown — flush + disconnect any pooled clients. */
+    close(): Promise<void>;
+}
+/** Single-process, in-memory store. Default when OMCP_REDIS_URL is
+ *  unset. Lazy expiry — entries are evicted on the next access. */
+export declare class InMemorySessionStore implements SessionStore {
+    readonly backend = "memory";
+    private readonly map;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    setEx<T = unknown>(key: string, ttlSeconds: number, value: T): Promise<void>;
+    del(key: string): Promise<void>;
+    keys(prefix: string): Promise<string[]>;
+    close(): Promise<void>;
+    /** Test-only: introspect size. */
+    size(): number;
+}
+/** Redis-backed store. Constructed lazily via `connectRedisStore` so
+ *  the `redis` driver only loads when actually used. */
+export declare class RedisSessionStore implements SessionStore {
+    readonly backend = "redis";
+    private readonly client;
+    private readonly prefix;
+    constructor(client: RedisClientLike, prefix?: string);
+    private k;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    setEx<T = unknown>(key: string, ttlSeconds: number, value: T): Promise<void>;
+    del(key: string): Promise<void>;
+    keys(prefix: string): Promise<string[]>;
+    close(): Promise<void>;
+}
+/** Minimum surface a Redis client must implement. Lets us inject a
+ *  fake in tests and stays compatible across the `redis` / `ioredis`
+ *  package shapes. */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, opts?: {
+        EX?: number;
+    }): Promise<string | null | undefined>;
+    del(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    quit(): Promise<unknown>;
+}
+/**
+ * Resolve the session store from env. Default: InMemorySessionStore.
+ * When OMCP_REDIS_URL is set: load `redis` dynamically, connect, and
+ * return a RedisSessionStore. On any connect failure, log + fall back
+ * to InMemory (the gateway must boot even when Redis is down).
+ */
+export declare function resolveSessionStore(env?: NodeJS.ProcessEnv): Promise<SessionStore>;