@lensmcp/core 1.0.0

package/lib/graph-from-events.js

@@ -0,0 +1,141 @@
+/**
+ * Convert one event into a graph node, or return undefined if the event
+ * doesn't promote to a node.
+ */
+function eventToNode(event) {
+    const raw = (event.raw ?? null);
+    const kind = raw?.kind;
+    const baseContext = event.context;
+    const common = {
+        id: event.id,
+        parentTraceNodeId: baseContext.causedByNodeId ?? baseContext.originNodeId,
+        lifecycle: 'completed',
+        context: baseContext,
+        startTime: event.timestamp,
+        attributes: { ...(raw ?? {}) },
+    };
+    if (event.source === 'react' && kind === 'render') {
+        const r = raw;
+        return {
+            parentAxis: 'render',
+            node: {
+                ...common,
+                type: 'render',
+                logicalId: r.render?.componentLogicalId,
+                instanceId: r.render?.componentInstanceId,
+                name: `render ${r.render?.componentName ?? '?'}`,
+                durationMs: r.render?.actualDurationMs,
+            },
+        };
+    }
+    if (event.source === 'valtio' && kind === 'state-update') {
+        const r = raw;
+        return {
+            parentAxis: 'state',
+            node: {
+                ...common,
+                type: 'state-update',
+                logicalId: r.update?.storeId,
+                name: `${r.update?.storeId ?? '?'}.${r.update?.path ?? '?'}`,
+            },
+        };
+    }
+    if (event.source === 'nestjs' && kind === 'server-request') {
+        const r = raw;
+        return {
+            parentAxis: 'backend',
+            node: {
+                ...common,
+                type: 'server-request',
+                name: `${r.request?.method ?? '?'} ${r.request?.route ?? '?'}`,
+                durationMs: r.request?.durationMs,
+            },
+        };
+    }
+    if (kind === 'loop') {
+        const r = raw;
+        return {
+            parentAxis: 'performance',
+            node: {
+                ...common,
+                type: 'loop',
+                name: 'loop',
+                durationMs: r.loop?.durationMs,
+            },
+        };
+    }
+    if (event.source === 'client-runtime' && kind === 'user-action') {
+        const r = raw;
+        return {
+            parentAxis: 'caused',
+            node: {
+                ...common,
+                type: 'ui-event',
+                logicalId: r.origin?.nodeId,
+                name: r.origin?.label ?? event.title,
+            },
+        };
+    }
+    return undefined;
+}
+/**
+ * Populate `store` from `events`. Edges are created two ways:
+ *   1. explicit `causedByNodeId` → an edge on the node's natural axis.
+ *   2. same-flow chronological chaining on the 'caused' axis so a flow's
+ *      nodes form a walkable spine even when explicit causality is absent.
+ */
+export function buildGraphFromEvents(store, events) {
+    const sorted = [...events].sort((a, b) => a.timestamp - b.timestamp);
+    const mapped = [];
+    for (const e of sorted) {
+        const m = eventToNode(e);
+        if (!m)
+            continue;
+        store.addNode(m.node);
+        mapped.push(m);
+    }
+    let edgeCount = 0;
+    const addEdge = (from, to, axis, type) => {
+        const edge = {
+            id: `${axis}:${from}->${to}`,
+            from,
+            to,
+            axis,
+            type,
+            timestamp: store.getNode(to)?.startTime ?? 0,
+        };
+        store.addEdge(edge);
+        edgeCount++;
+    };
+    // Explicit causedBy edges.
+    for (const m of mapped) {
+        const caused = m.node.context.causedByNodeId;
+        if (caused && store.getNode(caused)) {
+            addEdge(caused, m.node.id, m.parentAxis ?? 'caused', 'caused-by');
+        }
+    }
+    // Same-flow chronological spine on the caused axis.
+    const byFlow = new Map();
+    for (const m of mapped) {
+        const flowId = m.node.context.flowId;
+        if (!flowId)
+            continue;
+        let arr = byFlow.get(flowId);
+        if (!arr) {
+            arr = [];
+            byFlow.set(flowId, arr);
+        }
+        arr.push(m);
+    }
+    for (const chain of byFlow.values()) {
+        for (let i = 1; i < chain.length; i++) {
+            const prev = chain[i - 1].node;
+            const cur = chain[i].node;
+            // Skip if an explicit edge already connects them.
+            if (cur.context.causedByNodeId === prev.id)
+                continue;
+            addEdge(prev.id, cur.id, 'caused', 'flow-sequence');
+        }
+    }
+    return { nodeCount: mapped.length, edgeCount };
+}

