bilmem 0.1.0

package/dist/search/index.d.ts

@@ -0,0 +1,44 @@
+import { K as Knowledge, S as Scope, J as JevResult } from '../types-Nxq5Gzay.js';
+
+/**
+ * Rebuildable in-memory search index powered by Orama.
+ * Note: Orama is strictly a candidate retrieval cache, NEVER the canonical source of truth.
+ */
+declare class SearchIndex {
+    private db;
+    private idToDocId;
+    init(): Promise<void>;
+    buildIndex(knowledgeList: Knowledge[]): Promise<void>;
+    upsert(item: Knowledge): Promise<void>;
+    delete(id: string): Promise<void>;
+    searchCandidates(term: string, limit?: number): Promise<string[]>;
+    size(): number;
+}
+
+interface LookupOptions {
+    query?: string;
+    positive?: string[];
+    negative?: string[];
+    scope?: Scope;
+    limit?: number;
+    includeRejected?: boolean;
+}
+interface KnowledgeStoreProvider {
+    getKnowledge(id: string): Promise<Knowledge | undefined>;
+    getAllKnowledge(): Promise<Knowledge[]>;
+}
+declare class Retriever {
+    private index;
+    private store;
+    constructor(index: SearchIndex, store: KnowledgeStoreProvider);
+    /**
+     * Executes the full Bilmem retrieval pipeline:
+     * 1. Query / Context
+     * 2. Candidate retrieval (small candidate set)
+     * 3. JEV contextual reranking
+     * 4. MATCH / POSSIBLE / REJECT classification with explanations
+     */
+    lookup(options?: LookupOptions): Promise<JevResult[]>;
+}
+
+export { Retriever as BilmemRetriever, type KnowledgeStoreProvider, type LookupOptions, SearchIndex as OramaIndex, Retriever, SearchIndex };

package/dist/search/index.js

