byterover-cli 3.3.0 → 3.4.0

package/dist/agent/infra/swarm/config/swarm-config-schema.js

@@ -0,0 +1,305 @@
+/* eslint-disable camelcase -- mapKeys maps on-disk YAML snake_case to camelCase */
+import { z } from 'zod';
+// ============================================================
+// Helper: snake_case → camelCase key mapping
+// ============================================================
+function mapKeys(obj, mapping) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const mappedKey = mapping[key] ?? key;
+        result[mappedKey] = value;
+    }
+    return result;
+}
+// ============================================================
+// Environment variable resolution
+// ============================================================
+/**
+ * Resolve `${VAR}` patterns in a string using the given environment.
+ * Returns the original string if the variable is not found.
+ */
+export function resolveEnvVars(value, env) {
+    return value.replaceAll(/\$\{(\w+)\}/g, (_match, varName) => {
+        const envValue = env[varName];
+        return envValue ?? `\${${varName}}`;
+    });
+}
+// ============================================================
+// Provider sub-schemas
+// ============================================================
+const ByteRoverProviderSchema = z.object({
+    enabled: z.boolean(),
+});
+const ObsidianProviderSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        ignore_patterns: 'ignorePatterns',
+        index_on_startup: 'indexOnStartup',
+        read_only: 'readOnly',
+        vault_path: 'vaultPath',
+        watch_for_changes: 'watchForChanges',
+    });
+}, z.object({
+    enabled: z.boolean(),
+    ignorePatterns: z.array(z.string()).optional(),
+    indexOnStartup: z.boolean().optional().default(true),
+    readOnly: z.boolean().optional().default(true),
+    vaultPath: z.string(),
+    watchForChanges: z.boolean().optional().default(true),
+}));
+const LocalMarkdownFolderSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        follow_wikilinks: 'followWikilinks',
+        read_only: 'readOnly',
+    });
+}, z.object({
+    followWikilinks: z.boolean().optional().default(true),
+    name: z.string(),
+    path: z.string(),
+    readOnly: z.boolean().optional().default(true),
+}));
+const LocalMarkdownProviderSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        watch_for_changes: 'watchForChanges',
+    });
+}, z.object({
+    enabled: z.boolean(),
+    folders: z.array(LocalMarkdownFolderSchema),
+    watchForChanges: z.boolean().optional().default(true),
+}));
+const HonchoProviderSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        api_key: 'apiKey',
+        app_id: 'appId',
+        max_tokens_per_query: 'maxTokensPerQuery',
+        user_id: 'userId',
+    });
+}, z.object({
+    apiKey: z.string(),
+    appId: z.string(),
+    enabled: z.boolean(),
+    maxTokensPerQuery: z.number().int().positive().optional().default(4000),
+    userId: z.string().optional().default('default'),
+}));
+const HindsightProviderSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        cara_params: 'caraParams',
+        connection_string: 'connectionString',
+    });
+}, z.object({
+    caraParams: z.object({
+        empathy: z.number().min(0).max(1).optional().default(0.5),
+        literalism: z.number().min(0).max(1).optional().default(0.5),
+        skepticism: z.number().min(0).max(1).optional().default(0.5),
+    }).optional(),
+    connectionString: z.string(),
+    enabled: z.boolean(),
+    networks: z.array(z.string()).optional().default(['world', 'experience']),
+}));
+const GBrainProviderSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        connection_string: 'connectionString',
+        repo_path: 'repoPath',
+        search_mode: 'searchMode',
+    });
+}, z.object({
+    connectionString: z.string().optional(),
+    enabled: z.boolean(),
+    repoPath: z.string(),
+    searchMode: z.enum(['hybrid', 'keyword', 'vector']).optional().default('hybrid'),
+}));
+const MemoryWikiProviderSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        boost_fresh: 'boostFresh',
+        vault_path: 'vaultPath',
+        write_page_type: 'writePageType',
+    });
+}, z.object({
+    boostFresh: z.boolean().optional().default(true),
+    enabled: z.boolean(),
+    vaultPath: z.string(),
+    writePageType: z.enum(['concept', 'entity']).optional().default('concept'),
+}));
+// ============================================================
+// Top-level sections
+// ============================================================
+const ProvidersSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        local_markdown: 'localMarkdown',
+        memory_wiki: 'memoryWiki',
+    });
+}, z.object({
+    byterover: ByteRoverProviderSchema,
+    gbrain: GBrainProviderSchema.optional(),
+    hindsight: HindsightProviderSchema.optional(),
+    honcho: HonchoProviderSchema.optional(),
+    localMarkdown: LocalMarkdownProviderSchema.optional(),
+    memoryWiki: MemoryWikiProviderSchema.optional(),
+    obsidian: ObsidianProviderSchema.optional(),
+}));
+const RoutingSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        classification_method: 'classificationMethod',
+        default_max_results: 'defaultMaxResults',
+        default_strategy: 'defaultStrategy',
+        min_rrf_score: 'minRrfScore',
+        rrf_gap_ratio: 'rrfGapRatio',
+        rrf_k: 'rrfK',
+    });
+}, z.object({
+    classificationMethod: z.enum(['auto', 'llm']).optional().default('auto'),
+    defaultMaxResults: z.number().int().positive().optional().default(10),
+    defaultStrategy: z.enum(['adaptive', 'all', 'manual']).optional().default('adaptive'),
+    minRrfScore: z.number().min(0).optional().default(0.005),
+    rrfGapRatio: z.number().gt(0).max(1).optional().default(0.5),
+    rrfK: z.number().int().positive().optional().default(60),
+}));
+const PerProviderBudgetSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        max_queries_per_minute: 'maxQueriesPerMinute',
+        monthly_cap_cents: 'monthlyCapCents',
+    });
+}, z.object({
+    maxQueriesPerMinute: z.number().int().positive().optional(),
+    monthlyCapCents: z.number().int().nonnegative(),
+}));
+const BudgetSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        global_monthly_cap_cents: 'globalMonthlyCapCents',
+        per_provider: 'perProvider',
+        warning_threshold_pct: 'warningThresholdPct',
+        weight_reduction_threshold_pct: 'weightReductionThresholdPct',
+    });
+}, z.object({
+    globalMonthlyCapCents: z.number().int().nonnegative().optional().default(5000),
+    perProvider: z.record(PerProviderBudgetSchema).optional(),
+    warningThresholdPct: z.number().int().min(0).max(100).optional().default(80),
+    weightReductionThresholdPct: z.number().int().min(0).max(100).optional().default(90),
+}));
+const OptimizationSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        edge_learning: 'edgeLearning',
+        template_optimization: 'templateOptimization',
+    });
+}, z.object({
+    edgeLearning: z.preprocess((data) => {
+        if (typeof data !== 'object' || data === null)
+            return data;
+        return mapKeys(data, {
+            exploration_rate: 'explorationRate',
+            fix_threshold: 'fixThreshold',
+            min_observations_to_prune: 'minObservationsToPrune',
+            prune_threshold: 'pruneThreshold',
+        });
+    }, z.object({
+        enabled: z.boolean().optional().default(true),
+        explorationRate: z.number().min(0).max(1).optional().default(0.05),
+        fixThreshold: z.number().min(0).max(1).optional().default(0.95),
+        minObservationsToPrune: z.number().int().positive().optional().default(100),
+        pruneThreshold: z.number().min(0).max(1).optional().default(0.05),
+    })).optional().default({}),
+    templateOptimization: z.preprocess((data) => {
+        if (typeof data !== 'object' || data === null)
+            return data;
+        return mapKeys(data, {
+            ab_test_size: 'abTestSize',
+            failure_rate_trigger: 'failureRateTrigger',
+        });
+    }, z.object({
+        abTestSize: z.number().int().positive().optional().default(5),
+        enabled: z.boolean().optional().default(true),
+        failureRateTrigger: z.number().min(0).max(1).optional().default(0.3),
+        frequency: z.number().int().positive().optional().default(20),
+    })).optional().default({}),
+}));
+const ProvenanceSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        full_retention_days: 'fullRetentionDays',
+        keep_summaries: 'keepSummaries',
+        storage_path: 'storagePath',
+    });
+}, z.object({
+    enabled: z.boolean().optional().default(true),
+    fullRetentionDays: z.number().int().positive().optional().default(30),
+    keepSummaries: z.boolean().optional().default(true),
+    storagePath: z.string().optional().default('swarm/provenance'),
+}));
+const PerformanceSchema = z.preprocess((data) => {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    return mapKeys(data, {
+        file_watcher_debounce_ms: 'fileWatcherDebounceMs',
+        index_cache_ttl_seconds: 'indexCacheTtlSeconds',
+        max_concurrent_providers: 'maxConcurrentProviders',
+        max_query_latency_ms: 'maxQueryLatencyMs',
+        result_cache_ttl_ms: 'resultCacheTtlMs',
+    });
+}, z.object({
+    fileWatcherDebounceMs: z.number().int().positive().optional().default(1000),
+    indexCacheTtlSeconds: z.number().int().optional().default(300),
+    maxConcurrentProviders: z.number().int().positive().optional().default(4),
+    maxQueryLatencyMs: z.number().int().positive().optional().default(2000),
+    resultCacheTtlMs: z.number().int().min(0).optional().default(10_000),
+}));
+const EnrichmentEdgeSchema = z.object({
+    from: z.string(),
+    to: z.string(),
+});
+const EnrichmentSchema = z.object({
+    edges: z.array(EnrichmentEdgeSchema).optional().default([]),
+});
+// ============================================================
+// Root schema
+// ============================================================
+/**
+ * Full Zod schema for `.brv/swarm/config.yaml`.
+ * Accepts snake_case YAML input and outputs camelCase TypeScript.
+ */
+export const SwarmConfigSchema = z.object({
+    budget: BudgetSchema.optional(),
+    enrichment: EnrichmentSchema.optional().default({}),
+    optimization: OptimizationSchema.optional().default({}),
+    performance: PerformanceSchema.optional().default({}),
+    provenance: ProvenanceSchema.optional().default({}),
+    providers: ProvidersSchema,
+    routing: RoutingSchema.optional().default({}),
+});
+/**
+ * Validate swarm config (throwing).
+ * @throws ZodError on invalid input
+ */
+export function validateSwarmConfig(config) {
+    return SwarmConfigSchema.parse(config);
+}
+/**
+ * Validate swarm config (non-throwing).
+ * Returns a SafeParseResult with success/error.
+ */
+export function safeValidateSwarmConfig(config) {
+    return SwarmConfigSchema.safeParse(config);
+}

