pi-context-engine 0.1.4 → 0.3.0

package/src/memory/db.ts

@@ -1,6 +1,8 @@
 /**
- * Per-project memory.db — port of upstream `memory/db.py` (MIT), schema v3
+ * Per-project memory.db — port of upstream `memory/db.py` (MIT), schema v4
  * (minus `migrated_files`, which only served upstream's session-file import).
+ * Schema is enforced idempotently on every open (no version-step migrations),
+ * so databases from any earlier release converge to the current shape in place.
  * Synchronous better-sqlite3; vec tables degrade to FTS-only when the
  * sqlite-vec extension can't load.
  */
@@ -11,7 +13,7 @@ import { batchedParams, epochSeconds } from "../utils.js";
 import { redactPii } from "../indexer/secrets.js";
 import type { Embedder } from "../indexer/embedder.js";
 
-export const CURRENT_VERSION = 3;
+export const CURRENT_VERSION = 4;
 const VEC_DIM = 384; // bootstrap dim; rebuilt automatically on mismatch
 
 /** Canonical savings buckets — keep in sync with the savings renderer. */
@@ -27,7 +29,7 @@ export const BUCKETS = [
 export type Bucket = (typeof BUCKETS)[number];
 
 const SCHEMA_V1 = `
-CREATE TABLE sessions (
+CREATE TABLE IF NOT EXISTS sessions (
   id TEXT PRIMARY KEY,
   project TEXT NOT NULL,
   started_at_epoch INTEGER NOT NULL,
@@ -40,9 +42,9 @@ CREATE TABLE sessions (
   rollup_summary TEXT,
   rollup_summary_at_epoch INTEGER
 );
-CREATE INDEX idx_sessions_started ON sessions(started_at_epoch DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at_epoch DESC);
 
-CREATE TABLE prompts (
+CREATE TABLE IF NOT EXISTS prompts (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
   prompt_number INTEGER NOT NULL,
@@ -51,16 +53,16 @@ CREATE TABLE prompts (
   created_at TEXT NOT NULL,
   UNIQUE(session_id, prompt_number)
 );
-CREATE INDEX idx_prompts_session ON prompts(session_id, prompt_number);
+CREATE INDEX IF NOT EXISTS idx_prompts_session ON prompts(session_id, prompt_number);
 
-CREATE TABLE tool_event_payloads (
+CREATE TABLE IF NOT EXISTS tool_event_payloads (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   raw_input TEXT NOT NULL,
   raw_output TEXT,
   size_bytes INTEGER NOT NULL
 );
 
-CREATE TABLE tool_events (
+CREATE TABLE IF NOT EXISTS tool_events (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
   prompt_number INTEGER NOT NULL,
@@ -70,9 +72,9 @@ CREATE TABLE tool_events (
   created_at_epoch INTEGER NOT NULL,
   created_at TEXT NOT NULL
 );
-CREATE INDEX idx_events_session_turn ON tool_events(session_id, prompt_number);
+CREATE INDEX IF NOT EXISTS idx_events_session_turn ON tool_events(session_id, prompt_number);
 
-CREATE TABLE turn_summaries (
+CREATE TABLE IF NOT EXISTS turn_summaries (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
   prompt_number INTEGER NOT NULL,
@@ -82,7 +84,7 @@ CREATE TABLE turn_summaries (
   UNIQUE(session_id, prompt_number)
 );
 
-CREATE TABLE decisions (
+CREATE TABLE IF NOT EXISTS decisions (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
   decision TEXT NOT NULL,
@@ -91,10 +93,10 @@ CREATE TABLE decisions (
   created_at_epoch INTEGER NOT NULL,
   created_at TEXT NOT NULL
 );
-CREATE INDEX idx_decisions_created ON decisions(created_at_epoch DESC);
-CREATE INDEX idx_decisions_source ON decisions(source);
+CREATE INDEX IF NOT EXISTS idx_decisions_created ON decisions(created_at_epoch DESC);
+CREATE INDEX IF NOT EXISTS idx_decisions_source ON decisions(source);
 
-CREATE TABLE code_areas (
+CREATE TABLE IF NOT EXISTS code_areas (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
   file_path TEXT NOT NULL,
@@ -102,9 +104,9 @@ CREATE TABLE code_areas (
   source TEXT NOT NULL CHECK(source IN ('manual','migrated','auto')) DEFAULT 'manual',
   created_at_epoch INTEGER NOT NULL
 );
-CREATE INDEX idx_code_areas_file ON code_areas(file_path);
+CREATE INDEX IF NOT EXISTS idx_code_areas_file ON code_areas(file_path);
 
-CREATE TABLE pending_compressions (
+CREATE TABLE IF NOT EXISTS pending_compressions (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   kind TEXT NOT NULL CHECK(kind IN ('turn','session_rollup')),
   session_id TEXT NOT NULL,
@@ -115,44 +117,44 @@ CREATE TABLE pending_compressions (
   UNIQUE(kind, session_id, prompt_number)
 );
 
-CREATE VIRTUAL TABLE prompts_fts USING fts5(prompt_text, content='prompts', content_rowid='id');
-CREATE VIRTUAL TABLE decisions_fts USING fts5(decision, reason, content='decisions', content_rowid='id');
-CREATE VIRTUAL TABLE turn_summaries_fts USING fts5(summary, content='turn_summaries', content_rowid='id');
+CREATE VIRTUAL TABLE IF NOT EXISTS prompts_fts USING fts5(prompt_text, content='prompts', content_rowid='id');
+CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(decision, reason, content='decisions', content_rowid='id');
+CREATE VIRTUAL TABLE IF NOT EXISTS turn_summaries_fts USING fts5(summary, content='turn_summaries', content_rowid='id');
 
-CREATE TRIGGER prompts_ai AFTER INSERT ON prompts BEGIN
+CREATE TRIGGER IF NOT EXISTS prompts_ai AFTER INSERT ON prompts BEGIN
   INSERT INTO prompts_fts(rowid, prompt_text) VALUES (new.id, new.prompt_text);
 END;
-CREATE TRIGGER prompts_ad AFTER DELETE ON prompts BEGIN
+CREATE TRIGGER IF NOT EXISTS prompts_ad AFTER DELETE ON prompts BEGIN
   INSERT INTO prompts_fts(prompts_fts, rowid, prompt_text) VALUES('delete', old.id, old.prompt_text);
 END;
-CREATE TRIGGER prompts_au AFTER UPDATE ON prompts BEGIN
+CREATE TRIGGER IF NOT EXISTS prompts_au AFTER UPDATE ON prompts BEGIN
   INSERT INTO prompts_fts(prompts_fts, rowid, prompt_text) VALUES('delete', old.id, old.prompt_text);
   INSERT INTO prompts_fts(rowid, prompt_text) VALUES (new.id, new.prompt_text);
 END;
 
-CREATE TRIGGER decisions_ai AFTER INSERT ON decisions BEGIN
+CREATE TRIGGER IF NOT EXISTS decisions_ai AFTER INSERT ON decisions BEGIN
   INSERT INTO decisions_fts(rowid, decision, reason) VALUES (new.id, new.decision, new.reason);
 END;
-CREATE TRIGGER decisions_ad AFTER DELETE ON decisions BEGIN
+CREATE TRIGGER IF NOT EXISTS decisions_ad AFTER DELETE ON decisions BEGIN
   INSERT INTO decisions_fts(decisions_fts, rowid, decision, reason) VALUES('delete', old.id, old.decision, old.reason);
 END;
-CREATE TRIGGER decisions_au AFTER UPDATE ON decisions BEGIN
+CREATE TRIGGER IF NOT EXISTS decisions_au AFTER UPDATE ON decisions BEGIN
   INSERT INTO decisions_fts(decisions_fts, rowid, decision, reason) VALUES('delete', old.id, old.decision, old.reason);
   INSERT INTO decisions_fts(rowid, decision, reason) VALUES (new.id, new.decision, new.reason);
 END;
 
-CREATE TRIGGER turn_summaries_ai AFTER INSERT ON turn_summaries BEGIN
+CREATE TRIGGER IF NOT EXISTS turn_summaries_ai AFTER INSERT ON turn_summaries BEGIN
   INSERT INTO turn_summaries_fts(rowid, summary) VALUES (new.id, new.summary);
 END;
-CREATE TRIGGER turn_summaries_ad AFTER DELETE ON turn_summaries BEGIN
+CREATE TRIGGER IF NOT EXISTS turn_summaries_ad AFTER DELETE ON turn_summaries BEGIN
   INSERT INTO turn_summaries_fts(turn_summaries_fts, rowid, summary) VALUES('delete', old.id, old.summary);
 END;
-CREATE TRIGGER turn_summaries_au AFTER UPDATE ON turn_summaries BEGIN
+CREATE TRIGGER IF NOT EXISTS turn_summaries_au AFTER UPDATE ON turn_summaries BEGIN
   INSERT INTO turn_summaries_fts(turn_summaries_fts, rowid, summary) VALUES('delete', old.id, old.summary);
   INSERT INTO turn_summaries_fts(rowid, summary) VALUES (new.id, new.summary);
 END;
 
-CREATE TABLE schema_versions (
+CREATE TABLE IF NOT EXISTS schema_versions (
   version INTEGER PRIMARY KEY,
   applied_at_epoch INTEGER NOT NULL
 );
@@ -170,6 +172,20 @@ CREATE TABLE IF NOT EXISTS savings_log (
 CREATE INDEX IF NOT EXISTS idx_savings_bucket_ts ON savings_log(bucket, ts);
 `;
 
+const SCHEMA_V4 = `
+CREATE TABLE IF NOT EXISTS decision_links (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_id INTEGER NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+  to_id INTEGER NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK(kind IN ('related_to','annotates')),
+  note TEXT,
+  created_at_epoch INTEGER NOT NULL,
+  UNIQUE(from_id, to_id, kind)
+);
+CREATE INDEX IF NOT EXISTS idx_decision_links_from ON decision_links(from_id);
+CREATE INDEX IF NOT EXISTS idx_decision_links_to ON decision_links(to_id);
+`;
+
 const VEC_TRIGGERS = `
 CREATE TRIGGER IF NOT EXISTS decisions_vec_ad AFTER DELETE ON decisions BEGIN
   DELETE FROM decisions_vec WHERE rowid = old.id;
@@ -199,40 +215,137 @@ export class MemoryDb {
 	}
 
 	private ensureSchema(): void {
-		const bootstrap = this.db
-			.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='schema_versions'")
-			.get();
-		if (!bootstrap) {
-			const run = this.db.transaction(() => {
-				this.db.exec(SCHEMA_V1);
-				if (this.hasVec) {
-					this.db.exec(this.vecTableStmts(VEC_DIM));
-					this.db.exec(VEC_TRIGGERS);
-				}
-				this.db.exec(SCHEMA_V3);
-				this.db
-					.prepare("INSERT INTO schema_versions (version, applied_at_epoch) VALUES (?, ?)")
-					.run(this.hasVec ? CURRENT_VERSION : 1, epochSeconds());
-			});
-			run();
-			return;
-		}
-		const current = this.schemaVersion();
-		if (current >= CURRENT_VERSION) return;
+		// Shape enforcement instead of a version ladder: every statement below
+		// is idempotent, so a database from ANY earlier release converges to the
+		// current schema on open without version bookkeeping or stepwise
+		// migrations. Vec tables are created whenever sqlite-vec is available
+		// (and skipped when it isn't), which subsumes the old "created without
+		// vec, upgrade later" version dance.
 		const run = this.db.transaction(() => {
-			if (current < 2 && this.hasVec) {
+			this.db.exec(SCHEMA_V1);
+			this.applyV4Columns();
+			this.db.exec(SCHEMA_V3);
+			this.db.exec(SCHEMA_V4);
+			if (this.hasVec) {
 				this.db.exec(this.vecTableStmts(VEC_DIM));
 				this.db.exec(VEC_TRIGGERS);
 			}
-			if (current < 3) this.db.exec(SCHEMA_V3);
-			if (current < 2 && !this.hasVec) return; // vec step still pending
+			// Informational stamp only — nothing branches on it anymore.
 			this.db
-				.prepare("INSERT INTO schema_versions (version, applied_at_epoch) VALUES (?, ?)")
+				.prepare("INSERT OR REPLACE INTO schema_versions (version, applied_at_epoch) VALUES (?, ?)")
 				.run(CURRENT_VERSION, epochSeconds());
 		});
 		run();
 	}
 
+	/** `decisions.tags` / `decisions.files` (JSON arrays) on databases created
+	 * before R13; guarded so re-runs and partial states stay safe. */
+	private applyV4Columns(): void {
+		const cols = new Set(
+			(this.db.prepare("PRAGMA table_info(decisions)").all() as { name: string }[]).map((c) => c.name),
+		);
+		if (!cols.has("tags")) this.db.exec("ALTER TABLE decisions ADD COLUMN tags TEXT");
+		if (!cols.has("files")) this.db.exec("ALTER TABLE decisions ADD COLUMN files TEXT");
+	}
+
+	// ── R13: linked memory (A-MEM style) ─────────────────────────────────────
+
+	/** Outgoing `related_to` links a single decision may accumulate. */
+	static readonly MAX_OUTGOING_RELATED = 6;
+	/** Inbound `related_to` links a hub decision accepts before new links skip it. */
+	static readonly MAX_INBOUND_RELATED = 8;
+
+	/**
+	 * Create a directed link between two decisions. Refuses self-links,
+	 * unknown ids and cap overflow; dedupes via UNIQUE(from_id, to_id, kind)
+	 * (returns false on conflict instead of throwing).
+	 */
+	linkDecisions(fromId: number, toId: number, kind: "related_to" | "annotates", note: string | null = null): boolean {
+		if (!Number.isInteger(fromId) || !Number.isInteger(toId) || fromId === toId) return false;
+		const fromRow = this.db.prepare("SELECT 1 FROM decisions WHERE id = ?").get(fromId);
+		const toRow = this.db.prepare("SELECT 1 FROM decisions WHERE id = ?").get(toId);
+		if (!fromRow || !toRow) return false;
+		if (kind === "related_to") {
+			const outN = (
+				this.db.prepare("SELECT COUNT(*) AS n FROM decision_links WHERE from_id = ? AND kind = 'related_to'").get(fromId) as { n: number }
+			).n;
+			if (outN >= MemoryDb.MAX_OUTGOING_RELATED) return false;
+			const inN = (
+				this.db.prepare("SELECT COUNT(*) AS n FROM decision_links WHERE to_id = ? AND kind = 'related_to'").get(toId) as { n: number }
+			).n;
+			if (inN >= MemoryDb.MAX_INBOUND_RELATED) return false;
+		}
+		try {
+			this.db
+				.prepare("INSERT INTO decision_links (from_id, to_id, kind, note, created_at_epoch) VALUES (?, ?, ?, ?, ?)")
+				.run(fromId, toId, kind, note, epochSeconds());
+			return true;
+		} catch {
+			return false; // duplicate or FK violation — already linked
+		}
+	}
+
+	/** Both directions of a decision's links, ready for recall rendering. */
+	getDecisionLinks(id: number): {
+		relatedTo: number[];
+		relatedFrom: number[];
+		annotates: { id: number; note: string | null }[];
+		annotatedBy: { id: number; note: string | null }[];
+	} {
+		const rows = this.db
+			.prepare("SELECT from_id, to_id, kind, note FROM decision_links WHERE from_id = ? OR to_id = ?")
+			.all(id, id) as { from_id: number; to_id: number; kind: string; note: string | null }[];
+		const out = {
+			relatedTo: [] as number[],
+			relatedFrom: [] as number[],
+			annotates: [] as { id: number; note: string | null }[],
+			annotatedBy: [] as { id: number; note: string | null }[],
+		};
+		for (const r of rows) {
+			if (r.kind === "related_to") {
+				if (r.from_id === id) out.relatedTo.push(r.to_id);
+				else out.relatedFrom.push(r.from_id);
+			} else {
+				if (r.from_id === id) out.annotates.push({ id: r.to_id, note: r.note });
+				else out.annotatedBy.push({ id: r.from_id, note: r.note });
+			}
+		}
+		return out;
+	}
+
+	/** Short one-line text of a decision (for link rendering). */
+	decisionHeadline(id: number): string | null {
+		const row = this.db.prepare("SELECT decision FROM decisions WHERE id = ?").get(id) as { decision: string } | undefined;
+		return row ? row.decision : null;
+	}
+
+	/**
+	 * R13 auto-linking: embed the new decision, find similar past decisions
+	 * and connect them with `related_to` edges (A-MEM's dynamic indexing).
+	 * The similarity gate is deliberately tighter than recall (0.85 vs 0.92
+	 * L2 on normalized vectors ≈ cosine ≥ 0.64): a wrong link is worse than a
+	 * missing one, because recall walks them.
+	 */
+	autoLinkDecision(
+		embedder: Embedder,
+		newId: number,
+		text: string,
+		opts: { k?: number; maxDistance?: number; cap?: number } = {},
+	): Promise<number[]> {
+		const { k = 4, maxDistance = 0.85, cap = 3 } = opts;
+		return (async () => {
+			if (!this.hasVecTables() || !text.trim()) return [];
+			const ids = await this.searchDecisionsVec(embedder, text, k, maxDistance);
+			const linked: number[] = [];
+			for (const id of ids) {
+				if (id === newId) continue;
+				if (linked.length >= cap) break;
+				if (this.linkDecisions(newId, id, "related_to")) linked.push(id);
+			}
+			return linked;
+		})();
+	}
+
 	private vecTableStmts(dim: number): string {
 		return `
 CREATE VIRTUAL TABLE IF NOT EXISTS decisions_vec USING vec0(embedding float[${dim}]);

package/src/retrieval/confidence.ts

@@ -3,6 +3,8 @@
  * Weighted sum: vector similarity 0.5, keyword/file-hint 0.4, recency 0.1.
  */
 import type { Chunk } from "../types.js";
+import type { ParsedQuery } from "./query-parser.js";
+import type { QuerySignals } from "./retriever.js";
 
 const VECTOR_WEIGHT = 0.5;
 const KEYWORD_WEIGHT = 0.4;
@@ -27,3 +29,54 @@ export class ConfidenceScorer {
 		return Math.pow(0.5, ageSeconds / RECENCY_HALF_LIFE);
 	}
 }