@@ -0,0 +1,301 @@
+// src/search/indexer.ts
+import { create, insert, remove, search } from "@orama/orama";
+var SearchIndex = class {
+  db = null;
+  idToDocId = /* @__PURE__ */ new Map();
+  async init() {
+    this.db = await create({
+      schema: {
+        id: "string",
+        statement: "string",
+        type: "string",
+        scope: "string",
+        status: "string",
+        positive: "string[]",
+        negative: "string[]",
+        tags: "string[]"
+      }
+    });
+    this.idToDocId.clear();
+  }
+  async buildIndex(knowledgeList) {
+    await this.init();
+    for (const item of knowledgeList) {
+      await this.upsert(item);
+    }
+  }
+  async upsert(item) {
+    if (!this.db) {
+      await this.init();
+    }
+    const existingDocId = this.idToDocId.get(item.id);
+    if (existingDocId) {
+      try {
+        await remove(this.db, existingDocId);
+      } catch {
+      }
+      this.idToDocId.delete(item.id);
+    }
+    const docId = await insert(this.db, {
+      id: item.id,
+      statement: item.statement,
+      type: item.type,
+      scope: item.scope,
+      status: item.status,
+      positive: item.positive,
+      negative: item.negative,
+      tags: item.tags ?? []
+    });
+    this.idToDocId.set(item.id, docId);
+  }
+  async delete(id) {
+    if (!this.db) return;
+    const docId = this.idToDocId.get(id);
+    if (docId) {
+      try {
+        await remove(this.db, docId);
+      } catch {
+      }
+      this.idToDocId.delete(id);
+    }
+  }
+  async searchCandidates(term, limit = 25) {
+    if (!this.db) {
+      return [];
+    }
+    const cleanTerm = term.trim();
+    if (!cleanTerm) {
+      return Array.from(this.idToDocId.keys()).slice(0, limit);
+    }
+    try {
+      const results = await search(this.db, {
+        term: cleanTerm,
+        limit,
+        threshold: 0.2
+      });
+      return results.hits.map((h) => h.document.id);
+    } catch {
+      return Array.from(this.idToDocId.keys()).slice(0, limit);
+    }
+  }
+  size() {
+    return this.idToDocId.size;
+  }
+};
+
+// src/jev/scorer.ts
+var statementTokenCache = /* @__PURE__ */ new WeakMap();
+function extractTokens(text) {
+  if (!text) return /* @__PURE__ */ new Set();
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9_-]/g, " ").split(/\s+/).filter((t) => t.length > 2)
+  );
+}
+function getKnowledgeStatementTokens(k) {
+  let tokens = statementTokenCache.get(k);
+  if (!tokens) {
+    tokens = extractTokens(k.statement);
+    statementTokenCache.set(k, tokens);
+  }
+  return tokens;
+}
+function evaluateJev(knowledge, context) {
+  const queryTokens = extractTokens(context.query);
+  const contextPos = new Set((context.positive ?? []).map((p) => p.trim().toLowerCase()));
+  const contextNeg = new Set((context.negative ?? []).map((n) => n.trim().toLowerCase()));
+  const knowPos = new Set((knowledge.positive ?? []).map((p) => p.trim().toLowerCase()));
+  const knowNeg = new Set((knowledge.negative ?? []).map((n) => n.trim().toLowerCase()));
+  const negativeConflicts = [];
+  for (const n of knowNeg) {
+    if (contextPos.has(n) || queryTokens.has(n)) {
+      negativeConflicts.push(`Knowledge forbids "${n}", which was present in context`);
+    }
+  }
+  for (const p of knowPos) {
+    if (contextNeg.has(p)) {
+      negativeConflicts.push(`Context forbids "${p}", which is required by knowledge`);
+    }
+  }
+  const positiveMatches = [];
+  for (const p of knowPos) {
+    if (contextPos.has(p)) {
+      positiveMatches.push(`Context cue: ${p}`);
+    } else {
+      for (const q of queryTokens) {
+        if (p === q || p.startsWith(q) || q.startsWith(p)) {
+          positiveMatches.push(`Query term match: ${p}`);
+          break;
+        }
+      }
+    }
+  }
+  const stmtTokens = getKnowledgeStatementTokens(knowledge);
+  let queryOverlapCount = 0;
+  for (const q of queryTokens) {
+    let matched = false;
+    for (const st of stmtTokens) {
+      if (q === st || q.startsWith(st) || st.startsWith(q)) {
+        matched = true;
+        break;
+      }
+    }
+    if (matched) {
+      queryOverlapCount++;
+      positiveMatches.push(`Statement term: ${q}`);
+    }
+  }
+  const totalCues = Math.max(1, knowPos.size);
+  const matchedCuesCount = positiveMatches.filter((m2) => m2.startsWith("Context cue") || m2.startsWith("Query term")).length;
+  const cueMatchRatio = matchedCuesCount / totalCues;
+  const tokenOverlapScore = queryTokens.size > 0 ? queryOverlapCount / Math.max(1, queryTokens.size) : 0;
+  const rawPositiveScore = 0.65 * cueMatchRatio + 0.35 * tokenOverlapScore;
+  let scopeMultiplier = 1;
+  const targetScope = (context.scope ?? "project").toLowerCase();
+  const knowScope = (knowledge.scope ?? "project").toLowerCase();
+  if (targetScope === knowScope) {
+    scopeMultiplier = 1;
+  } else if (knowScope === "global" || targetScope.startsWith(knowScope)) {
+    scopeMultiplier = 0.85;
+  } else if (knowScope === "project" && targetScope.startsWith("branch:")) {
+    scopeMultiplier = 0.9;
+  } else {
+    scopeMultiplier = 0.3;
+  }
+  const m = knowledge.metrics;
+  const evRatio = (m.support_count + 1) / (m.support_count + 2 * m.contradiction_count + 1);
+  const confidenceFactor = knowledge.confidence * evRatio;
+  let outcomeAdjustment = 0;
+  if (m.successful_outcomes > 0) {
+    outcomeAdjustment += Math.min(0.1, m.successful_outcomes * 0.03);
+  }
+  if (m.failed_outcomes > 0) {
+    outcomeAdjustment -= Math.min(0.2, m.failed_outcomes * 0.05);
+  }
+  let score = (rawPositiveScore * 0.45 + confidenceFactor * 0.4 + outcomeAdjustment) * scopeMultiplier;
+  if (knowledge.status === "stale") {
+    score *= 0.6;
+  } else if (knowledge.status === "contradicted") {
+    score *= 0.3;
+  } else if (knowledge.status === "invalid" || knowledge.status === "superseded") {
+    score *= 0.1;
+  }
+  let status = "POSSIBLE";
+  const reasons = [];
+  if (negativeConflicts.length > 0) {
+    score = Math.max(0.01, score * 0.2);
+    status = "REJECT";
+    reasons.push(`Rejected due to ${negativeConflicts.length} negative contextual conflicts.`);
+  } else if (score >= 0.45 && positiveMatches.length > 0) {
+    status = "MATCH";
+    reasons.push(`Strong contextual match with ${positiveMatches.length} matching signals.`);
+  } else if (score >= 0.25) {
+    status = "POSSIBLE";
+    reasons.push(`Potential match; partial contextual overlap.`);
+  } else {
+    status = "REJECT";
+    reasons.push(`Insufficient contextual match score (${score.toFixed(2)} < 0.25).`);
+  }
+  const finalScore = Math.round(Math.min(1, Math.max(0, score)) * 100) / 100;
+  const explanation = {
+    positiveMatches,
+    negativeConflicts,
+    score: finalScore,
+    confidence: knowledge.confidence,
+    status,
+    reasons
+  };
+  return {
+    knowledge,
+    status,
+    score: finalScore,
+    explanation
+  };
+}
+
+// src/jev/matcher.ts
+function rerankCandidates(candidates, context) {
+  const results = [];
+  for (const candidate of candidates) {
+    const res = evaluateJev(candidate, context);
+    results.push(res);
+  }
+  const statusPriority = {
+    MATCH: 3,
+    POSSIBLE: 2,
+    REJECT: 1
+  };
+  results.sort((a, b) => {
+    const prioDiff = (statusPriority[b.status] ?? 0) - (statusPriority[a.status] ?? 0);
+    if (prioDiff !== 0) return prioDiff;
+    const scoreDiff = b.score - a.score;
+    if (Math.abs(scoreDiff) > 1e-3) return scoreDiff;
+    return b.knowledge.confidence - a.knowledge.confidence;
+  });
+  return results;
+}
+
+// src/search/retriever.ts
+var Retriever = class {
+  constructor(index, store) {
+    this.index = index;
+    this.store = store;
+  }
+  index;
+  store;
+  /**
+   * Executes the full Bilmem retrieval pipeline:
+   * 1. Query / Context
+   * 2. Candidate retrieval (small candidate set)
+   * 3. JEV contextual reranking
+   * 4. MATCH / POSSIBLE / REJECT classification with explanations
+   */
+  async lookup(options = {}) {
+    const limit = options.limit ?? 5;
+    const query = options.query?.trim() ?? "";
+    const positive = options.positive ?? [];
+    const negative = options.negative ?? [];
+    const scope = options.scope ?? "project";
+    const searchTerms = [];
+    if (query) searchTerms.push(query);
+    if (positive.length > 0) searchTerms.push(...positive.slice(0, 3));
+    const searchTerm = searchTerms.join(" ").trim();
+    let candidateIds = await this.index.searchCandidates(searchTerm, 30);
+    let candidates = [];
+    if (candidateIds.length === 0) {
+      const all = await this.store.getAllKnowledge();
+      candidates = all.filter((k) => k.status !== "invalid" && k.status !== "superseded");
+    } else {
+      for (const id of candidateIds) {
+        const item = await this.store.getKnowledge(id);
+        if (item && item.status !== "invalid" && item.status !== "superseded") {
+          candidates.push(item);
+        }
+      }
+      if (candidates.length < 5) {
+        const all = await this.store.getAllKnowledge();
+        for (const k of all) {
+          if (!candidateIds.includes(k.id) && k.status !== "invalid" && k.status !== "superseded") {
+            candidates.push(k);
+            if (candidates.length >= 20) break;
+          }
+        }
+      }
+    }
+    const queryContext = {
+      query,
+      positive,
+      negative,
+      scope
+    };
+    const reranked = rerankCandidates(candidates, queryContext);
+    const filtered = options.includeRejected ? reranked : reranked.filter((r) => r.status !== "REJECT");
+    return filtered.slice(0, limit);
+  }
+};
+export {
+  Retriever as BilmemRetriever,
+  SearchIndex as OramaIndex,
+  Retriever,
+  SearchIndex
+};
+//# sourceMappingURL=index.js.map