package/dist/agent/infra/swarm/provider-factory.d.ts

@@ -0,0 +1,21 @@
+import type { IMemoryProvider } from '../../core/interfaces/i-memory-provider.js';
+import type { SwarmConfig } from './config/swarm-config-schema.js';
+import { type SearchService } from './adapters/byterover-adapter.js';
+/**
+ * Options for building providers from config.
+ */
+export interface ProviderFactoryOptions {
+    /**
+     * Search service for ByteRover adapter.
+     * In agent mode, this is the real SearchKnowledgeService.
+     * In CLI mode, this can be omitted (a no-op stub is used).
+     */
+    searchService?: SearchService;
+}
+/**
+ * Build IMemoryProvider instances from a validated SwarmConfig.
+ *
+ * Used by both the CLI command and the agent runtime to avoid duplicating
+ * adapter construction logic.
+ */
+export declare function buildProvidersFromConfig(config: SwarmConfig, options?: ProviderFactoryOptions): IMemoryProvider[];

package/dist/agent/infra/swarm/provider-factory.js

@@ -0,0 +1,67 @@
+import { ByteRoverAdapter } from './adapters/byterover-adapter.js';
+import { GBrainAdapter } from './adapters/gbrain-adapter.js';
+import { LocalMarkdownAdapter } from './adapters/local-markdown-adapter.js';
+import { MemoryWikiAdapter } from './adapters/memory-wiki-adapter.js';
+import { ObsidianAdapter } from './adapters/obsidian-adapter.js';
+/**
+ * No-op search service for CLI-only mode when no real search service is available.
+ * ByteRover adapter will return empty results, but other providers (Obsidian, local-markdown)
+ * will still work with their own indexes.
+ */
+const STUB_SEARCH_SERVICE = {
+    async search() {
+        return { results: [], totalFound: 0 };
+    },
+};
+/**
+ * Build IMemoryProvider instances from a validated SwarmConfig.
+ *
+ * Used by both the CLI command and the agent runtime to avoid duplicating
+ * adapter construction logic.
+ */
+export function buildProvidersFromConfig(config, options) {
+    const providers = [];
+    // ByteRover — always first, always the "home" provider
+    if (config.providers.byterover.enabled) {
+        const searchService = options?.searchService ?? STUB_SEARCH_SERVICE;
+        providers.push(new ByteRoverAdapter(searchService));
+    }
+    // Obsidian
+    if (config.providers.obsidian?.enabled) {
+        providers.push(new ObsidianAdapter(config.providers.obsidian.vaultPath, {
+            ignorePatterns: config.providers.obsidian.ignorePatterns,
+            watchForChanges: config.providers.obsidian.watchForChanges,
+        }));
+    }
+    // Local Markdown — one adapter per folder, with deduplication of names
+    if (config.providers.localMarkdown?.enabled) {
+        const nameCount = new Map();
+        for (const folder of config.providers.localMarkdown.folders) {
+            // Deduplicate: if two folders share the same name, suffix with index
+            const count = nameCount.get(folder.name) ?? 0;
+            nameCount.set(folder.name, count + 1);
+            const uniqueName = count === 0 ? folder.name : `${folder.name}-${count}`;
+            providers.push(new LocalMarkdownAdapter(folder.path, uniqueName, {
+                followWikilinks: folder.followWikilinks,
+                readOnly: folder.readOnly,
+                watchForChanges: config.providers.localMarkdown.watchForChanges,
+            }));
+        }
+    }
+    // GBrain
+    if (config.providers.gbrain?.enabled) {
+        providers.push(new GBrainAdapter({
+            repoPath: config.providers.gbrain.repoPath,
+            searchMode: config.providers.gbrain.searchMode,
+        }));
+    }
+    if (config.providers.memoryWiki?.enabled) {
+        providers.push(new MemoryWikiAdapter({
+            boostFresh: config.providers.memoryWiki.boostFresh,
+            vaultPath: config.providers.memoryWiki.vaultPath,
+            writePageType: config.providers.memoryWiki.writePageType,
+        }));
+    }
+    // Cloud providers (honcho, hindsight) are temporarily disabled — adapters coming in Phase 3.
+    return providers;
+}