+
+// ── R8: query-level confidence ─────────────────────────────────────────────
+
+export type QueryConfidence = "high" | "medium" | "low";
+
+export interface QueryAssessment {
+	level: QueryConfidence;
+	/** Composite 0..1 quality score (reported for observability). */
+	quality: number;
+	/** 1-3 deterministic recovery hints; non-empty only below `high`. */
+	hints: string[];
+}
+
+/** Signal weights for the composite quality score. */
+const SIGNAL_WEIGHTS = { topScore: 0.5, agreement: 0.35, margin: 0.15 };
+/** Candidate pools this small cap the level at `medium` (tiny indexes lie). */
+const MIN_CANDIDATES = 5;
+
+/**
+ * Map query signals to high/medium/low plus recovery hints. Thresholds come
+ * from config (calibrated on the eval fixture); hints are derived from the
+ * parsed query so the agent gets actionable, deterministic advice instead of
+ * a silent rewrite it cannot inspect.
+ */
+export function assessQuery(
+	signals: QuerySignals,
+	parsed: ParsedQuery,
+	thresholds: { high: number; low: number },
+): QueryAssessment {
+	const marginNorm = Math.min(1, Math.max(0, signals.margin));
+	const quality =
+		SIGNAL_WEIGHTS.topScore * Math.min(1, Math.max(0, signals.topScore)) +
+		SIGNAL_WEIGHTS.agreement * Math.min(1, Math.max(0, signals.agreement)) +
+		SIGNAL_WEIGHTS.margin * marginNorm;
+
+	let level: QueryConfidence;
+	if (quality >= thresholds.high) level = "high";
+	else if (quality >= thresholds.low) level = "medium";
+	else level = "low";
+	if (signals.candidates < MIN_CANDIDATES && level === "high") level = "medium";
+
+	const hints: string[] = [];
+	if (level !== "high") {
+		if (parsed.fileHints.length === 0) hints.push("name a file or path fragment (e.g. retriever.ts)");
+		const identifierLike = parsed.keywords.some((k) => k.length >= 4 && /[a-z][A-Z]|[A-Z][a-z]/.test(k));
+		if (!identifierLike) hints.push("use an exact symbol name (function or class, e.g. HybridRetriever)");
+		if (parsed.keywords.length > 8) hints.push("drop vague terms; keep 2-4 specific keywords");
+		if (signals.agreement < 0.2) hints.push("results disagree between retrieval paths; try a more specific query");
+	}
+	return { level, quality, hints: hints.slice(0, 3) };
+}

