codetrap 0.1.3 → 0.1.4

package/src/lib/embedding-index.ts

@@ -0,0 +1,53 @@
+import type { Database } from "bun:sqlite";
+import * as embeddingQueries from "../db/embedding-queries";
+import type { Trap } from "../domain/trap";
+import type { TrapStatus } from "./constants";
+import type {
+  EmbeddingConfig,
+  FreshEmbedding,
+  StoredEmbedding,
+} from "./embedder";
+import type { EmbeddingStateCounts } from "./embedding-health";
+
+export type EmbeddingIndexFilter = {
+  scope?: string;
+  category?: string;
+  status?: TrapStatus | "all";
+};
+
+export type EmbeddingRefreshFilter = EmbeddingIndexFilter & {
+  force?: boolean;
+  limit?: number;
+};
+
+export class DatabaseEmbeddingIndex {
+  constructor(private readonly db: Database) {}
+
+  get(trapId: number): StoredEmbedding | null {
+    return embeddingQueries.getEmbedding(this.db, trapId);
+  }
+
+  save(record: StoredEmbedding): void {
+    embeddingQueries.upsertEmbedding(this.db, record);
+  }
+
+  delete(trapId: number): void {
+    embeddingQueries.deleteEmbedding(this.db, trapId);
+  }
+
+  freshEmbeddings(config: EmbeddingConfig, filter: EmbeddingIndexFilter = {}): FreshEmbedding[] {
+    return embeddingQueries.getAllFreshEmbeddings(this.db, config, filter);
+  }
+
+  trapsNeedingEmbeddings(config: EmbeddingConfig, filter: EmbeddingRefreshFilter = {}): Trap[] {
+    return embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, filter);
+  }
+
+  countEmbeddable(filter: EmbeddingIndexFilter = {}): number {
+    return embeddingQueries.countEmbeddableTraps(this.db, filter);
+  }
+
+  stateCounts(config: EmbeddingConfig | null, filter: EmbeddingIndexFilter = {}): EmbeddingStateCounts {
+    return embeddingQueries.getEmbeddingStateCounts(this.db, config, filter);
+  }
+}

package/src/lib/format.ts

@@ -18,7 +18,7 @@ Why relevant: ${card.why_relevant}
 Avoid: ${card.avoid}
 Do instead: ${card.do_instead}
 Score: ${formatScore(card.score)} (${sourceLabel})
