byterover-cli 3.2.0 → 3.4.0

package/dist/agent/infra/swarm/swarm-coordinator.js

@@ -0,0 +1,436 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { SwarmGraph } from './swarm-graph.js';
+import { mergeResults } from './swarm-merger.js';
+import { classifyQuery, selectProviders } from './swarm-router.js';
+import { classifyWrite, selectWriteTarget } from './swarm-write-router.js';
+const execFileAsync = promisify(execFileCb);
+const MAX_ARG_LENGTH = 200_000; // ~200KB safe for most OS arg limits
+async function execBrvCurate(content) {
+    if (content.length > MAX_ARG_LENGTH) {
+        throw new Error(`Content too large for CLI argument (${content.length} bytes, max ${MAX_ARG_LENGTH}). Use brv curate directly.`);
+    }
+    let stdout;
+    try {
+        ;
+        ({ stdout } = await execFileAsync('brv', ['curate', '--detach', '--format', 'json', content], {
+            encoding: 'utf8',
+            timeout: 30_000,
+        }));
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            const stderr = error.stderr?.trim();
+            throw new Error(stderr ?? error.message);
+        }
+        throw new Error(String(error));
+    }
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`Failed to parse brv curate output: ${stdout.slice(0, 200)}`);
+    }
+}
+/**
+ * Default provider weights for RRF fusion.
+ * ByteRover (home provider) gets highest weight.
+ */
+const DEFAULT_WEIGHTS = {
+    byterover: 1,
+    gbrain: 0.85,
+    hindsight: 0.8,
+    honcho: 0.75,
+    'local-markdown': 0.8,
+    'memory-wiki': 0.9,
+    obsidian: 0.85,
+};
+/**
+ * Resolves the weight for a provider ID.
+ * Supports prefixed IDs like `local-markdown:notes` → matches `local-markdown`.
+ */
+function resolveWeight(providerId) {
+    if (DEFAULT_WEIGHTS[providerId] !== undefined) {
+        return DEFAULT_WEIGHTS[providerId];
+    }
+    // Try prefix match (e.g., local-markdown:notes → local-markdown)
+    for (const [key, weight] of Object.entries(DEFAULT_WEIGHTS)) {
+        if (providerId.startsWith(`${key}:`)) {
+            return weight;
+        }
+    }
+    return 0.5;
+}
+/**
+ * Expand generic provider names in enrichment edges to concrete provider IDs,
+ * then deduplicate and drop self-edges and cycles.
+ *
+ * Config edges may use "local-markdown" as a shorthand, but actual providers
+ * are registered as "local-markdown:notes", "local-markdown:docs", etc.
+ * This function expands each generic endpoint to all matching concrete IDs,
+ * removes duplicates and self-edges, and detects/drops cycles.
+ */
+function expandEnrichmentEdges(configEdges, providerIds) {
+    // 1. Expand generic endpoints to concrete IDs
+    const seen = new Set();
+    const expanded = [];
+    for (const edge of configEdges) {
+        const fromIds = resolveEndpoint(edge.from, providerIds);
+        const toIds = resolveEndpoint(edge.to, providerIds);
+        for (const from of fromIds) {
+            for (const to of toIds) {
+                // Drop self-edges
+                if (from === to)
+                    continue;
+                // Deduplicate
+                const key = `${from}->${to}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                expanded.push({ from, to });
+            }
+        }
+    }
+    // 2. Drop all edges if the expanded graph has cycles
+    if (hasCycleInEdges(expanded)) {
+        return [];
+    }
+    return expanded;
+}
+/**
+ * Detect cycles in an edge list using DFS.
+ */
+function hasCycleInEdges(edges) {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        const existing = adjacency.get(edge.from) ?? [];
+        existing.push(edge.to);
+        adjacency.set(edge.from, existing);
+    }
+    const visited = new Set();
+    const inStack = new Set();
+    function dfs(node) {
+        if (inStack.has(node))
+            return true;
+        if (visited.has(node))
+            return false;
+        visited.add(node);
+        inStack.add(node);
+        for (const neighbor of adjacency.get(node) ?? []) {
+            if (dfs(neighbor))
+                return true;
+        }
+        inStack.delete(node);
+        return false;
+    }
+    const allNodes = new Set([...edges.map((e) => e.from), ...edges.map((e) => e.to)]);
+    for (const node of allNodes) {
+        if (dfs(node))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve a config endpoint to one or more concrete provider IDs.
+ * Prefers prefix expansion over exact match so "local-markdown" expands to
+ * concrete folder IDs rather than staying generic.
+ */
+function resolveEndpoint(endpoint, providerIds) {
+    // Prefer prefix expansion: "local-markdown" → ["local-markdown:notes", "local-markdown:docs"]
+    const prefixMatches = providerIds.filter((id) => id.startsWith(`${endpoint}:`));
+    if (prefixMatches.length > 0)
+        return prefixMatches;
+    // Exact match (for providers without sub-IDs like "obsidian", "byterover")
+    if (providerIds.includes(endpoint))
+        return [endpoint];
+    // No match — return as-is (will be a no-op in the graph, but doesn't crash)
+    return [endpoint];
+}
+export class SwarmCoordinator {
+    config;
+    curateFallback;
+    graph;
+    healthCache = new Map();
+    maxCacheSize = 20;
+    providers;
+    resultCache = new Map();
+    resultCacheTtlMs;
+    totalQueries = 0;
+    constructor(providers, config, curateFallback) {
+        this.providers = providers;
+        this.config = config;
+        this.curateFallback = curateFallback ?? execBrvCurate;
+        this.resultCacheTtlMs = config.performance.resultCacheTtlMs ?? 10_000;
+        this.graph = new SwarmGraph(providers, {
+            timeoutMs: config.performance.maxQueryLatencyMs,
+        });
+        // Wire enrichment edges from config into the graph engine.
+        // Expand generic provider names (e.g. "local-markdown") to concrete IDs
+        // (e.g. "local-markdown:notes", "local-markdown:docs") so the graph can match them.
+        const configEdges = config.enrichment?.edges ?? [];
+        if (configEdges.length > 0) {
+            const providerIds = providers.map((p) => p.id);
+            const expanded = expandEnrichmentEdges(configEdges, providerIds);
+            this.graph.setEnrichmentEdges(expanded);
+        }
+        // Initialize health cache — assume all healthy until checked
+        for (const p of providers) {
+            this.healthCache.set(p.id, true);
+        }
+    }
+    /**
+     * Execute a swarm query: classify → select providers → execute in parallel → fuse results.
+     */
+    async execute(request) {
+        // Cache check — return early if identical query was recently executed
+        const cacheKey = this.buildCacheKey(request);
+        const cached = this.resultCache.get(cacheKey);
+        if (cached) {
+            if (Date.now() - cached.timestamp < this.resultCacheTtlMs) {
+                // Move to end for LRU semantics
+                this.resultCache.delete(cacheKey);
+                this.resultCache.set(cacheKey, cached);
+                this.totalQueries++;
+                return { ...cached.result, results: cached.result.results.map((r) => ({ ...r, metadata: { ...r.metadata } })) };
+            }
+            // Expired — clean up stale entry
+            this.resultCache.delete(cacheKey);
+        }
+        const start = Date.now();
+        // 1. Classify query type
+        const queryType = request.type ?? classifyQuery(request.query);
+        // 2. Select active providers based on query type, excluding unhealthy ones
+        const healthyIds = this.providers.filter((p) => this.healthCache.get(p.id) !== false).map((p) => p.id);
+        const activeIds = selectProviders(queryType, healthyIds);
+        // 3. Estimate total cost
+        let costCents = 0;
+        for (const id of activeIds) {
+            const provider = this.providers.find((p) => p.id === id);
+            if (provider) {
+                costCents += provider.estimateCost(request).estimatedCostCents;
+            }
+        }
+        // 4. Execute via SwarmGraph (parallel with timeout)
+        const resultSets = await this.graph.execute(request, activeIds);
+        // 5. Build provider weights map
+        const weights = new Map();
+        for (const id of activeIds) {
+            weights.set(id, resolveWeight(id));
+        }
+        // 6. Fuse results via RRF merger
+        const maxResults = request.maxResults ?? this.config.routing.defaultMaxResults;
+        const merged = mergeResults(resultSets, weights, {
+            K: this.config.routing.rrfK,
+            maxResults,
+            minRRFScore: this.config.routing.minRrfScore,
+            rrfGapRatio: this.config.routing.rrfGapRatio,
+        });
+        // 7. Collect execution metadata from graph
+        const graphMeta = this.graph.getLastExecutionMeta();
+        const providerMeta = { ...graphMeta?.providers };
+        // 8. Record excluded providers (available but not selected by the routing matrix).
+        // Note: healthCache.get() returns undefined for unchecked providers, which is
+        // intentionally treated as healthy (!== false) — providers start healthy until proven otherwise.
+        const activeSet = new Set(activeIds);
+        for (const p of this.providers) {
+            if (!activeSet.has(p.id) && !providerMeta[p.id]) {
+                const healthy = this.healthCache.get(p.id) !== false;
+                providerMeta[p.id] = {
+                    excludeReason: healthy ? `not in selection matrix for ${queryType}` : 'unhealthy',
+                    latencyMs: 0,
+                    resultCount: 0,
+                    selected: false,
+                };
+            }
+        }
+        this.totalQueries++;
+        const result = {
+            meta: {
+                costCents,
+                providers: providerMeta,
+                queryType,
+                totalLatencyMs: Date.now() - start,
+            },
+            results: merged,
+        };
+        // Cache store — deep-clone to prevent mutation of cached data via returned references
+        if (this.resultCacheTtlMs > 0) {
+            this.resultCache.set(cacheKey, {
+                result: { ...result, results: result.results.map((r) => ({ ...r, metadata: { ...r.metadata } })) },
+                timestamp: Date.now(),
+            });
+            this.evictIfOverSize();
+        }
+        return result;
+    }
+    /**
+     * Get info about all registered providers and their cached health status.
+     */
+    getActiveProviders() {
+        return this.providers.map((p) => ({
+            capabilities: p.capabilities,
+            healthy: this.healthCache.get(p.id) ?? true,
+            id: p.id,
+            type: p.type,
+        }));
+    }
+    /**
+     * Get a presentation-oriented summary of the swarm state.
+     */
+    getSummary() {
+        const providerInfos = this.providers.map((p) => ({
+            capabilities: p.capabilities,
+            healthy: this.healthCache.get(p.id) ?? true,
+            id: p.id,
+            type: p.type,
+        }));
+        const activeCount = providerInfos.filter((p) => p.healthy).length;
+        const avgLatencyMs = this.providers.length > 0
+            ? this.providers.reduce((sum, p) => sum + p.capabilities.avgLatencyMs, 0) / this.providers.length
+            : 0;
+        return {
+            activeCount,
+            avgLatencyMs,
+            learningStatus: 'cold-start',
+            monthlyBudgetCents: this.config.budget?.globalMonthlyCapCents ?? 0,
+            monthlySpendCents: 0,
+            providers: providerInfos,
+            totalCount: this.providers.length,
+            totalQueries: this.totalQueries,
+        };
+    }
+    /**
+     * Run health checks on all providers and update the cache.
+     */
+    async refreshHealth() {
+        const results = await Promise.all(this.providers.map(async (p) => {
+            const health = await p.healthCheck();
+            this.healthCache.set(p.id, health.available);
+            return {
+                capabilities: p.capabilities,
+                healthy: health.available,
+                id: p.id,
+                type: p.type,
+            };
+        }));
+        this.resultCache.clear();
+        return results;
+    }
+    /**
+     * Store knowledge in the best writable provider.
+     *
+     * Routing:
+     * 1. If request.provider is set → use that provider (verify writable + healthy)
+     * 2. If request.contentType is set → use it as write type (skip classification)
+     * 3. Otherwise → classifyWrite(content) → selectWriteTarget()
+     */
+    async store(request) {
+        const start = Date.now();
+        let target;
+        if (request.provider) {
+            // Explicit provider target
+            const provider = this.providers.find((p) => p.id === request.provider);
+            if (!provider) {
+                return {
+                    error: `Provider '${request.provider}' not found`,
+                    id: '',
+                    latencyMs: 0,
+                    provider: request.provider,
+                    success: false,
+                };
+            }
+            if (!provider.capabilities.writeSupported) {
+                return {
+                    error: `Provider '${request.provider}' does not support writes`,
+                    id: '',
+                    latencyMs: 0,
+                    provider: request.provider,
+                    success: false,
+                };
+            }
+            if (this.healthCache.get(provider.id) === false) {
+                return {
+                    error: `Provider '${request.provider}' is not healthy`,
+                    id: '',
+                    latencyMs: 0,
+                    provider: request.provider,
+                    success: false,
+                };
+            }
+            target = provider;
+        }
+        else {
+            // Auto-route: classify content type, then select target
+            const writeType = request.contentType ?? classifyWrite(request.content);
+            const selected = selectWriteTarget(writeType, this.providers, this.healthCache);
+            if (!selected) {
+                return this.fallbackToByterover(request, start);
+            }
+            target = selected;
+        }
+        try {
+            const result = await target.store({
+                content: request.content,
+                metadata: {
+                    source: 'swarm-curate',
+                    timestamp: Date.now(),
+                },
+            });
+            if (result.success) {
+                this.resultCache.clear();
+            }
+            return {
+                id: result.id,
+                latencyMs: Date.now() - start,
+                provider: target.id,
+                success: result.success,
+            };
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : String(error),
+                id: '',
+                latencyMs: Date.now() - start,
+                provider: target.id,
+                success: false,
+            };
+        }
+    }
+    buildCacheKey(request) {
+        const q = request.query.toLowerCase().trim().replaceAll(/\s+/g, ' ');
+        const scope = request.scope ?? '';
+        const max = request.maxResults ?? this.config.routing.defaultMaxResults;
+        return JSON.stringify([q, scope, max, request.type, request.timeRange]);
+    }
+    evictIfOverSize() {
+        if (this.resultCache.size <= this.maxCacheSize)
+            return;
+        const firstKey = this.resultCache.keys().next().value;
+        if (firstKey !== undefined) {
+            this.resultCache.delete(firstKey);
+        }
+    }
+    async fallbackToByterover(request, start) {
+        try {
+            const parsed = await this.curateFallback(request.content);
+            return {
+                error: parsed.success === true ? undefined : (parsed.error ?? 'brv curate returned success: false'),
+                fallback: true,
+                id: parsed.data?.logId ?? parsed.data?.taskId ?? '',
+                latencyMs: Date.now() - start,
+                provider: 'byterover',
+                success: parsed.success === true,
+            };
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : String(error),
+                fallback: true,
+                id: '',
+                latencyMs: Date.now() - start,
+                provider: 'byterover',
+                success: false,
+            };
+        }
+    }
+}

package/dist/agent/infra/swarm/swarm-graph.d.ts

@@ -0,0 +1,63 @@
+import type { QueryRequest, QueryResult } from '../../core/domain/swarm/types.js';
+import type { IMemoryProvider } from '../../core/interfaces/i-memory-provider.js';
+import type { ProviderQueryMeta } from '../../core/interfaces/i-swarm-coordinator.js';
+/**
+ * Per-provider execution metadata from the last query.
+ */
+export type GraphExecutionMeta = {
+    providers: Record<string, ProviderQueryMeta>;
+    totalLatencyMs: number;
+};
+/**
+ * Options for the swarm graph.
+ */
+export type SwarmGraphOptions = {
+    /** Timeout per provider in milliseconds (default: 2000) */
+    timeoutMs?: number;
+};
+/**
+ * An enrichment edge: provider `from` feeds results to provider `to`.
+ */
+export type EnrichmentEdge = {
+    from: string;
+    to: string;
+};
+/**
+ * Swarm Graph — executes providers in topological levels with enrichment chains.
+ *
+ * Level 0: providers with no incoming enrichment edges (run in parallel).
+ * Level 1+: providers that depend on earlier-level results (run after predecessors complete).
+ *
+ * Supports arbitrary DAG depth (A→B→C) and fan-in (A→C, B→C).
+ * Fan-in nodes receive merged enrichment from ALL predecessors.
+ */
+export declare class SwarmGraph {
+    private edges;
+    private lastMeta?;
+    private readonly providerMap;
+    private readonly timeoutMs;
+    constructor(providers: IMemoryProvider[], options?: SwarmGraphOptions);
+    /**
+     * Execute a query across the specified active providers.
+     * Providers are grouped into topological levels based on enrichment edges.
+     * Level-0 runs in parallel; level-1+ providers receive enrichment from predecessors.
+     */
+    execute(request: QueryRequest, activeProviderIds: string[]): Promise<Map<string, QueryResult[]>>;
+    /**
+     * Get execution metadata from the last query.
+     */
+    getLastExecutionMeta(): GraphExecutionMeta | undefined;
+    /**
+     * Configure enrichment edges between providers.
+     * An edge { from: 'A', to: 'B' } means B runs after A and receives A's results.
+     */
+    setEnrichmentEdges(edges: EnrichmentEdge[]): void;
+    /**
+     * Compute topological execution levels using Kahn's algorithm.
+     *
+     * Supports arbitrary DAG depth (A→B→C→...) and fan-in (A→C, B→C).
+     * Returns levels grouped for parallel execution and a map of
+     * provider ID → ALL predecessor IDs that feed it enrichment.
+     */
+    private buildExecutionLevels;
+}

package/dist/agent/infra/swarm/swarm-graph.js

@@ -0,0 +1,167 @@
+/**
+ * Execute a query against a provider with a timeout.
+ * Returns empty results if the provider times out or throws.
+ */
+async function queryWithTimeout(provider, request, timeoutMs) {
+    const start = Date.now();
+    try {
+        const result = await Promise.race([
+            provider.query(request),
+            new Promise((_resolve, reject) => {
+                setTimeout(() => { reject(new Error(`Provider ${provider.id} timed out after ${timeoutMs}ms`)); }, timeoutMs);
+            }),
+        ]);
+        return { latencyMs: Date.now() - start, results: result };
+    }
+    catch {
+        return { latencyMs: Date.now() - start, results: [] };
+    }
+}
+/**
+ * Build enrichment data by merging results from multiple predecessor providers.
+ */
+function buildEnrichment(allResults) {
+    const excerpts = allResults
+        .map((r) => r.content)
+        .filter((c) => c.length > 0);
+    return { excerpts };
+}
+/**
+ * Swarm Graph — executes providers in topological levels with enrichment chains.
+ *
+ * Level 0: providers with no incoming enrichment edges (run in parallel).
+ * Level 1+: providers that depend on earlier-level results (run after predecessors complete).
+ *
+ * Supports arbitrary DAG depth (A→B→C) and fan-in (A→C, B→C).
+ * Fan-in nodes receive merged enrichment from ALL predecessors.
+ */
+export class SwarmGraph {
+    edges = [];
+    lastMeta;
+    providerMap;
+    timeoutMs;
+    constructor(providers, options) {
+        this.providerMap = new Map(providers.map((p) => [p.id, p]));
+        this.timeoutMs = options?.timeoutMs ?? 2000;
+    }
+    /**
+     * Execute a query across the specified active providers.
+     * Providers are grouped into topological levels based on enrichment edges.
+     * Level-0 runs in parallel; level-1+ providers receive enrichment from predecessors.
+     */
+    async execute(request, activeProviderIds) {
+        const start = Date.now();
+        const results = new Map();
+        const providerMeta = {};
+        const activeSet = new Set(activeProviderIds);
+        // Build execution levels
+        const { levels, predecessors } = this.buildExecutionLevels(activeSet);
+        // Execute each level sequentially; providers within a level run in parallel
+        for (const level of levels) {
+            const executions = level
+                .map((id) => {
+                const provider = this.providerMap.get(id);
+                if (!provider)
+                    return;
+                // Build enriched request by merging results from ALL predecessors
+                let enrichedRequest = request;
+                let enrichmentForMeta;
+                const predIds = predecessors.get(id);
+                if (predIds && predIds.length > 0) {
+                    const allPredResults = [];
+                    for (const predId of predIds) {
+                        const predResults = results.get(predId);
+                        if (predResults) {
+                            allPredResults.push(...predResults);
+                        }
+                    }
+                    if (allPredResults.length > 0) {
+                        enrichmentForMeta = buildEnrichment(allPredResults);
+                        enrichedRequest = {
+                            ...request,
+                            enrichment: enrichmentForMeta,
+                        };
+                    }
+                }
+                return queryWithTimeout(provider, enrichedRequest, this.timeoutMs).then((outcome) => {
+                    results.set(id, outcome.results);
+                    providerMeta[id] = {
+                        enrichedBy: predIds && predIds.length > 0 ? predIds.join(',') : undefined,
+                        enrichmentExcerpts: enrichmentForMeta?.excerpts?.slice(0, 10).map((k) => k.split(/\s+/).slice(0, 5).join(' ')),
+                        latencyMs: outcome.latencyMs,
+                        resultCount: outcome.results.length,
+                        selected: true,
+                    };
+                });
+            })
+                .filter(Boolean);
+            // eslint-disable-next-line no-await-in-loop -- levels must run sequentially
+            await Promise.all(executions);
+        }
+        this.lastMeta = {
+            providers: providerMeta,
+            totalLatencyMs: Date.now() - start,
+        };
+        return results;
+    }
+    /**
+     * Get execution metadata from the last query.
+     */
+    getLastExecutionMeta() {
+        return this.lastMeta;
+    }
+    /**
+     * Configure enrichment edges between providers.
+     * An edge { from: 'A', to: 'B' } means B runs after A and receives A's results.
+     */
+    setEnrichmentEdges(edges) {
+        this.edges = edges;
+    }
+    /**
+     * Compute topological execution levels using Kahn's algorithm.
+     *
+     * Supports arbitrary DAG depth (A→B→C→...) and fan-in (A→C, B→C).
+     * Returns levels grouped for parallel execution and a map of
+     * provider ID → ALL predecessor IDs that feed it enrichment.
+     */
+    buildExecutionLevels(activeSet) {
+        // Filter edges to only active providers on both sides
+        const activeEdges = this.edges.filter((e) => activeSet.has(e.from) && activeSet.has(e.to));
+        // Build the predecessors map (to → [from1, from2, ...])
+        const predecessors = new Map();
+        for (const edge of activeEdges) {
+            const existing = predecessors.get(edge.to) ?? [];
+            existing.push(edge.from);
+            predecessors.set(edge.to, existing);
+        }
+        // Build in-degree counts and adjacency list
+        const inDegree = new Map();
+        const successors = new Map();
+        for (const id of activeSet) {
+            inDegree.set(id, 0);
+            successors.set(id, []);
+        }
+        for (const edge of activeEdges) {
+            inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+            successors.get(edge.from).push(edge.to);
+        }
+        // Kahn's algorithm: peel off nodes with in-degree 0, level by level
+        const levels = [];
+        let currentLevel = [...activeSet].filter((id) => inDegree.get(id) === 0);
+        while (currentLevel.length > 0) {
+            levels.push(currentLevel);
+            const nextLevel = [];
+            for (const id of currentLevel) {
+                for (const succ of successors.get(id) ?? []) {
+                    const newDegree = (inDegree.get(succ) ?? 1) - 1;
+                    inDegree.set(succ, newDegree);
+                    if (newDegree === 0) {
+                        nextLevel.push(succ);
+                    }
+                }
+            }
+            currentLevel = nextLevel;
+        }
+        return { levels, predecessors };
+    }
+}

package/dist/agent/infra/swarm/swarm-merger.d.ts

@@ -0,0 +1,29 @@
+import type { QueryResult } from '../../core/domain/swarm/types.js';
+/**
+ * Options for the RRF merger.
+ */
+export type MergerOptions = {
+    /** RRF constant (default: 60) */
+    K?: number;
+    /** Maximum results to return (default: 10) */
+    maxResults?: number;
+    /** T4: Drop results with RRF score below this absolute threshold (RRF-space, not 0-1) */
+    minRRFScore?: number;
+    /** T5: Drop results where rrfScore < topRRF * ratio (0, 1] */
+    rrfGapRatio?: number;
+};
+/**
+ * Fuse results from multiple providers using Weighted Reciprocal Rank Fusion.
+ *
+ * Algorithm:
+ *   RRF_score(r) = Σᵢ wᵢ / (K + rankᵢ(r))
+ *   where wᵢ is the provider weight and rankᵢ(r) is the 0-based rank.
+ *
+ * Deduplication: results with identical content are merged (highest provider weight kept).
+ *
+ * @param resultSets - Map of provider ID → ranked results
+ * @param providerWeights - Map of provider ID → weight (0-1)
+ * @param options - Merger options
+ * @returns Fused, ranked, deduplicated results
+ */
+export declare function mergeResults(resultSets: Map<string, QueryResult[]>, providerWeights: Map<string, number>, options?: MergerOptions): QueryResult[];