package/src/retrieval/query-parser.ts

@@ -80,3 +80,36 @@ export class QueryParser {
 		return result;
 	}
 }
+
+/**
+ * R8: deterministic query elaboration. Strips stopwords, caps the raw terms,
+ * and injects up to three identifier-like words that appear in ≥2 of the
+ * near-miss FTS hits. No LLM, no network, fully reproducible — the raw
+ * query's own ranking is never modified (callers fuse the variant as an
+ * additional, lower-weighted candidate source only).
+ */
+export function elaborateQuery(query: string, nearMissChunks: { content: string }[]): string | null {
+	const words = query.match(/[a-zA-Z_$][a-zA-Z0-9_$]*/g) ?? [];
+	const kept: string[] = [];
+	for (const w of words) {
+		if (STOP_WORDS.has(w.toLowerCase()) || w.length < 3) continue;
+		if (!kept.includes(w)) kept.push(w);
+	}
+	const freq = new Map<string, number>();
+	for (const chunk of nearMissChunks) {
+		const local = new Set<string>();
+		for (const m of chunk.content.matchAll(/[A-Za-z_$][A-Za-z0-9_$]{3,}/g)) {
+			const w = m[0];
+			if (!kept.includes(w)) local.add(w);
+		}
+		for (const w of local) freq.set(w, (freq.get(w) ?? 0) + 1);
+	}
+	const extras = [...freq.entries()]
+		.filter(([, n]) => n >= 2)
+		.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+		.slice(0, 3)
+		.map(([w]) => w);
+	const variant = [...kept.slice(0, 8), ...extras].join(" ");
+	if (variant.length < 3 || variant === query.trim()) return null;
+	return variant;
+}

