kairo-mcp 1.3.0

package/dist/core/graph/imports.js.map

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

package/dist/core/graph/mermaid.d.ts

@@ -0,0 +1,6 @@
+import type { RepoGraph } from './types.js';
+/** Render a graph as deterministic Mermaid `flowchart` source (no code fence). */
+export declare function renderMermaid(graph: RepoGraph): string;
+/** Human/agent-readable markdown mirror written under `.kairo/graphs/`. */
+export declare function renderGraphMarkdown(graph: RepoGraph): string;
+//# sourceMappingURL=mermaid.d.ts.map

package/dist/core/graph/mermaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../../src/core/graph/mermaid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAe5C,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAqBtD;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAK5D"}

package/dist/core/graph/mermaid.js

@@ -0,0 +1,40 @@
+/** Escape a label for safe use inside a Mermaid `["..."]` node. */
+function esc(label) {
+    return label
+        .replace(/"/g, '#quot;')
+        .replace(/[[\]{}]/g, '')
+        .replace(/\r?\n/g, '<br/>')
+        .trim();
+}
+function classId(group) {
+    return `g_${group.replace(/[^A-Za-z0-9_]/g, '_')}`;
+}
+/** Render a graph as deterministic Mermaid `flowchart` source (no code fence). */
+export function renderMermaid(graph) {
+    const lines = ['flowchart TD'];
+    for (const n of graph.nodes) {
+        lines.push(`  ${n.id}["${esc(n.label)}"]`);
+    }
+    for (const e of graph.edges) {
+        const label = e.label ?? (e.weight && e.weight > 1 ? `×${e.weight}` : undefined);
+        lines.push(label ? `  ${e.from} -->|${esc(label)}| ${e.to}` : `  ${e.from} --> ${e.to}`);
+    }
+    const groups = [...new Set(graph.nodes.map((n) => n.group).filter((g) => !!g))];
+    for (const g of groups.sort()) {
+        lines.push(`  classDef ${classId(g)} stroke-width:1px;`);
+    }
+    for (const n of graph.nodes) {
+        if (n.group)
+            lines.push(`  class ${n.id} ${classId(n.group)};`);
+    }
+    return lines.join('\n');
+}
+/** Human/agent-readable markdown mirror written under `.kairo/graphs/`. */
+export function renderGraphMarkdown(graph) {
+    const lines = [`# ${graph.title}`, '', `> ${graph.note}`];
+    if (graph.truncated)
+        lines.push('>', '> ⚠️ Truncated — partial view (node/edge cap hit).');
+    lines.push('', '```mermaid', renderMermaid(graph), '```', '');
+    return lines.join('\n');
+}
+//# sourceMappingURL=mermaid.js.map

package/dist/core/graph/mermaid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.js","sourceRoot":"","sources":["../../../src/core/graph/mermaid.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,SAAS,GAAG,CAAC,KAAa;IACxB,OAAO,KAAK;SACT,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC;SAC1B,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,KAAgB;IAC5C,MAAM,KAAK,GAAa,CAAC,cAAc,CAAC,CAAC;IAEzC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACjF,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,QAAQ,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,cAAc,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC3D,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,MAAM,KAAK,GAAG,CAAC,KAAK,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1D,IAAI,KAAK,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,oDAAoD,CAAC,CAAC;IAC3F,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC9D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/core/graph/moduleGraph.d.ts

@@ -0,0 +1,27 @@
+import type { RepoGraph } from './types.js';
+import type { SalienceConfig, SalienceContext } from '../salience/types.js';
+export interface ModuleGraphOptions {
+    /** Directory depth to collapse files to (under a `src/`-style root). */
+    groupDepth?: number;
+    /** Hard cap on rendered nodes; above this the graph auto-collapses shallower. */
+    maxNodes?: number;
+    /**
+     * Salience inputs. When provided, truncation keeps the most *architecturally
+     * salient* groups (see ADR-0004) instead of merely the highest-degree ones.
+     */
+    salience?: {
+        context: SalienceContext;
+        config: SalienceConfig;
+    };
+}
+/** Exposed so callers (the scanner) can map entry-point paths to graph groups. */
+export declare function pathToGroup(rel: string, depth: number): string;
+/**
+ * Collapse file-level internal edges into a readable directory-granularity graph.
+ * If the chosen depth produces too many nodes we auto-collapse one level shallower;
+ * if still over the cap we keep the most *salient* groups (ADR-0004) — first-party
+ * production architecture and real dependency centres over examples/docs/fixtures —
+ * and flag the graph truncated honestly.
+ */
+export declare function buildModuleGraph(fileEdges: Array<[string, string]>, sourceFiles: string[], opts?: ModuleGraphOptions): RepoGraph;
+//# sourceMappingURL=moduleGraph.d.ts.map

package/dist/core/graph/moduleGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleGraph.d.ts","sourceRoot":"","sources":["../../../src/core/graph/moduleGraph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,SAAS,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAgB,MAAM,sBAAsB,CAAC;AAG1F,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,eAAe,CAAC;QAAC,MAAM,EAAE,cAAc,CAAA;KAAE,CAAC;CACjE;AA4CD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAoCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAClC,WAAW,EAAE,MAAM,EAAE,EACrB,IAAI,GAAE,kBAAuB,GAC5B,SAAS,CA6GX"}

package/dist/core/graph/moduleGraph.js

@@ -0,0 +1,186 @@
+import { rankAndSelect } from '../salience/salienceEngine.js';
+const DEFAULTS = { groupDepth: 2, maxNodes: 40 };
+const SOURCE_SEGMENTS = new Set(['src', 'lib', 'app', 'sources']);
+const MONOREPO_CONTAINERS = new Set(['packages', 'apps', 'libs', 'modules']);
+/**
+ * Collapse a file path to a readable group label.
+ *
+ * The naive "strip a known prefix" approach is wrong for the two commonest real
+ * layouts: monorepos (`packages/<pkg>/src/**`) and nested source roots — it collapses
+ * an entire package to one node so every intra-package edge becomes a dropped
+ * self-edge (observed in dogfood: zod 504 file-edges → 6). Instead we locate the
+ * DEEPEST source segment and group by the owning package plus the directories *under*
+ * that source root, so a package's internal structure (and its edges) survives.
+ */
+function groupOf(rel, depth) {
+    const all = rel.split('/');
+    const dirs = all.slice(0, -1); // drop filename
+    if (dirs.length === 0)
+        return '(root)';
+    let srcIdx = -1;
+    for (let i = 0; i < dirs.length; i++) {
+        if (SOURCE_SEGMENTS.has(dirs[i]))
+            srcIdx = i;
+    }
+    if (srcIdx >= 0) {
+        // Owning package/app = the dir immediately before the source segment, if any
+        // (e.g. `packages/zod/src/types` → pkg "zod"; top-level `src/core` → pkg "").
+        const pkg = srcIdx >= 1 ? dirs[srcIdx - 1] : '';
+        const under = dirs.slice(srcIdx + 1); // dirs beneath the source root
+        const parts = (pkg ? [pkg, ...under] : under).filter(Boolean);
+        if (parts.length === 0)
+            return pkg || '(src)';
+        return parts.slice(0, Math.max(depth, pkg ? 2 : 1)).join('/');
+    }
+    // No source segment: drop a leading monorepo container so the package name leads.
+    const start = MONOREPO_CONTAINERS.has(dirs[0]) ? 1 : 0;
+    const parts = dirs.slice(start);
+    if (parts.length === 0)
+        return '(root)';
+    return parts.slice(0, depth).join('/');
+}
+/** Exposed so callers (the scanner) can map entry-point paths to graph groups. */
+export function pathToGroup(rel, depth) {
+    return groupOf(rel, depth);
+}
+const EDGE_SEP = ' '; // single space — group labels never contain spaces
+function buildAtDepth(fileEdges, sourceFiles, depth) {
+    const nodes = new Set();
+    // Representative original path per group. Grouping strips prefixes like
+    // `sample/`/`examples/`, so the label alone hides whether a group is noise;
+    // salience must score this fuller path. Deterministic = lexicographically first.
+    const repPath = new Map();
+    for (const f of [...sourceFiles].sort()) {
+        const g = groupOf(f, depth);
+        nodes.add(g);
+        const cur = repPath.get(g);
+        if (cur === undefined || f < cur)
+            repPath.set(g, f);
+    }
+    const edges = new Map();
+    for (const [from, to] of fileEdges) {
+        const a = groupOf(from, depth);
+        const b = groupOf(to, depth);
+        if (a === b)
+            continue;
+        const key = `${a}${EDGE_SEP}${b}`;
+        edges.set(key, (edges.get(key) ?? 0) + 1);
+    }
+    return { nodes, edges, repPath };
+}
+function sanitizeId(label, index) {
+    const base = label.replace(/[^A-Za-z0-9_]/g, '_').replace(/^_+|_+$/g, '');
+    return base.length > 0 ? `n_${index}_${base}`.slice(0, 60) : `n_${index}`;
+}
+/**
+ * Collapse file-level internal edges into a readable directory-granularity graph.
+ * If the chosen depth produces too many nodes we auto-collapse one level shallower;
+ * if still over the cap we keep the most *salient* groups (ADR-0004) — first-party
+ * production architecture and real dependency centres over examples/docs/fixtures —
+ * and flag the graph truncated honestly.
+ */
+export function buildModuleGraph(fileEdges, sourceFiles, opts = {}) {
+    const maxNodes = opts.maxNodes ?? DEFAULTS.maxNodes;
+    let depth = opts.groupDepth ?? DEFAULTS.groupDepth;
+    let built = buildAtDepth(fileEdges, sourceFiles, depth);
+    if (built.nodes.size > maxNodes && depth > 1) {
+        depth = 1;
+        built = buildAtDepth(fileEdges, sourceFiles, depth);
+    }
+    // Per-node directional metrics + adjacency from the collapsed edges.
+    const fanIn = new Map();
+    const fanOut = new Map();
+    const adj = new Map();
+    for (const [key, w] of built.edges) {
+        const [a, b] = key.split(EDGE_SEP);
+        fanOut.set(a, (fanOut.get(a) ?? 0) + w);
+        fanIn.set(b, (fanIn.get(b) ?? 0) + w);
+        if (!adj.has(a))
+            adj.set(a, []);
+        adj.get(a).push(b);
+    }
+    for (const n of built.nodes) {
+        if (!fanIn.has(n))
+            fanIn.set(n, 0);
+        if (!fanOut.has(n))
+            fanOut.set(n, 0);
+    }
+    const degreeOf = (n) => (fanIn.get(n) ?? 0) + (fanOut.get(n) ?? 0);
+    // Reachability/depth from runtime entry points (groups owning an entry path).
+    const depthFromEntry = new Map();
+    if (opts.salience) {
+        const entryGroups = new Set(opts.salience.context.entryPoints
+            .filter((p) => p.includes('/') || p.includes('.'))
+            .map((p) => groupOf(p, depth))
+            .filter((g) => built.nodes.has(g)));
+        const queue = [];
+        for (const g of entryGroups) {
+            depthFromEntry.set(g, 0);
+            queue.push([g, 0]);
+        }
+        while (queue.length > 0) {
+            const [node, d] = queue.shift();
+            for (const next of adj.get(node) ?? []) {
+                if (!depthFromEntry.has(next)) {
+                    depthFromEntry.set(next, d + 1);
+                    queue.push([next, d + 1]);
+                }
+            }
+        }
+    }
+    let truncated = false;
+    let kept = [...built.nodes];
+    if (kept.length > maxNodes) {
+        truncated = true;
+        if (opts.salience) {
+            const items = kept.map((label) => ({
+                id: label,
+                path: built.repPath.get(label) ?? label,
+                metrics: {
+                    fanIn: fanIn.get(label) ?? 0,
+                    fanOut: fanOut.get(label) ?? 0,
+                    reachableFromEntry: depthFromEntry.has(label),
+                    depthFromEntry: depthFromEntry.get(label) ?? Number.POSITIVE_INFINITY,
+                },
+            }));
+            const sel = rankAndSelect(items, opts.salience.context, opts.salience.config, maxNodes);
+            kept = sel.kept.map((s) => s.id);
+        }
+        else {
+            kept = kept
+                .sort((a, b) => degreeOf(b) - degreeOf(a) || a.localeCompare(b))
+                .slice(0, maxNodes);
+        }
+    }
+    const keptSet = new Set(kept);
+    const labelToId = new Map();
+    const nodes = [...kept]
+        .sort((a, b) => a.localeCompare(b))
+        .map((label, i) => {
+        const id = sanitizeId(label, i);
+        labelToId.set(label, id);
+        const top = label === '(root)' ? 'root' : label.split('/')[0];
+        return { id, label, group: top };
+    });
+    const edges = [];
+    for (const [key, w] of [...built.edges.entries()].sort((x, y) => x[0].localeCompare(y[0]))) {
+        const [a, b] = key.split(EDGE_SEP);
+        if (!keptSet.has(a) || !keptSet.has(b)) {
+            truncated = true;
+            continue;
+        }
+        edges.push({ from: labelToId.get(a), to: labelToId.get(b), weight: w });
+    }
+    const ranked = opts.salience ? ' Truncation is salience-ranked (ADR-0004).' : '';
+    return {
+        kind: 'module',
+        title: `Module dependency graph (depth ${depth})`,
+        nodes,
+        edges,
+        truncated,
+        note: 'Directory-collapsed internal import graph (regex-extracted static imports; ' +
+            'relative edges only). External packages and dynamic imports are excluded by ' +
+            `design.${ranked}`,
+    };
+}
+//# sourceMappingURL=moduleGraph.js.map

package/dist/core/graph/moduleGraph.js.map

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

package/dist/core/graph/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Graph engine model (v0.5.0). Graphs are deliberately *collapsed* and *capped*: a
+ * per-file dependency graph on a real repo is an unreadable hairball and overruns
+ * Mermaid's practical limits. The valuable artifact is a directory-granularity graph
+ * an engineer can actually read, so that is what we build and cache.
+ */
+export type GraphKind = 'module' | 'service' | 'architecture' | 'pipeline';
+export interface GraphNode {
+    /** Mermaid-safe identifier. */
+    id: string;
+    label: string;
+    /** Optional grouping/styling hint. */
+    group?: string;
+}
+export interface GraphEdge {
+    from: string;
+    to: string;
+    /** Number of underlying file-level edges this collapsed edge represents. */
+    weight?: number;
+    label?: string;
+}
+export interface RepoGraph {
+    kind: GraphKind;
+    title: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    /** True if nodes/edges were capped — the graph is then a partial view. */
+    truncated: boolean;
+    /** Honest one-line description of how this graph was derived and its limits. */
+    note: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/graph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAE3E,MAAM,WAAW,SAAS;IACxB,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/core/graph/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/graph/types.ts"],"names":[],"mappings":""}

package/dist/core/query/queryEngine.d.ts

@@ -0,0 +1,26 @@
+import type { KairoEvent, AuditEntry } from '../../types/events.js';
+import type { Checkpoint } from '../../types/domain.js';
+import type { CausalityResult, ConflictEntry, EventFilter, LineageNode, RetrievalTrace, TimelineEntry, TimelineKind, UnifiedEvent } from './types.js';
+import type { TelemetryEvent } from '../telemetry/types.js';
+/**
+ * Pure deterministic query primitives (ADR-0009). The same inputs always produce
+ * identical output — stable ts-only sort preserves append/causal order, as we
+ * learned in v0.7.0. Namespace isolation is enforced here: caller-namespace
+ * filtering matches the retrieval-isolation discipline.
+ */
+export interface QueryInputs {
+    events: KairoEvent[];
+    telemetry: TelemetryEvent[];
+    audit: AuditEntry[];
+    /** Resolve worker by sessionId via `worker.registered`. */
+    sessionToWorker: Map<string, string>;
+}
+export declare function buildSessionToWorker(events: KairoEvent[]): Map<string, string>;
+export declare function queryEvents(filter: EventFilter, inputs: QueryInputs): UnifiedEvent[];
+export declare function timeline(kind: TimelineKind, inputs: QueryInputs, callerNamespace?: string): TimelineEntry[];
+export declare function checkpointLineage(checkpointId: string, loadCheckpoint: (id: string) => Promise<Checkpoint | undefined>): Promise<LineageNode[]>;
+export declare function conflictHistory(inputs: QueryInputs, callerNamespace?: string): ConflictEntry[];
+export declare function retrievalTrace(retrievalEventId: string, inputs: QueryInputs, callerNamespace?: string): RetrievalTrace | undefined;
+/** "Why was this guard.hold (or any event) emitted?" — immediate preceding causes. */
+export declare function whyEvent(eventId: string, inputs: QueryInputs, callerNamespace?: string): CausalityResult | undefined;
+//# sourceMappingURL=queryEngine.d.ts.map

package/dist/core/query/queryEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryEngine.d.ts","sourceRoot":"","sources":["../../../src/core/query/queryEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,2DAA2D;IAC3D,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAoCD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAS9E;AAsDD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,EAAE,CAcpF;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,WAAW,EACnB,eAAe,CAAC,EAAE,MAAM,GACvB,aAAa,EAAE,CA4CjB;AAED,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,GAC9D,OAAO,CAAC,WAAW,EAAE,CAAC,CAExB;AAuBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CA4B9F;AAED,wBAAgB,cAAc,CAC5B,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,WAAW,EACnB,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,GAAG,SAAS,CAiB5B;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,EACnB,eAAe,CAAC,EAAE,MAAM,GACvB,eAAe,GAAG,SAAS,CAgC7B"}

package/dist/core/query/queryEngine.js

@@ -0,0 +1,258 @@
+function unifyEvent(e, worker) {
+    return {
+        source: 'event',
+        id: e.id,
+        ts: e.ts,
+        kind: e.type,
+        sessionId: e.sessionId,
+        ...(worker ? { worker } : {}),
+        data: e.payload ?? {},
+    };
+}
+function unifyTelemetry(t) {
+    return {
+        source: 'telemetry',
+        id: t.id,
+        ts: t.ts,
+        kind: t.kind,
+        sessionId: t.sessionId,
+        worker: t.worker,
+        namespace: t.namespace,
+        data: t.data,
+    };
+}
+function unifyAudit(a, idx) {
+    return {
+        source: 'audit',
+        id: `audit-${idx}`,
+        ts: a.ts,
+        kind: `audit.${a.kind}`,
+        sessionId: '',
+        data: { message: a.message, ...(a.details ?? {}) },
+    };
+}
+export function buildSessionToWorker(events) {
+    const m = new Map();
+    for (const e of events) {
+        if (e.type === 'worker.registered') {
+            const p = e.payload;
+            if (p.workerId)
+                m.set(e.sessionId, p.workerId);
+        }
+    }
+    return m;
+}
+/** Safe string coercion for unknown telemetry/event payload values. */
+function sval(v) {
+    if (typeof v === 'string')
+        return v;
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return JSON.stringify(v);
+}
+function kindMatches(kind, patterns) {
+    for (const p of patterns) {
+        if (p.endsWith('*')) {
+            if (kind.startsWith(p.slice(0, -1)))
+                return true;
+        }
+        else if (kind === p)
+            return true;
+    }
+    return false;
+}
+function unify(inputs) {
+    const out = [
+        ...inputs.events.map((e) => unifyEvent(e, inputs.sessionToWorker.get(e.sessionId))),
+        ...inputs.telemetry.map(unifyTelemetry),
+        ...inputs.audit.map((a, i) => unifyAudit(a, i)),
+    ];
+    // Stable ts-only sort keeps append/causal order on equal timestamps (ADR-0007).
+    out.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+    return out;
+}
+/**
+ * Coordination telemetry kinds carry only shared metadata (scope/holder/risk-level)
+ * and **no private content**, so they are visible to every worker regardless of the
+ * emitting worker's namespace tag. Worker-private kinds (memory.refreshed,
+ * retrieval.performed, risk.assessed, guard.hold) remain isolated.
+ */
+const SHARED_KINDS = new Set([
+    'session.started',
+    'session.ended',
+    'checkpoint.created',
+    'lease.granted',
+    'lease.denied',
+    'release.prepared',
+    'worker.registered',
+]);
+/** Namespace-safe visibility filter: workspace + caller's own namespace + shared. */
+function visible(e, ns) {
+    if (!ns)
+        return true;
+    if (!e.namespace || e.namespace === 'workspace')
+        return true;
+    if (SHARED_KINDS.has(e.kind))
+        return true;
+    return e.namespace === ns;
+}
+export function queryEvents(filter, inputs) {
+    const sources = new Set(filter.sources ?? ['event', 'telemetry', 'audit']);
+    const sIds = filter.sessionIds ? new Set(filter.sessionIds) : undefined;
+    const workers = filter.workers ? new Set(filter.workers) : undefined;
+    const limit = filter.limit === 0 ? Infinity : (filter.limit ?? 100);
+    let out = unify(inputs).filter((e) => sources.has(e.source));
+    if (filter.kinds && filter.kinds.length > 0)
+        out = out.filter((e) => kindMatches(e.kind, filter.kinds));
+    if (sIds)
+        out = out.filter((e) => sIds.has(e.sessionId));
+    if (workers)
+        out = out.filter((e) => e.worker !== undefined && workers.has(e.worker));
+    if (filter.since)
+        out = out.filter((e) => e.ts >= filter.since);
+    if (filter.until)
+        out = out.filter((e) => e.ts <= filter.until);
+    out = out.filter((e) => visible(e, filter.callerNamespace));
+    return out.slice(0, limit);
+}
+export function timeline(kind, inputs, callerNamespace) {
+    const pool = unify(inputs).filter((e) => visible(e, callerNamespace));
+    const entry = (e, summary) => ({
+        ts: e.ts,
+        kind,
+        sessionId: e.sessionId,
+        ...(e.worker ? { worker: e.worker } : {}),
+        summary,
+        data: e.data,
+    });
+    switch (kind) {
+        case 'sessions':
+            return pool
+                .filter((e) => e.kind === 'session.started' || e.kind === 'session.ended')
+                .map((e) => entry(e, e.kind === 'session.started' ? `start: ${sval(e.data.task)}`.trim() : 'end'));
+        case 'checkpoints':
+            return pool
+                .filter((e) => e.source === 'telemetry' && e.kind === 'checkpoint.created')
+                .map((e) => entry(e, `checkpoint (${String(e.data.reason)}, risk ${String(e.data.risk)})`));
+        case 'lease-conflicts':
+            return pool
+                .filter((e) => e.kind === 'lease.denied' || e.kind === 'lease.granted')
+                .map((e) => entry(e, `${e.kind === 'lease.denied' ? 'DENIED' : 'GRANTED'} ${String(e.data.scopeKind)}:${String(e.data.scope)}` +
+                (e.kind === 'lease.denied' ? ` held by ${String(e.data.holder)}` : '')));
+        case 'retrievals':
+            return pool
+                .filter((e) => e.kind === 'retrieval.performed')
+                .map((e) => entry(e, `retrieval: ${String(e.data.results)} results (top ${String(e.data.topKind)})`));
+        case 'memory-refresh':
+            return pool
+                .filter((e) => e.kind === 'memory.refreshed')
+                .map((e) => entry(e, `${e.data.rebuilt ? 'rebuilt' : 'reused'} (${String(e.data.chunks)} chunks)`));
+    }
+}
+export function checkpointLineage(checkpointId, loadCheckpoint) {
+    return walk(checkpointId, loadCheckpoint, []);
+}
+async function walk(id, load, acc) {
+    if (!id)
+        return acc;
+    const cp = await load(id);
+    if (!cp)
+        return acc;
+    const node = {
+        id: cp.id,
+        createdAt: cp.createdAt,
+        workerId: cp.ownerWorkerId ?? cp.agent,
+        task: cp.task,
+        reason: cp.reason,
+        riskLevel: cp.risk.level,
+        ...(cp.parentCheckpointId ? { parentId: cp.parentCheckpointId } : {}),
+    };
+    acc.unshift(node); // root-first order
+    return walk(cp.parentCheckpointId, load, acc);
+}
+export function conflictHistory(inputs, callerNamespace) {
+    const tel = unify(inputs).filter((e) => visible(e, callerNamespace));
+    const granted = tel.filter((e) => e.kind === 'lease.granted');
+    return tel
+        .filter((e) => e.kind === 'lease.denied')
+        .map((d) => {
+        const scope = String(d.data.scope);
+        const scopeKind = String(d.data.scopeKind);
+        const holder = sval(d.data.holder);
+        const prior = granted
+            .filter((g) => String(g.data.scope) === scope &&
+            String(g.data.scopeKind) === scopeKind &&
+            g.worker === holder &&
+            g.ts <= d.ts)
+            .pop();
+        const out = {
+            deniedAt: d.ts,
+            scopeKind,
+            scope,
+            deniedWorker: d.worker ?? '?',
+            holder,
+        };
+        if (prior?.ts)
+            out.holderGrantedAt = prior.ts;
+        return out;
+    });
+}
+export function retrievalTrace(retrievalEventId, inputs, callerNamespace) {
+    const all = unify(inputs).filter((e) => visible(e, callerNamespace));
+    const r = all.find((e) => e.id === retrievalEventId && e.kind === 'retrieval.performed');
+    if (!r)
+        return undefined;
+    const before = all.filter((e) => e.ts <= r.ts);
+    const last = (kind, sameSession = true) => [...before]
+        .reverse()
+        .find((e) => e.kind === kind && (!sameSession || e.sessionId === r.sessionId));
+    const out = { retrieval: r };
+    const s = last('session.started');
+    const m = last('memory.refreshed');
+    const c = last('checkpoint.created', false); // shared continuity
+    if (s)
+        out.precedingSessionStart = s;
+    if (m)
+        out.latestMemoryRefresh = m;
+    if (c)
+        out.latestCheckpointBefore = c;
+    return out;
+}
+/** "Why was this guard.hold (or any event) emitted?" — immediate preceding causes. */
+export function whyEvent(eventId, inputs, callerNamespace) {
+    const all = unify(inputs).filter((e) => visible(e, callerNamespace));
+    const target = all.find((e) => e.id === eventId);
+    if (!target)
+        return undefined;
+    const sameSessionBefore = all.filter((e) => e.sessionId === target.sessionId && e.ts <= target.ts && e.id !== target.id);
+    let causes = [];
+    if (target.kind === 'guard.hold') {
+        const r = [...sameSessionBefore].reverse().find((e) => e.kind === 'risk.assessed');
+        if (r)
+            causes.push(r);
+    }
+    else if (target.kind === 'risk.assessed') {
+        causes = sameSessionBefore
+            .filter((e) => ['session.started', 'checkpoint.created', 'memory.refreshed'].includes(e.kind))
+            .slice(-3);
+    }
+    else if (target.kind === 'lease.denied') {
+        const holder = sval(target.data.holder);
+        const scope = String(target.data.scope);
+        const prior = all
+            .filter((e) => e.kind === 'lease.granted' &&
+            e.worker === holder &&
+            String(e.data.scope) === scope &&
+            e.ts <= target.ts)
+            .pop();
+        if (prior)
+            causes.push(prior);
+    }
+    else {
+        causes = sameSessionBefore.slice(-3);
+    }
+    return { target, precedingCauses: causes };
+}
+//# sourceMappingURL=queryEngine.js.map