package/dist/agent/infra/swarm/search-precision.d.ts

@@ -0,0 +1,95 @@
+import type MiniSearch from 'minisearch';
+/**
+ * Maximum content length (in chars) returned per result from adapters.
+ * The renderer applies a separate display limit; this controls payload size.
+ */
+export declare const ADAPTER_CONTENT_LIMIT = 5000;
+/**
+ * Default absolute score floor for adapter-level OOD detection.
+ * Lower than ByteRover's 0.45 because adapters use pure BM25 normalization
+ * without compound scoring (importance/recency/maturity).
+ */
+export declare const DEFAULT_SCORE_FLOOR = 0.3;
+/**
+ * Default gap ratio for adapter-level tail filtering.
+ * Slightly tighter than ByteRover's 0.7 to compensate for the
+ * absence of compound scoring differentiation.
+ */
+export declare const DEFAULT_GAP_RATIO = 0.75;
+/**
+ * Gap ratio for second pass after wikilink expansion.
+ * Must be <= WIKILINK_DECAY (0.7) so one-hop expansions are not automatically filtered.
+ * Uses 0.6 to give expanded results some headroom.
+ */
+export declare const POST_EXPANSION_GAP_RATIO = 0.6;
+/**
+ * Normalized search result from MiniSearch with precision metadata.
+ */
+export type NormalizedResult = {
+    /** Document ID from MiniSearch */
+    id: number | string;
+    /** Score normalized to [0, 1) via score / (1 + score) */
+    normalizedScore: number;
+    /** Query terms that matched (from MiniSearch, for future unmatched-term detection) */
+    queryTerms: string[];
+    /** Raw MiniSearch BM25 score before normalization */
+    rawScore: number;
+};
+/**
+ * Options for precision-filtered MiniSearch queries.
+ */
+export type PrecisionSearchOptions = {
+    /** Field boost weights. Default: {title: 2} */
+    boost?: Record<string, number>;
+    /** Fuzzy matching tolerance. Default: 0.2 */
+    fuzzy?: number;
+    /** Gap ratio: only keep results >= topScore * ratio. Default: 0.75 */
+    gapRatio?: number;
+    /** Maximum results to return. Default: 10 */
+    maxResults?: number;
+    /** Enable prefix matching. Default: true */
+    prefix?: boolean;
+    /** Absolute score floor: if top result < threshold, return empty. Default: 0.3 */
+    scoreFloor?: number;
+};
+/**
+ * Remove common stop words from a query string.
+ * Returns the original query if all tokens are stop words (never returns empty).
+ * Matches ByteRover behavior at search-knowledge-service.ts:291-295.
+ */
+export declare function filterStopWords(query: string): string;
+/**
+ * Drop all results if the best normalized score is below the threshold.
+ * This is an absolute OOD (out-of-domain) gate.
+ * Input may be sorted or unsorted — uses Math.max to find the best score.
+ *
+ * @param results - Results (sorted or unsorted)
+ * @param threshold - Minimum acceptable top score
+ * @returns Original results if best >= threshold, empty otherwise
+ */
+export declare function applyScoreFloor(results: NormalizedResult[], threshold: number): NormalizedResult[];
+/**
+ * Keep only results whose score is >= topScore * ratio.
+ * Sorts internally to find the true top score, then early-breaks on sorted input.
+ * Matches ByteRover's gap filter pattern at search-knowledge-service.ts:1234-1242.
+ *
+ * @param results - Results (sorted or unsorted)
+ * @param ratio - Gap ratio (0, 1]. Only results >= topScore * ratio are kept.
+ * @returns Filtered results sorted descending by normalizedScore
+ */
+export declare function applyGapRatio(results: NormalizedResult[], ratio: number): NormalizedResult[];
+/**
+ * Execute a precision-filtered MiniSearch query combining T1/T2/T3:
+ *
+ * 1. Filter stop words from query (T1)
+ * 2. Try AND for multi-word queries, fall back to OR if empty (T1)
+ * 3. Normalize scores: score / (1 + score)
+ * 4. Apply absolute score floor gate (T2)
+ * 5. Apply relative gap ratio filter (T3)
+ *
+ * @param index - MiniSearch index to search
+ * @param query - Raw query string
+ * @param options - Precision search options
+ * @returns Filtered, normalized results sorted descending by score
+ */
+export declare function searchWithPrecision<T>(index: MiniSearch<T>, query: string, options?: PrecisionSearchOptions): NormalizedResult[];