-Next: get_trap id=${card.next_action.details_args.id} scope=${card.next_action.details_args.scope}`;
+Next: codetrap show ${card.trap_id} --scope ${card.scope} --json`;
 }
 
 export function formatTrapDetail(t: Trap, scopeLabel: string): string {

package/src/lib/output-json.ts

@@ -1,4 +1,4 @@
-import type { RankingSignal, TrapActionCard, TrapDetails } from "../domain/trap";
+import type { RankingSignal, TrapActionCard, TrapDetails, TrapSearchDiagnostic } from "../domain/trap";
 import type { Scope } from "./constants";
 import type { DoctorReport } from "./doctor";
 import type { EmbeddingStatsResult } from "./embedding-health";
@@ -16,11 +16,24 @@ export type JsonTrapDetails = {
   evidence: JsonTrapEvidence[];
 };
 
-export type CliTrapActionCard = Omit<TrapActionCard, "next_action"> & {
+export type CliTrapActionCard = TrapActionCard & {
   next_action: {
     command: string;
   };
   ranking_signals?: RankingSignal[];
+  diagnostics?: TrapSearchDiagnostic[];
+};
+
+export type McpTrapActionCard = TrapActionCard & {
+  next_action: {
+    details_tool: "get_trap";
+    details_args: {
+      id: number;
+      scope: Scope;
+    };
+  };
+  ranking_signals?: RankingSignal[];
+  diagnostics?: TrapSearchDiagnostic[];
 };
 
 export type McpTextResult = {
@@ -43,6 +56,7 @@ export function toCliSearchJson(cards: TrapActionCard[]): CliTrapActionCard[] {
     severity: card.severity,
     score: card.score,
     sources: card.sources,
+    ...(card.diagnostics ? { diagnostics: card.diagnostics } : {}),
     ...(card.ranking_signals ? { ranking_signals: card.ranking_signals } : {}),
     next_action: {
       command: `codetrap show ${card.trap_id} --scope ${card.scope} --json`,
@@ -50,8 +64,17 @@ export function toCliSearchJson(cards: TrapActionCard[]): CliTrapActionCard[] {
   }));
 }
 
-export function toMcpSearchJson(cards: TrapActionCard[]): TrapActionCard[] {
-  return cards;
+export function toMcpSearchJson(cards: TrapActionCard[]): McpTrapActionCard[] {
+  return cards.map((card) => ({
+    ...card,
+    next_action: {
+      details_tool: "get_trap",
+      details_args: {
+        id: card.trap_id,
+        scope: card.scope,
+      },
+    },
+  }));
 }
 
 export function toMcpTextJson(value: unknown, isError = false): McpTextResult {
@@ -102,10 +125,12 @@ export function toStatsJson(stats: TrapStatsResult, embeddings?: EmbeddingStatsR
           embeddings: embeddings?.project ?? null,
         }
       : null,
-    global: {
-      ...stats.global,
-      embeddings: embeddings?.global ?? null,
-    },
+    global: stats.global
+      ? {
+          ...stats.global,
+          embeddings: embeddings?.global ?? null,
+        }
+      : null,
   };
 }
 

package/src/lib/scope-context.ts

@@ -1,10 +1,12 @@
-import { join, resolve } from "node:path";
 import { openGlobal, openProject } from "../db/connection";
 import { TrapRepository } from "../db/repository";
 import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
 import type { Scope } from "./constants";
 import type { EmbeddingProvider } from "./embedder";
-import { findProjectRoot, getGlobalDB } from "./scope";
+import { findProjectRoot, getGlobalDB, resolveScopePath } from "./scope";
+import { ScopePathResolver } from "./scope-path";
+
+const scopePath = new ScopePathResolver();
 
 export type ScopeContext = {
   cwd: string;
@@ -14,12 +16,12 @@ export type ScopeContext = {
 };
 
 export function createScopeContext(cwd = process.cwd()): ScopeContext {
-  const resolvedCwd = resolve(cwd);
+  const resolvedCwd = resolveScopePath(cwd);
   const projectRoot = findProjectRoot(resolvedCwd);
   return {
     cwd: resolvedCwd,
     project_root: projectRoot,
-    project_db: projectRoot ? join(projectRoot, CODETRAP_DIR, TRAPS_DB_FILE) : null,
+    project_db: projectRoot ? scopePath.join(projectRoot, CODETRAP_DIR, TRAPS_DB_FILE) : null,
     global_db: getGlobalDB(),
   };
 }

package/src/lib/scope-maintenance.ts

@@ -0,0 +1,71 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { TrapRepository } from "../db/repository";
+import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
+import { ScopePathResolver } from "./scope-path";
+
+const scopePath = new ScopePathResolver();
+
+export type ScopeMaintenanceCommand = "repair-scope" | "migrate-project";
+
+export type ScopeMaintenancePaths = {
+  command: ScopeMaintenanceCommand;
+  fromProjectPath: string;
+  toProjectPath: string;
+  sourceDb: string;
+  destinationDb: string;
+};
+
+export function buildScopeMaintenancePaths(input: {
+  command: ScopeMaintenanceCommand;
+  fromProjectPath: string;
+  toProjectPath: string;
+}): ScopeMaintenancePaths {
+  return {
+    command: input.command,
+    fromProjectPath: input.fromProjectPath,
+    toProjectPath: input.toProjectPath,
+    sourceDb: projectDbPath(input.fromProjectPath),
+    destinationDb: projectDbPath(input.toProjectPath),
+  };
+}
+
+export function validateScopeMaintenancePaths(input: ScopeMaintenancePaths): void {
+  if (input.command === "migrate-project" && scopePath.same(input.fromProjectPath, input.toProjectPath)) {
+    throw new Error("--from-project-path and --to-project-path must be different.");
+  }
+  if (scopePath.same(input.sourceDb, input.destinationDb)) {
+    throw new Error("Source and destination database paths are the same.");
+  }
+  if (!existsSync(scopePath.join(input.toProjectPath, CODETRAP_DIR))) {
+    throw new Error(`Destination project is not initialized: ${input.toProjectPath}. Run 'codetrap init' first.`);
+  }
+}
+
+export function projectDbPath(projectPath: string): string {
+  return scopePath.join(projectPath, CODETRAP_DIR, TRAPS_DB_FILE);
+}
+
+export function withReadOnlyScopeRepository<T>(dbPath: string, callback: (repository: TrapRepository) => T): T {
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    return callback(new TrapRepository(db));
+  } finally {
+    db.close();
+  }
+}
+
+export function backupScopeDatabase(dbPath: string, label: string): string {
+  const backupDir = join(dirname(dbPath), "backups");
+  mkdirSync(backupDir, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = join(backupDir, `${basename(dbPath)}.${label}.${timestamp}.backup`);
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    writeFileSync(backupPath, db.serialize());
+  } finally {
+    db.close();
+  }
+  return backupPath;
+}

package/src/lib/scope-migration.ts

@@ -1,19 +1,23 @@
-import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
 import { openDatabase } from "../db/connection";
 import { TrapRepository } from "../db/repository";
 import type { TrapExportRecord } from "../domain/trap";
-import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
-import { findProjectRoot } from "./scope";
+import { findProjectRoot, resolveScopePath } from "./scope";
+import {
+  backupScopeDatabase,
+  buildScopeMaintenancePaths,
+  validateScopeMaintenancePaths,
+  withReadOnlyScopeRepository,
+  type ScopeMaintenanceCommand,
+} from "./scope-maintenance";
 import {
   deleteTransferredSourceTraps,
   importProjectTrapTransfer,
   type TrapTransferMapping,
 } from "./trap-transfer";
 
-export type ScopeMigrationCommand = "repair-scope" | "migrate-project";
+export type ScopeMigrationCommand = ScopeMaintenanceCommand;
 export type ScopeMigrationMode = "dry-run" | "apply";
 
 export type ScopeMigrationCandidate = {
@@ -151,16 +155,16 @@ export function formatScopeMigrationText(result: ScopeMigrationResult): string {
 
 function buildScopeMigrationPlan(options: ScopeMigrationOptions): ScopeMigrationPlan {
   const resolved = resolveScopeMigrationOptions(options);
-  validateMigrationPaths(resolved);
+  validateScopeMaintenancePaths(resolved);
   const sourceDbExists = existsSync(resolved.sourceDb);
   const destinationDbExists = existsSync(resolved.destinationDb);
   const records = sourceDbExists
-    ? withReadOnlyRepository(resolved.sourceDb, (repository) =>
+    ? withReadOnlyScopeRepository(resolved.sourceDb, (repository) =>
         repository.exportProjectTrapsByPath(resolved.fromProjectPath)
       )
     : [];
   const destinationBefore = destinationDbExists
-    ? withReadOnlyRepository(resolved.destinationDb, (repository) =>
+    ? withReadOnlyScopeRepository(resolved.destinationDb, (repository) =>
         repository.countProjectTrapsByPath(resolved.toProjectPath)
       )
     : 0;
@@ -177,8 +181,8 @@ function buildScopeMigrationPlan(options: ScopeMigrationOptions): ScopeMigration
 
 function applyScopeMigrationPlan(plan: ScopeMigrationPlan): ScopeMigrationApplyResult {
   const backups = {
-    source_db: backupDatabase(plan.sourceDb, "source"),
-    destination_db: plan.destinationDbExists ? backupDatabase(plan.destinationDb, "destination") : null,
+    source_db: backupScopeDatabase(plan.sourceDb, "source"),
+    destination_db: plan.destinationDbExists ? backupScopeDatabase(plan.destinationDb, "destination") : null,
   };
 
   const applyResult = applyScopeMigration(
@@ -197,45 +201,27 @@ function applyScopeMigrationPlan(plan: ScopeMigrationPlan): ScopeMigrationApplyR
 }
 
 function resolveScopeMigrationOptions(options: ScopeMigrationOptions): ResolvedScopeMigration {
-  const cwd = resolve(options.cwd ?? process.cwd());
+  const cwd = resolveScopePath(options.cwd ?? process.cwd());
   const projectRoot = findProjectRoot(cwd);
-  const fromProjectPath = resolve(options.fromProjectPath ?? homedir());
+  const fromProjectPath = resolveScopePath(options.fromProjectPath ?? homedir());
   const rawToProjectPath = options.toProjectPath ?? projectRoot;
 
   if (!rawToProjectPath) {
     throw new Error("Destination project not found. Run 'codetrap init' first, or pass --to-project-path.");
   }
-  const toProjectPath = resolve(rawToProjectPath);
+  const toProjectPath = resolveScopePath(rawToProjectPath);
 
   return {
-    command: options.command,
+    ...buildScopeMaintenancePaths({
+      command: options.command,
+      fromProjectPath,
+      toProjectPath,
+    }),
     mode: options.apply ? "apply" : "dry-run",
     apply: options.apply === true,
-    fromProjectPath,
-    toProjectPath,
-    sourceDb: projectDbPath(fromProjectPath),
-    destinationDb: projectDbPath(toProjectPath),
   };
 }
 
-function validateMigrationPaths(input: {
-  command: ScopeMigrationCommand;
-  fromProjectPath: string;
-  toProjectPath: string;
-  sourceDb: string;
-  destinationDb: string;
-}): void {
-  if (input.command === "migrate-project" && input.fromProjectPath === input.toProjectPath) {
-    throw new Error("--from-project-path and --to-project-path must be different.");
-  }
-  if (canonicalPath(input.sourceDb) === canonicalPath(input.destinationDb)) {
-    throw new Error("Source and destination database paths are the same.");
-  }
-  if (!existsSync(join(input.toProjectPath, CODETRAP_DIR))) {
-    throw new Error(`Destination project is not initialized: ${input.toProjectPath}. Run 'codetrap init' first.`);
-  }
-}
-
 function applyScopeMigration(
   sourceDbPath: string,
   destinationDbPath: string,
@@ -307,29 +293,6 @@ function toCandidate(record: TrapExportRecord): ScopeMigrationCandidate {
   };
 }
 
-function withReadOnlyRepository<T>(dbPath: string, callback: (repository: TrapRepository) => T): T {
-  const db = new Database(dbPath, { readonly: true });
-  try {
-    return callback(new TrapRepository(db));
-  } finally {
-    db.close();
-  }
-}
-
-function backupDatabase(dbPath: string, label: string): string {
-  const backupDir = join(dirname(dbPath), "backups");
-  mkdirSync(backupDir, { recursive: true });
-  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const backupPath = join(backupDir, `${basename(dbPath)}.${label}.${timestamp}.backup`);
-  const db = new Database(dbPath, { readonly: true });
-  try {
-    writeFileSync(backupPath, db.serialize());
-  } finally {
-    db.close();
-  }
-  return backupPath;
-}
-
 function buildApplyCommand(
   command: ScopeMigrationCommand,
   fromProjectPath: string,
@@ -347,14 +310,6 @@ function buildApplyCommand(
   ].join(" ");
 }
 
-function projectDbPath(projectPath: string): string {
-  return join(projectPath, CODETRAP_DIR, TRAPS_DB_FILE);
-}
-
-function canonicalPath(path: string): string {
-  return existsSync(path) ? realpathSync(path) : path;
-}
-
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }

package/src/lib/scope-path.ts

@@ -0,0 +1,99 @@
+import { existsSync, realpathSync } from "node:fs";
+import { posix, win32 } from "node:path";
+
+export type ScopePathFlavor = "posix" | "win32";
+
+export type ScopePathFs = {
+  exists(path: string): boolean;
+  realpath(path: string): string;
+};
+
+export type ScopePathResolverOptions = {
+  fs?: ScopePathFs;
+  platform?: NodeJS.Platform;
+};
+
+const nodeFs: ScopePathFs = {
+  exists: existsSync,
+  realpath: realpathSync,
+};
+
+export class ScopePathResolver {
+  private readonly fs: ScopePathFs;
+  private readonly platform: NodeJS.Platform;
+
+  constructor(options: ScopePathResolverOptions = {}) {
+    this.fs = options.fs ?? nodeFs;
+    this.platform = options.platform ?? process.platform;
+  }
+
+  resolve(path: string, relatedPath = path): string {
+    return this.resolveWithFlavor(path, this.flavorFor(path, relatedPath));
+  }
+
+  canonical(path: string, relatedPath = path): string {
+    const flavor = this.flavorFor(path, relatedPath);
+    const resolved = this.resolveWithFlavor(path, flavor);
+    const real = this.fs.exists(resolved) ? this.fs.realpath(resolved) : resolved;
+    const normalized = pathApi(flavor).normalize(real);
+    return flavor === "win32" ? normalized.toLowerCase() : normalized;
+  }
+
+  same(left: string, right: string): boolean {
+    const flavor = this.flavorFor(left, right);
+    return this.canonicalWithFlavor(left, flavor) === this.canonicalWithFlavor(right, flavor);
+  }
+
+  join(base: string, ...segments: string[]): string {
+    return pathApi(this.flavorFor(base)).join(base, ...segments);
+  }
+
+  exists(path: string): boolean {
+    return this.fs.exists(path);
+  }
+
+  dirname(path: string): string {
+    return pathApi(this.flavorFor(path)).dirname(path);
+  }
+
+  flavorFor(...paths: string[]): ScopePathFlavor {
+    if (this.platform === "win32") return "win32";
+    return paths.some((path) => isWindowsAbsolutePath(path) || isMsysAbsolutePath(path)) ? "win32" : "posix";
+  }
+
+  private canonicalWithFlavor(path: string, flavor: ScopePathFlavor): string {
+    const resolved = this.resolveWithFlavor(path, flavor);
+    const real = this.fs.exists(resolved) ? this.fs.realpath(resolved) : resolved;
+    const normalized = pathApi(flavor).normalize(real);
+    return flavor === "win32" ? normalized.toLowerCase() : normalized;
+  }
+
+  private resolveWithFlavor(path: string, flavor: ScopePathFlavor): string {
+    return pathApi(flavor).resolve(flavor === "win32" ? msysToWindowsPath(path) : path);
+  }
+}
+
+export const defaultScopePathResolver = new ScopePathResolver();
+
+export function resolveScopePath(path: string, relatedPath = path): string {
+  return defaultScopePathResolver.resolve(path, relatedPath);
+}
+
+function pathApi(flavor: ScopePathFlavor): typeof posix {
+  return flavor === "win32" ? win32 : posix;
+}
+
+function msysToWindowsPath(path: string): string {
+  const match = path.match(/^\/([a-zA-Z])(?:\/(.*))?$/);
+  if (!match) return path;
+  const [, drive, rest = ""] = match;
+  return `${drive.toUpperCase()}:\\${rest.replaceAll("/", "\\")}`;
+}
+
+function isWindowsAbsolutePath(path: string): boolean {
+  return /^[a-zA-Z]:[\\/]/.test(path) || /^\\\\/.test(path);
+}
+
+function isMsysAbsolutePath(path: string): boolean {
+  return /^\/[a-zA-Z](?:\/|$)/.test(path);
+}

package/src/lib/scope.ts

@@ -1,32 +1,37 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
+import { defaultScopePathResolver, resolveScopePath, ScopePathResolver } from "./scope-path";
+
+export { resolveScopePath, ScopePathResolver } from "./scope-path";
 
 export function getGlobalDir(): string {
-  const dir = join(homedir(), CODETRAP_DIR);
+  const dir = defaultScopePathResolver.join(homedir(), CODETRAP_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   return dir;
 }
 
 export function getGlobalDB(): string {
-  return join(getGlobalDir(), TRAPS_DB_FILE);
+  return defaultScopePathResolver.join(getGlobalDir(), TRAPS_DB_FILE);
 }
 
-export function findProjectRoot(cwd: string, homeDir = homedir()): string | null {
-  let dir = resolve(cwd);
-  const home = resolve(homeDir);
+export function findProjectRoot(
+  cwd: string,
+  homeDir = homedir(),
+  resolver: ScopePathResolver = defaultScopePathResolver
+): string | null {
+  let dir = resolver.resolve(cwd, homeDir);
   while (true) {
-    if (dir === home) return null;
-    if (existsSync(join(dir, CODETRAP_DIR))) return dir;
-    const parent = dirname(dir);
+    if (resolver.same(dir, homeDir)) return null;
+    if (resolver.exists(resolver.join(dir, CODETRAP_DIR))) return dir;
+    const parent = resolver.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 
 export function getProjectDB(root: string): string {
-  const dir = join(root, CODETRAP_DIR);
+  const dir = defaultScopePathResolver.join(root, CODETRAP_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  return join(dir, TRAPS_DB_FILE);
+  return defaultScopePathResolver.join(dir, TRAPS_DB_FILE);
 }

package/src/lib/search-policy.ts

@@ -1,4 +1,5 @@
 import type { RankingSignal, Trap, TrapSearchResult } from "../domain/trap";
+import type { TrapStatus } from "./constants";
 import { EmbeddingProviderUnavailableError } from "./embedder";
 import { parseTrapPathGlobs, parseTrapTags } from "./trap-json-fields";
 import {
@@ -8,11 +9,39 @@ import {
 } from "./trap-scope-match";
 
 export interface SearchPolicyOptions extends ApplicabilityFilter {
+  category?: string;
+  scope?: string;
+  status?: TrapStatus | "all";
   limit?: number;
   rerank?: boolean;
   includeRankingSignals?: boolean;
 }
 
+export type SearchStorageFilter = {
+  category?: string;
+  scope?: string;
+  status?: TrapStatus | "all";
+  module?: string;
+  owner?: string;
+  limit?: number;
+};
+
+export type SemanticStorageFilter = {
+  category?: string;
+  scope?: string;
+  status?: TrapStatus | "all";
+};
+
+export type SearchRetrievalSource = "fts" | "semantic";
+
+export interface SearchRetrievalPlan {
+  resultLimit: number;
+  candidateLimit: number;
+  ftsStorageFilter: SearchStorageFilter & { limit: number };
+  semanticStorageFilter: SemanticStorageFilter;
+  applicabilityFilter: ApplicabilityFilter;
+}
+
 export interface RankingConfig {
   rrfK: number;
   semanticMinScore: number;
@@ -48,6 +77,33 @@ export const DEFAULT_RANKING_CONFIG: RankingConfig = {
 export class TrapSearchPolicy {
   constructor(private readonly ranking: RankingConfig = DEFAULT_RANKING_CONFIG) {}
 
+  plan(opts: SearchPolicyOptions, defaultLimit: number): SearchRetrievalPlan {
+    const resultLimit = opts.limit ?? defaultLimit;
+    const candidateLimit = this.candidateLimit(opts, resultLimit);
+    return {
+      resultLimit,
+      candidateLimit,
+      ftsStorageFilter: {
+        category: opts.category,
+        scope: opts.scope,
+        status: opts.status,
+        module: opts.module,
+        owner: opts.owner,
+        limit: candidateLimit,
+      },
+      semanticStorageFilter: {
+        category: opts.category,
+        scope: opts.scope,
+        status: opts.status,
+      },
+      applicabilityFilter: {
+        path: opts.path,
+        module: opts.module,
+        owner: opts.owner,
+      },
+    };
+  }
+
   candidateLimit(opts: SearchPolicyOptions, resultLimit: number): number {
     return shouldOverfetch(opts) ? Math.max(resultLimit * 5, 50) : resultLimit;
   }
@@ -68,6 +124,30 @@ export class TrapSearchPolicy {
     return traps.filter((trap) => this.matchesTrap(trap, filter));
   }
 
+  prepareRetrievedResults(
+    results: TrapSearchResult[],
+    source: SearchRetrievalSource,
+    plan: SearchRetrievalPlan
+  ): TrapSearchResult[] {
+    const applicable = this.filterResults(results, plan.applicabilityFilter);
+    if (source === "semantic") {
+      return applicable
+        .filter((result) => (result.score ?? 0) >= this.semanticMinScore())
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+        .slice(0, plan.candidateLimit);
+    }
+    return applicable.slice(0, plan.candidateLimit);
+  }
+
+  finalizeResults(
+    results: TrapSearchResult[],
+    query: string,
+    opts: SearchPolicyOptions,
+    plan: SearchRetrievalPlan
+  ): TrapSearchResult[] {
+    return this.rankResults(results, query, opts, plan.resultLimit);
+  }
+
   rankResults(
     results: TrapSearchResult[],
     query: string,
@@ -95,12 +175,21 @@ export class TrapSearchPolicy {
         score: applyLengthNormalization(result.score, result.trap, this.ranking),
         rank: applyLengthNormalization(result.score, result.trap, this.ranking),
       }))
-      .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
-      .slice(0, limit);
+      .sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
 
     return this.rankResults(fused, query, opts, limit);
   }
 
+  fuseAndFinalize(
+    ftsResults: TrapSearchResult[],
+    semanticResults: TrapSearchResult[],
+    query: string,
+    opts: SearchPolicyOptions,
+    plan: SearchRetrievalPlan
+  ): TrapSearchResult[] {
+    return this.fuse(ftsResults, semanticResults, query, opts, plan.resultLimit);
+  }
+
   withDiagnostics(
     results: TrapSearchResult[],
     diagnostic: { code: string; message: string }