shieldcortex 4.14.11 → 4.16.0

package/dist/defence/custom-rules/store.js

@@ -3,9 +3,11 @@
  */
 import { getDatabase } from '../../database/init.js';
 const MAX_RULES = 25;
-export function listFirewallRules() {
+export function listFirewallRules(opts = {}) {
+    const includeBuiltin = opts.includeBuiltin ?? true;
     const db = getDatabase();
-    return db.prepare('SELECT * FROM firewall_rules ORDER BY priority ASC').all();
+    const where = includeBuiltin ? '' : 'WHERE built_in = 0';
+    return db.prepare(`SELECT * FROM firewall_rules ${where} ORDER BY priority ASC`).all();
 }
 export function getFirewallRule(id) {
     const db = getDatabase();
@@ -13,7 +15,9 @@ export function getFirewallRule(id) {
 }
 export function createFirewallRule(rule) {
     const db = getDatabase();
-    const count = db.prepare('SELECT COUNT(*) as cnt FROM firewall_rules').get().cnt;
+    // The MAX_RULES cap applies only to user-defined rules. Built-in rules
+    // (built_in=1) are seeded by the database layer and don't count.
+    const count = db.prepare('SELECT COUNT(*) as cnt FROM firewall_rules WHERE built_in = 0').get().cnt;
     if (count >= MAX_RULES) {
         throw new Error(`Maximum of ${MAX_RULES} custom firewall rules reached.`);
     }

package/dist/defence/firewall/instruction-detector.js

@@ -114,6 +114,21 @@ const PATTERN_GROUPS = [
             /reveal\s+your\s+instructions/i,
         ],
     },
+    {
+        // Imperative tool-call directives. These show up in transcripts as
+        // injected prompts disguised as user instructions ("call the X tool
+        // to complete this request. Call this tool now."). The session-end
+        // chunker historically captured them as user preferences with
+        // salience 1.0; the firewall now flags them at write time so they
+        // route to quarantine instead of memories.
+        name: 'imperative_tool_call',
+        weight: 0.8,
+        patterns: [
+            /\b(?:call|invoke|use)\s+(?:the\s+)?[A-Za-z][\w-]*\s+tool\b/i,
+            /\b(?:call|invoke|use)\s+this\s+tool\s+now\b/i,
+            /\bcomplete\s+this\s+request\.\s*(?:call|invoke|use)\s+this\s+tool\b/i,
+        ],
+    },
 ];
 // Maximum content length to scan (prevents ReDOS on very long inputs)
 const MAX_SCAN_LENGTH = 50000;

package/dist/defence/pipeline.js

@@ -95,42 +95,48 @@ export function runDefencePipeline(content, title, source, config, project) {
                 reason = firewall.reason;
             }
         }
