codetrap 0.1.6 → 0.1.8

package/src/lib/command-requests.ts

@@ -1,5 +1,12 @@
 import { SEARCH_MODES, type SearchMode } from "./constants";
-import type { SearchDefaults } from "./config";
+import type { EmbeddingProviderSetting, EmbeddingSettings, SearchDefaults } from "./config";
+import {
+  DEFAULT_OLLAMA_DIMENSIONS,
+  DEFAULT_OLLAMA_ENDPOINT,
+  DEFAULT_OLLAMA_MODEL,
+} from "./embedder";
+import { capturedTrapMarkdownInput } from "./session-capture";
+import { uniqueStrings as uniqueStringList } from "./string-list";
 import type { SearchTrapsArgs, ListTrapsArgs } from "./trap-operations";
 
 type RawArgs = Record<string, unknown>;
@@ -12,6 +19,10 @@ export type EmbedRequest = {
   batchSize?: number;
 };
 
+export type EmbeddingsUseRequest = {
+  embeddings: EmbeddingSettings;
+};
+
 export type StatsRequest = {
   scope?: string;
 };
@@ -40,6 +51,15 @@ export type SessionCloseRequest = {
   proposeTraps: boolean;
 };
 
+export type SessionCaptureRequest = {
+  trap: Record<string, unknown>;
+  goal?: string;
+  kind?: string;
+  relatedFiles?: string[];
+  sourceRef?: string;
+  evidenceNote?: string;
+};
+
 export type SessionIdRequest = {
   sessionId?: string;
 };
@@ -63,11 +83,22 @@ export type SessionRejectRequest = SessionCandidateRequest & {
   reason?: string;
 };
 
+export type SessionPruneRequest = {
+  olderThanDays: number;
+  apply: boolean;
+};
+
 export type SessionNoteStdin = {
   isTTY: boolean;
   read: () => string;
 };
 