package/dist/search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/search/indexer.ts","../../src/jev/scorer.ts","../../src/jev/matcher.ts","../../src/search/retriever.ts"],"sourcesContent":["import { create, insert, remove, search, type AnyOrama } from '@orama/orama';\nimport type { Knowledge } from '../core/types.js';\n\n/**\n * Rebuildable in-memory search index powered by Orama.\n * Note: Orama is strictly a candidate retrieval cache, NEVER the canonical source of truth.\n */\nexport class SearchIndex {\n  private db: AnyOrama | null = null;\n  private idToDocId = new Map<string, string>();\n\n  async init(): Promise<void> {\n    this.db = await create({\n      schema: {\n        id: 'string',\n        statement: 'string',\n        type: 'string',\n        scope: 'string',\n        status: 'string',\n        positive: 'string[]',\n        negative: 'string[]',\n        tags: 'string[]'\n      }\n    });\n    this.idToDocId.clear();\n  }\n\n  async buildIndex(knowledgeList: Knowledge[]): Promise<void> {\n    await this.init();\n    for (const item of knowledgeList) {\n      await this.upsert(item);\n    }\n  }\n\n  async upsert(item: Knowledge): Promise<void> {\n    if (!this.db) {\n      await this.init();\n    }\n\n    // If already in index, remove first\n    const existingDocId = this.idToDocId.get(item.id);\n    if (existingDocId) {\n      try {\n        await remove(this.db!, existingDocId);\n      } catch {\n        // Ignore if already deleted\n      }\n      this.idToDocId.delete(item.id);\n    }\n\n    const docId = await insert(this.db!, {\n      id: item.id,\n      statement: item.statement,\n      type: item.type,\n      scope: item.scope,\n      status: item.status,\n      positive: item.positive,\n      negative: item.negative,\n      tags: item.tags ?? []\n    });\n\n    this.idToDocId.set(item.id, docId);\n  }\n\n  async delete(id: string): Promise<void> {\n    if (!this.db) return;\n    const docId = this.idToDocId.get(id);\n    if (docId) {\n      try {\n        await remove(this.db, docId);\n      } catch {\n        // Ignore\n      }\n      this.idToDocId.delete(id);\n    }\n  }\n\n  async searchCandidates(term: string, limit = 25): Promise<string[]> {\n    if (!this.db) {\n      return [];\n    }\n\n    const cleanTerm = term.trim();\n    if (!cleanTerm) {\n      return Array.from(this.idToDocId.keys()).slice(0, limit);\n    }\n\n    try {\n      const results = await search(this.db, {\n        term: cleanTerm,\n        limit,\n        threshold: 0.2\n      });\n\n      return results.hits.map((h) => (h.document as any).id as string);\n    } catch {\n      // Fallback: term might contain special characters or fail tokenization\n      return Array.from(this.idToDocId.keys()).slice(0, limit);\n    }\n  }\n\n  size(): number {\n    return this.idToDocId.size;\n  }\n}\n\nexport { SearchIndex as OramaIndex };\n\n","import type {\n  Knowledge,\n  JevMatchStatus,\n  JevExplanation,\n  JevResult,\n  Scope\n} from '../core/types.js';\n\nexport interface QueryContext {\n  query?: string;\n  positive?: string[];\n  negative?: string[];\n  scope?: Scope;\n}\n\nconst statementTokenCache = new WeakMap<Knowledge, Set<string>>();\n\nfunction extractTokens(text?: string): Set<string> {\n  if (!text) return new Set();\n  return new Set(\n    text\n      .toLowerCase()\n      .replace(/[^a-z0-9_-]/g, ' ')\n      .split(/\\s+/)\n      .filter((t) => t.length > 2)\n  );\n}\n\nfunction getKnowledgeStatementTokens(k: Knowledge): Set<string> {\n  let tokens = statementTokenCache.get(k);\n  if (!tokens) {\n    tokens = extractTokens(k.statement);\n    statementTokenCache.set(k, tokens);\n  }\n  return tokens;\n}\n\n/**\n * Evaluates JEV-style positive and negative contextual proximity for a knowledge unit.\n */\nexport function evaluateJev(\n  knowledge: Knowledge,\n  context: QueryContext\n): JevResult {\n  const queryTokens = extractTokens(context.query);\n  const contextPos = new Set((context.positive ?? []).map((p) => p.trim().toLowerCase()));\n  const contextNeg = new Set((context.negative ?? []).map((n) => n.trim().toLowerCase()));\n\n  const knowPos = new Set((knowledge.positive ?? []).map((p) => p.trim().toLowerCase()));\n  const knowNeg = new Set((knowledge.negative ?? []).map((n) => n.trim().toLowerCase()));\n\n  // 1. Negative Conflict Detection\n  const negativeConflicts: string[] = [];\n\n  // Knowledge forbids something present in positive context\n  for (const n of knowNeg) {\n    if (contextPos.has(n) || queryTokens.has(n)) {\n      negativeConflicts.push(`Knowledge forbids \"${n}\", which was present in context`);\n    }\n  }\n\n  // Context forbids something present in knowledge\n  for (const p of knowPos) {\n    if (contextNeg.has(p)) {\n      negativeConflicts.push(`Context forbids \"${p}\", which is required by knowledge`);\n    }\n  }\n\n  // 2. Positive Matches\n  const positiveMatches: string[] = [];\n\n  // Direct cue overlap\n  for (const p of knowPos) {\n    if (contextPos.has(p)) {\n      positiveMatches.push(`Context cue: ${p}`);\n    } else {\n      // Check if any query token matches or stems into cue\n      for (const q of queryTokens) {\n        if (p === q || p.startsWith(q) || q.startsWith(p)) {\n          positiveMatches.push(`Query term match: ${p}`);\n          break;\n        }\n      }\n    }\n  }\n\n  // Statement query token overlap\n  const stmtTokens = getKnowledgeStatementTokens(knowledge);\n  let queryOverlapCount = 0;\n  for (const q of queryTokens) {\n    let matched = false;\n    for (const st of stmtTokens) {\n      if (q === st || q.startsWith(st) || st.startsWith(q)) {\n        matched = true;\n        break;\n      }\n    }\n    if (matched) {\n      queryOverlapCount++;\n      positiveMatches.push(`Statement term: ${q}`);\n    }\n  }\n\n  // 3. Positive Score Calculation\n  const totalCues = Math.max(1, knowPos.size);\n  const matchedCuesCount = positiveMatches.filter((m) => m.startsWith('Context cue') || m.startsWith('Query term')).length;\n  const cueMatchRatio = matchedCuesCount / totalCues;\n  const tokenOverlapScore = queryTokens.size > 0 ? queryOverlapCount / Math.max(1, queryTokens.size) : 0;\n  const rawPositiveScore = 0.65 * cueMatchRatio + 0.35 * tokenOverlapScore;\n\n  // 4. Scope Alignment\n  let scopeMultiplier = 1.0;\n  const targetScope = (context.scope ?? 'project').toLowerCase();\n  const knowScope = (knowledge.scope ?? 'project').toLowerCase();\n\n  if (targetScope === knowScope) {\n    scopeMultiplier = 1.0;\n  } else if (knowScope === 'global' || targetScope.startsWith(knowScope)) {\n    scopeMultiplier = 0.85;\n  } else if (knowScope === 'project' && targetScope.startsWith('branch:')) {\n    scopeMultiplier = 0.90;\n  } else {\n    // Mismatched scopes\n    scopeMultiplier = 0.30;\n  }\n\n  // 5. Confidence and Evidence Ratio\n  const m = knowledge.metrics;\n  const evRatio = (m.support_count + 1) / (m.support_count + 2 * m.contradiction_count + 1);\n  const confidenceFactor = knowledge.confidence * evRatio;\n\n  // 6. Outcome Boost / Penalty\n  let outcomeAdjustment = 0;\n  if (m.successful_outcomes > 0) {\n    outcomeAdjustment += Math.min(0.10, m.successful_outcomes * 0.03);\n  }\n  if (m.failed_outcomes > 0) {\n    outcomeAdjustment -= Math.min(0.20, m.failed_outcomes * 0.05);\n  }\n\n  // 7. Base Combined Score\n  let score = (rawPositiveScore * 0.45 + confidenceFactor * 0.40 + outcomeAdjustment) * scopeMultiplier;\n\n  // Stale or Contradicted Status Penalty\n  if (knowledge.status === 'stale') {\n    score *= 0.6;\n  } else if (knowledge.status === 'contradicted') {\n    score *= 0.3;\n  } else if (knowledge.status === 'invalid' || knowledge.status === 'superseded') {\n    score *= 0.1;\n  }\n\n  // 8. Negative Conflict Penalty & Decision\n  let status: JevMatchStatus = 'POSSIBLE';\n  const reasons: string[] = [];\n\n  if (negativeConflicts.length > 0) {\n    // Severe penalty for negative conflicts\n    score = Math.max(0.01, score * 0.2);\n    status = 'REJECT';\n    reasons.push(`Rejected due to ${negativeConflicts.length} negative contextual conflicts.`);\n  } else if (score >= 0.45 && positiveMatches.length > 0) {\n    status = 'MATCH';\n    reasons.push(`Strong contextual match with ${positiveMatches.length} matching signals.`);\n  } else if (score >= 0.25) {\n    status = 'POSSIBLE';\n    reasons.push(`Potential match; partial contextual overlap.`);\n  } else {\n    status = 'REJECT';\n    reasons.push(`Insufficient contextual match score (${score.toFixed(2)} < 0.25).`);\n  }\n\n  const finalScore = Math.round(Math.min(1.0, Math.max(0.0, score)) * 100) / 100;\n\n  const explanation: JevExplanation = {\n    positiveMatches,\n    negativeConflicts,\n    score: finalScore,\n    confidence: knowledge.confidence,\n    status,\n    reasons\n  };\n\n  return {\n    knowledge,\n    status,\n    score: finalScore,\n    explanation\n  };\n}\n","import type { Knowledge, JevResult } from '../core/types.js';\nimport { evaluateJev, type QueryContext } from './scorer.js';\n\n/**\n * Re-ranks a small set of candidate knowledge units using JEV contextual evaluation.\n */\nexport function rerankCandidates(\n  candidates: Knowledge[],\n  context: QueryContext\n): JevResult[] {\n  const results: JevResult[] = [];\n\n  for (const candidate of candidates) {\n    const res = evaluateJev(candidate, context);\n    results.push(res);\n  }\n\n  // Sort: MATCH first, then POSSIBLE, then REJECT; within each group, highest score first\n  const statusPriority: Record<string, number> = {\n    MATCH: 3,\n    POSSIBLE: 2,\n    REJECT: 1\n  };\n\n  results.sort((a, b) => {\n    const prioDiff = (statusPriority[b.status] ?? 0) - (statusPriority[a.status] ?? 0);\n    if (prioDiff !== 0) return prioDiff;\n    const scoreDiff = b.score - a.score;\n    if (Math.abs(scoreDiff) > 0.001) return scoreDiff;\n    return b.knowledge.confidence - a.knowledge.confidence;\n  });\n\n  return results;\n}\n","import type { Knowledge, JevResult, Scope } from '../core/types.js';\nimport { rerankCandidates } from '../jev/matcher.js';\nimport type { QueryContext } from '../jev/scorer.js';\nimport type { SearchIndex } from './indexer.js';\n\nexport interface LookupOptions {\n  query?: string;\n  positive?: string[];\n  negative?: string[];\n  scope?: Scope;\n  limit?: number;\n  includeRejected?: boolean;\n}\n\nexport interface KnowledgeStoreProvider {\n  getKnowledge(id: string): Promise<Knowledge | undefined>;\n  getAllKnowledge(): Promise<Knowledge[]>;\n}\n\nexport class Retriever {\n  constructor(\n    private index: SearchIndex,\n    private store: KnowledgeStoreProvider\n  ) {}\n\n  /**\n   * Executes the full Bilmem retrieval pipeline:\n   * 1. Query / Context\n   * 2. Candidate retrieval (small candidate set)\n   * 3. JEV contextual reranking\n   * 4. MATCH / POSSIBLE / REJECT classification with explanations\n   */\n  async lookup(options: LookupOptions = {}): Promise<JevResult[]> {\n    const limit = options.limit ?? 5;\n    const query = options.query?.trim() ?? '';\n    const positive = options.positive ?? [];\n    const negative = options.negative ?? [];\n    const scope = options.scope ?? 'project';\n\n    const searchTerms: string[] = [];\n    if (query) searchTerms.push(query);\n    if (positive.length > 0) searchTerms.push(...positive.slice(0, 3));\n\n    const searchTerm = searchTerms.join(' ').trim();\n\n    // 1. Retrieve Candidate IDs from Orama\n    let candidateIds = await this.index.searchCandidates(searchTerm, 30);\n\n    // If no candidate found via search or empty term, get active items from store\n    let candidates: Knowledge[] = [];\n    if (candidateIds.length === 0) {\n      const all = await this.store.getAllKnowledge();\n      candidates = all.filter((k) => k.status !== 'invalid' && k.status !== 'superseded');\n    } else {\n      for (const id of candidateIds) {\n        const item = await this.store.getKnowledge(id);\n        if (item && item.status !== 'invalid' && item.status !== 'superseded') {\n          candidates.push(item);\n        }\n      }\n\n      // If candidates are very few (< 5), broaden candidate pool with active knowledge\n      if (candidates.length < 5) {\n        const all = await this.store.getAllKnowledge();\n        for (const k of all) {\n          if (!candidateIds.includes(k.id) && k.status !== 'invalid' && k.status !== 'superseded') {\n            candidates.push(k);\n            if (candidates.length >= 20) break;\n          }\n        }\n      }\n    }\n\n    // 2. JEV Reranking on Candidates\n    const queryContext: QueryContext = {\n      query,\n      positive,\n      negative,\n      scope\n    };\n\n    const reranked = rerankCandidates(candidates, queryContext);\n\n    // 3. Filter by includeRejected and limit\n    const filtered = options.includeRejected\n      ? reranked\n      : reranked.filter((r) => r.status !== 'REJECT');\n\n    return filtered.slice(0, limit);\n  }\n}\n\nexport { Retriever as BilmemRetriever };\n\n"],"mappings":"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","names":["m"]}

package/dist/stats/index.d.ts

@@ -0,0 +1,60 @@
+import { M as MetricEvent, K as KnowledgeHealthCategory, S as Storage, a as KnowledgeStatsReport, b as StatsReport } from '../canonical-CglQQ0xc.js';
+export { E as EffectivenessRatio, J as JevRejectReason } from '../canonical-CglQQ0xc.js';
+import { K as Knowledge } from '../types-Nxq5Gzay.js';
+import '../search/index.js';
+
+declare function getEventsFilePath(rootDir: string): string;
+/**
+ * Appends a metric event to .bilmem/events.jsonl.
+ * Fire-and-forget safe: will not crash caller if filesystem error occurs.
+ */
+declare function appendMetricEvent(rootDir: string, event: MetricEvent): Promise<void>;
+/**
+ * Reads all metric events from .bilmem/events.jsonl with resilience against
+ * corrupted tails, empty lines, and malformed entries.
+ */
+declare function readMetricEvents(rootDir: string, filter?: {
+    sinceTimestamp?: number;
+    knowledgeId?: string;
+}): Promise<MetricEvent[]>;
+/**
+ * Safely resets only the metric events log.
+ * Preserves all knowledge, evidence, unknowns, rules, and receipts.
+ */
+declare function resetMetricEvents(rootDir: string): Promise<void>;
+
+declare function classifyKnowledgeHealth(knowledge: Knowledge, knowledgeEvents: MetricEvent[], independentSourcesCount: number): {
+    category: KnowledgeHealthCategory;
+    reason: string;
+};
+declare function computeStats(storage: Storage, events: MetricEvent[], options?: {
+    since?: string;
+    sinceTimestamp?: number;
+}): Promise<StatsReport>;
+declare function computeKnowledgeStats(storage: Storage, knowledgeId: string, events: MetricEvent[]): Promise<KnowledgeStatsReport | undefined>;
+
+/**
+ * Resolves a --since argument into a numeric unix timestamp in milliseconds.
+ * Supports relative duration (e.g. 24h, 7d, 30d) or Git revision (e.g. HEAD~20, commit SHA).
+ */
+declare function resolveSinceTimestamp(since: string, projectDir?: string): Promise<number>;
+
+declare function formatStatsReport(report: StatsReport): string;
+declare function formatKnowledgeStatsReport(report: KnowledgeStatsReport): string;
+
+interface RunStatsOptions {
+    rootDir?: string;
+    since?: string;
+    knowledgeId?: string;
+    reset?: boolean;
+}
+/**
+ * High-level stats runner for CLI and programmatic API.
+ */
+declare function runStats(options?: RunStatsOptions): Promise<{
+    report?: StatsReport;
+    knowledgeReport?: KnowledgeStatsReport;
+    reset?: boolean;
+}>;
+
+export { KnowledgeHealthCategory, KnowledgeStatsReport, MetricEvent, type RunStatsOptions, StatsReport, appendMetricEvent, classifyKnowledgeHealth, computeKnowledgeStats, computeStats, formatKnowledgeStatsReport, formatStatsReport, getEventsFilePath, readMetricEvents, resetMetricEvents, resolveSinceTimestamp, runStats };