codetrap 0.1.7 → 0.1.8

package/src/commands/workflow.ts

@@ -2,7 +2,6 @@ import { readFileSync } from "node:fs";
 import { TrapStore } from "../lib/store";
 import { formatTrapShort, formatTrapDetails, formatTrapActionCard } from "../lib/format";
 import type { Trap } from "../domain/trap";
-import type { SessionMetadata } from "../domain/session";
 import {
   formatScopeMigrationText,
   runScopeMigration,
@@ -11,6 +10,12 @@ import {
 import { TrapOperations } from "../lib/trap-operations";
 import { buildDoctorReport, formatDoctorText } from "../lib/doctor";
 import { formatEmbedText } from "../lib/embed-output";
+import {
+  formatEmbeddingProfilesText,
+  formatEmbeddingStatusText,
+  formatEmbeddingsUseText,
+  type EmbeddingsUseResult,
+} from "../lib/embedding-management";
 import { searchDefaultsFromConfig } from "../lib/config";
 import { SessionStore } from "../lib/session-store";
 import { SessionOperations, type SessionConflictResult } from "../lib/session-operations";
@@ -18,9 +23,17 @@ import {
   CANDIDATES_FILE,
   NOTES_FILE,
   RECAP_FILE,
-  sessionRelativeDir,
   sessionRelativeFile,
 } from "../lib/session-codec";
+import {
+  sessionAcceptPayload,
+  sessionCliConflictPayload,
+  sessionCleanupPayload,
+  sessionConflictPayload,
+  sessionConflictText,
+  sessionPayload,
+  sessionRejectPayload,
+} from "../lib/session-review";
 import {
   toCliSearchJson,
   toListJson,
@@ -36,10 +49,12 @@ import {
 import { mutationJsonPayload } from "../lib/trap-mutation-result";
 import {
   embedRequestFromArgs,
+  embeddingsUseRequestFromArgs,
   evidenceRequestFromArgs,
   listRequestFromArgs,
   searchRequestFromArgs,
   sessionAcceptRequestFromArgs,
+  sessionCaptureRequestFromArgs,
   sessionCandidateRequestFromArgs,
   sessionCloseRequestFromArgs,
   sessionIdRequestFromArgs,
@@ -101,12 +116,14 @@ export async function executeCommand(strip: string[], store: TrapStore): Promise
       return cmdScopeMigration("migrate-project", args, operations);
     case "embed":
       return cmdEmbed(args, store);
+    case "embeddings":
+      return cmdEmbeddings(args, store);
     case "session":
       return cmdSession(args, store, operations);
     default:
       return errorResult([
         `Unknown command: ${sub}`,
-        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed, session",
+        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed, embeddings, session",
       ].join("\n"));
   }
 }
@@ -341,9 +358,13 @@ function cmdStats(args: string[], operations: TrapOperations): CommandResult {
     : textResult(formatStatsText(stats));
 }
 
-function cmdDoctor(args: string[], store: TrapStore, operations: TrapOperations): CommandResult {
+async function cmdDoctor(args: string[], store: TrapStore, operations: TrapOperations): Promise<CommandResult> {
   const { opts } = parseArgs(args);
-  const report = buildDoctorReport(store, operations);
+  const projectRoot = store.getProjectRoot();
+  const candidateReview = projectRoot
+    ? new SessionOperations(new SessionStore(projectRoot), operations).candidateReviewSummary()
+    : null;
+  const report = await buildDoctorReport(store, operations, process.cwd(), candidateReview);
   return opts.json !== undefined
     ? jsonResult(report)
     : textResult(formatDoctorText(report));
@@ -388,6 +409,59 @@ async function cmdEmbed(args: string[], store: TrapStore): Promise<CommandResult
   }
 }
 
+async function cmdEmbeddings(args: string[], store: TrapStore): Promise<CommandResult> {
+  const sub = args[0] ?? "status";
+  const rest = args.length === 0 ? [] : args.slice(1);
+
+  try {
+    switch (sub) {
+      case "status": {
+        const { opts } = parseArgs(rest);
+        const status = await store.embeddingStatus({ scope: opts.scope });
+        return opts.json !== undefined
+          ? jsonResult(status)
+          : textResult(formatEmbeddingStatusText(status));
+      }
+      case "list":
+      case "profiles": {
+        const { opts } = parseArgs(rest);
+        const profiles = store.embeddingProfiles({ scope: opts.scope });
+        const payload = {
+          active_profile_id: store.embeddingRuntimeStatus().profile_id,
+          ...profiles,
+        };
+        return opts.json !== undefined
+          ? jsonResult(payload)
+          : textResult(formatEmbeddingProfilesText(profiles));
+      }
+      case "use": {
+        const { opts, positionals } = parseArgs(rest);
+        const request = embeddingsUseRequestFromArgs(positionals, opts);
+        const written = store.configureEmbeddings(request.embeddings);
+        const scope = store.hasProject() ? "project" : "global";
+        const result: EmbeddingsUseResult = {
+          ...written,
+          embeddings: written.config.embeddings ?? request.embeddings,
+          next_action: {
+            command: `codetrap embeddings reindex --scope ${scope}`,
+            reason: "Generate embeddings for the selected profile.",
+          },
+        };
+        return opts.json !== undefined
+          ? jsonResult(result)
+          : textResult(formatEmbeddingsUseText(result));
+      }
+      case "reindex":
+      case "embed":
+        return cmdEmbed(rest, store);
+      default:
+        return errorResult("Usage: codetrap embeddings <status|list|profiles|use|reindex> [--json]");
+    }
+  } catch (error) {
+    return errorFrom(error);
+  }
+}
+
 async function cmdSession(args: string[], store: TrapStore, trapOperations: TrapOperations): Promise<CommandResult> {
   const sub = args[0];
   const rest = args.slice(1);
@@ -413,6 +487,8 @@ async function cmdSession(args: string[], store: TrapStore, trapOperations: Trap
         return cmdSessionNotes(rest, sessions);
       case "close":
         return cmdSessionClose(rest, sessions);
+      case "capture":
+        return cmdSessionCapture(rest, sessions);
       case "candidates":
         return cmdSessionCandidates(rest, sessions);
       case "candidate":
@@ -428,7 +504,7 @@ async function cmdSession(args: string[], store: TrapStore, trapOperations: Trap
       case "cleanup":
         return cmdSessionCleanup(rest, sessions);
       default:
-        return errorResult("Usage: codetrap session <start|note|status|list|show|notes|close|candidates|candidate|accept|reject|delete|prune|cleanup>");
+        return errorResult("Usage: codetrap session <start|note|status|list|show|notes|close|capture|candidates|candidate|accept|reject|delete|prune|cleanup>");
     }
   } catch (error) {
     return errorFrom(error);
@@ -472,14 +548,31 @@ function cmdSessionStatus(args: string[], sessions: SessionOperations): CommandR
     return jsonResult({
       active_session_id: status.active_session_id,
       session: status.session ? sessionPayload(status.session) : null,
+      candidate_review: status.candidate_review,
     });
   }
-  if (!status.session) return textResult("No active session.");
-  return textResult([
+  if (!status.session) {
+    const lines = ["No active session."];
+    if (status.candidate_review.pending_count > 0) {
+      lines.push(
+        `Pending candidate review: ${status.candidate_review.pending_count} candidate(s) across ${status.candidate_review.pending_session_count} session(s).`
+      );
+      if (status.candidate_review.next_session_id) {
+        lines.push(`Review: codetrap session candidates ${status.candidate_review.next_session_id}`);
+      }
+      lines.push("Open web review: codetrap web");
+    }
+    return textResult(lines.join("\n"));
+  }
+  const lines = [
     `Active session ${status.session.id}`,
     `Goal: ${status.session.goal}`,
     `Notes: ${sessionRelativeFile(status.session.id, NOTES_FILE)}`,
-  ].join("\n"));
+  ];
+  if (status.candidate_review.pending_count > 0) {
+    lines.push(`Pending candidate review: ${status.candidate_review.pending_count} candidate(s).`);
+  }
+  return textResult(lines.join("\n"));
 }
 
 function cmdSessionList(args: string[], sessions: SessionOperations): CommandResult {
@@ -487,7 +580,9 @@ function cmdSessionList(args: string[], sessions: SessionOperations): CommandRes
   const entries = sessions.listSessions(sessionListRequestFromArgs(opts));
   if (opts.json !== undefined) return jsonResult(entries);
   if (entries.length === 0) return textResult("No sessions found.");
-  return textResult(entries.map((entry) => `${entry.id} [${entry.status}] ${entry.goal}`).join("\n"));
+  return textResult(entries.map((entry) =>
+    `${entry.id} [${entry.status}] ${entry.goal} (${entry.pending_count} pending, ${entry.reviewed_count} reviewed)`
+  ).join("\n"));
 }
 
 function cmdSessionShow(args: string[], sessions: SessionOperations): CommandResult {
@@ -525,7 +620,6 @@ function cmdSessionClose(args: string[], sessions: SessionOperations): CommandRe
     ...sessionPayload(result.session),
     recap_path: result.recap_path,
     candidate_count: result.candidate_count,
-    traps_written: result.traps_written,
   };
   if (opts.json !== undefined) return jsonResult(payload);
   const lines = [
@@ -539,6 +633,39 @@ function cmdSessionClose(args: string[], sessions: SessionOperations): CommandRe
   return textResult(lines.join("\n"));
 }
 
+function cmdSessionCapture(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const result = sessions.captureCandidate(sessionCaptureRequestFromArgs(opts, {
+    isTTY: process.stdin.isTTY === true,
+    readStdin: () => readFileSync(0, "utf-8"),
+    readFile: (path) => readFileSync(path, "utf-8"),
+  }));
+  const nextAction = `codetrap session candidate ${result.candidate.id} --session ${result.session.id} --json`;
+  const payload = {
+    success: true,
+    session_id: result.session.id,
+    candidate_id: result.candidate.id,
+    status: result.candidate.status,
+    quality_score: result.candidate.quality_score,
+    candidate_count: result.candidate_count,
+    created_session: result.created_session,
+    closed_session: result.closed_session,
+    duplicate: result.duplicate,
+    candidate_traps_path: sessionRelativeFile(result.session.id, CANDIDATES_FILE),
+    recap_path: result.recap_path,
+    next_action: {
+      command: nextAction,
+    },
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult([
+    `${result.duplicate ? "Reused" : "Captured"} candidate ${result.candidate.id} in session ${result.session.id}.`,
+    result.created_session ? "Created and closed a post-flight session." : "Session remains active.",
+    `Candidate inbox: ${payload.candidate_traps_path}`,
+    `Review: ${nextAction}`,
+  ].join("\n"));
+}
+
 function cmdSessionCandidates(args: string[], sessions: SessionOperations): CommandResult {
   const { opts, positionals } = parseArgs(args);
   const request = sessionIdRequestFromArgs(positionals);
@@ -562,16 +689,7 @@ async function cmdSessionAccept(args: string[], sessions: SessionOperations): Pr
   const { opts, positionals } = parseArgs(args);
   const accepted = await sessions.acceptCandidate(sessionAcceptRequestFromArgs(positionals, opts));
   if (!accepted.success) return possibleConflictResult(accepted, opts.json !== undefined);
-  const payload = {
-    success: true,
-    session_id: accepted.session.id,
-    candidate_id: accepted.candidate.id,
-    status: accepted.candidate.status,
-    trap_id: accepted.trap_id,
-    scope: accepted.scope,
-    evidence_id: accepted.evidence_id,
-    superseded_id: accepted.superseded_id,
-  };
+  const payload = sessionAcceptPayload(accepted);
   if (opts.json !== undefined) return jsonResult(payload);
   const lines = [`Accepted ${accepted.candidate.id}; wrote trap #${accepted.trap_id} to ${accepted.scope} scope.`];
   if (accepted.superseded_id !== null) lines.push(`Superseded trap #${accepted.superseded_id}.`);
@@ -581,13 +699,7 @@ async function cmdSessionAccept(args: string[], sessions: SessionOperations): Pr
 function cmdSessionReject(args: string[], sessions: SessionOperations): CommandResult {
   const { opts, positionals } = parseArgs(args);
   const rejected = sessions.rejectCandidate(sessionRejectRequestFromArgs(positionals, opts));
-  const payload = {
-    success: true,
-    session_id: rejected.session.id,
-    candidate_id: rejected.candidate.id,
-    status: rejected.candidate.status,
-    reason: rejected.candidate.rejection_reason ?? null,
-  };
+  const payload = sessionRejectPayload(rejected);
   if (opts.json !== undefined) return jsonResult(payload);
   return textResult(`Rejected ${rejected.candidate.id}.`);
 }
@@ -621,12 +733,7 @@ function cmdSessionCleanup(args: string[], sessions: SessionOperations): Command
   }
   const request = sessionIdRequestFromArgs(positionals);
   const result = sessions.cleanupDeletedTrapCandidates(request.sessionId);
-  const payload = {
-    success: true,
-    session_id: result.session.id,
-    removed_count: result.removed_count,
-    removed_candidate_ids: result.removed_candidate_ids,
-  };
+  const payload = sessionCleanupPayload(result);
   if (opts.json !== undefined) return jsonResult(payload);
   return textResult(`Removed ${result.removed_count} deleted-trap candidate(s) from session ${result.session.id}.`);
 }
@@ -679,42 +786,11 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function sessionPayload(session: SessionMetadata) {
-  return {
-    ...session,
-    session_dir: sessionRelativeDir(session.id),
-    notes_path: sessionRelativeFile(session.id, NOTES_FILE),
-    recap_path: sessionRelativeFile(session.id, RECAP_FILE),
-    candidate_traps_path: sessionRelativeFile(session.id, CANDIDATES_FILE),
-  };
-}
-
 function possibleConflictResult(
   result: SessionConflictResult,
   asJson: boolean
 ): CommandResult {
-  const payload = {
-    success: false,
-    error: "Possible active trap conflict found.",
-    session_id: result.session_id,
-    candidate_id: result.candidate_id,
-    possible_conflicts: result.possible_conflicts,
-    next_actions: [
-      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --accept-anyway`,
-      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --supersedes <trap-id>`,
-      `codetrap session reject ${result.candidate_id} --session ${result.session_id} --reason <reason>`,
-    ],
-  };
-  if (asJson) return jsonResult(payload, 1);
-
-  return errorResult([
-    "Possible active trap conflict found:",
-    ...result.possible_conflicts.map((conflict) => [
-      `#${conflict.trap_id} ${conflict.title}`,
-      `  reason: ${conflict.reason}`,
-      `  fix: ${conflict.fix}`,
-    ].join("\n")),
-    "",
-    `Use --accept-anyway to save as a new trap, or --supersedes <trap-id> to preserve lifecycle history.`,
-  ].join("\n"));
+  const payload = sessionConflictPayload(result);
+  if (asJson) return jsonResult(sessionCliConflictPayload(payload), 1);
+  return errorResult(sessionConflictText(payload));
 }

package/src/db/embedding-queries.ts

@@ -5,15 +5,17 @@ import {
   decodeEmbedding,
   encodeEmbedding,
   type EmbeddingConfig,
+  embeddingProfileId,
   type FreshEmbedding,
   type StoredEmbedding,
 } from "../lib/embedder";
 import type { EmbeddingStateCounts } from "../lib/embedding-health";
-import { embeddingIsFresh, passageHashForTrap } from "../lib/trap-search-document";
-import { countTraps, listTraps } from "./queries";
+import { passageHashForTrap } from "../lib/trap-search-document";
+import { countTraps } from "./queries";
 
 type TrapEmbeddingRow = {
   trap_id: number;
+  profile_id: string;
   provider: string;
   model: string;
   dimensions: number;
@@ -23,33 +25,98 @@ type TrapEmbeddingRow = {
   updated_at: string;
 };
 
-export function getEmbedding(db: Database, trapId: number): StoredEmbedding | null {
+export type EmbeddingProfileSummary = {
+  id: string;
+  provider: string;
+  model: string;
+  dimensions: number;
+  passage_version: number;
+  embedding_count: number;
+  updated_at: string | null;
+};
+
+type EmbeddingProfileRow = Omit<EmbeddingProfileSummary, "embedding_count"> & {
+  embedding_count: number;
+};
+
+type TrapEmbeddingStateRow = Trap & {
+  embedding_passage_hash: string | null;
+};
+
+type TrapAnyEmbeddingStateRow = Trap & {
+  has_embedding: number;
+};
+
+export function getEmbedding(
+  db: Database,
+  trapId: number,
+  config?: EmbeddingConfig
+): StoredEmbedding | null {
+  const profileClause = config ? "AND e.profile_id = ?" : "";
+  const params: SQLQueryBindings[] = [trapId];
+  if (config) params.push(embeddingProfileId(config));
+
   const row = db
-    .query("SELECT * FROM trap_embeddings WHERE trap_id = ?")
-    .get(trapId) as TrapEmbeddingRow | null;
+    .query(`
+      SELECT
+        e.trap_id,
+        e.profile_id,
+        p.provider,
+        p.model,
+        p.dimensions,
+        p.passage_version,
+        e.passage_hash,
+        e.embedding,
+        e.updated_at
+      FROM trap_embeddings e
+      JOIN embedding_profiles p ON p.id = e.profile_id
+      WHERE e.trap_id = ? ${profileClause}
+      ORDER BY e.updated_at DESC
+      LIMIT 1
+    `)
+    .get(...params) as TrapEmbeddingRow | null;
   return row ? rowToStoredEmbedding(row) : null;
 }
 
 export function upsertEmbedding(db: Database, record: StoredEmbedding): void {
+  const profileId = record.profile_id || embeddingProfileId({
+    provider: record.provider,
+    model: record.model,
+    dimensions: record.dimensions,
+    passageVersion: record.passage_version,
+  });
+
   db.prepare(`
-    INSERT INTO trap_embeddings (
-      trap_id, provider, model, dimensions, passage_version, passage_hash, embedding, updated_at
+    INSERT INTO embedding_profiles (
+      id, provider, model, dimensions, passage_version, created_at, updated_at
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
-    ON CONFLICT(trap_id) DO UPDATE SET
+    VALUES (?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+    ON CONFLICT(id) DO UPDATE SET
       provider = excluded.provider,
       model = excluded.model,
       dimensions = excluded.dimensions,
       passage_version = excluded.passage_version,
-      passage_hash = excluded.passage_hash,
-      embedding = excluded.embedding,
       updated_at = datetime('now')
   `).run(
-    record.trap_id,
+    profileId,
     record.provider,
     record.model,
     record.dimensions,
-    record.passage_version,
+    record.passage_version
+  );
+
+  db.prepare(`
+    INSERT INTO trap_embeddings (
+      trap_id, profile_id, passage_hash, embedding, updated_at
+    )
+    VALUES (?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(trap_id, profile_id) DO UPDATE SET
+      passage_hash = excluded.passage_hash,
+      embedding = excluded.embedding,
+      updated_at = datetime('now')
+  `).run(
+    record.trap_id,
+    profileId,
     record.passage_hash,
     encodeEmbedding(record.embedding)
   );
@@ -65,16 +132,10 @@ export function getAllFreshEmbeddings(
   opts: { category?: string; scope?: string; status?: TrapStatus | "all" } = {}
 ): FreshEmbedding[] {
   const conditions = [
-    "e.provider = ?",
-    "e.model = ?",
-    "e.dimensions = ?",
-    "e.passage_version = ?",
+    "e.profile_id = ?",
   ];
   const params: SQLQueryBindings[] = [
-    config.provider,
-    config.model,
-    config.dimensions,
-    config.passageVersion,
+    embeddingProfileId(config),
   ];
 
   if (opts.category) {
@@ -116,22 +177,11 @@ export function getTrapsNeedingEmbeddings(
   config: EmbeddingConfig,
   opts: { scope?: string; category?: string; status?: TrapStatus | "all"; force?: boolean; limit?: number } = {}
 ): Trap[] {
-  const traps = listTraps(db, {
-    scope: opts.scope,
-    category: opts.category,
-    status: opts.status,
-    limit: 100000,
-  });
-  const needed: Trap[] = [];
-
-  for (const trap of traps) {
-    const embedding = getEmbedding(db, trap.id);
-    if (opts.force || !embeddingIsFresh(trap, embedding, config)) {
-      needed.push(trap);
-    }
-  }
-
-  return needed.slice(0, opts.limit ?? needed.length);
+  const rows = trapEmbeddingStateRows(db, config, opts);
+  const needed = opts.force
+    ? rows
+    : rows.filter((row) => row.embedding_passage_hash !== passageHashForTrap(row));
+  return needed.map(rowToTrap).slice(0, opts.limit ?? needed.length);
 }
 
 export function countEmbeddableTraps(
@@ -146,24 +196,20 @@ export function getEmbeddingStateCounts(
   config: EmbeddingConfig | null,
   opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
 ): EmbeddingStateCounts {
-  const traps = listTraps(db, {
-    scope: opts.scope,
-    category: opts.category,
-    status: opts.status,
-    limit: 100000,
-  });
+  if (!config) return getAnyEmbeddingStateCounts(db, opts);
+
+  const rows = trapEmbeddingStateRows(db, config, opts);
   const counts: EmbeddingStateCounts = {
-    total: traps.length,
+    total: rows.length,
     fresh: 0,
     stale: 0,
     missing: 0,
   };
 
-  for (const trap of traps) {
-    const embedding = getEmbedding(db, trap.id);
-    if (!embedding) {
+  for (const row of rows) {
+    if (!row.embedding_passage_hash) {
       counts.missing++;
-    } else if (config && embeddingIsFresh(trap, embedding, config)) {
+    } else if (row.embedding_passage_hash === passageHashForTrap(row)) {
       counts.fresh++;
     } else {
       counts.stale++;
@@ -173,9 +219,56 @@ export function getEmbeddingStateCounts(
   return counts;
 }
 
+export function listEmbeddingProfiles(
+  db: Database,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): EmbeddingProfileSummary[] {
+  const conditions: string[] = [];
+  const params: SQLQueryBindings[] = [];
+
+  if (opts.category) {
+    conditions.push("t.category = ?");
+    params.push(opts.category);
+  }
+  if (opts.scope) {
+    conditions.push("t.scope = ?");
+    params.push(opts.scope);
+  }
+  if (opts.status !== "all") {
+    conditions.push("t.status = ?");
+    params.push(opts.status ?? DEFAULT_TRAP_STATUS);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const rows = db
+    .query(`
+      SELECT
+        p.id,
+        p.provider,
+        p.model,
+        p.dimensions,
+        p.passage_version,
+        COUNT(e.trap_id) AS embedding_count,
+        MAX(e.updated_at) AS updated_at
+      FROM embedding_profiles p
+      JOIN trap_embeddings e ON e.profile_id = p.id
+      JOIN traps t ON t.id = e.trap_id
+      ${where}
+      GROUP BY p.id, p.provider, p.model, p.dimensions, p.passage_version
+      ORDER BY updated_at DESC, p.provider ASC, p.model ASC
+    `)
+    .all(...params) as EmbeddingProfileRow[];
+
+  return rows.map((row) => ({
+    ...row,
+    embedding_count: Number(row.embedding_count),
+  }));
+}
+
 function rowToStoredEmbedding(row: TrapEmbeddingRow): StoredEmbedding {
   return {
     trap_id: row.trap_id,
+    profile_id: row.profile_id,
     provider: row.provider,
     model: row.model,
     dimensions: row.dimensions,
@@ -185,3 +278,92 @@ function rowToStoredEmbedding(row: TrapEmbeddingRow): StoredEmbedding {
     updated_at: row.updated_at,
   };
 }
+
+function getAnyEmbeddingStateCounts(
+  db: Database,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): EmbeddingStateCounts {
+  const rows = trapAnyEmbeddingStateRows(db, opts);
+  const stale = rows.filter((row) => row.has_embedding > 0).length;
+  return {
+    total: rows.length,
+    fresh: 0,
+    stale,
+    missing: rows.length - stale,
+  };
+}
+
+function trapEmbeddingStateRows(
+  db: Database,
+  config: EmbeddingConfig,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): TrapEmbeddingStateRow[] {
+  const conditions: string[] = [];
+  const filterParams = trapFilterParams(conditions, opts, "t");
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  return db
+    .query(`
+      SELECT
+        t.*,
+        e.passage_hash AS embedding_passage_hash
+      FROM traps t
+      LEFT JOIN trap_embeddings e
+        ON e.trap_id = t.id
+       AND e.profile_id = ?
+      ${where}
+      ORDER BY t.updated_at DESC
+      LIMIT 100000
+    `)
+    .all(embeddingProfileId(config), ...filterParams) as TrapEmbeddingStateRow[];
+}
+
+function trapAnyEmbeddingStateRows(
+  db: Database,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): TrapAnyEmbeddingStateRow[] {
+  const conditions: string[] = [];
+  const params = trapFilterParams(conditions, opts, "t");
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  return db
+    .query(`
+      SELECT
+        t.*,
+        EXISTS (
+          SELECT 1
+          FROM trap_embeddings e
+          WHERE e.trap_id = t.id
+        ) AS has_embedding
+      FROM traps t
+      ${where}
+      ORDER BY t.updated_at DESC
+      LIMIT 100000
+    `)
+    .all(...params) as TrapAnyEmbeddingStateRow[];
+}
+
+function trapFilterParams(
+  conditions: string[],
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" },
+  alias: string
+): SQLQueryBindings[] {
+  const params: SQLQueryBindings[] = [];
+  const prefix = `${alias}.`;
+  if (opts.category) {
+    conditions.push(`${prefix}category = ?`);
+    params.push(opts.category);
+  }
+  if (opts.scope) {
+    conditions.push(`${prefix}scope = ?`);
+    params.push(opts.scope);
+  }
+  if (opts.status !== "all") {
+    conditions.push(`${prefix}status = ?`);
+    params.push(opts.status ?? DEFAULT_TRAP_STATUS);
+  }
+  return params;
+}
+
+function rowToTrap(row: TrapEmbeddingStateRow): Trap {
+  const { embedding_passage_hash: _embeddingPassageHash, ...trap } = row;
+  return trap as Trap;
+}