package/src/retrieval/reranker.ts

@@ -0,0 +1,112 @@
+/**
+ * R10: opt-in local cross-encoder reranker (plan: docs/IMPLEMENTATION-PLAN.md).
+ *
+ * Why opt-in and OFF by default: reranking evidence is split — a core gain in
+ * CodeRAG-style pipelines, but measured harmful for SE tasks when it costs
+ * ~800 ms per query. Only this package's own eval can decide, and the model
+ * download (~80 MB) must never happen implicitly in a package that markets
+ * "one npm command".
+ *
+ * The reranker reorders the fused candidate list (capped); path penalty, file
+ * diversity and the marginal stop are applied AFTER it, unchanged. If the
+ * model cannot load, retrieval silently falls back to the fused order — a
+ * missing optional download degrades, never breaks.
+ *
+ * Implementation notes (PR #7 review): we do NOT go through the
+ * text-classification pipeline. Two reasons:
+ *
+ * 1. Its input is a plain string — there is no `{text, text_pair}` shape, so
+ *    pair scoring via the pipeline throws and permanently disables reranking.
+ * 2. Cross-encoder rerankers (ms-marco-MiniLM) emit ONE logit; the pipeline
+ *    softmaxes it, so every document scores exactly 1.0 and no reordering
+ *    can happen. Sentence-transformers' CrossEncoder applies a sigmoid to
+ *    the raw logit instead — we do the same, on raw model logits.
+ */
+
+import { transformersCacheDir } from "../indexer/embedder.js";
+
+/** Minimal interface so unit tests can inject a stub (no model download). */
+export interface RerankerLike {
+	rerank(query: string, docs: string[]): Promise<number[]>;
+}
+
+/** Structural slice of @huggingface/transformers we need (kept `any`-light). */
+interface TransformersModule {
+	AutoTokenizer: {
+		from_pretrained: (model: string, options?: Record<string, unknown>) => Promise<TokenizerLike>;
+	};
+	AutoModelForSequenceClassification: {
+		from_pretrained: (model: string, options?: Record<string, unknown>) => Promise<ModelLike>;
+	};
+	env: Record<string, unknown>;
+}
+
+interface TokenizerLike {
+	(text: string, options: Record<string, unknown>): unknown;
+}
+
+interface ModelLike {
+	(inputs: unknown): Promise<{ logits: { data: Float32Array | number[] } }>;
+}
+
+type LoadedReranker = { tokenizer: TokenizerLike; model: ModelLike };
+
+export class LocalReranker implements RerankerLike {
+	private loaded: LoadedReranker | null = null;
+	private loading: Promise<LoadedReranker | null> | null = null;
+	/** Set after a load failure; every later call short-circuits to no-op. */
+	failed = false;
+
+	constructor(
+		readonly model: string,
+		private readonly loadTransformers: () => Promise<TransformersModule> = async () =>
+			(await import("@huggingface/transformers")) as unknown as TransformersModule,
+	) {}
+
+	async rerank(query: string, docs: string[]): Promise<number[]> {
+		if (this.failed || docs.length === 0) return [];
+		try {
+			const loaded = await this.ensureLoaded();
+			if (!loaded) return [];
+			const { tokenizer, model } = loaded;
+			const scores: number[] = [];
+			// One pair per call: 30 sequential CPU inferences are well inside
+			// the latency budget this opt-in feature accepts, and per-pair
+			// truncation keeps a long doc from padding the whole batch.
+			for (const doc of docs) {
+				const inputs = tokenizer(query, { text_pair: doc, padding: true, truncation: true });
+				const out = await model(inputs);
+				const logit = Number(out.logits.data[0] ?? 0);
+				// Sigmoid, not softmax: single-logit cross-encoders must keep
+				// their ranking signal (softmax over one logit is constant 1).
+				scores.push(1 / (1 + Math.exp(-logit)));
+			}
+			return scores;
+		} catch {
+			this.failed = true;
+			return [];
+		}
+	}
+
+	private ensureLoaded(): Promise<LoadedReranker | null> {
+		if (this.loaded) return Promise.resolve(this.loaded);
+		if (!this.loading) {
+			this.loading = (async () => {
+				const mod = await this.loadTransformers();
+				// Same models dir as the embedder, so opt-in reranking never
+				// downloads into a stray ./Xenova folder inside the project.
+				mod.env.cacheDir = transformersCacheDir();
+				const tokenizer = await mod.AutoTokenizer.from_pretrained(this.model);
+				const model = await mod.AutoModelForSequenceClassification.from_pretrained(this.model, {
+					quantized: true,
+				});
+				this.loaded = { tokenizer, model };
+				return this.loaded;
+			})().catch(() => {
+				this.failed = true;
+				return null;
+			});
+		}
+		return this.loading;
+	}
+}