package/lib/graph-store.d.ts

@@ -0,0 +1,48 @@
+import type { EdgeAxis, TraceEdge, TraceNode } from '@lensmcp/protocol-types';
+export type Lens = EdgeAxis | readonly EdgeAxis[];
+export type TraversalDirection = 'out' | 'in' | 'both';
+export interface TraverseOptions {
+    from: string;
+    lens: Lens;
+    depth?: number;
+    direction?: TraversalDirection;
+    /** Cap on visited nodes so a hub node can't blow up tool latency. */
+    maxNodes?: number;
+}
+export interface TraverseResult {
+    nodes: TraceNode[];
+    edges: TraceEdge[];
+}
+/**
+ * Typed multi-axis trace graph. Hot-tier only (in-memory). Nodes and
+ * edges are indexed for cheap per-axis traversal.
+ */
+export declare class GraphStore {
+    private readonly nodes;
+    private readonly edges;
+    private readonly byParent;
+    private readonly byFlow;
+    private readonly byLogical;
+    private readonly byInstance;
+    private readonly byRequest;
+    /** axis → { from-nodeId → Set<edgeId> } */
+    private readonly outByAxis;
+    /** axis → { to-nodeId → Set<edgeId> } */
+    private readonly inByAxis;
+    addNode(node: TraceNode): void;
+    updateNode(id: string, patch: Partial<TraceNode>): TraceNode;
+    getNode(id: string): TraceNode | undefined;
+    addEdge(edge: TraceEdge): void;
+    getEdge(id: string): TraceEdge | undefined;
+    childrenOf(parentId: string): TraceNode[];
+    nodesInFlow(flowId: string): TraceNode[];
+    nodesByLogical(logicalId: string): TraceNode[];
+    nodesByInstance(instanceId: string): TraceNode[];
+    nodesByRequest(requestId: string): TraceNode[];
+    traverse(opts: TraverseOptions): TraverseResult;
+    nodeCount(): number;
+    edgeCount(): number;
+    private addToIndex;
+    private materialiseNodes;
+}
+//# sourceMappingURL=graph-store.d.ts.map

package/lib/graph-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store.d.ts","sourceRoot":"","sources":["../../src/lib/graph-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE9E,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,SAAS,QAAQ,EAAE,CAAC;AAClD,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAGtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAC3E,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiD;IAE1E,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAmB9B,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS;IAQ5D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI1C,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAgB9B,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAM1C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE;IAIzC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE;IAIxC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE;IAI9C,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE;IAIhD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE;IAM9C,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc;IA8D/C,SAAS,IAAI,MAAM;IAInB,SAAS,IAAI,MAAM;IAMnB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,gBAAgB;CASzB"}

package/lib/graph-store.js