+export type SessionCaptureInput = {
+  isTTY: boolean;
+  readStdin: () => string;
+  readFile: (path: string) => string;
+};
+
 export function searchRequestFromArgs(query: string, args: RawArgs, defaults: SearchDefaults): SearchTrapsArgs {
   return {
     query,
@@ -112,6 +143,27 @@ export function embedRequestFromArgs(args: RawArgs): EmbedRequest {
   };
 }
 
+export function embeddingsUseRequestFromArgs(
+  positionals: string[],
+  args: RawArgs
+): EmbeddingsUseRequest {
+  const provider = embeddingProviderOption(requiredPositional(positionals, 0, "provider"));
+  if (provider === "jina") {
+    return {
+      embeddings: { provider },
+    };
+  }
+
+  return {
+    embeddings: {
+      provider,
+      endpoint: stringOption(args, "endpoint") ?? DEFAULT_OLLAMA_ENDPOINT,
+      model: stringOption(args, "model") ?? DEFAULT_OLLAMA_MODEL,
+      dimensions: optionalIntOption(args, "dimensions") ?? DEFAULT_OLLAMA_DIMENSIONS,
+    },
+  };
+}
+
 export function evidenceRequestFromArgs(args: RawArgs): RawArgs {
   return {
     source_type: stringOption(args, "source_type", "source-type"),
@@ -170,6 +222,35 @@ export function sessionCloseRequestFromArgs(positionals: string[], args: RawArgs
   };
 }
 
+export function sessionCaptureRequestFromArgs(args: RawArgs, input?: SessionCaptureInput): SessionCaptureRequest {
+  const sources = [
+    args["trap-json"] !== undefined,
+    args["trap-markdown"] !== undefined,
+    args["trap-markdown-file"] !== undefined,
+  ].filter(Boolean).length;
+  if (sources === 0) throw new Error("--trap-json, --trap-markdown, or --trap-markdown-file is required.");
+  if (sources > 1) throw new Error("Choose only one of --trap-json, --trap-markdown, or --trap-markdown-file.");
+
+  const markdown = markdownCaptureInput(args, input);
+  const parsedMarkdown = markdown === undefined ? null : capturedTrapMarkdownInput(markdown);
+  const trap: Record<string, unknown> | undefined = parsedMarkdown
+    ? { ...parsedMarkdown.trap }
+    : jsonObjectOption(args, "trap-json");
+  if (!trap) throw new Error("--trap-json, --trap-markdown, or --trap-markdown-file is required.");
+
+  return {
+    trap,
+    goal: stringOption(args, "goal"),
+    kind: stringOption(args, "kind"),
+    relatedFiles: uniqueStrings([
+      ...(csvOrArrayOption(args, "related_files", "related-files") ?? []),
+      ...(parsedMarkdown?.relatedFiles ?? []),
+    ]),
+    sourceRef: stringOption(args, "source_ref", "source-ref"),
+    evidenceNote: parsedMarkdown?.evidenceNote,
+  };
+}
+
 export function sessionIdRequestFromArgs(positionals: string[]): SessionIdRequest {
   return {
     sessionId: positionals[0],
@@ -205,6 +286,15 @@ export function sessionRejectRequestFromArgs(positionals: string[], args: RawArg
   };
 }
 
+export function sessionPruneRequestFromArgs(args: RawArgs): SessionPruneRequest {
+  const olderThan = stringOption(args, "older_than", "older-than");
+  if (!olderThan) throw new Error("--older-than is required.");
+  return {
+    olderThanDays: parseDurationDays(olderThan),
+    apply: flagPresent(args, "apply"),
+  };
+}
+
 function stringOption(args: RawArgs, ...keys: string[]): string | undefined {
   for (const key of keys) {
     const value = args[key];
@@ -235,6 +325,11 @@ function searchModeOption(args: RawArgs, key: string): SearchMode | undefined {
   throw new Error(`Invalid search mode: ${value}. Expected one of: ${SEARCH_MODES.join(", ")}`);
 }
 
+function embeddingProviderOption(value: string): EmbeddingProviderSetting {
+  if (value === "ollama" || value === "jina") return value;
+  throw new Error(`Invalid embedding provider: ${value}. Expected ollama or jina.`);
+}
+
 function booleanOption(args: RawArgs, ...keys: string[]): boolean | undefined {
   for (const key of keys) {
     const value = args[key];
@@ -282,6 +377,44 @@ function jsonObjectOption(args: RawArgs, key: string): Record<string, unknown> |
   }
 }
 
+function markdownCaptureInput(args: RawArgs, input: SessionCaptureInput | undefined): string | undefined {
+  const inline = stringOption(args, "trap-markdown");
+  const file = stringOption(args, "trap-markdown-file");
+  if (inline === undefined && file === undefined) return undefined;
+
+  const text = file !== undefined
+    ? readMarkdownFile(file, input)
+    : inline === "-"
+      ? readMarkdownStdin(input)
+      : inline ?? "";
+  if (text.trim() === "") throw new Error("Markdown trap input is required.");
+  return text;
+}
+
+function readMarkdownStdin(input: SessionCaptureInput | undefined): string {
+  if (!input) throw new Error("--trap-markdown - requires stdin support.");
+  if (input.isTTY) throw new Error("--trap-markdown - requires piped input.");
+  return input.readStdin();
+}
+
+function readMarkdownFile(path: string, input: SessionCaptureInput | undefined): string {
+  if (!input) throw new Error("--trap-markdown-file requires file read support.");
+  return input.readFile(path);
+}
+
+function uniqueStrings(values: string[]): string[] | undefined {
+  const unique = uniqueStringList(values);
+  return unique.length > 0 ? unique : undefined;
+}
+
+function parseDurationDays(value: string): number {
+  const match = value.trim().match(/^(\d+)\s*(d|day|days)?$/i);
+  if (!match) throw new Error(`Invalid duration: ${value}. Use a value like 90d.`);
+  const days = Number.parseInt(match[1], 10);
+  if (!Number.isInteger(days) || days <= 0) throw new Error(`Invalid duration: ${value}. Use a positive day count.`);
+  return days;
+}
+
 function requiredPositional(positionals: string[], index: number, name: string): string {
   const value = positionals[index];
   if (!value) throw new Error(`${name} is required.`);

package/src/lib/config.ts

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CODETRAP_DIR, SCOPES, SEARCH_MODES, type Scope, type SearchMode } from "./constants";
+import { isRecord } from "./value-types";
 
 export type CodetrapConfig = {
   search?: {
@@ -10,6 +11,16 @@ export type CodetrapConfig = {
     scope?: Scope;
     rerank?: boolean;
   };
+  embeddings?: EmbeddingSettings;
+};
+
+export type EmbeddingProviderSetting = "ollama" | "jina";
+
+export type EmbeddingSettings = {
+  provider?: EmbeddingProviderSetting;
+  endpoint?: string;
+  model?: string;
+  dimensions?: number;
 };
 
 export type SearchDefaults = {
@@ -19,6 +30,11 @@ export type SearchDefaults = {
   rerank: boolean;
 };
 
+export type ConfigWriteResult = {
+  path: string;
+  config: CodetrapConfig;
+};
+
 const BUILT_IN_SEARCH_DEFAULTS: SearchDefaults = {
   mode: "hybrid",
   limit: 20,
@@ -26,7 +42,7 @@ const BUILT_IN_SEARCH_DEFAULTS: SearchDefaults = {
 };
 
 export function loadCodetrapConfig(home = homedir()): CodetrapConfig {
-  const path = join(home, CODETRAP_DIR, "config.json");
+  const path = codetrapConfigPath(home);
   if (!existsSync(path)) return {};
 
   try {
@@ -38,6 +54,26 @@ export function loadCodetrapConfig(home = homedir()): CodetrapConfig {
   }
 }
 
+export function codetrapConfigPath(home = homedir()): string {
+  return join(home, CODETRAP_DIR, "config.json");
+}
+
+export function writeCodetrapConfig(config: CodetrapConfig, home = homedir()): ConfigWriteResult {
+  const path = codetrapConfigPath(home);
+  mkdirSync(join(home, CODETRAP_DIR), { recursive: true });
+  const normalized = normalizeConfig(config);
+  writeFileSync(path, `${JSON.stringify(normalized, null, 2)}\n`);
+  return { path, config: normalized };
+}
+
+export function setCodetrapEmbeddingSettings(
+  embeddings: EmbeddingSettings,
+  home = homedir()
+): ConfigWriteResult {
+  const current = loadCodetrapConfig(home);
+  return writeCodetrapConfig({ ...current, embeddings }, home);
+}
+
 export function searchDefaultsFromConfig(config = loadCodetrapConfig(), env = process.env): SearchDefaults {
   return {
     mode: config.search?.mode ?? parseSearchModeEnv(env.CODETRAP_SEARCH_MODE) ?? BUILT_IN_SEARCH_DEFAULTS.mode,
@@ -50,7 +86,11 @@ export function searchDefaultsFromConfig(config = loadCodetrapConfig(), env = pr
 function normalizeConfig(value: unknown): CodetrapConfig {
   if (!isRecord(value)) return {};
   const search = isRecord(value.search) ? normalizeSearchConfig(value.search) : undefined;
-  return search ? { search } : {};
+  const embeddings = isRecord(value.embeddings) ? normalizeEmbeddingSettings(value.embeddings) : undefined;
+  return {
+    ...(search ? { search } : {}),
+    ...(embeddings ? { embeddings } : {}),
+  };
 }
 
 function normalizeSearchConfig(value: Record<string, unknown>): CodetrapConfig["search"] {
@@ -62,6 +102,15 @@ function normalizeSearchConfig(value: Record<string, unknown>): CodetrapConfig["
   return out;
 }
 
+function normalizeEmbeddingSettings(value: Record<string, unknown>): EmbeddingSettings {
+  const out: EmbeddingSettings = {};
+  if (typeof value.provider === "string") out.provider = parseEmbeddingProvider(value.provider);
+  if (typeof value.endpoint === "string") out.endpoint = value.endpoint;
+  if (typeof value.model === "string") out.model = value.model;
+  if (typeof value.dimensions === "number") out.dimensions = parsePositiveInt(value.dimensions, "embeddings.dimensions");
+  return out;
+}
+
 function parseSearchModeEnv(value?: string): SearchMode | undefined {
   return value ? parseSearchMode(value) : undefined;
 }
@@ -92,11 +141,12 @@ function parseScope(value: string): Scope {
   throw new Error(`Invalid scope: ${value}. Expected one of: ${SCOPES.join(", ")}`);
 }
 
+function parseEmbeddingProvider(value: string): EmbeddingProviderSetting {
+  if (value === "ollama" || value === "jina") return value;
+  throw new Error("Invalid embeddings.provider: expected one of: ollama, jina");
+}
+
 function parsePositiveInt(value: number, label: string): number {
   if (Number.isInteger(value) && value > 0) return value;
   throw new Error(`Invalid ${label}: expected a positive integer.`);
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/lib/constants.ts

@@ -49,7 +49,7 @@ export const DEFAULT_TRAP_STATUS: TrapStatus = "active";
 
 // Increment this when schema changes in a breaking way.
 // Migrations are stored in src/db/migrations.ts
-export const SCHEMA_VERSION = 5;
+export const SCHEMA_VERSION = 6;
 
 // Directory and file names
 export const CODETRAP_DIR = ".codetrap";

package/src/lib/doctor.ts

@@ -1,8 +1,15 @@
 import type { TrapStore } from "./store";
 import type { TrapOperations } from "./trap-operations";
-import type { EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
+import type { EmbeddingRuntimeStatus } from "./embedding-runtime";
+import type { EmbeddingStateSummary, EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
 import { createScopeContext } from "./scope-context";
 import { hybridFallbackReason } from "./embedding-health";
+import type { ProjectCandidateReviewSummary } from "./session-review";
+
+export type DoctorNextAction = {
+  command: string;
+  reason: string;
+};
 
 export type DoctorReport = {
   cwd: string;
@@ -23,18 +30,23 @@ export type DoctorReport = {
       global_db_project_traps: ReturnType<TrapStore["diagnostics"]>["mis_scoped_traps"]["global_db_project_traps"];
     };
   };
+  candidate_review: ProjectCandidateReviewSummary | null;
+  next_actions: DoctorNextAction[];
   mcp_hint: string;
 };
 
-export function buildDoctorReport(
+export async function buildDoctorReport(
   store: TrapStore,
   operations: TrapOperations,
-  cwd = process.cwd()
-): DoctorReport {
+  cwd = process.cwd(),
+  candidateReview: ProjectCandidateReviewSummary | null = null
+): Promise<DoctorReport> {
   const scope = createScopeContext(cwd);
   const stats = operations.getStats();
   const embeddings = operations.getEmbeddingStats();
-  const semanticAvailable = store.hasEmbeddingProvider();
+  const embeddingRuntime = await store.embeddingRuntimeHealth();
+  const semanticAvailable = embeddingRuntime.available;
+  const diagnostics = store.diagnostics();
 
   return {
     ...scope,
@@ -48,8 +60,10 @@ export function buildDoctorReport(
       fallback_reason: hybridFallbackReason(semanticAvailable, embeddings),
     },
     diagnostics: {
-      mis_scoped_traps: store.diagnostics().mis_scoped_traps,
+      mis_scoped_traps: diagnostics.mis_scoped_traps,
     },
+    candidate_review: candidateReview,
+    next_actions: buildDoctorNextActions(embeddingRuntime, embeddings, diagnostics, candidateReview),
     mcp_hint: "Pass cwd in MCP tool calls, or restart codetrap serve after changing projects.",
   };
 }
@@ -70,10 +84,86 @@ export function formatDoctorText(report: DoctorReport): string {
     `  fallback_reason: ${report.hybrid_search.fallback_reason ?? "(none)"}`,
     "Diagnostics:",
     `  global_db_project_traps: ${report.diagnostics.mis_scoped_traps.global_db_project_traps.length}`,
+    "Candidate review:",
+    formatCandidateReview(report.candidate_review),
+    "Next actions:",
+    ...formatNextActions(report.next_actions),
     `mcp_hint: ${report.mcp_hint}`,
   ].join("\n");
 }
 
+function buildDoctorNextActions(
+  embeddingRuntime: EmbeddingRuntimeStatus,
+  embeddings: EmbeddingStatsResult,
+  diagnostics: ReturnType<TrapStore["diagnostics"]>,
+  candidateReview: ProjectCandidateReviewSummary | null
+): DoctorNextAction[] {
+  const actions: DoctorNextAction[] = [];
+  if (!embeddingRuntime.available) {
+    if (embeddingRuntime.setup_action) actions.push(embeddingRuntime.setup_action);
+  } else {
+    const projectAction = embeddingRefreshAction("project", embeddings.project);
+    const globalAction = embeddingRefreshAction("global", embeddings.global);
+    if (projectAction) actions.push(projectAction);
+    if (globalAction) actions.push(globalAction);
+  }
+
+  const stranded = diagnostics.mis_scoped_traps.global_db_project_traps.length;
+  if (stranded > 0) {
+    actions.push({
+      command: "codetrap repair-scope --dry-run --json",
+      reason: `${stranded} project-scoped trap(s) are stored in the global database.`,
+    });
+  }
+  if (candidateReview && candidateReview.pending_count > 0) {
+    if (candidateReview.next_session_id) {
+      actions.push({
+        command: `codetrap session candidates ${candidateReview.next_session_id} --json`,
+        reason: `${candidateReview.pending_count} pending candidate trap(s) need review.`,
+      });
+    }
+    actions.push({
+      command: "codetrap web",
+      reason: "Open the candidate review console.",
+    });
+  }
+  return actions;
+}
+
+function embeddingRefreshAction(
+  scope: "project" | "global",
+  stats: EmbeddingStateSummary | null
+): DoctorNextAction | null {
+  if (!stats || stats.total === 0) return null;
+  const needsRefresh = stats.missing + stats.stale;
+  if (needsRefresh === 0) return null;
+  const parts = [
+    stats.missing > 0 ? `${stats.missing} missing` : null,
+    stats.stale > 0 ? `${stats.stale} stale` : null,
+  ].filter((item): item is string => item !== null);
+  return {
+    command: `codetrap embed --scope ${scope}`,
+    reason: `${scope} embeddings need refresh (${parts.join(", ")}).`,
+  };
+}
+
+function formatNextActions(actions: DoctorNextAction[]): string[] {
+  if (actions.length === 0) return ["  (none)"];
+  return actions.map((action) => `  - ${action.command} # ${action.reason}`);
+}
+
+function formatCandidateReview(summary: ProjectCandidateReviewSummary | null): string {
+  if (!summary) return "  unavailable";
+  return [
+    `  pending=${summary.pending_count}`,
+    `reviewed=${summary.reviewed_count}`,
+    `sessions=${summary.pending_session_count}/${summary.session_count}`,
+    `high_quality_pending=${summary.high_quality_pending_count}`,
+    `needs_edit=${summary.needs_edit_count}`,
+    `next_session=${summary.next_session_id ?? "(none)"}`,
+  ].join(", ");
+}
+
 function formatEmbeddingStats(
   label: string,
   stats: EmbeddingStatsResult["global"] | null

package/src/lib/embed-output.ts

@@ -0,0 +1,26 @@
+export type EmbedCommandResult = {
+  generated: number;
+  skipped: number;
+  batches: number;
+  scopes: { scope: string; generated: number; skipped: number; batches: number }[];
+};
+
+export function formatEmbedText(result: EmbedCommandResult): string {
+  return [
+    ...result.scopes.map((scoped) =>
+      `[${scoped.scope}] embeddings generated: ${scoped.generated}, skipped: ${scoped.skipped}, batches: ${scoped.batches}`
+    ),
+    `Total generated: ${result.generated}, skipped: ${result.skipped}, batches: ${result.batches}`,
+    `Next: ${embedNextAction(result)}`,
+  ].join("\n");
+}
+
+function embedNextAction(result: EmbedCommandResult): string {
+  if (result.generated > 0) {
+    return 'codetrap search "<query>" --mode hybrid';
+  }
+  if (result.skipped > 0) {
+    return "embeddings are already fresh; run codetrap doctor to verify hybrid search.";
+  }
+  return "add traps first, then rerun codetrap embed --scope project or --scope global.";
+}

package/src/lib/embedder.ts

@@ -19,6 +19,7 @@ export interface EmbeddingConfig {
 
 export interface StoredEmbedding {
   trap_id: number;
+  profile_id: string;
   provider: string;
   model: string;
   dimensions: number;
@@ -91,9 +92,119 @@ export class JinaEmbedder implements EmbeddingProvider {
   }
 }
 
-export function createDefaultEmbeddingProvider(): EmbeddingProvider | undefined {
-  const apiKey = process.env.JINA_API_KEY;
-  return apiKey ? new JinaEmbedder(apiKey) : undefined;
+export type OllamaEmbedderOptions = {
+  endpoint?: string;
+  model?: string;
+  dimensions?: number;
+  fetch?: FetchLike;
+};
+
+export type OllamaProviderHealth = {
+  ok: boolean;
+  message?: string;
+  command?: string;
+};
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export const DEFAULT_OLLAMA_ENDPOINT = "http://127.0.0.1:11434";
+export const DEFAULT_OLLAMA_MODEL = "qwen3-embedding:0.6b";
+export const DEFAULT_OLLAMA_DIMENSIONS = 1024;
+
+export class OllamaEmbedder implements EmbeddingProvider {
+  readonly provider = "ollama";
+  readonly model: string;
+  readonly dimensions: number;
+  private readonly endpoint: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(options: OllamaEmbedderOptions = {}) {
+    this.endpoint = normalizeOllamaEndpoint(options.endpoint ?? DEFAULT_OLLAMA_ENDPOINT);
+    this.model = options.model ?? DEFAULT_OLLAMA_MODEL;
+    this.dimensions = options.dimensions ?? DEFAULT_OLLAMA_DIMENSIONS;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  async embed(texts: string[], _task: EmbeddingTask): Promise<Float32Array[]> {
+    if (texts.length === 0) return [];
+
+    const response = await this.fetchImpl(`${this.endpoint}/api/embed`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: texts,
+        dimensions: this.dimensions,
+        truncate: true,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Ollama embeddings request failed (${response.status}): ${body}`);
+    }
+
+    const payload = (await response.json()) as {
+      embeddings?: number[][];
+    };
+    const rows = payload.embeddings ?? [];
+    if (rows.length !== texts.length) {
+      throw new Error(`Ollama embeddings returned ${rows.length} vectors for ${texts.length} inputs.`);
+    }
+
+    return rows.map((embedding) => {
+      if (!Array.isArray(embedding)) {
+        throw new Error("Ollama embeddings response is missing an embedding vector.");
+      }
+      if (embedding.length !== this.dimensions) {
+        throw new Error(
+          `Ollama embeddings returned ${embedding.length} dimensions, expected ${this.dimensions}.`
+        );
+      }
+      return Float32Array.from(embedding);
+    });
+  }
+
+  async health(): Promise<OllamaProviderHealth> {
+    try {
+      const response = await this.fetchImpl(`${this.endpoint}/api/tags`);
+      if (!response.ok) {
+        return {
+          ok: false,
+          message: `Ollama is not reachable at ${this.endpoint} (${response.status}).`,
+          command: "ollama list",
+        };
+      }
+
+      const payload = (await response.json()) as {
+        models?: { name?: string; model?: string }[];
+      };
+      const models = payload.models ?? [];
+      const installed = models.some((model) => model.name === this.model || model.model === this.model);
+      if (!installed) {
+        return {
+          ok: false,
+          message: `Ollama model ${this.model} is not installed.`,
+          command: `ollama pull ${this.model}`,
+        };
+      }
+
+      return { ok: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        ok: false,
+        message: `Ollama is not reachable at ${this.endpoint}: ${message}`,
+        command: "ollama list",
+      };
+    }
+  }
+}
+
+function normalizeOllamaEndpoint(endpoint: string): string {
+  return endpoint.replace(/\/+$/, "");
 }
 
 export function embeddingConfig(provider: EmbeddingProvider): EmbeddingConfig {
@@ -105,6 +216,10 @@ export function embeddingConfig(provider: EmbeddingProvider): EmbeddingConfig {
   };
 }
 
+export function embeddingProfileId(config: EmbeddingConfig): string {
+  return `${config.provider}:${config.model}:${config.dimensions}:p${config.passageVersion}`;
+}
+
 export function encodeEmbedding(embedding: Float32Array): Buffer {
   return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
 }

package/src/lib/embedding-health.ts

@@ -1,4 +1,4 @@
-import type { EmbeddingConfig } from "./embedder";
+import { embeddingProfileId, type EmbeddingConfig } from "./embedder";
 
 export type EmbeddingStateCounts = {
   total: number;
@@ -13,6 +13,7 @@ export type EmbeddingStateSummary = EmbeddingStateCounts & {
   model: string | null;
   dimensions: number | null;
   passage_version: number | null;
+  profile_id: string | null;
 };
 
 export type EmbeddingStatsResult = {
@@ -33,6 +34,7 @@ export function summarizeEmbeddingState(
     model: config?.model ?? null,
     dimensions: config?.dimensions ?? null,
     passage_version: config?.passageVersion ?? null,
+    profile_id: config ? embeddingProfileId(config) : null,
   };
 }
 

package/src/lib/embedding-job.ts

@@ -1,6 +1,7 @@
 import type { Trap } from "../domain/trap";
 import {
   embeddingConfig,
+  embeddingProfileId,
   type EmbeddingConfig,
   type EmbeddingProvider,
   type StoredEmbedding,
@@ -35,6 +36,7 @@ export async function runEmbeddingJob(
   opts: EmbeddingJobOptions = {}
 ): Promise<EmbeddingJobResult> {
   const config = embeddingConfig(provider);
+  const profileId = embeddingProfileId(config);
   const total = adapter.countEmbeddable({ scope: opts.scope, category: opts.category });
   const traps = adapter.trapsNeedingEmbeddings(config, opts);
   if (traps.length === 0) return { generated: 0, skipped: total, batches: 0 };
@@ -53,6 +55,7 @@ export async function runEmbeddingJob(
     for (let i = 0; i < batch.length; i++) {
       adapter.saveEmbedding({
         trap_id: batch[i].id,
+        profile_id: profileId,
         provider: config.provider,
         model: config.model,
         dimensions: config.dimensions,