seer-mcp 0.1.0

package/src/indexer/context.ts

@@ -0,0 +1,340 @@
+import { Store } from '../db/store.js';
+import { rankedBehavior } from './behavior.js';
+import { computeRisk, RiskResult } from './risk.js';
+import type { SymbolRow, CallerRow, CalleeRow } from '../types.js';
+
+/**
+ * One compact, structured pre-edit packet for a symbol.
+ *
+ * The aim is workflow compression: an agent that's about to edit a symbol
+ * should be able to call ONE tool and get back the deterministic evidence
+ * it needs — definition, callers, callees, routes, config reads, behavioral
+ * tests, recent history, complexity, module, blast radius, and the
+ * decomposed risk score. The agent then decides which slices to expand
+ * (`seer_history` for full chain, `seer_callers` for everyone, etc.).
+ *
+ * This is intentionally NOT an explanation layer. Seer-Core stays
+ * deterministic facts only; any narrative about "why this matters" belongs
+ * outside Core.
+ */
+
+export interface ContextPacket {
+  symbol: {
+    id: number;
+    name: string;
+    qualifiedName: string | null;
+    kind: string;
+    file: string;
+    lineStart: number;
+    lineEnd: number;
+    signature: string | null;
+    pagerank: number;
+    symbolRole: string | null;
+  };
+  module: { id: number; label: string } | null;
+  /** v10 — monorepo boundary the symbol's file belongs to (null when none). */
+  boundary: { id: number; label: string; kind: string; rootRelPath: string } | null;
+  complexity: {
+    loc: number | null;
+    cyclomatic: number | null;
+    cognitive: number | null;
+    maxNesting: number | null;
+  };
+  callers: {
+    total: number;
+    preview: Array<{
+      name: string; qualifiedName: string | null; kind: string;
+      file: string; line: number;
+    }>;
+  };
+  callees: {
+    total: number;
+    preview: Array<{
+      name: string; kind: string | null;
+      file: string | null; line: number | null;
+    }>;
+  };
+  blastRadius: {
+    directCallers: number;
+    transitiveCallers: number;
+    /** Sample of the highest-PageRank reverse-reachable callers (capped). */
+    topAffected: Array<{ id: number; name: string; qualifiedName: string | null; file: string; pagerank: number }>;
+    maxDepth: number;
+  };
+  routes: Array<{ method: string; path: string; framework: string }>;
+  configKeys: Array<{ key: string; source: string; line: number }>;
+  /**
+   * v8 Track-G — outbound service calls this symbol makes (preview, capped).
+   * Empty array on Pre-Track-G DBs or symbols with no outgoing client calls.
+   */
+  serviceCalls: Array<{
+    method: string | null;
+    path: string | null;
+    framework: string;
+    rawTarget: string;
+    line: number;
+    envKey: string | null;
+    hostHint: string | null;
+    confidence: number;
+  }>;
+  /**
+   * v8 Track-G — service-link evidence pointing at this symbol as the handler
+   * (inbound) and as the caller (outbound). Capped previews.
+   */
+  serviceLinksInbound: Array<{
+    routePath: string | null;
+    method: string | null;
+    matchKind: string;
+    confidence: number;
+    callerName: string | null;
+    callerFile: string | null;
+  }>;
+  serviceLinksOutbound: Array<{
+    routePath: string | null;
+    method: string | null;
+    matchKind: string;
+    confidence: number;
+    handlerName: string | null;
+    handlerFile: string | null;
+  }>;
+  behavior: {
+    direct: number;
+    indirect: number;
+    namingMatches: number;
+    sameFileMatches: number;
+    preview: Array<{
+      name: string; qualifiedName: string | null; file: string; lineStart: number;
+      relationship: string; assertionCount: number; specificity: number;
+    }>;
+  };
+  recentHistory: {
+    total: number;
+    preview: Array<{
+      sha: string; author: string | null; email: string | null;
+      committedAt: number; message: string | null;
+      linesAdded: number; linesRemoved: number;
+      prNumber: number | null; prUrl: string | null;
+      confidence: number;
+    }>;
+  };
+  fileChurn: {
+    commitCount: number;
+    lastCommitAt: number | null;
+    topAuthor: string | null;
+  } | null;
+  risk: {
+    risk: 'low' | 'medium' | 'high';
+    score: number;
+    signals: RiskResult['signals'];
+    signalContributions: RiskResult['signalContributions'];
+  };
+  source: 'tree-sitter';
+}
+
+export interface ContextOptions {
+  filePath?: string;
+  callerLimit?: number;
+  calleeLimit?: number;
+  testLimit?: number;
+  historyLimit?: number;
+  callerDepth?: number;
+  affectedLimit?: number;
+}
+
+export function buildContext(
+  store: Store,
+  nameOrId: string | number,
+  options: ContextOptions = {},
+): ContextPacket | null {
+  const callerLimit = options.callerLimit ?? 10;
+  const calleeLimit = options.calleeLimit ?? 10;
+  const testLimit = options.testLimit ?? 10;
+  const historyLimit = options.historyLimit ?? 5;
+  const callerDepth = options.callerDepth ?? 3;
+  const affectedLimit = options.affectedLimit ?? 10;
+
+  let target: SymbolRow | null = null;
+  if (typeof nameOrId === 'number') {
+    target = store.getSymbolById(nameOrId);
+  } else {
+    const defs = store.getDefinition(nameOrId, { filePath: options.filePath });
+    if (defs.length === 0) return null;
+    target = defs[0];
+  }
+  if (!target) return null;
+
+  // Callers + callees use the id-based path so short-name siblings
+  // (Alpha.run vs Beta.run) don't share evidence. The legacy name-based
+  // APIs (findCallers / countCallers / findCallees) intentionally stay
+  // broad for the agent-facing CLI tools — Track E packets always have a
+  // resolved id and should never collapse.
+  const totalCallers = store.countCallersById(target.id);
+  const directCallers: CallerRow[] = store.findCallersById(target.id, callerLimit);
+
+  const allCallees: CalleeRow[] = store.findCalleesById(target.id);
+  const calleesPreview = allCallees.slice(0, calleeLimit);
+
+  // Blast radius.
+  const reverseHits = store.reverseReachableWithDepth(target.id, callerDepth);
+  const directRows = store.rawDb().prepare(
+    "SELECT DISTINCT from_id FROM edges WHERE to_id = ? AND kind = 'call'",
+  ).all(target.id) as Array<{ from_id: unknown }>;
+  const directSet = new Set<number>(directRows.map(r => Number(r.from_id)));
+  const transitive = reverseHits.filter(h => !directSet.has(h.id));
+  let topAffected: ContextPacket['blastRadius']['topAffected'] = [];
+  if (reverseHits.length > 0) {
+    const ids = reverseHits.map(h => h.id);
+    const ph = ids.map(() => '?').join(',');
+    const rows = store.rawDb().prepare(`
+      SELECT s.id, s.name, s.qualified_name AS qualifiedName, f.path AS file, s.pagerank
+      FROM symbols s JOIN files f ON f.id = s.file_id
+      WHERE s.id IN (${ph}) AND s.is_rankable = 1
+      ORDER BY s.pagerank DESC
+      LIMIT ?
+    `).all(...ids, affectedLimit) as Array<{
+      id: unknown; name: unknown; qualifiedName: unknown; file: unknown; pagerank: unknown;
+    }>;
+    topAffected = rows.map(r => ({
+      id: Number(r.id),
+      name: String(r.name),
+      qualifiedName: r.qualifiedName == null ? null : String(r.qualifiedName),
+      file: String(r.file),
+      pagerank: Number(r.pagerank),
+    }));
+  }
+
+  // Routes / config / behavior / history.
+  const routes = store.routesForHandler(target.id);
+  const configKeys = store.configKeysForSymbol(target.id);
+  const behavior = rankedBehavior(store, target.id, { limit: testLimit });
+
+  // v8 Track-G — service-link evidence. Capped previews so the packet stays
+  // compact even when the symbol is a hub.
+  const SERVICE_CALL_PREVIEW_CAP = 12;
+  const SERVICE_LINK_PREVIEW_CAP = 12;
+  const serviceCallsRows = store.listServiceCalls({
+    callerSymbolId: target.id, limit: SERVICE_CALL_PREVIEW_CAP,
+  });
+  const serviceLinksInbound = store.serviceLinksForHandler(target.id, { limit: SERVICE_LINK_PREVIEW_CAP });
+  const serviceLinksOutbound = store.serviceLinksForCaller(target.id, { limit: SERVICE_LINK_PREVIEW_CAP });
+  const history = store.getSymbolHistory(target.id, { limit: historyLimit });
+  const totalHistory = store.countSymbolHistory(target.id);
+  const fileChurn = (() => {
+    try {
+      const c = store.getFileChurn(target.filePath);
+      if (!c) return null;
+      return { commitCount: c.commitCount, lastCommitAt: c.lastCommitAt, topAuthor: c.topAuthor };
+    } catch { return null; }
+  })();
+
+  // Risk (reuses behavior + history + signals computed above; cheaper to
+  // recompute than to share through a back-channel.)
+  const risk = computeRisk(store, target.id, { callerDepth })!;
+
+  const moduleRow = store.moduleForFile(target.fileId);
+  const boundaryRow = store.boundaryForFile(target.fileId);
+
+  return {
+    symbol: {
+      id: target.id, name: target.name, qualifiedName: target.qualifiedName,
+      kind: target.kind, file: target.filePath,
+      lineStart: target.lineStart, lineEnd: target.lineEnd,
+      signature: target.signature, pagerank: target.pagerank,
+      symbolRole: target.symbolRole ?? null,
+    },
+    module: moduleRow,
+    boundary: boundaryRow,
+    complexity: {
+      loc: target.loc ?? null,
+      cyclomatic: target.cyclomatic ?? null,
+      cognitive: target.cognitive ?? null,
+      maxNesting: target.maxNesting ?? null,
+    },
+    callers: {
+      total: totalCallers,
+      preview: directCallers.map(c => ({
+        name: c.callerName, qualifiedName: c.callerQualifiedName, kind: c.callerKind,
+        file: c.callerFile, line: c.callerLine,
+      })),
+    },
+    callees: {
+      total: allCallees.length,
+      preview: calleesPreview.map(c => ({
+        name: c.calleeName, kind: c.calleeKind,
+        file: c.calleeFile, line: c.calleeLineStart,
+      })),
+    },
+    blastRadius: {
+      directCallers: directSet.size,
+      transitiveCallers: transitive.length,
+      topAffected,
+      maxDepth: callerDepth,
+    },
+    routes,
+    configKeys,
+    serviceCalls: serviceCallsRows.map(sc => ({
+      method: sc.method,
+      path: sc.normalizedPath,
+      framework: sc.framework,
+      rawTarget: sc.rawTarget,
+      line: sc.line,
+      envKey: sc.envKey,
+      hostHint: sc.hostHint,
+      confidence: sc.confidence,
+    })),
+    serviceLinksInbound: serviceLinksInbound.map(l => ({
+      routePath: l.routePath,
+      method: l.routeMethod ?? l.callMethod,
+      matchKind: l.matchKind,
+      confidence: l.confidence,
+      callerName: l.callerQualifiedName ?? l.callerName,
+      callerFile: l.callerFile,
+    })),
+    serviceLinksOutbound: serviceLinksOutbound.map(l => ({
+      routePath: l.routePath,
+      method: l.routeMethod ?? l.callMethod,
+      matchKind: l.matchKind,
+      confidence: l.confidence,
+      handlerName: l.handlerQualifiedName ?? l.handlerName,
+      handlerFile: l.handlerFile,
+    })),
+    behavior: {
+      direct: behavior?.direct ?? 0,
+      indirect: behavior?.indirect ?? 0,
+      namingMatches: behavior?.namingMatches ?? 0,
+      sameFileMatches: behavior?.sameFileMatches ?? 0,
+      preview: (behavior?.tests ?? []).map(t => ({
+        name: t.testSymbol.name,
+        qualifiedName: t.testSymbol.qualifiedName,
+        file: t.testSymbol.file,
+        lineStart: t.testSymbol.lineStart,
+        relationship: t.relationship,
+        assertionCount: t.assertionCount,
+        specificity: t.specificity,
+      })),
+    },
+    recentHistory: {
+      total: totalHistory,
+      preview: history.map(h => ({
+        sha: h.commitSha,
+        author: h.authorName,
+        email: h.authorEmail,
+        committedAt: h.committedAt,
+        message: h.message,
+        linesAdded: h.linesAdded,
+        linesRemoved: h.linesRemoved,
+        prNumber: h.prNumber,
+        prUrl: h.prUrl,
+        confidence: h.confidence,
+      })),
+    },
+    fileChurn,
+    risk: {
+      risk: risk.risk,
+      score: risk.score,
+      signals: risk.signals,
+      signalContributions: risk.signalContributions,
+    },
+    source: 'tree-sitter',
+  };
+}

