oh-my-llmwikimode 1.0.0

package/src/wiki/search-feedback.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * B2 Search Feedback — Append-Only Failure Log
+ *
+ * Stores zero-result search queries under .system/search-feedback/failures.jsonl
+ * Schema: {version, id, ts, query, query_hash, result_count, max_results, top_paths, source, actor, review_required, zero_results}
+ */
+
+export const SEARCH_FEEDBACK_VERSION = 1;
+export const SEARCH_FEEDBACK_DIR = ".system/search-feedback";
+export const SEARCH_FEEDBACK_FILE = "failures.jsonl";
+export const MAX_QUERY_LENGTH = 200;
+
+// Key-value secret patterns (key = secret) — keep key, redact value
+const KEY_VALUE_PATTERNS = [
+  /\btoken\s*[:=]\s*\S+/gi,
+  /\bapi[_-]?key\s*[:=]\s*\S+/gi,
+  /\bpassword\s*[:=]\s*\S+/gi,
+  /\bsecret\s*[:=]\s*\S+/gi,
+  /\bauth\s*[:=]\s*\S+/gi,
+  /\bbearer\s+\S+/gi,
+];
+
+// Standalone token patterns — replace entire match
+const STANDALONE_PATTERNS = [
+  /ghp_[a-zA-Z0-9]{36}/g,
+  /sk-(?:proj-)?[a-zA-Z0-9_-]+/g,
+];
+
+export function getSearchFeedbackPaths(wikiRoot) {
+  const dir = path.join(wikiRoot, SEARCH_FEEDBACK_DIR);
+  return {
+    dir,
+    failuresFile: path.join(dir, SEARCH_FEEDBACK_FILE),
+    suggestionsDir: path.join(wikiRoot, ".system/search-feedback/suggestions"),
+  };
+}
+
+function getFeedbackDir(wikiRoot) {
+  return path.join(wikiRoot, SEARCH_FEEDBACK_DIR);
+}
+
+function getFeedbackFilePath(wikiRoot) {
+  return path.join(getFeedbackDir(wikiRoot), SEARCH_FEEDBACK_FILE);
+}
+
+function ensureFeedbackDir(wikiRoot) {
+  const dir = getFeedbackDir(wikiRoot);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function hashQuery(query) {
+  if (!query) return "";
+  return crypto.createHash("sha256").update(String(query)).digest("hex");
+}
+
+function shortHash(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex").slice(0, 12);
+}
+
+/**
+ * Redact secrets and truncate query to MAX_QUERY_LENGTH characters.
+ *
+ * @param {string} query
+ * @returns {string}
+ */
+export function redactSearchQuery(query) {
+  let redacted = String(query || "");
+
+  // Redact key-value secrets (keep key, replace value)
+  for (const pattern of KEY_VALUE_PATTERNS) {
+    redacted = redacted.replace(pattern, (match) => {
+      const prefix = match.split(/[=:\s]/)[0];
+      return `${prefix}=***REDACTED***`;
+    });
+  }
+
+  // Redact standalone tokens (replace entire match)
+  for (const pattern of STANDALONE_PATTERNS) {
+    redacted = redacted.replace(pattern, "***REDACTED***");
+  }
+
+  if (redacted.length > MAX_QUERY_LENGTH) {
+    redacted = redacted.slice(0, MAX_QUERY_LENGTH - 3) + "...";
+  }
+
+  return redacted;
+}
+
+function generateFeedbackId(queryHash, timestamp) {
+  return `sf_${shortHash(queryHash + timestamp)}`;
+}
+
+/**
+ * Append a search failure event.
+ *
+ * @param {string} wikiRoot
+ * @param {Object} event
+ * @param {string} event.query - Original query text
+ * @param {number} event.result_count - Number of results (MVP: must be 0)
+ * @param {number} [event.max_results=3] - Max results requested
+ * @param {string[]} [event.top_paths=[]] - Top result paths if any
+ * @param {string} [event.source="wiki_search"] - Source: wiki_search, wiki_query, manual_cli
+ * @param {string} [event.actor="local"] - Actor identifier
+ * @param {Object} [options]
+ * @param {Date|string} [options.now] - Injected timestamp for determinism
+ * @returns {{success: boolean, path?: string, record?: Object, error?: string}}
+ */
+export function appendSearchFailure(wikiRoot, event, options = {}) {
+  try {
+    ensureFeedbackDir(wikiRoot);
+
+    const query = String(event.query || "").trim();
+    if (!query) {
+      return { success: false, error: "query is required" };
+    }
+
+    const resultCount = Number(event.result_count);
+    if (resultCount !== 0) {
+      return { success: false, error: "MVP only records zero-result failures" };
+    }
+
+    const now = options.now ? new Date(options.now) : new Date();
+    const ts = now.toISOString();
+    const queryHash = hashQuery(query);
+    const redactedQuery = redactSearchQuery(query);
+
+    const record = {
+      version: SEARCH_FEEDBACK_VERSION,
+      id: generateFeedbackId(queryHash, ts),
+      ts,
+      query: redactedQuery,
+      query_hash: queryHash,
+      result_count: 0,
+      max_results: Math.max(1, Math.min(Number(event.max_results) || 3, 20)),
+      top_paths: Array.isArray(event.top_paths) ? event.top_paths : [],
+      source: String(event.source || "wiki_search").trim(),
+      actor: String(event.actor || "local").trim(),
+      review_required: true,
+      zero_results: true,
+    };
+
+    const filePath = getFeedbackFilePath(wikiRoot);
+    const line = JSON.stringify(record);
+    fs.appendFileSync(filePath, `${line}\n`, { encoding: "utf-8" });
+
+    return { success: true, path: filePath, record };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Read search failure events.
+ *
+ * @param {string} wikiRoot
+ * @param {Object} [options]
+ * @param {number} [options.limit=100] - Max events to return
+ * @param {boolean} [options.reverse=false] - Newest first when true; default is oldest-first
+ * @returns {{success: boolean, events?: Array, error?: string}}
+ */
+export function readSearchFailures(wikiRoot, options = {}) {
+  try {
+    const filePath = getFeedbackFilePath(wikiRoot);
+
+    if (!fs.existsSync(filePath)) {
+      return { success: true, events: [] };
+    }
+
+    const limit = Number(options.limit) || 100;
+    const reverse = options.reverse === true;
+
+    const lines = fs
+      .readFileSync(filePath, "utf-8")
+      .split(/\r?\n/)
+      .filter(Boolean);
+
+    const events = [];
+    for (const line of lines) {
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    // Default is oldest-first (newest-last) per plan
+    if (reverse) {
+      events.reverse();
+    }
+
+    return { success: true, events: events.slice(0, limit) };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Count total search failures.
+ *
+ * @param {string} wikiRoot
+ * @returns {number}
+ */
+export function countSearchFailures(wikiRoot) {
+  const result = readSearchFailures(wikiRoot, { limit: Infinity, reverse: false });
+  return result.success ? result.events.length : 0;
+}

package/src/wiki/semantic-index.js

@@ -0,0 +1,333 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { EmbeddingModel } from "../utils/embedding-model.js";
+import { countSearchFailures } from "./search-feedback.js";
+
+export const SEMANTIC_INDEX_VERSION = "b2.0";
+export const SEMANTIC_INDEX_DIR = "data/semantic-index";
+export const SEMANTIC_INDEX_FILE = "embeddings.jsonl";
+export const SEMANTIC_BATCH_SIZE = 32;
+export const SEMANTIC_AUTO_BUILD_FAILURE_THRESHOLD = 10;
+export const SEMANTIC_AUTO_BUILD_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+
+const ENTRY_ROOTS = [
+  { relativePath: "editorial/lessons", category: "lessons" },
+  { relativePath: "inbox", category: "inbox" },
+  { relativePath: "problems", category: "problems" },
+];
+
+function compareStrings(left, right) {
+  const a = String(left || "");
+  const b = String(right || "");
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || "").trim()).filter(Boolean);
+  if (!value) return [];
+  return [String(value).trim()].filter(Boolean);
+}
+
+function unquoteScalar(value) {
+  const trimmed = String(value || "").trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+function parseMarkdownEntry(content) {
+  const match = String(content || "").match(/^\uFEFF?---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: String(content || "") };
+
+  const frontmatter = {};
+  let currentKey = null;
+  for (const line of match[1].split(/\r?\n/)) {
+    const itemMatch = line.trim().match(/^-\s+(.*)$/);
+    if (itemMatch && currentKey) {
+      if (!Array.isArray(frontmatter[currentKey])) frontmatter[currentKey] = [];
+      frontmatter[currentKey].push(unquoteScalar(itemMatch[1]));
+      continue;
+    }
+
+    const keyMatch = line.match(/^(\w+):\s*(.*)$/);
+    if (!keyMatch) continue;
+    const [, key, rawValue] = keyMatch;
+    currentKey = key;
+    if (!rawValue.trim()) {
+      frontmatter[key] = [];
+    } else {
+      frontmatter[key] = unquoteScalar(rawValue);
+    }
+  }
+
+  return { frontmatter, body: match[2].trim() };
+}
+
+function hashContent(content) {
+  return crypto.createHash("sha256").update(String(content || "")).digest("hex");
+}
+
+function getNow(options) {
+  return options.now ? new Date(options.now).toISOString() : new Date().toISOString();
+}
+
+function ensureSemanticIndexDir(wikiRoot) {
+  const dir = path.join(wikiRoot, SEMANTIC_INDEX_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function getSemanticIndexPath(wikiRoot) {
+  return path.join(wikiRoot, SEMANTIC_INDEX_DIR, SEMANTIC_INDEX_FILE);
+}
+
+function writeJsonl(filePath, records) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const content = records.length > 0
+    ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n`
+    : "";
+  const tmpFile = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  fs.writeFileSync(tmpFile, content, "utf-8");
+  fs.renameSync(tmpFile, filePath);
+}
+
+function scanMarkdownEntries(wikiRoot) {
+  const records = [];
+
+  function scanDir(directory, category) {
+    if (!fs.existsSync(directory)) return;
+    const dirents = fs.readdirSync(directory, { withFileTypes: true })
+      .sort((a, b) => compareStrings(a.name, b.name));
+
+    for (const dirent of dirents) {
+      const fullPath = path.join(directory, dirent.name);
+      if (dirent.isSymbolicLink()) continue;
+      if (dirent.isDirectory()) {
+        scanDir(fullPath, category);
+      } else if (dirent.isFile() && dirent.name.endsWith(".md")) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        const { frontmatter, body } = parseMarkdownEntry(content);
+        const entryPath = path.relative(wikiRoot, fullPath).replace(/\\/g, "/");
+        const title = String(frontmatter.title || path.basename(entryPath, ".md")).trim();
+        const indexText = [
+          title,
+          frontmatter.summary,
+          ...normalizeList(frontmatter.aliases),
+          ...normalizeList(frontmatter.tags),
+          body,
+        ].filter(Boolean).join("\n");
+
+        records.push({
+          category,
+          entry_path: entryPath,
+          title,
+          content,
+          content_hash: hashContent(content),
+          index_text: indexText,
+        });
+      }
+    }
+  }
+
+  for (const root of ENTRY_ROOTS) {
+    scanDir(path.join(wikiRoot, root.relativePath), root.category);
+  }
+
+  return records.sort((a, b) => compareStrings(a.entry_path, b.entry_path));
+}
+
+async function embedRecords(records, options = {}) {
+  const model = options.model || new EmbeddingModel();
+  if (!model.isAvailable()) {
+    return { success: false, error: "Embedding model is not available" };
+  }
+
+  await model.load();
+  const embeddingsByPath = new Map();
+  for (let index = 0; index < records.length; index += SEMANTIC_BATCH_SIZE) {
+    const batch = records.slice(index, index + SEMANTIC_BATCH_SIZE);
+    const embeddings = await model.embedBatch(batch.map((record) => record.index_text));
+    batch.forEach((record, offset) => {
+      embeddingsByPath.set(record.entry_path, embeddings[offset]);
+    });
+  }
+  return { success: true, embeddingsByPath };
+}
+
+export function loadSemanticIndex(wikiRoot) {
+  try {
+    const filePath = getSemanticIndexPath(wikiRoot);
+    if (!fs.existsSync(filePath)) {
+      return { success: true, entries: [], count: 0, path: filePath };
+    }
+
+    const entries = [];
+    const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed && parsed.entry_path && Array.isArray(parsed.embedding)) {
+          entries.push(parsed);
+        }
+      } catch {
+        // Skip malformed lines so one bad record does not disable the index.
+      }
+    }
+
+    entries.sort((a, b) => compareStrings(a.entry_path, b.entry_path));
+    return { success: true, entries, count: entries.length, path: filePath };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+export function getSemanticIndexSize(wikiRoot) {
+  const result = loadSemanticIndex(wikiRoot);
+  return result.success ? result.entries.length : 0;
+}
+
+export async function buildSemanticIndex(wikiRoot, options = {}) {
+  try {
+    ensureSemanticIndexDir(wikiRoot);
+    const scannedEntries = scanMarkdownEntries(wikiRoot);
+    const embedded = await embedRecords(scannedEntries, options);
+    if (!embedded.success) return embedded;
+
+    const ts = getNow(options);
+    const records = scannedEntries.map((entry) => ({
+      version: SEMANTIC_INDEX_VERSION,
+      entry_path: entry.entry_path,
+      title: entry.title,
+      content_hash: entry.content_hash,
+      embedding: embedded.embeddingsByPath.get(entry.entry_path),
+      ts,
+      source: "batch_index",
+    }));
+
+    const filePath = getSemanticIndexPath(wikiRoot);
+    writeJsonl(filePath, records);
+    return { success: true, count: records.length, path: filePath };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function updateSemanticIndex(wikiRoot, options = {}) {
+  try {
+    ensureSemanticIndexDir(wikiRoot);
+    const existing = loadSemanticIndex(wikiRoot);
+    if (!existing.success) return existing;
+
+    const existingByPath = new Map(existing.entries.map((entry) => [entry.entry_path, entry]));
+    const scannedEntries = scanMarkdownEntries(wikiRoot);
+    const changedEntries = scannedEntries.filter((entry) => {
+      const previous = existingByPath.get(entry.entry_path);
+      return !previous || previous.content_hash !== entry.content_hash;
+    });
+
+    const embedded = await embedRecords(changedEntries, options);
+    if (!embedded.success) return embedded;
+
+    const ts = getNow(options);
+    const records = scannedEntries.map((entry) => {
+      const previous = existingByPath.get(entry.entry_path);
+      if (previous && previous.content_hash === entry.content_hash) {
+        return previous;
+      }
+      return {
+        version: SEMANTIC_INDEX_VERSION,
+        entry_path: entry.entry_path,
+        title: entry.title,
+        content_hash: entry.content_hash,
+        embedding: embedded.embeddingsByPath.get(entry.entry_path),
+        ts,
+        source: "batch_index",
+      };
+    });
+
+    const filePath = getSemanticIndexPath(wikiRoot);
+    writeJsonl(filePath, records);
+    return { success: true, count: records.length, path: filePath };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+function getAutoBuildNowMs(options) {
+  if (!options.now) return Date.now();
+  const nowMs = new Date(options.now).getTime();
+  return Number.isFinite(nowMs) ? nowMs : Date.now();
+}
+
+function isSemanticIndexStale(wikiRoot, options = {}) {
+  const filePath = getSemanticIndexPath(wikiRoot);
+  if (!fs.existsSync(filePath)) return true;
+  const updatedAtMs = fs.statSync(filePath).mtimeMs;
+  return getAutoBuildNowMs(options) - updatedAtMs >= SEMANTIC_AUTO_BUILD_STALE_MS;
+}
+
+function warnAutoBuildFailure(action, error) {
+  const detail = error ? String(error) : "unknown error";
+  console.warn(`[llmwiki] Semantic index auto-${action} failed: ${detail}`);
+}
+
+export async function maybeAutoBuildSemanticIndex(wikiRoot, options = {}) {
+  try {
+    const failureCount = countSearchFailures(wikiRoot);
+    if (failureCount < SEMANTIC_AUTO_BUILD_FAILURE_THRESHOLD) {
+      return { triggered: false, reason: "failure_threshold_not_met" };
+    }
+
+    const indexResult = loadSemanticIndex(wikiRoot);
+    if (!indexResult.success) {
+      return { triggered: false, reason: `index_load_failed: ${indexResult.error || "unknown error"}` };
+    }
+
+    const indexPath = getSemanticIndexPath(wikiRoot);
+    const indexExists = fs.existsSync(indexPath);
+    const indexIsSmall = indexResult.count < SEMANTIC_AUTO_BUILD_FAILURE_THRESHOLD;
+    const indexIsStale = isSemanticIndexStale(wikiRoot, options);
+    if (!indexIsSmall && !indexIsStale) {
+      return { triggered: false, reason: "index_current" };
+    }
+
+    const action = !indexExists || indexIsSmall ? "build" : "update";
+    const result = action === "build"
+      ? await buildSemanticIndex(wikiRoot, options)
+      : await updateSemanticIndex(wikiRoot, options);
+
+    if (!result.success) {
+      warnAutoBuildFailure(action, result.error);
+      return { triggered: false, reason: `${action}_failed: ${result.error || "unknown error"}` };
+    }
+
+    return { triggered: true, reason: action === "build" ? "built" : "updated" };
+  } catch (error) {
+    warnAutoBuildFailure("build", error?.message || error);
+    return { triggered: false, reason: `auto_build_failed: ${error?.message || "unknown error"}` };
+  }
+}
+
+export async function buildIndex(wikiRoot, options = {}) {
+  return buildSemanticIndex(wikiRoot, options);
+}
+
+export async function updateIndex(wikiRoot, options = {}) {
+  return updateSemanticIndex(wikiRoot, options);
+}
+
+export function loadIndex(wikiRoot) {
+  return loadSemanticIndex(wikiRoot);
+}
+
+export function getIndexSize(wikiRoot) {
+  return getSemanticIndexSize(wikiRoot);
+}

package/src/wiki/semantic-search.js

@@ -0,0 +1,170 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { EmbeddingModel } from "../utils/embedding-model.js";
+import { loadSemanticIndex } from "./semantic-index.js";
+
+const DEFAULT_TOP_K = 5;
+const DEFAULT_THRESHOLD = 0.6;
+const SEMANTIC_RESULT_VERSION = "b2.0";
+const EXCLUDED_STATUSES = new Set([
+  "private",
+  "rejected",
+  "superseded",
+  "needs-clarification",
+]);
+
+function hashQuery(query) {
+  const normalized = String(query || "").trim();
+  if (!normalized) return "";
+  return crypto.createHash("sha256").update(normalized).digest("hex");
+}
+
+function semanticResultEnvelope(query, results, options = {}) {
+  return {
+    version: SEMANTIC_RESULT_VERSION,
+    query_hash: hashQuery(query),
+    method: "semantic",
+    results,
+    fallback_from_keyword: options.fallbackFromKeyword === true,
+    review_required: false,
+  };
+}
+
+function normalizeTopK(options) {
+  const requestedTopK = options.topK ?? options.maxResults ?? DEFAULT_TOP_K;
+  return Math.max(1, Math.min(Number(requestedTopK) || DEFAULT_TOP_K, 50));
+}
+
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function resolveSemanticEntryPath(wikiRoot, entryPath) {
+  const normalizedEntryPath = String(entryPath || "").replace(/\\/g, "/").trim();
+  if (!normalizedEntryPath || path.isAbsolute(normalizedEntryPath)) return null;
+
+  const rootPath = path.resolve(wikiRoot);
+  const fullPath = path.resolve(rootPath, ...normalizedEntryPath.split("/").filter(Boolean));
+  if (!isPathInside(rootPath, fullPath)) return null;
+
+  try {
+    const realRoot = fs.realpathSync(rootPath);
+    const realPath = fs.realpathSync(fullPath);
+    if (!isPathInside(realRoot, realPath)) return null;
+    return realPath;
+  } catch {
+    return null;
+  }
+}
+
+function unquoteStatus(value) {
+  const trimmed = String(value || "").trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1).trim();
+    }
+  }
+  return trimmed;
+}
+
+function readMarkdownStatus(content) {
+  const match = String(content || "").match(/^\uFEFF?---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (!match) return "candidate";
+
+  for (const line of match[1].split(/\r?\n/)) {
+    const statusMatch = line.match(/^status:\s*(.*)$/i);
+    if (statusMatch) return unquoteStatus(statusMatch[1]).toLowerCase() || "candidate";
+  }
+  return "candidate";
+}
+
+function isSemanticEntrySearchable(wikiRoot, entry) {
+  const sourcePath = resolveSemanticEntryPath(wikiRoot, entry?.entry_path);
+  if (!sourcePath) return false;
+
+  try {
+    const stat = fs.statSync(sourcePath);
+    if (!stat.isFile()) return false;
+
+    const status = readMarkdownStatus(fs.readFileSync(sourcePath, "utf-8"));
+    return !EXCLUDED_STATUSES.has(status);
+  } catch {
+    return false;
+  }
+}
+
+function compareStrings(left, right) {
+  const a = String(left || "");
+  const b = String(right || "");
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function vectorNorm(vector) {
+  return Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
+}
+
+export function cosineSimilarity(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return 0;
+  if (left.length === 0 || left.length !== right.length) return 0;
+
+  let dot = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    dot += Number(left[index] || 0) * Number(right[index] || 0);
+  }
+
+  const leftNorm = vectorNorm(left);
+  const rightNorm = vectorNorm(right);
+  if (leftNorm === 0 || rightNorm === 0) return 0;
+  return dot / (leftNorm * rightNorm);
+}
+
+export async function semanticSearch(wikiRoot, query, options = {}) {
+  const searchText = String(query || "").trim();
+
+  try {
+    if (!searchText) return semanticResultEnvelope(searchText, [], options);
+
+    const topK = normalizeTopK(options);
+    const threshold = typeof options.threshold === "number" ? options.threshold : DEFAULT_THRESHOLD;
+    const indexResult = Array.isArray(options.entries)
+      ? { success: true, entries: options.entries }
+      : loadSemanticIndex(wikiRoot);
+    if (!indexResult.success || indexResult.entries.length === 0) {
+      return semanticResultEnvelope(searchText, [], options);
+    }
+
+    const model = options.model || new EmbeddingModel();
+    if (!model.isAvailable()) return semanticResultEnvelope(searchText, [], options);
+    await model.load();
+    const queryEmbedding = await model.embed(searchText);
+
+    const results = [];
+    for (const entry of indexResult.entries) {
+      const similarity = cosineSimilarity(queryEmbedding, entry.embedding);
+      if (similarity < threshold) continue;
+      if (!isSemanticEntrySearchable(wikiRoot, entry)) continue;
+      results.push({
+        path: entry.entry_path,
+        title: entry.title,
+        similarity,
+      });
+    }
+
+    results.sort((a, b) => {
+      if (b.similarity !== a.similarity) return b.similarity - a.similarity;
+      const titleCompare = compareStrings(a.title, b.title);
+      if (titleCompare !== 0) return titleCompare;
+      return compareStrings(a.path, b.path);
+    });
+
+    return semanticResultEnvelope(searchText, results.slice(0, topK), options);
+  } catch {
+    return semanticResultEnvelope(searchText, [], options);
+  }
+}