package/dist/agent/infra/swarm/search-precision.js

@@ -0,0 +1,141 @@
+import { removeStopwords } from 'stopword';
+// ============================================================
+// Constants
+// ============================================================
+/**
+ * Maximum content length (in chars) returned per result from adapters.
+ * The renderer applies a separate display limit; this controls payload size.
+ */
+export const ADAPTER_CONTENT_LIMIT = 5000;
+/**
+ * Default absolute score floor for adapter-level OOD detection.
+ * Lower than ByteRover's 0.45 because adapters use pure BM25 normalization
+ * without compound scoring (importance/recency/maturity).
+ */
+export const DEFAULT_SCORE_FLOOR = 0.3;
+/**
+ * Default gap ratio for adapter-level tail filtering.
+ * Slightly tighter than ByteRover's 0.7 to compensate for the
+ * absence of compound scoring differentiation.
+ */
+export const DEFAULT_GAP_RATIO = 0.75;
+/**
+ * Gap ratio for second pass after wikilink expansion.
+ * Must be <= WIKILINK_DECAY (0.7) so one-hop expansions are not automatically filtered.
+ * Uses 0.6 to give expanded results some headroom.
+ */
+export const POST_EXPANSION_GAP_RATIO = 0.6;
+// ============================================================
+// T1: Stop word filtering
+// ============================================================
+/**
+ * Remove common stop words from a query string.
+ * Returns the original query if all tokens are stop words (never returns empty).
+ * Matches ByteRover behavior at search-knowledge-service.ts:291-295.
+ */
+export function filterStopWords(query) {
+    if (!query.trim())
+        return query;
+    const words = query.toLowerCase().split(/\s+/);
+    const filtered = removeStopwords(words);
+    return filtered.length > 0 ? filtered.join(' ') : query;
+}
+// ============================================================
+// T2: Absolute score floor gate
+// ============================================================
+/**
+ * Drop all results if the best normalized score is below the threshold.
+ * This is an absolute OOD (out-of-domain) gate.
+ * Input may be sorted or unsorted — uses Math.max to find the best score.
+ *
+ * @param results - Results (sorted or unsorted)
+ * @param threshold - Minimum acceptable top score
+ * @returns Original results if best >= threshold, empty otherwise
+ */
+export function applyScoreFloor(results, threshold) {
+    if (results.length === 0)
+        return [];
+    // Use max score regardless of input order
+    const topScore = Math.max(...results.map((r) => r.normalizedScore));
+    return topScore >= threshold ? results : [];
+}
+// ============================================================
+// T3: Relative gap ratio filter
+// ============================================================
+/**
+ * Keep only results whose score is >= topScore * ratio.
+ * Sorts internally to find the true top score, then early-breaks on sorted input.
+ * Matches ByteRover's gap filter pattern at search-knowledge-service.ts:1234-1242.
+ *
+ * @param results - Results (sorted or unsorted)
+ * @param ratio - Gap ratio (0, 1]. Only results >= topScore * ratio are kept.
+ * @returns Filtered results sorted descending by normalizedScore
+ */
+export function applyGapRatio(results, ratio) {
+    if (results.length === 0)
+        return [];
+    // Sort descending to find top score and enable early break
+    const sorted = [...results].sort((a, b) => b.normalizedScore - a.normalizedScore);
+    const floor = sorted[0].normalizedScore * ratio;
+    const filtered = [];
+    for (const r of sorted) {
+        if (r.normalizedScore < floor)
+            break;
+        filtered.push(r);
+    }
+    return filtered;
+}
+// ============================================================
+// Combined precision search
+// ============================================================
+/**
+ * Execute a precision-filtered MiniSearch query combining T1/T2/T3:
+ *
+ * 1. Filter stop words from query (T1)
+ * 2. Try AND for multi-word queries, fall back to OR if empty (T1)
+ * 3. Normalize scores: score / (1 + score)
+ * 4. Apply absolute score floor gate (T2)
+ * 5. Apply relative gap ratio filter (T3)
+ *
+ * @param index - MiniSearch index to search
+ * @param query - Raw query string
+ * @param options - Precision search options
+ * @returns Filtered, normalized results sorted descending by score
+ */
+export function searchWithPrecision(index, query, options) {
+    const { boost = { title: 2 }, fuzzy = 0.2, gapRatio = DEFAULT_GAP_RATIO, maxResults = 10, prefix = true, scoreFloor = DEFAULT_SCORE_FLOOR, } = options ?? {};
+    // T1: Filter stop words
+    const filteredQuery = filterStopWords(query);
+    const words = filteredQuery.split(/\s+/).filter(Boolean);
+    // T1: AND-first for multi-word queries, OR fallback
+    const searchOpts = { boost, fuzzy, prefix };
+    let rawResults;
+    if (words.length >= 2) {
+        rawResults = index.search(filteredQuery, { combineWith: 'AND', ...searchOpts });
+        if (rawResults.length === 0) {
+            rawResults = index.search(filteredQuery, { combineWith: 'OR', ...searchOpts });
+            // For 2-word queries minTerms=2, effectively requiring both terms.
+            // This is intentional: AND failed on exact match, but OR with prefix/fuzzy
+            // may still find docs matching both terms via stemming or partial overlap.
+            const minTerms = Math.floor(words.length / 2) + 1;
+            rawResults = rawResults.filter((r) => (r.queryTerms ?? []).length >= minTerms);
+        }
+    }
+    else {
+        rawResults = index.search(filteredQuery, { combineWith: 'OR', ...searchOpts });
+    }
+    // Cap candidate set by MiniSearch rank order before applying T2/T3.
+    // This limits the precision pipeline to the top-N MiniSearch hits.
+    const normalized = rawResults.slice(0, maxResults).map((r) => ({
+        id: r.id,
+        normalizedScore: r.score / (1 + r.score),
+        queryTerms: r.queryTerms ?? [],
+        rawScore: r.score,
+    }));
+    // T2: Absolute score floor
+    const afterFloor = applyScoreFloor(normalized, scoreFloor);
+    if (afterFloor.length === 0)
+        return [];
+    // T3: Relative gap ratio
+    return applyGapRatio(afterFloor, gapRatio);
+}

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