package/src/indexer/continuity.ts

@@ -0,0 +1,322 @@
+/**
+ * v10 — Symbol Rename/Move Continuity heuristics.
+ *
+ * Goal: when exact `symbol_key` history walking terminates (because the
+ * function was renamed or moved), surface honest, confidence-labelled
+ * continuity evidence so the agent can decide whether to trust the link.
+ *
+ * Heuristics (current pass — opt-in, low-confidence by default):
+ *   - shape_hash exact match: previous-symbol candidate has the same
+ *     structural SimHash → strong (confidence 0.85+)
+ *   - shape_hash close match: small Hamming distance (≤ 4) + similar name
+ *     → medium (confidence 0.65)
+ *   - signature similarity: same arity + same containing class/module
+ *     → weak (confidence 0.5)
+ *   - same file rename history: file was renamed in git history, the
+ *     historical file had a same-shape function with a different name → boost
+ *     (confidence 0.75)
+ *
+ * Stored on `symbol_history_continuity`. Never pretends rename continuity
+ * is certain.
+ *
+ * This module does NOT replace existing exact-key history. It only proposes
+ * additional links when buildSymbolHistory's exact-key walk ran out of
+ * commits. The Preflight / seer_history layers can read continuity rows
+ * alongside symbol_history.
+ */
+
+import { Store } from '../db/store.js';
+
+export interface ContinuityCandidate {
+  symbolId: number;
+  symbolKey: string;
+  previousSymbolKey: string;
+  previousName: string;
+  previousFile: string;
+  confidence: number;
+  matchReasons: string[];
+}
+
+export interface ContinuityResult {
+  candidatesConsidered: number;
+  inserted: number;
+  skipped: number;
+  elapsedMs: number;
+}
+
+/**
+ * Run the continuity pass over every symbol whose recorded history has
+ * fewer than `historyThreshold` commits AND that has a shape_hash. For each
+ * such symbol we scan other symbols sharing a close shape_hash and propose
+ * the highest-confidence candidate (deduped per symbol_id).
+ */
+export function buildContinuity(
+  store: Store,
+  options: {
+    historyThreshold?: number;
+    maxHammingDistance?: number;
+    log?: (msg: string) => void;
+    /** When true, also create candidate links for symbols that have full history
+     *  (useful for fixture tests and debugging). Default false. */
+    includeAllSymbols?: boolean;
+  } = {},
+): ContinuityResult {
+  const start = Date.now();
+  const log = options.log ?? (() => { /* */ });
+  const historyThreshold = options.historyThreshold ?? 1;
+  const maxHamming = options.maxHammingDistance ?? 4;
+
+  // Pool of candidates: every symbol with a shape_hash.
+  const pool = store.listSymbolsWithShapeHash({ minLoc: 1, limit: 100000 });
+  if (pool.length === 0) {
+    log('no shape-hashed symbols; nothing to do');
+    return { candidatesConsidered: 0, inserted: 0, skipped: 0, elapsedMs: Date.now() - start };
+  }
+
+  // Bucket by qualifiedName/name → list of candidates (so we can detect
+  // rename: same shape, different name).
+  const byHash = new Map<string, typeof pool>();
+  for (const s of pool) {
+    const k = s.shapeHash.toString();
+    const list = byHash.get(k) ?? [];
+    list.push(s);
+    byHash.set(k, list);
+  }
+
+  let considered = 0;
+  let inserted = 0;
+  let skipped = 0;
+
+  const raw = store.rawDb();
+
+  for (const s of pool) {
+    // Find the symbol's stored history count. If it's >= historyThreshold
+    // AND we're not in includeAllSymbols mode, skip — exact history is fine.
+    if (!options.includeAllSymbols) {
+      const cnt = raw.prepare(
+        'SELECT COUNT(*) AS c FROM symbol_history WHERE symbol_id = ?',
+      ).get(s.id) as { c: number } | undefined;
+      if (cnt && cnt.c >= historyThreshold) continue;
+    }
+
+    // Exact shape match candidates with a DIFFERENT (qualifiedName ?? name).
+    const exactMatches = (byHash.get(s.shapeHash.toString()) ?? [])
+      .filter(c => c.id !== s.id);
+    if (exactMatches.length > 0) {
+      const cand = pickBestCandidate(s, exactMatches);
+      if (cand) {
+        const sameClass = sharesContainingScope(s, cand);
+        const nameRelated = similarName(s.name, cand.name);
+        // How many OTHER symbols share this exact shape? A shape shared by many
+        // symbols (trivial getters, `return null;`, boilerplate) is NOT a
+        // reliable rename signal on its own. Only assert a high-confidence link
+        // when the shape is (near-)unique to this pair; otherwise require
+        // corroboration (same scope or a related name) and label the ambiguity
+        // honestly with a lower, capped confidence. Never pretend certainty.
+        const ambiguous = exactMatches.length >= 2;
+        if (ambiguous && !sameClass && !nameRelated) {
+          // Common shape, no corroborating evidence — do not invent a rename.
+          skipped++;
+          continue;
+        }
+        considered++;
+        const reasons = ['shape_hash_exact'];
+        if (sameClass) reasons.push('same_containing_scope');
+        if (nameRelated) reasons.push('similar_name');
+        let confidence: number;
+        if (ambiguous) {
+          reasons.push(`ambiguous_shape_bucket:n=${exactMatches.length + 1}`);
+          confidence = 0.6;
+          if (sameClass) confidence = Math.min(0.7, confidence + 0.05);
+          if (nameRelated) confidence = Math.min(0.7, confidence + 0.05);
+        } else {
+          confidence = 0.85;
+          if (sameClass) confidence = Math.min(0.95, confidence + 0.05);
+          if (nameRelated) confidence = Math.min(0.95, confidence + 0.05);
+        }
+        upsertContinuity(store, {
+          symbolId: s.id,
+          symbolKey: keyFor(s),
+          previousSymbolKey: keyFor(cand),
+          previousName: cand.name,
+          previousFile: cand.filePath,
+          confidence,
+          matchReasons: reasons,
+        });
+        inserted++;
+        continue;
+      }
+    }
+
+    // Close hash match.
+    let best: { peer: typeof pool[number]; distance: number } | null = null;
+    for (const peer of pool) {
+      if (peer.id === s.id) continue;
+      if ((peer.name === s.name) && (peer.qualifiedName === s.qualifiedName)) continue;
+      const d = hammingDistance(s.shapeHash, peer.shapeHash);
+      if (d > maxHamming) continue;
+      if (!best || d < best.distance) best = { peer, distance: d };
+    }
+    if (best && best.distance <= maxHamming) {
+      const cand = best.peer;
+      // Only act when names are at least loosely related (share a prefix or
+      // a suffix), to avoid pairing every short function in the codebase.
+      if (similarName(s.name, cand.name) || sharesContainingScope(s, cand)) {
+        considered++;
+        const reasons = [`shape_hash_close:d=${best.distance}`];
+        if (similarName(s.name, cand.name)) reasons.push('similar_name');
+        if (sharesContainingScope(s, cand)) reasons.push('same_containing_scope');
+        const confidence = best.distance === 0 ? 0.8
+          : best.distance <= 2 ? 0.6
+          : 0.4;
+        upsertContinuity(store, {
+          symbolId: s.id,
+          symbolKey: keyFor(s),
+          previousSymbolKey: keyFor(cand),
+          previousName: cand.name,
+          previousFile: cand.filePath,
+          confidence,
+          matchReasons: reasons,
+        });
+        inserted++;
+        continue;
+      }
+    }
+
+    skipped++;
+  }
+
+  return {
+    candidatesConsidered: considered,
+    inserted, skipped,
+    elapsedMs: Date.now() - start,
+  };
+}
+
+function upsertContinuity(
+  store: Store, c: ContinuityCandidate,
+): void {
+  const raw = store.rawDb();
+  raw.prepare(`
+    INSERT INTO symbol_history_continuity
+      (symbol_id, symbol_key, previous_symbol_key, previous_name, previous_file,
+       bridging_sha, confidence, match_reasons, recorded_at)
+    VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?)
+    ON CONFLICT(symbol_id, previous_symbol_key) DO UPDATE SET
+      confidence = excluded.confidence,
+      match_reasons = excluded.match_reasons,
+      previous_name = excluded.previous_name,
+      previous_file = excluded.previous_file,
+      recorded_at = excluded.recorded_at
+  `).run(
+    c.symbolId, c.symbolKey, c.previousSymbolKey,
+    c.previousName, c.previousFile,
+    c.confidence, JSON.stringify(c.matchReasons),
+    Date.now(),
+  );
+}
+
+function keyFor(s: { kind: string; qualifiedName: string | null; name: string }): string {
+  return `${s.kind}:${s.qualifiedName ?? s.name}`;
+}
+
+function sharesContainingScope(
+  a: { qualifiedName: string | null; name: string; filePath: string },
+  b: { qualifiedName: string | null; name: string; filePath: string },
+): boolean {
+  if (a.filePath === b.filePath) return true;
+  // Compare class/module prefix in the qualified name (e.g. `AuthService.foo`
+  // and `AuthService.bar` share `AuthService`).
+  const aQual = a.qualifiedName ?? '';
+  const bQual = b.qualifiedName ?? '';
+  if (!aQual.includes('.') || !bQual.includes('.')) return false;
+  const aPrefix = aQual.split('.').slice(0, -1).join('.');
+  const bPrefix = bQual.split('.').slice(0, -1).join('.');
+  return aPrefix.length > 0 && aPrefix === bPrefix;
+}
+
+function similarName(a: string, b: string): boolean {
+  if (!a || !b) return false;
+  if (a === b) return false; // we only flag potential RENAMES
+  const aL = a.toLowerCase();
+  const bL = b.toLowerCase();
+  // Same prefix of length >= 4 or same suffix of length >= 4.
+  const minLen = Math.min(aL.length, bL.length);
+  if (minLen < 4) return false;
+  let prefix = 0;
+  while (prefix < minLen && aL[prefix] === bL[prefix]) prefix++;
+  if (prefix >= 4) return true;
+  let suffix = 0;
+  while (suffix < minLen && aL[aL.length - 1 - suffix] === bL[bL.length - 1 - suffix]) suffix++;
+  if (suffix >= 4) return true;
+  // Names that differ by a verb prefix swap (validate → verify) — drop the
+  // first 4 characters and compare the rest.
+  if (aL.length >= 4 && bL.length >= 4 && aL.slice(4) === bL.slice(4)) return true;
+  return false;
+}
+
+function pickBestCandidate<T extends { id: number; name: string; qualifiedName: string | null; filePath: string; kind: string }>(
+  target: T,
+  candidates: T[],
+): T | null {
+  // Prefer same-file rename. Then same-class rename. Then any candidate.
+  const sameFile = candidates.filter(c => c.filePath === target.filePath);
+  if (sameFile.length > 0) return sameFile[0];
+  const sameClass = candidates.filter(c => sharesContainingScope(target, c));
+  if (sameClass.length > 0) return sameClass[0];
+  return candidates[0] ?? null;
+}
+
+function hammingDistance(a: bigint, b: bigint): number {
+  let x = a ^ b;
+  let n = 0;
+  while (x !== 0n) {
+    x &= x - 1n;
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Fetch continuity rows for a given symbol id, ordered by confidence desc.
+ */
+export function getContinuityForSymbol(
+  store: Store, symbolId: number,
+): Array<{
+  previousSymbolKey: string;
+  previousName: string;
+  previousFile: string;
+  confidence: number;
+  matchReasons: string[];
+}> {
+  if (!store.hasV10()) return [];
+  try {
+    const rows = store.rawDb().prepare(`
+      SELECT previous_symbol_key AS previousSymbolKey,
+             previous_name AS previousName,
+             previous_file AS previousFile,
+             confidence, match_reasons AS matchReasons
+      FROM symbol_history_continuity
+      WHERE symbol_id = ?
+      ORDER BY confidence DESC, id DESC
+    `).all(symbolId) as Array<{
+      previousSymbolKey: unknown; previousName: unknown; previousFile: unknown;
+      confidence: unknown; matchReasons: unknown;
+    }>;
+    return rows.map(r => ({
+      previousSymbolKey: String(r.previousSymbolKey),
+      previousName: String(r.previousName ?? ''),
+      previousFile: String(r.previousFile ?? ''),
+      confidence: Number(r.confidence ?? 0),
+      matchReasons: parseReasons(r.matchReasons),
+    }));
+  } catch { return []; }
+}
+
+function parseReasons(v: unknown): string[] {
+  if (typeof v !== 'string') return [];
+  try {
+    const parsed = JSON.parse(v);
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+  } catch { return []; }
+}