@@ -0,0 +1,171 @@
+const DEFAULT_DEPTH = 4;
+const DEFAULT_MAX_NODES = 1000;
+/**
+ * Typed multi-axis trace graph. Hot-tier only (in-memory). Nodes and
+ * edges are indexed for cheap per-axis traversal.
+ */
+export class GraphStore {
+    constructor() {
+        this.nodes = new Map();
+        this.edges = new Map();
+        // Indices
+        this.byParent = new Map();
+        this.byFlow = new Map();
+        this.byLogical = new Map();
+        this.byInstance = new Map();
+        this.byRequest = new Map();
+        /** axis → { from-nodeId → Set<edgeId> } */
+        this.outByAxis = new Map();
+        /** axis → { to-nodeId → Set<edgeId> } */
+        this.inByAxis = new Map();
+    }
+    addNode(node) {
+        this.nodes.set(node.id, node);
+        if (node.parentTraceNodeId) {
+            this.addToIndex(this.byParent, node.parentTraceNodeId, node.id);
+        }
+        if (node.context.flowId) {
+            this.addToIndex(this.byFlow, node.context.flowId, node.id);
+        }
+        if (node.logicalId) {
+            this.addToIndex(this.byLogical, node.logicalId, node.id);
+        }
+        if (node.instanceId) {
+            this.addToIndex(this.byInstance, node.instanceId, node.id);
+        }
+        if (node.context.requestId) {
+            this.addToIndex(this.byRequest, node.context.requestId, node.id);
+        }
+    }
+    updateNode(id, patch) {
+        const existing = this.nodes.get(id);
+        if (!existing)
+            throw new Error(`Unknown node: ${id}`);
+        const next = { ...existing, ...patch, id: existing.id };
+        this.nodes.set(id, next);
+        return next;
+    }
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    addEdge(edge) {
+        this.edges.set(edge.id, edge);
+        let outMap = this.outByAxis.get(edge.axis);
+        if (!outMap) {
+            outMap = new Map();
+            this.outByAxis.set(edge.axis, outMap);
+        }
+        this.addToIndex(outMap, edge.from, edge.id);
+        let inMap = this.inByAxis.get(edge.axis);
+        if (!inMap) {
+            inMap = new Map();
+            this.inByAxis.set(edge.axis, inMap);
+        }
+        this.addToIndex(inMap, edge.to, edge.id);
+    }
+    getEdge(id) {
+        return this.edges.get(id);
+    }
+    // ---------- Indexed lookups ----------
+    childrenOf(parentId) {
+        return this.materialiseNodes(this.byParent.get(parentId));
+    }
+    nodesInFlow(flowId) {
+        return this.materialiseNodes(this.byFlow.get(flowId));
+    }
+    nodesByLogical(logicalId) {
+        return this.materialiseNodes(this.byLogical.get(logicalId));
+    }
+    nodesByInstance(instanceId) {
+        return this.materialiseNodes(this.byInstance.get(instanceId));
+    }
+    nodesByRequest(requestId) {
+        return this.materialiseNodes(this.byRequest.get(requestId));
+    }
+    // ---------- Lens traversal ----------
+    traverse(opts) {
+        const start = this.nodes.get(opts.from);
+        if (!start)
+            return { nodes: [], edges: [] };
+        const axes = Array.isArray(opts.lens)
+            ? opts.lens
+            : [opts.lens];
+        const direction = opts.direction ?? 'both';
+        const depth = opts.depth ?? DEFAULT_DEPTH;
+        const maxNodes = opts.maxNodes ?? DEFAULT_MAX_NODES;
+        const visitedNodes = new Set();
+        const visitedEdges = new Set();
+        const queue = [{ id: start.id, d: 0 }];
+        while (queue.length) {
+            if (visitedNodes.size >= maxNodes)
+                break;
+            const { id, d } = queue.shift();
+            if (visitedNodes.has(id))
+                continue;
+            visitedNodes.add(id);
+            if (d >= depth)
+                continue;
+            for (const axis of axes) {
+                if (direction === 'out' || direction === 'both') {
+                    const outMap = this.outByAxis.get(axis);
+                    const edgeIds = outMap?.get(id);
+                    if (edgeIds) {
+                        for (const eid of edgeIds) {
+                            visitedEdges.add(eid);
+                            const edge = this.edges.get(eid);
+                            if (!visitedNodes.has(edge.to)) {
+                                queue.push({ id: edge.to, d: d + 1 });
+                            }
+                        }
+                    }
+                }
+                if (direction === 'in' || direction === 'both') {
+                    const inMap = this.inByAxis.get(axis);
+                    const edgeIds = inMap?.get(id);
+                    if (edgeIds) {
+                        for (const eid of edgeIds) {
+                            visitedEdges.add(eid);
+                            const edge = this.edges.get(eid);
+                            if (!visitedNodes.has(edge.from)) {
+                                queue.push({ id: edge.from, d: d + 1 });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return {
+            nodes: this.materialiseNodes(visitedNodes),
+            edges: [...visitedEdges]
+                .map((eid) => this.edges.get(eid))
+                .filter((e) => Boolean(e)),
+        };
+    }
+    // ---------- Stats ----------
+    nodeCount() {
+        return this.nodes.size;
+    }
+    edgeCount() {
+        return this.edges.size;
+    }
+    // ---------- internals ----------
+    addToIndex(index, key, value) {
+        let set = index.get(key);
+        if (!set) {
+            set = new Set();
+            index.set(key, set);
+        }
+        set.add(value);
+    }
+    materialiseNodes(ids) {
+        if (!ids)
+            return [];
+        const out = [];
+        for (const id of ids) {
+            const n = this.nodes.get(id);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+}

package/lib/patterns.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pattern detectors. Each is a pure function over a window of
+ * `BaseEvent`s (or already-extracted records) and returns zero or more
+ * `PatternMatch`es. Reducers call these on a streaming window; tools
+ * call them on demand.
+ *
+ * Detectors covered (Phase 7):
+ *   - db-in-loop      — a `loop` node completed with dbCallsInsideLoop > N
+ *   - n+1-query       — the same query signature repeated ≥ N times in a window
+ *   - slow-path       — the longest cumulative duration on the caused/async axis
+ *   - render-storm    — one componentInstanceId rendered > N times in < T ms
+ */
+import type { BaseEvent } from '@lensmcp/protocol-types';
+export type PatternKind = 'db-in-loop' | 'n+1-query' | 'slow-path' | 'render-storm' | 'leak';
+export interface PatternMatch {
+    kind: PatternKind;
+    severity: 'info' | 'warning' | 'error';
+    title: string;
+    /** Node/event ids that evidence the pattern. */
+    evidence: string[];
+    /** Free-form per-pattern details. */
+    details: Record<string, unknown>;
+    detectedAt: number;
+}
+export interface DbInLoopOptions {
+    /** Minimum DB calls inside a loop before it's flagged. Default 5. */
+    threshold?: number;
+}
+/**
+ * Flag `loop` events whose `dbCallsInsideLoop` exceeds the threshold.
+ * Events are expected to carry `raw.kind === 'loop'` with a `loop`
+ * attribute matching `LoopAttrs`.
+ */
+export declare function detectDbInLoop(events: readonly BaseEvent[], options?: DbInLoopOptions): PatternMatch[];
+export interface NPlusOneOptions {
+    /** Minimum repeats of an identical signature before flagging. Default 3. */
+    threshold?: number;
+}
+/**
+ * Flag repeated identical DB query signatures. Events are expected to
+ * carry `raw.kind === 'db-query'` with `raw.query.signature`.
+ */
+export declare function detectNPlusOne(events: readonly BaseEvent[], options?: NPlusOneOptions): PatternMatch[];
+export interface RenderStormOptions {
+    /** Max renders per component in the window before flagging. Default 5. */
+    threshold?: number;
+    /** Window in ms. Default 250. */
+    windowMs?: number;
+}
+/**
+ * Flag a component instance that rendered more than `threshold` times
+ * inside any `windowMs` window. Events are `source:'react'`,
+ * `raw.kind === 'render'`, `raw.render.componentInstanceId`.
+ */
+export declare function detectRenderStorm(events: readonly BaseEvent[], options?: RenderStormOptions): PatternMatch[];
+export interface SlowPathResult {
+    /** Ordered node/event ids along the slowest cumulative chain. */
+    path: string[];
+    totalDurationMs: number;
+}
+/**
+ * Find the single slowest cumulative chain on the caused/async axis,
+ * given a precomputed adjacency (nodeId → outgoing nodeIds) and a
+ * per-node duration map. Pure + bounded (visits each node once via
+ * memoised DFS).
+ */
+export declare function findSlowPath(roots: readonly string[], adjacency: ReadonlyMap<string, readonly string[]>, durationOf: (nodeId: string) => number): SlowPathResult;
+//# sourceMappingURL=patterns.d.ts.map

package/lib/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/lib/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,WAAW,GACX,WAAW,GACX,cAAc,GACd,MAAM,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,GAAE,eAAoB,GAC5B,YAAY,EAAE,CA0BhB;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,GAAE,eAAoB,GAC5B,YAAY,EAAE,CA4BhB;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,GAAE,kBAAuB,GAC/B,YAAY,EAAE,CAkDhB;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EACjD,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GACrC,cAAc,CAmChB"}

package/lib/patterns.js

@@ -0,0 +1,163 @@
+/**
+ * Flag `loop` events whose `dbCallsInsideLoop` exceeds the threshold.
+ * Events are expected to carry `raw.kind === 'loop'` with a `loop`
+ * attribute matching `LoopAttrs`.
+ */
+export function detectDbInLoop(events, options = {}) {
+    const threshold = options.threshold ?? 5;
+    const out = [];
+    for (const e of events) {
+        const raw = (e.raw ?? null);
+        if (raw?.kind !== 'loop' || !raw.loop)
+            continue;
+        const dbCalls = raw.loop.dbCallsInsideLoop ?? 0;
+        if (dbCalls > threshold) {
+            out.push({
+                kind: 'db-in-loop',
+                severity: 'warning',
+                title: `${dbCalls} DB calls inside a loop (${raw.loop.iterations ?? '?'} iterations)`,
+                evidence: [e.id],
+                details: {
+                    dbCallsInsideLoop: dbCalls,
+                    iterations: raw.loop.iterations,
+                    durationMs: raw.loop.durationMs,
+                    threshold,
+                },
+                detectedAt: e.timestamp,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Flag repeated identical DB query signatures. Events are expected to
+ * carry `raw.kind === 'db-query'` with `raw.query.signature`.
+ */
+export function detectNPlusOne(events, options = {}) {
+    const threshold = options.threshold ?? 3;
+    const groups = new Map();
+    for (const e of events) {
+        const raw = (e.raw ?? null);
+        if (raw?.kind !== 'db-query' || !raw.query?.signature)
+            continue;
+        const sig = raw.query.signature;
+        let arr = groups.get(sig);
+        if (!arr) {
+            arr = [];
+            groups.set(sig, arr);
+        }
+        arr.push(e);
+    }
+    const out = [];
+    for (const [signature, group] of groups) {
+        if (group.length >= threshold) {
+            out.push({
+                kind: 'n+1-query',
+                severity: 'warning',
+                title: `Query repeated ${group.length}× — likely N+1`,
+                evidence: group.map((e) => e.id),
+                details: { signature, count: group.length, threshold },
+                detectedAt: group[group.length - 1].timestamp,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Flag a component instance that rendered more than `threshold` times
+ * inside any `windowMs` window. Events are `source:'react'`,
+ * `raw.kind === 'render'`, `raw.render.componentInstanceId`.
+ */
+export function detectRenderStorm(events, options = {}) {
+    const threshold = options.threshold ?? 5;
+    const windowMs = options.windowMs ?? 250;
+    const byInstance = new Map();
+    for (const e of events) {
+        if (e.source !== 'react')
+            continue;
+        const raw = (e.raw ?? null);
+        if (raw?.kind !== 'render' || !raw.render?.componentInstanceId)
+            continue;
+        const id = raw.render.componentInstanceId;
+        let arr = byInstance.get(id);
+        if (!arr) {
+            arr = [];
+            byInstance.set(id, arr);
+        }
+        arr.push(e);
+    }
+    const out = [];
+    for (const [instanceId, group] of byInstance) {
+        group.sort((a, b) => a.timestamp - b.timestamp);
+        // Sliding window: find the densest run.
+        let start = 0;
+        for (let end = 0; end < group.length; end++) {
+            while (group[end].timestamp - group[start].timestamp > windowMs) {
+                start++;
+            }
+            const count = end - start + 1;
+            if (count > threshold) {
+                const window = group.slice(start, end + 1);
+                const name = window[0].raw.render
+                    ?.componentName ?? instanceId;
+                out.push({
+                    kind: 'render-storm',
+                    severity: 'warning',
+                    title: `${name} rendered ${count}× in ${windowMs}ms`,
+                    evidence: window.map((e) => e.id),
+                    details: {
+                        componentInstanceId: instanceId,
+                        count,
+                        windowMs,
+                        threshold,
+                    },
+                    detectedAt: window[window.length - 1].timestamp,
+                });
+                break; // one match per instance is enough
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Find the single slowest cumulative chain on the caused/async axis,
+ * given a precomputed adjacency (nodeId → outgoing nodeIds) and a
+ * per-node duration map. Pure + bounded (visits each node once via
+ * memoised DFS).
+ */
+export function findSlowPath(roots, adjacency, durationOf) {
+    const memo = new Map();
+    const inProgress = new Set();
+    function best(nodeId) {
+        const cached = memo.get(nodeId);
+        if (cached)
+            return cached;
+        if (inProgress.has(nodeId)) {
+            // cycle guard
+            return { path: [nodeId], totalDurationMs: durationOf(nodeId) };
+        }
+        inProgress.add(nodeId);
+        const selfMs = durationOf(nodeId);
+        const children = adjacency.get(nodeId) ?? [];
+        let bestChild;
+        for (const child of children) {
+            const r = best(child);
+            if (!bestChild || r.totalDurationMs > bestChild.totalDurationMs) {
+                bestChild = r;
+            }
+        }
+        inProgress.delete(nodeId);
+        const result = bestChild
+            ? { path: [nodeId, ...bestChild.path], totalDurationMs: selfMs + bestChild.totalDurationMs }
+            : { path: [nodeId], totalDurationMs: selfMs };
+        memo.set(nodeId, result);
+        return result;
+    }
+    let overall = { path: [], totalDurationMs: 0 };
+    for (const root of roots) {
+        const r = best(root);
+        if (r.totalDurationMs > overall.totalDurationMs)
+            overall = r;
+    }
+    return overall;
+}

package/lib/reducer-registry.d.ts

@@ -0,0 +1,20 @@
+import type { BaseEvent } from '@lensmcp/protocol-types';
+/**
+ * A reducer consumes events from the bus and may mutate the graph store
+ * and/or mark resources dirty. We deliberately do not pass a "world"
+ * object here — reducers are registered with their dependencies via
+ * closures by `bootstrapLensmcp()`.
+ */
+export type Reducer = (event: BaseEvent) => void | Promise<void>;
+export interface ReducerEntry {
+    name: string;
+    reducer: Reducer;
+}
+export declare class ReducerRegistry {
+    private readonly reducers;
+    register(name: string, reducer: Reducer): void;
+    list(): readonly ReducerEntry[];
+    /** Run every registered reducer against one event. */
+    dispatch(event: BaseEvent): Promise<void>;
+}
+//# sourceMappingURL=reducer-registry.d.ts.map

package/lib/reducer-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer-registry.d.ts","sourceRoot":"","sources":["../../src/lib/reducer-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAE/C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAO9C,IAAI,IAAI,SAAS,YAAY,EAAE;IAI/B,sDAAsD;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAYhD"}

package/lib/reducer-registry.js

@@ -0,0 +1,28 @@
+export class ReducerRegistry {
+    constructor() {
+        this.reducers = [];
+    }
+    register(name, reducer) {
+        if (this.reducers.some((r) => r.name === name)) {
+            throw new Error(`Reducer already registered: ${name}`);
+        }
+        this.reducers.push({ name, reducer });
+    }
+    list() {
+        return this.reducers;
+    }
+    /** Run every registered reducer against one event. */
+    async dispatch(event) {
+        for (const { reducer } of this.reducers) {
+            try {
+                const r = reducer(event);
+                if (r && typeof r.then === 'function') {
+                    await r;
+                }
+            }
+            catch {
+                /* swallow reducer errors */
+            }
+        }
+    }
+}

package/lib/resource-store.d.ts

@@ -0,0 +1,31 @@
+import type { Unsubscribe } from './common.js';
+/**
+ * Anything that JSON.stringify can safely serialise. Intentionally loose:
+ * reducers compose plain objects with optional fields (which structurally
+ * don't fit a strict recursive `JsonValue` type) and we'd rather not
+ * pollute every call site with casts.
+ */
+export type ResourceValue = unknown;
+export type ResourceProducer = () => ResourceValue | Promise<ResourceValue>;
+export type ResourceUpdatedHandler = (uri: string, revision: number) => void;
+/**
+ * The resource store. URIs are registered once; reading is cheap; the
+ * `markDirty` call bumps the revision counter and notifies subscribers
+ * only when the produced JSON actually changes (diff-aware).
+ */
+export declare class ResourceStore {
+    private readonly entries;
+    private readonly subs;
+    register(uri: string, produce: ResourceProducer): Unsubscribe;
+    read(uri: string): Promise<ResourceValue>;
+    list(): string[];
+    /**
+     * Recompute the JSON, bump the revision counter if it differs, and
+     * notify subscribers. No-op if the URI is unknown or the JSON didn't
+     * change.
+     */
+    markDirty(uri: string): Promise<void>;
+    revision(uri: string): number | undefined;
+    subscribe(uri: string, handler: ResourceUpdatedHandler): Unsubscribe;
+}
+//# sourceMappingURL=resource-store.d.ts.map