@@ -0,0 +1,59 @@
+import type { QueryRequest } from '../../core/domain/swarm/types.js';
+import type { IMemoryProvider } from '../../core/interfaces/i-memory-provider.js';
+import type { ISwarmCoordinator, ProviderInfo, SwarmQueryResult, SwarmStoreRequest, SwarmStoreResult, SwarmSummary } from '../../core/interfaces/i-swarm-coordinator.js';
+import type { SwarmConfig } from './config/swarm-config-schema.js';
+export type BrvCurateResult = {
+    data?: {
+        logId?: string;
+        taskId?: string;
+    };
+    error?: string;
+    success?: boolean;
+};
+/**
+ * SwarmCoordinator — orchestrates query classification, provider selection,
+ * parallel execution, and result fusion.
+ *
+ * Implements ISwarmCoordinator to serve the CLI command and agent tool.
+ */
+export type CurateFallbackFn = (content: string) => Promise<BrvCurateResult>;
+export declare class SwarmCoordinator implements ISwarmCoordinator {
+    private readonly config;
+    private readonly curateFallback;
+    private readonly graph;
+    private readonly healthCache;
+    private readonly maxCacheSize;
+    private readonly providers;
+    private readonly resultCache;
+    private readonly resultCacheTtlMs;
+    private totalQueries;
+    constructor(providers: IMemoryProvider[], config: SwarmConfig, curateFallback?: CurateFallbackFn);
+    /**
+     * Execute a swarm query: classify → select providers → execute in parallel → fuse results.
+     */
+    execute(request: QueryRequest): Promise<SwarmQueryResult>;
+    /**
+     * Get info about all registered providers and their cached health status.
+     */
+    getActiveProviders(): ProviderInfo[];
+    /**
+     * Get a presentation-oriented summary of the swarm state.
+     */
+    getSummary(): SwarmSummary;
+    /**
+     * Run health checks on all providers and update the cache.
+     */
+    refreshHealth(): Promise<ProviderInfo[]>;
+    /**
+     * 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()
+     */
+    store(request: SwarmStoreRequest): Promise<SwarmStoreResult>;
+    private buildCacheKey;
+    private evictIfOverSize;
+    private fallbackToByterover;
+}