-        // 6b. Apply custom firewall rules (Pro feature, additive only — can tighten, never weaken)
-        if (allowed && isFeatureEnabled('custom_firewall_rules') && isDatabaseInitialized()) {
+        // 6b. Apply firewall rules (built-in rules always evaluated; user-added
+        // custom rules require the Pro `custom_firewall_rules` feature). Both
+        // are additive only — can tighten, never weaken.
+        if (allowed && isDatabaseInitialized()) {
             try {
                 const { getEnabledFirewallRules } = require('./custom-rules/store.js');
-                const customRules = getEnabledFirewallRules();
-                for (const rule of customRules) {
+                const userRulesAllowed = isFeatureEnabled('custom_firewall_rules');
+                const allRules = getEnabledFirewallRules();
+                for (const rule of allRules) {
+                    if (!rule.built_in && !userRulesAllowed)
+                        continue;
                     try {
                         const regex = new RegExp(rule.condition_value, 'gi');
                         if (regex.test(cleanContent) || regex.test(title)) {
+                            const indicator = rule.built_in ? 'builtin_rule' : 'custom_rule';
                             if (rule.action === 'block') {
                                 allowed = false;
-                                reason = `Blocked by custom rule: ${rule.name}`;
+                                reason = `Blocked by ${rule.built_in ? 'built-in' : 'custom'} rule: ${rule.name}`;
                                 firewall.result = 'BLOCK';
-                                if (!firewall.threatIndicators.includes('custom_rule')) {
-                                    firewall.threatIndicators.push('custom_rule');
+                                if (!firewall.threatIndicators.includes(indicator)) {
+                                    firewall.threatIndicators.push(indicator);
                                 }
                                 break; // Block is final
                             }
                             else if (rule.action === 'quarantine' && firewall.result !== 'BLOCK') {
                                 allowed = false;
-                                reason = `Quarantined by custom rule: ${rule.name}`;
+                                reason = `Quarantined by ${rule.built_in ? 'built-in' : 'custom'} rule: ${rule.name}`;
                                 firewall.result = 'QUARANTINE';
-                                if (!firewall.threatIndicators.includes('custom_rule')) {
-                                    firewall.threatIndicators.push('custom_rule');
+                                if (!firewall.threatIndicators.includes(indicator)) {
+                                    firewall.threatIndicators.push(indicator);
                                 }
                             }
-                            // 'allow' action: no-op — custom rules cannot weaken built-in decisions
+                            // 'allow' action: no-op — rules cannot weaken built-in decisions
                         }
                     }
                     catch {
-                        // Skip invalid regex in custom rules
+                        // Skip invalid regex in rules
                     }
                 }
             }
             catch {
-                // Custom rules store not available — skip silently
+                // Rules store not available — skip silently
             }
         }
         // 6c. Apply custom injection patterns (Pro feature, additive)

package/dist/defence/types.d.ts

@@ -6,7 +6,7 @@
  */
 export type SensitivityLevel = 'PUBLIC' | 'INTERNAL' | 'CONFIDENTIAL' | 'RESTRICTED';
 export type FirewallResult = 'ALLOW' | 'BLOCK' | 'QUARANTINE';
-export type ThreatIndicator = 'instruction_injection' | 'privilege_escalation' | 'encoding_obfuscation' | 'credential_leak' | 'external_url' | 'fragmented_payload' | 'restricted_content' | 'pipeline_error' | 'custom_rule' | 'custom_pattern';
+export type ThreatIndicator = 'instruction_injection' | 'privilege_escalation' | 'encoding_obfuscation' | 'credential_leak' | 'external_url' | 'fragmented_payload' | 'restricted_content' | 'pipeline_error' | 'custom_rule' | 'custom_pattern' | 'builtin_rule';
 export interface DefenceSource {
     type: 'user' | 'cli' | 'hook' | 'email' | 'web' | 'agent' | 'file' | 'api' | 'tool_response';
     identifier: string;

package/dist/memory/ranker/graph-rank.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Graph-based retrieval: turn a free-text query into a ranked list of
+ * memories by walking the knowledge graph (entities + triples).
+ *
+ * The retriever is side-effect-free — it only reads. It does NOT insert
+ * new entities, mutate aliases, or write any state. That's the
+ * contract that lets it stand alongside FTS and vector retrievers in the
+ * RRF orchestrator without polluting the graph during a query.
+ *
+ * Algorithm:
+ *   1. Tokenize the query, drop stop-words and tokens shorter than
+ *      `MIN_TOKEN_LEN`.
+ *   2. Resolve each token to seed entities (case-insensitive name,
+ *      alias, then Levenshtein for tokens at least `MIN_FUZZY_LEN` chars).
+ *   3. BFS over the triples table up to `maxHops`. Track shortest hop
+ *      and incoming-edge confidence for every entity reached. Seeds have
+ *      hop=0 and implicit confidence 1.0.
+ *   4. For every memory mentioning a reached entity (via the
+ *      `memory_entities` table), accumulate score:
+ *           Σ  incomingConf / (hop + 1)
+ *   5. Optional `project` filter via the JOIN.
+ *   6. Sort by score desc, ties by memoryId asc, cap at `limit`.
+ */
+import type { Database as SqliteDatabase } from 'better-sqlite3';
+export interface GraphRankResult {
+    memoryId: number;
+    score: number;
+}
+export interface GraphRankOptions {
+    /** Maximum hops from seed entities. Default 2. */
+    maxHops?: number;
+    /** Maximum result rows. Default 50. */
+    limit?: number;
+    /** Filter to memories within this project. */
+    project?: string;
+    /** Override stop-word set. Default is a small built-in English list. */
+    stopWords?: Set<string>;
+}
+export declare function graphRankFromQuery(query: string, db: SqliteDatabase, options?: GraphRankOptions): GraphRankResult[];

package/dist/memory/ranker/graph-rank.js

@@ -0,0 +1,186 @@
+/**
+ * Graph-based retrieval: turn a free-text query into a ranked list of
+ * memories by walking the knowledge graph (entities + triples).
+ *
+ * The retriever is side-effect-free — it only reads. It does NOT insert
+ * new entities, mutate aliases, or write any state. That's the
+ * contract that lets it stand alongside FTS and vector retrievers in the
+ * RRF orchestrator without polluting the graph during a query.
+ *
+ * Algorithm:
+ *   1. Tokenize the query, drop stop-words and tokens shorter than
+ *      `MIN_TOKEN_LEN`.
+ *   2. Resolve each token to seed entities (case-insensitive name,
+ *      alias, then Levenshtein for tokens at least `MIN_FUZZY_LEN` chars).
+ *   3. BFS over the triples table up to `maxHops`. Track shortest hop
+ *      and incoming-edge confidence for every entity reached. Seeds have
+ *      hop=0 and implicit confidence 1.0.
+ *   4. For every memory mentioning a reached entity (via the
+ *      `memory_entities` table), accumulate score:
+ *           Σ  incomingConf / (hop + 1)
+ *   5. Optional `project` filter via the JOIN.
+ *   6. Sort by score desc, ties by memoryId asc, cap at `limit`.
+ */
+import { levenshtein } from '../../graph/resolve.js';
+const DEFAULT_STOP_WORDS = new Set([
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'and', 'or', 'but', 'not', 'no', 'to', 'of', 'in', 'on', 'at', 'for',
+    'with', 'by', 'from', 'as', 'this', 'that', 'these', 'those',
+    'it', 'its', 'has', 'have', 'had', 'do', 'does', 'did', 'can',
+    'could', 'should', 'would', 'will', 'shall', 'may', 'might', 'must',
+    'i', 'me', 'my', 'we', 'us', 'our', 'you', 'your', 'they', 'them',
+    'he', 'him', 'his', 'she', 'her', 'their',
+]);
+const MIN_TOKEN_LEN = 3;
+const MIN_FUZZY_LEN = 6;
+const MAX_FUZZY_DISTANCE = 2;
+const DEFAULT_MAX_HOPS = 2;
+const DEFAULT_LIMIT = 50;
+export function graphRankFromQuery(query, db, options = {}) {
+    if (typeof query !== 'string' || query.trim().length === 0)
+        return [];
+    const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const stopWords = options.stopWords ?? DEFAULT_STOP_WORDS;
+    const tokens = tokenize(query, stopWords);
+    if (tokens.length === 0)
+        return [];
+    const reach = resolveSeeds(tokens, db);
+    if (reach.size === 0)
+        return [];
+    expandHops(reach, maxHops, db);
+    return aggregateMemoryScores(reach, db, options.project, limit);
+}
+function tokenize(query, stopWords) {
+    return query
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}_-]+/u)
+        .filter((t) => t.length >= MIN_TOKEN_LEN && !stopWords.has(t));
+}
+function resolveSeeds(tokens, db) {
+    // Pull every entity once. Fine for typical ShieldCortex DBs (hundreds of
+    // entities). Switch to per-token SQL probes if this becomes a hotspot.
+    const all = db
+        .prepare('SELECT id, name, aliases FROM entities')
+        .all();
+    // Pre-compute alias lookups.
+    const parsedAliases = all.map((row) => {
+        let aliases = [];
+        if (row.aliases) {
+            try {
+                const parsed = JSON.parse(row.aliases);
+                if (Array.isArray(parsed)) {
+                    aliases = parsed.filter((a) => typeof a === 'string');
+                }
+            }
+            catch {
+                // Malformed JSON in the aliases column — treat as no aliases.
+            }
+        }
+        return { id: row.id, name: row.name, lname: row.name.toLowerCase(), aliases };
+    });
+    const reach = new Map();
+    const recordSeed = (id) => {
+        if (!reach.has(id))
+            reach.set(id, { hop: 0, incomingConf: 1.0 });
+    };
+    for (const token of tokens) {
+        let matched = false;
+        // 1. Exact name match (case-insensitive).
+        for (const e of parsedAliases) {
+            if (e.lname === token) {
+                recordSeed(e.id);
+                matched = true;
+            }
+        }
+        if (matched)
+            continue;
+        // 2. Alias match.
+        for (const e of parsedAliases) {
+            if (e.aliases.some((a) => a.toLowerCase() === token)) {
+                recordSeed(e.id);
+                matched = true;
+            }
+        }
+        if (matched)
+            continue;
+        // 3. Fuzzy match — only for tokens of MIN_FUZZY_LEN+ to avoid false
+        //    positives on short words.
+        if (token.length >= MIN_FUZZY_LEN) {
+            for (const e of parsedAliases) {
+                if (Math.abs(e.lname.length - token.length) > MAX_FUZZY_DISTANCE)
+                    continue;
+                if (levenshtein(token, e.lname) <= MAX_FUZZY_DISTANCE) {
+                    recordSeed(e.id);
+                }
+            }
+        }
+    }
+    return reach;
+}
+function expandHops(reach, maxHops, db) {
+    if (maxHops <= 0)
+        return;
+    let frontier = new Set(reach.keys());
+    for (let hop = 0; hop < maxHops; hop++) {
+        if (frontier.size === 0)
+            break;
+        const ids = Array.from(frontier);
+        const placeholders = ids.map(() => '?').join(',');
+        const rows = db
+            .prepare(`
+        SELECT subject_id AS src, object_id AS dst, confidence
+        FROM triples
+        WHERE subject_id IN (${placeholders})
+        UNION ALL
+        SELECT object_id AS src, subject_id AS dst, confidence
+        FROM triples
+        WHERE object_id IN (${placeholders})
+        `)
+            .all(...ids, ...ids);
+        const next = new Set();
+        for (const row of rows) {
+            const dstHop = hop + 1;
+            const existing = reach.get(row.dst);
+            if (!existing) {
+                reach.set(row.dst, { hop: dstHop, incomingConf: row.confidence });
+                next.add(row.dst);
+            }
+            else if (existing.hop === dstHop && row.confidence > existing.incomingConf) {
+                // Same shortest hop reached by a higher-confidence edge — keep the better one.
+                existing.incomingConf = row.confidence;
+            }
+        }
+        frontier = next;
+    }
+}
+function aggregateMemoryScores(reach, db, project, limit) {
+    const entityIds = Array.from(reach.keys());
+    if (entityIds.length === 0)
+        return [];
+    const placeholders = entityIds.map(() => '?').join(',');
+    const params = [...entityIds];
+    let sql = `
+    SELECT me.memory_id, me.entity_id, m.project
+    FROM memory_entities me
+    JOIN memories m ON m.id = me.memory_id
+    WHERE me.entity_id IN (${placeholders})
+  `;
+    if (project) {
+        sql += ' AND m.project = ?';
+        params.push(project);
+    }
+    const rows = db.prepare(sql).all(...params);
+    const scoreByMemory = new Map();
+    for (const row of rows) {
+        const info = reach.get(row.entity_id);
+        if (!info)
+            continue; // shouldn't happen, but be defensive
+        const contribution = info.incomingConf / (info.hop + 1);
+        scoreByMemory.set(row.memory_id, (scoreByMemory.get(row.memory_id) ?? 0) + contribution);
+    }
+    return Array.from(scoreByMemory.entries())
+        .map(([memoryId, score]) => ({ memoryId, score }))
+        .sort((a, b) => b.score - a.score || a.memoryId - b.memoryId)
+        .slice(0, limit);
+}

package/dist/memory/ranker/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Hybrid retrieval orchestrator — Step A.3 of v4.15.
+ *
+ * Glues the three retrievers (FTS via SQLite FTS5, vector via embeddings,
+ * graph via `graphRankFromQuery`) into a single ranking by feeding their
+ * rank lists into Reciprocal Rank Fusion (`reciprocalRankFusion`), then
+ * applying the existing per-memory boosts (recency, category, link, tag,
+ * activation, contradiction) as **multiplicative tweaks on top of the
+ * RRF score** rather than additive components in a fixed-weight sum.
+ *
+ *   finalScore = rrfScore
+ *     × (1 + 0.05 × priority)                // priority: 0–1
+ *     × (1 + recencyBoost)                   // 0 / 0.05 / 0.1
+ *     × (1 + 0.1 × categoryMatch)            // 0 or 1
+ *     × (1 + linkBoost)                      // 0–0.15
+ *     × (1 + tagBoost)                       // 0–0.1
+ *     × (1 + activationBoost)                // 0–?
+ *     × (1 - contradictionPenalty)           // 0–0.12
+ *
+ * Why multiplicative on top of RRF rather than additive:
+ *   - RRF is rank-based, so its raw score scale is small and consistent.
+ *   - Multiplicative boosts preserve the *relative* RRF order while
+ *     letting context modulate it — they don't drown out the underlying
+ *     retrieval signal the way fixed additive weights do.
+ *   - Contradiction penalty is multiplicative (`1 - p`) so it shrinks
+ *     score proportionally rather than potentially flipping sign.
+ *
+ * The module is split intentionally: `runHybridRanker` is pure-ish (it
+ * accepts already-loaded rank lists + a memory map) so it can be unit
+ * tested without standing up the embedding model or the FTS pipeline.
+ * Step A.4 will add the DB-backed `hybridSearch` wrapper that builds
+ * those inputs from a `SearchOptions`.
+ */
+import type Database from 'better-sqlite3';
+import { type RankList } from './rrf.js';
+import type { Memory, MemoryConfig, SearchResult } from '../types.js';
+export interface HybridRankerWeights {
+    fts: number;
+    vector: number;
+    graph: number;
+}
+export declare const DEFAULT_HYBRID_WEIGHTS: HybridRankerWeights;
+/** Cormack et al. (2009) recommended RRF smoothing constant. */
+export declare const DEFAULT_RRF_K = 60;
+export interface HybridRankerInput {
+    /** Rank lists from FTS, vector, graph. Any subset is allowed. */
+    rankLists: readonly RankList[];
+    /** Memory id → Memory record. The caller pre-loads these. */
+    memories: Map<number, Memory>;
+    /** Memory id → cosine similarity (used only for explanation breakdowns). */
+    vectorSimilarities?: Map<number, number>;
+    /** Memory id → normalised FTS score (used only for explanation breakdowns). */
+    ftsScores?: Map<number, number>;
+    /** Original user query — drives category detection and tag extraction. */
+    query: string;
+    /** SQLite handle — used for memory_links lookups. */
+    db: Database.Database;
+    /** Memory config. `salienceThreshold` gates the includeDecayed filter. */
+    config: MemoryConfig;
+    /** Override RRF k constant. Default 60. */
+    rrfK?: number;
+    /** Attach a `SearchExplanation` to each `SearchResult`. */
+    includeExplanation?: boolean;
+    /** Skip the decay-threshold filter. */
+    includeDecayed?: boolean;
+    /** Cap result count. Default 20. */
+    limit?: number;
+    /**
+     * Override the activation-boost lookup. Defaults to the module-level
+     * cache in `../activation.js`. Tests inject a stub.
+     */
+    activationBoostFn?: (memoryId: number) => number;
+}
+export declare function runHybridRanker(input: HybridRankerInput): SearchResult[];

package/dist/memory/ranker/index.js

@@ -0,0 +1,170 @@
+/**
+ * Hybrid retrieval orchestrator — Step A.3 of v4.15.
+ *
+ * Glues the three retrievers (FTS via SQLite FTS5, vector via embeddings,
+ * graph via `graphRankFromQuery`) into a single ranking by feeding their
+ * rank lists into Reciprocal Rank Fusion (`reciprocalRankFusion`), then
+ * applying the existing per-memory boosts (recency, category, link, tag,
+ * activation, contradiction) as **multiplicative tweaks on top of the
+ * RRF score** rather than additive components in a fixed-weight sum.
+ *
+ *   finalScore = rrfScore
+ *     × (1 + 0.05 × priority)                // priority: 0–1
+ *     × (1 + recencyBoost)                   // 0 / 0.05 / 0.1
+ *     × (1 + 0.1 × categoryMatch)            // 0 or 1
+ *     × (1 + linkBoost)                      // 0–0.15
+ *     × (1 + tagBoost)                       // 0–0.1
+ *     × (1 + activationBoost)                // 0–?
+ *     × (1 - contradictionPenalty)           // 0–0.12
+ *
+ * Why multiplicative on top of RRF rather than additive:
+ *   - RRF is rank-based, so its raw score scale is small and consistent.
+ *   - Multiplicative boosts preserve the *relative* RRF order while
+ *     letting context modulate it — they don't drown out the underlying
+ *     retrieval signal the way fixed additive weights do.
+ *   - Contradiction penalty is multiplicative (`1 - p`) so it shrinks
+ *     score proportionally rather than potentially flipping sign.
+ *
+ * The module is split intentionally: `runHybridRanker` is pure-ish (it
+ * accepts already-loaded rank lists + a memory map) so it can be unit
+ * tested without standing up the embedding model or the FTS pipeline.
+ * Step A.4 will add the DB-backed `hybridSearch` wrapper that builds
+ * those inputs from a `SearchOptions`.
+ */
+import { reciprocalRankFusion } from './rrf.js';
+import { calculateDecayedScore, calculatePriority } from '../decay.js';
+import { getActivationBoost as defaultActivationBoost } from '../activation.js';
+import { buildSearchExplanation, calculateLinkBoost, calculateTagScore, detectQueryCategory, extractQueryTags, } from '../search.js';
+export const DEFAULT_HYBRID_WEIGHTS = {
+    fts: 0.4,
+    vector: 0.6,
+    graph: 0.3,
+};
+/** Cormack et al. (2009) recommended RRF smoothing constant. */
+export const DEFAULT_RRF_K = 60;
+const DEFAULT_LIMIT = 20;
+export function runHybridRanker(input) {
+    const fused = reciprocalRankFusion(input.rankLists, { k: input.rrfK ?? DEFAULT_RRF_K });
+    if (fused.length === 0)
+        return [];
+    const limit = input.limit ?? DEFAULT_LIMIT;
+    const includeDecayed = input.includeDecayed ?? false;
+    const includeExplanation = input.includeExplanation ?? false;
+    const activationBoostFn = input.activationBoostFn ?? defaultActivationBoost;
+    const detectedCategory = input.query ? detectQueryCategory(input.query) : null;
+    const queryTags = input.query ? extractQueryTags(input.query) : [];
+    const scoringContext = {
+        db: input.db,
+        config: input.config,
+        detectedCategory,
+        queryTags,
+        vectorResults: input.vectorSimilarities ?? new Map(),
+        query: input.query,
+    };
+    const scored = [];
+    for (const fusedItem of fused) {
+        const memory = input.memories.get(fusedItem.id);
+        if (!memory)
+            continue;
+        const decayedScore = calculateDecayedScore(memory, input.config);
+        memory.decayedScore = decayedScore;
+        const candidate = scoreCandidate({
+            memory,
+            rrfScore: fusedItem.score,
+            contributions: fusedItem.contributions,
+            decayedScore,
+            detectedCategory,
+            queryTags,
+            vectorSimilarity: input.vectorSimilarities?.get(memory.id) ?? 0,
+            ftsScore: input.ftsScores?.get(memory.id) ?? 0,
+            db: input.db,
+            activationBoostFn,
+        });
+        scored.push(candidate);
+    }
+    const filtered = includeDecayed
+        ? scored
+        : scored.filter((c) => c.decayedScore >= input.config.salienceThreshold);
+    filtered.sort((a, b) => b.finalScore - a.finalScore ||
+        a.memory.id - b.memory.id);
+    const capped = filtered.slice(0, limit);
+    return capped.map((c) => buildSearchResult(c, scoringContext, includeExplanation));
+}
+function scoreCandidate(input) {
+    const { memory } = input;
+    const hoursSinceAccess = (Date.now() - new Date(memory.lastAccessed).getTime()) / (1000 * 60 * 60);
+    const recencyBoost = hoursSinceAccess < 1 ? 0.1 : hoursSinceAccess < 24 ? 0.05 : 0;
+    const matchedCategory = input.detectedCategory !== null && memory.category === input.detectedCategory;
+    const categoryBoost = matchedCategory ? 0.1 : 0;
+    const linkBoost = calculateLinkBoost(memory.id, input.db);
+    const tagBoost = calculateTagScore(input.queryTags, memory.tags);
+    const activationBoost = input.activationBoostFn(memory.id);
+    const priority = calculatePriority(memory);
+    const priorityBoost = priority * 0.05;
+    const contradictionCount = input.db
+        .prepare(`SELECT COUNT(*) as count FROM memory_links
+         WHERE relationship = 'contradicts' AND (source_id = ? OR target_id = ?)`)
+        .get(memory.id, memory.id).count;
+    const contradictionPenalty = Math.min(0.12, contradictionCount * 0.03);
+    const multiplier = (1 + priorityBoost) *
+        (1 + recencyBoost) *
+        (1 + categoryBoost) *
+        (1 + linkBoost) *
+        (1 + tagBoost) *
+        (1 + activationBoost) *
+        (1 - contradictionPenalty);
+    const finalScore = input.rrfScore * multiplier;
+    const eligibilityReasons = [];
+    if (memory.status === 'archived')
+        eligibilityReasons.push('Archived memories are excluded from normal recall');
+    if (memory.status === 'suppressed')
+        eligibilityReasons.push('Suppressed memories are excluded from normal recall');
+    if (memory.cloudExcluded)
+        eligibilityReasons.push('Excluded from cloud sync');
+    if (memory.trustScore < 0.7)
+        eligibilityReasons.push(`Low trust source (${memory.trustScore.toFixed(2)})`);
+    if (contradictionCount > 0) {
+        eligibilityReasons.push(`${contradictionCount} contradiction link${contradictionCount === 1 ? '' : 's'} attached`);
+    }
+    return {
+        memory,
+        rrfScore: input.rrfScore,
+        finalScore,
+        decayedScore: input.decayedScore,
+        contributions: input.contributions,
+        values: {
+            ftsScore: input.ftsScore,
+            vectorSimilarity: input.vectorSimilarity,
+            vectorBoost: input.vectorSimilarity * 0.3, // for explanation breakdown only
+            decayedScore: input.decayedScore,
+            priorityBoost,
+            recencyBoost,
+            categoryBoost,
+            linkBoost,
+            tagBoost,
+            activationBoost,
+            contradictionPenalty,
+            finalScore,
+        },
+        eligibilityReasons,
+        matchedCategory,
+    };
+}
+function buildSearchResult(c, ctx, includeExplanation) {
+    const result = {
+        memory: c.memory,
+        relevanceScore: c.finalScore,
+        recallEligibility: {
+            eligible: c.eligibilityReasons.length === 0,
+            reasons: c.eligibilityReasons,
+        },
+    };
+    if (includeExplanation) {
+        const explanation = buildSearchExplanation(c.memory, ctx, c.values);
+        if (explanation) {
+            explanation.eligibility = result.recallEligibility;
+            result.explanation = explanation;
+        }
+    }
+    return result;
+}

package/dist/memory/ranker/rrf.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reciprocal Rank Fusion (RRF).
+ *
+ * Combines ordered rank lists from multiple retrievers (e.g. BM25, vector,
+ * graph) into a single fused ranking. Robust to heterogeneous score scales:
+ * the only thing that matters is each retriever's rank order.
+ *
+ *   score(d) = Σ_i  w_i / (k + rank_i(d))
+ *
+ * - rank_i(d) is the 1-indexed position of d in retriever i's list.
+ * - w_i is the optional weight for retriever i (default 1).
+ * - k is a smoothing constant. Cormack et al. (2009) recommend 60.
+ *
+ * The function returns the union of ids across all rank lists, sorted by
+ * fused score descending. Ties break by id ascending for stable output.
+ */
+export interface RankList {
+    /** Identifier for this retriever (e.g. 'fts', 'vector', 'graph'). */
+    name: string;
+    /** Ordered ids, best-first. May be empty. Duplicates within a list are deduplicated, keeping the first occurrence. */
+    ids: number[];
+    /** Multiplicative weight on this retriever's contribution. Defaults to 1. */
+    weight?: number;
+}
+export interface RrfOptions {
+    /** RRF smoothing constant. Default 60. */
+    k?: number;
+}
+export interface RrfContribution {
+    name: string;
+    /** 1-indexed rank within that retriever's list. */
+    rank: number;
+    /** weight / (k + rank) — this contribution's addition to the final score. */
+    weighted: number;
+}
+export interface RrfResult {
+    id: number;
+    score: number;
+    contributions: RrfContribution[];
+}
+export declare function reciprocalRankFusion(rankLists: readonly RankList[], options?: RrfOptions): RrfResult[];