pi-context-engine 0.1.1 → 0.1.3

package/README.md

@@ -58,6 +58,20 @@ Ten tools the agent can call, plus three slash commands.
 
 Commands: `/context-index [--full]`, `/context-status`, `/context-savings`.
 
+**Shipped guidance.** The package also injects a ~900-token guidance section
+into the system prompt while `context_search` is active: how to formulate
+queries, when *not* to search, how to read confidence and overflow markers,
+and the index lifecycle.
+
+- **Why it ships:** retrieval only saves tokens when queries are good, and
+  these rules describe this package's own semantics. Keeping them in the tool
+  description alone would leave every user guessing.
+- **Cost-aware gate:** the section appears only while the tool is selected, and
+  `guidance.enabled: false` turns it off entirely for prompt-lean setups.
+- **Structured, not forced:** it is written to `systemPromptOptions.sections`,
+  so pi replays and diffs it like any other section instead of freezing the
+  whole prompt.
+
 ## How it works
 
 1. **Chunk**: tree-sitter parses source into functions, classes and modules.
@@ -93,6 +107,8 @@ retrieval:
   top_k: 20
   confidence_threshold: 0.2
   marginal_ratio: 0.75   # stop adding chunks below this fraction of the top score
+guidance:
+  enabled: true          # inject context_search guidance into the system prompt
 compression:
   level: standard        # minimal | standard | full
   ollama_url: http://localhost:11434
@@ -100,7 +116,6 @@ embedding:
   model: local           # or a specific transformers.js model id
   ollama_model: nomic-embed-text
 indexer:
-  watch: true
   redact_secrets: true
 memory:
   redact_pii: true

package/docs/ARCHITECTURE.md

@@ -26,6 +26,7 @@ pi session
 | `indexer/embedder.ts` | Ollama + local ONNX backends, selection | `indexer/embedder.py` |
 | `indexer/secrets.ts` | Secret filename skip, content redaction, PII scrub | `indexer/secrets.py` |
 | `retrieval/retriever.ts` | RRF merge, confidence blend, graph expansion | `retrieval/retriever.py` |
+| `guidance.ts` | Query-formulation system-prompt section (config-gated) | upstream's session-start tool instructions |
 | `compression/compressor.ts` | Truncation signatures, Ollama summaries, quality gate | `compression/*` |
 | `memory/db.ts` | Schema, vec recall, savings ledger, retention | `memory/db.py` |
 | `memory/grammar.ts` | Deterministic prose compression | `memory/grammar.py` |
@@ -71,6 +72,11 @@ contending with embedding writes. Upstream made the same split.
 - **Best-effort everywhere it must not crash.** Savings accounting, audit logs,
   session capture and shutdown all swallow their own errors: an instrumentation
   problem must never break a tool response.
+- **Guidance pays for its tokens or does not ship.** The ~900-token section is
+  injected only when `context_search` is in the run's selected tools *and*
+  `guidance.enabled` is true, through `sections` (replayable, diffable) rather
+  than a forced prompt replacement. Users who count prompt tokens opt out with
+  one config line.
 
 ## Degradation paths
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-context-engine",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Semantic code context for pi: tree-sitter index + hybrid vector/BM25 retrieval + cross-session memory, all local. Port of code-context-engine (MIT, elara-labs) as a native pi extension.",
 	"keywords": [
 		"pi-package",

package/src/config.ts

@@ -51,16 +51,18 @@ export interface Config {
 	ollamaUrl: string;
 	embeddingModel: string;
 	ollamaEmbedModel: string;
+	/**
+	 * Inject the query-formulation guidance section into the system prompt
+	 * while `context_search` is active. Default true: retrieval quality depends
+	 * on how queries are written. Set false for the leanest possible prompt.
+	 */
+	guidanceEnabled: boolean;
 	retrievalConfidenceThreshold: number;
 	retrievalTopK: number;
 	retrievalMarginalRatio: number;
-	bootstrapMaxTokens: number;
-	indexerWatch: boolean;
-	indexerDebounceMs: number;
 	indexerIgnore: string[];
 	indexerRedactSecrets: boolean;
 	memoryRedactPii: boolean;
-	auditLogEnabled: boolean;
 	pricingModel: string;
 	pricingInput: number | null;
 	pricingOutput: number | null;
@@ -74,16 +76,13 @@ export function defaultConfig(): Config {
 		ollamaUrl: "http://localhost:11434",
 		embeddingModel: "local",
 		ollamaEmbedModel: "nomic-embed-text",
+		guidanceEnabled: true,
 		retrievalConfidenceThreshold: 0.2,
 		retrievalTopK: 20,
 		retrievalMarginalRatio: 0.75,
-		bootstrapMaxTokens: 10000,
-		indexerWatch: true,
-		indexerDebounceMs: 500,
 		indexerIgnore: [...DEFAULT_IGNORE],
 		indexerRedactSecrets: true,
 		memoryRedactPii: true,
-		auditLogEnabled: false,
 		pricingModel: "opus",
 		pricingInput: null,
 		pricingOutput: null,
@@ -96,18 +95,15 @@ const MAPPING: Record<string, keyof Config> = {
 	"compression.level": "compressionLevel",
 	"compression.model": "compressionModel",
 	"compression.ollama_url": "ollamaUrl",
+	"guidance.enabled": "guidanceEnabled",
 	"embedding.model": "embeddingModel",
 	"embedding.ollama_model": "ollamaEmbedModel",
 	"retrieval.confidence_threshold": "retrievalConfidenceThreshold",
 	"retrieval.top_k": "retrievalTopK",
 	"retrieval.marginal_ratio": "retrievalMarginalRatio",
-	"retrieval.bootstrap_max_tokens": "bootstrapMaxTokens",
-	"indexer.watch": "indexerWatch",
-	"indexer.debounce_ms": "indexerDebounceMs",
 	"indexer.ignore": "indexerIgnore",
 	"indexer.redact_secrets": "indexerRedactSecrets",
 	"memory.redact_pii": "memoryRedactPii",
-	"audit.enabled": "auditLogEnabled",
 	"storage.path": "storagePath",
 	"pricing.model": "pricingModel",
 	"pricing.input": "pricingInput",

package/src/engine.ts

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import path from "node:path";
 import type { Config } from "./config.js";
 import { loadConfigForProject, resolveOllamaUrl } from "./config.js";
-import { epochSeconds, humaniseRelativeTime, projectStorageDir, sha256Hex } from "./utils.js";
+import { atomicWriteText, epochSeconds, humaniseRelativeTime, projectStorageDir, sha256Hex } from "./utils.js";
 import { LocalBackend } from "./storage/local-backend.js";
 import { Embedder, selectBackend } from "./indexer/embedder.js";
 import { HybridRetriever } from "./retrieval/retriever.js";
@@ -146,6 +146,7 @@ export class ContextEngine {
 	draining = false;
 	private searchesSinceDecision = 0;
 	private hasRecordedDecision = false;
+	private vecBackfillStarted = false;
 
 	constructor(options: EngineOptions) {
 		this.projectDir = fs.realpathSync(path.resolve(options.projectDir));
@@ -247,7 +248,7 @@ export class ContextEngine {
 
 	private saveStats(): void {
 		try {
-			fs.writeFileSync(this.statsPath, JSON.stringify(this.stats));
+			atomicWriteText(this.statsPath, JSON.stringify(this.stats));
 		} catch {
 			// stats are best-effort
 		}
@@ -426,6 +427,25 @@ export class ContextEngine {
 			void this.drainCompressionQueue();
 		}, 5000);
 		this.drainTimer.unref?.();
+		void this.backfillMemoryVec().catch(() => undefined);
+	}
+
+	/**
+	 * One-shot semantic-memory backfill (upstream #137 lesson). After an
+	 * embedder change the vec tables are recreated empty; without this, old
+	 * decisions silently lose semantic recall (FTS still works, so the loss is
+	 * easy to miss). Guarded by a cheap missing-row count so the steady state
+	 * never initialises an embedder for this. Recall also self-heals via
+	 * `MemoryDb.healVecTables`, covering wipes that happen after this runs.
+	 */
+	private async backfillMemoryVec(): Promise<void> {
+		if (this.vecBackfillStarted) return;
+		this.vecBackfillStarted = true;
+		const memory = this.getMemory();
+		if (!memory || !memory.vecAvailable || !memory.hasVecTables()) return;
+		const pending = memory.vecBackfillPending();
+		if (pending.decisions + pending.turnSummaries === 0) return;
+		await memory.backfillVecTables(await this.getEmbedder());
 	}
 
 	async shutdown(): Promise<void> {

package/src/extension.ts

@@ -11,6 +11,7 @@ import { Type } from "typebox";
 import fs from "node:fs";
 import path from "node:path";
 import { ContextEngine, isPceConfig } from "./engine.js";
+import { applyContextSearchGuidance } from "./guidance.js";
 
 /** Tools whose payloads are worth capturing for session timelines. */
 const CAPTURED_TOOLS = new Set(["bash", "read", "edit", "write", "grep", "find", "ls"]);
@@ -305,6 +306,12 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 		promptNumber = eng.recordPrompt(event.prompt ?? "");
 		eng.enqueueTurnCompression(promptNumber);
 
+		// Query-formulation guidance for context_search: gated on the tool being
+		// active and on `guidance.enabled` (config), so prompt-lean setups pay
+		// nothing. Section, not a forced prompt override: pi diffs it like any
+		// other section and the transcript stays stable.
+		applyContextSearchGuidance(event.systemPromptOptions, eng.config.guidanceEnabled);
+
 		// First prompt of the session: inject a compact "where you left off"
 		// block as a non-displayed custom message (upstream's SessionStart hook).
 		if (!bootstrapSent) {

package/src/guidance.ts

@@ -0,0 +1,114 @@
+/**
+ * System-prompt guidance for the package's own tools.
+ *
+ * Why this ships with the package: retrieval quality depends on how the query
+ * is written, and the tool's `promptSnippet`/`promptGuidelines` only say "use
+ * this instead of grep/read". Everything specific to *this* package's
+ * semantics (confidence scores, overflow references, `/context-index`, the
+ * empty-index background build) has to travel with the package, or it drifts
+ * the moment a tool parameter changes.
+ *
+ * Injection is gated on three conditions so the ~900-token block never lands
+ * where it does not pay for itself:
+ *  1. `context_search` must be in the run's selected tools
+ *  2. `guidance.enabled` must be true in config (default true)
+ *  3. only runs that start from a user prompt get the bootstrap message;
+ *     guidance itself applies to every run while the tool is active
+ *
+ * Registered through `systemPromptOptions.sections` rather than a forced
+ * `systemPrompt`: pi replays and diffs structured sections like any other, so
+ * the transcript stays stable instead of freezing a whole-prompt override.
+ */
+
+export const CONTEXT_SEARCH_SECTION_KEY = "context_search_guidelines";
+
+/** Minimal shape of the mutable prompt options this module touches. */
+export interface GuidanceTarget {
+	selectedTools: string[];
+	sections: Record<string, string>;
+}
+
+export const CONTEXT_SEARCH_GUIDELINES = `You have context_search, a semantic code search over this project's index (tree-sitter chunks, hybrid vector + BM25, confidence-scored). Use it well.
+
+### When to search vs. when not to
+
+SEARCH when:
+- Starting a new task and you need to understand the relevant code area
+- You need to find where a concept, pattern, or feature is implemented
+- Before editing code you haven't recently read
+- You need cross-file relationships (callers, imports, dependents)
+
+SKIP the search when:
+- You already have the file contents in context from a recent read
+- You were given an exact file path and line numbers
+- You need a simple exact-string match (use bash with grep/rg instead)
+- You are editing a file you just read in the current turn
+
+### Writing effective queries
+
+GOOD queries - specific, scoped, with concrete symbols or behaviour:
+- "How does the AuthenticationMiddleware validate JWT tokens? Show the verify method and its error handling"
+- "Where is the UserService.createUser method defined? Show the full implementation and parameters"
+- "Find all HTTP route handlers that accept file uploads"
+- "How does the EventBus dispatch events to subscribers?"
+
+POOR queries - vague, broad, or just a symbol dump:
+- "Show me the codebase"
+- "Authentication"
+- "Find UserService"
+
+RULES:
+1. Describe WHAT you want in natural language - the index is semantic, prose works better than keywords
+2. Include CONTEXT: what it is for (implementation? debugging? refactoring?)
+3. Ask for the LEVEL OF DETAIL: "full method", "the interface and its implementors", "the call chain"
+4. Combine related lookups into ONE query instead of several calls
+
+### Reading the results
+
+- Each hit is a compressed chunk: \`[path:start] (confidence: 0.xx)\` followed by the code
+- A "\`expand_chunk\`" reference list means results were cut by the token budget - expand only the ones you actually need, never every entry
+- Confidence below ~0.5 usually means the index has nothing better; rephrase rather than trusting a weak hit
+- Results come from the index, not the live file: before editing, open the file with \`read\` to see its current state
+
+### Before editing code
+
+Search once with a query covering ALL of:
+- The function/method/class you are modifying (full implementation)
+- Its types and constants
+- Callers that could break
+
+Example: "I need to add a retry parameter to HttpClient.request. Show the HttpClient class with the request method, HttpClientConfig, every caller of request(), and error types it throws."
+
+### Iterative search
+
+If the first search misses:
+1. REPHRASE - the codebase may use different names than you expect
+2. BROADEN - add surroundings ("and the module that defines it")
+3. NARROW - add specifics ("the async version returning a Promise")
+4. Change ANGLE - search for tests, the type definition, or a usage example
+
+### Combining with other tools
+
+- \`related_context\` - walk import/defines edges from a hit to reach neighbouring code
+- \`read\` - full current file contents when you are about to edit (search returns excerpts)
+- \`bash\` with grep/rg - exact strings (TODO markers, error messages, literal identifiers)
+- \`bash\` with git - history: \`git log -p -- path/to/file\`
+
+### Index lifecycle
+
+- If a search says the index is empty, a background index is already running - retry shortly, or run \`/context-index\` for a synchronous build
+- After large refactors, \`reindex\` (or \`/context-index\`) keeps results current; \`index_status\` reports freshness and measured token savings
+- Incremental re-index only re-reads changed files, so it is cheap
+`;
+
+/**
+ * Apply the guidance section to mutable prompt options.
+ * No-op (and safe to call on every run) when the tool is inactive or the
+ * user turned guidance off. Returns whether it injected, for tests.
+ */
+export function applyContextSearchGuidance(options: GuidanceTarget, enabled: boolean): boolean {
+	if (!enabled) return false;
+	if (!options.selectedTools.includes("context_search")) return false;
+	options.sections[CONTEXT_SEARCH_SECTION_KEY] = CONTEXT_SEARCH_GUIDELINES;
+	return true;
+}

package/src/indexer/pipeline.ts

@@ -139,6 +139,40 @@ function resolveWithin(projectDir: string, target: string): string {
 	return resolved;
 }
 
+/** A directory target is excluded when it or any ancestor matches a dir rule (upstream #165b). */
+function cceignoreMatchesDir(relPosix: string, patterns: string[]): boolean {
+	const parts = relPosix.split("/");
+	for (let i = 1; i <= parts.length; i++) {
+		if (matchesAny(parts.slice(0, i).join("/"), true, patterns)) return true;
+	}
+	return false;
+}
+
+/**
+ * Target-path policy gate, mirroring what the full walker enforces while
+ * descending: every path segment must pass `indexer.ignore`, files must pass
+ * the secret-filename check, and `.cceignore` is matched against the
+ * project-relative path (dir rules for directories, file + ancestor rules for
+ * files). The project root (`rel === ""`) is exempt — rules apply to entries
+ * below the root, not to the root itself (a checkout named `build` must still
+ * reindex via `path: "."`).
+ */
+function targetExcluded(
+	relPosix: string,
+	opts: { isDir: boolean; ignoreSet: Set<string>; redactSecrets: boolean; patterns: string[] },
+): boolean {
+	if (relPosix === "") return false;
+	const segments = relPosix.split("/");
+	for (const seg of segments) {
+		if (opts.ignoreSet.has(seg)) return true;
+	}
+	// The walker only classifies secret names on file entries; a secret-named
+	// directory's contents are still gated per file.
+	if (!opts.isDir && opts.redactSecrets && isSecretFile(segments[segments.length - 1]!)) return true;
+	if (opts.patterns.length === 0) return false;
+	return opts.isDir ? cceignoreMatchesDir(relPosix, opts.patterns) : cceignoreMatchesFile(relPosix, opts.patterns);
+}
+
 function safeRead(filePath: string): string | null {
 	try {
 		if (fs.statSync(filePath).size > MAX_FILE_BYTES) return null;
@@ -149,7 +183,9 @@ function safeRead(filePath: string): string | null {
 }
 
 function* iterProjectFiles(
-	root: string,
+	walkRoot: string,
+	/** Project root: `.cceignore` patterns are matched against project-relative paths even when walking from a target. */
+	relRoot: string,
 	ignoreSet: Set<string>,
 	opts: { redactSecrets: boolean; cceignorePatterns: string[] },
 ): Generator<string> {
@@ -175,7 +211,7 @@ function* iterProjectFiles(
 			}
 			if (seen.has(resolved)) continue;
 			seen.add(resolved);
-			const rel = path.relative(root, full).replace(/\\/g, "/");
+			const rel = path.relative(relRoot, full).replace(/\\/g, "/");
 			if (opts.cceignorePatterns.length > 0 && matchesAny(rel, entry.isDirectory(), opts.cceignorePatterns)) {
 				continue;
 			}
@@ -188,7 +224,7 @@ function* iterProjectFiles(
 			}
 		}
 	};
-	yield* walk(root);
+	yield* walk(walkRoot);
 }
 
 /** `{embeddings, cacheHits, cacheMisses}` for a batch, using the content cache. */
@@ -385,32 +421,77 @@ async function runIndexingLocked(
 	if (cceignorePatterns.length > 0) log?.(`  [.cceignore] ${cceignorePatterns.length} pattern(s) loaded`);
 
 	// ── Determine the file set ─────────────────────────────────────────────
+	/**
+	 * A file the inclusion policy now rejects must not leave stale chunks
+	 * behind (upstream #127): purge its manifest entry and indexed rows so a
+	 * targeted reindex is enough to enforce a new secret/ignore rule.
+	 */
+	const purgeIndexed = (rels: string[]): void => {
+		const indexed = rels.filter((rel) => manifest.getHash(rel) !== undefined);
+		if (indexed.length === 0) return;
+		backend.deleteByFiles(indexed);
+		for (const rel of indexed) {
+			manifest.remove(rel);
+			result.deletedFiles.push(rel);
+			log?.(`  [delete] ${rel} (excluded by policy)`);
+		}
+		manifest.save();
+	};
 	let fileList: string[];
 	if (targetPath) {
 		const target = resolveWithin(projectDir, targetPath);
 		if (fs.existsSync(target) && fs.statSync(target).isFile()) {
 			const rel = path.relative(projectDir, target).replace(/\\/g, "/");
 			if (SKIP_EXTENSIONS.has(path.extname(target).toLowerCase())) {
+				purgeIndexed([rel]);
 				fileList = [];
-			} else if (ignoreSet.has(path.basename(target))) {
-				result.skippedFiles.push(rel);
-				fileList = [];
-			} else if (config.indexerRedactSecrets && isSecretFile(target)) {
-				result.skippedFiles.push(rel);
-				fileList = [];
-			} else if (cceignorePatterns.length > 0 && cceignoreMatchesFile(rel, cceignorePatterns)) {
+			} else if (
+				targetExcluded(rel, {
+					isDir: false,
+					ignoreSet,
+					redactSecrets: config.indexerRedactSecrets,
+					patterns: cceignorePatterns,
+				})
+			) {
+				// Ancestor segments included: the full walker would have pruned
+				// the path before reaching this file (upstream #165b parity).
 				result.skippedFiles.push(rel);
+				purgeIndexed([rel]);
 				fileList = [];
 			} else {
 				fileList = [target];
 			}
 		} else if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
-			fileList = [
-				...iterProjectFiles(target, ignoreSet, {
-					redactSecrets: config.indexerRedactSecrets,
-					cceignorePatterns,
-				}),
-			];
+			// Upstream #165b: the walk starts inside the target, so the target
+			// path itself must first pass the same policy the full walker
+			// enforces while descending — every segment vs `indexer.ignore`
+			// (e.g. `dist/nested` is rejected because `dist` is), plus
+			// `.cceignore` dir rules for the target and its ancestors.
+			const rel = path.relative(projectDir, target).replace(/\\/g, "/");
+			const excluded = targetExcluded(rel, {
+				isDir: true,
+				ignoreSet,
+				redactSecrets: config.indexerRedactSecrets,
+				patterns: cceignorePatterns,
+			});
+			if (excluded) {
+				result.skippedFiles.push(rel);
+				fileList = [];
+			} else {
+				fileList = [
+					...iterProjectFiles(target, projectDir, ignoreSet, {
+						redactSecrets: config.indexerRedactSecrets,
+						cceignorePatterns,
+					}),
+				];
+			}
+			// Targeted runs skip the full-run prune below, so purge manifest
+			// entries under this subtree the walk no longer yields: newly
+			// excluded files, secret files, and deleted files (upstream
+			// #127/#165b). Scoped to the target so siblings are untouched.
+			const yielded = new Set(fileList.map((f) => path.relative(projectDir, f).replace(/\\/g, "/")));
+			const underScope = (p: string): boolean => (rel === "" ? true : p === rel || p.startsWith(`${rel}/`));
+			purgeIndexed(Object.keys(manifest.fileEntries).filter((p) => underScope(p) && !yielded.has(p)));
 		} else {
 			// Watcher deletion path: prune instead of erroring out.
 			const rel = path.relative(projectDir, target).replace(/\\/g, "/");
@@ -426,7 +507,7 @@ async function runIndexingLocked(
 		}
 	} else {
 		fileList = [
-			...iterProjectFiles(projectDir, ignoreSet, {
+			...iterProjectFiles(projectDir, projectDir, ignoreSet, {
 				redactSecrets: config.indexerRedactSecrets,
 				cceignorePatterns,
 			}),

package/src/memory/db.ts

@@ -309,9 +309,31 @@ CREATE VIRTUAL TABLE IF NOT EXISTS turn_summaries_vec USING vec0(embedding float
 		this.writeVecRow("turn_summaries_vec", turnId, vec);
 	}
 
+	/**
+	 * Count rows still missing a vec entry, without touching an embedder.
+	 * Lets callers skip the backfill (and its model init) in the steady state.
+	 */
+	vecBackfillPending(): { decisions: number; turnSummaries: number } {
+		if (!this.hasVecTables()) return { decisions: 0, turnSummaries: 0 };
+		try {
+			const d = this.db
+				.prepare("SELECT COUNT(*) AS n FROM decisions d WHERE NOT EXISTS (SELECT 1 FROM decisions_vec v WHERE v.rowid = d.id)")
+				.get() as { n: number };
+			const t = this.db
+				.prepare("SELECT COUNT(*) AS n FROM turn_summaries t WHERE NOT EXISTS (SELECT 1 FROM turn_summaries_vec v WHERE v.rowid = t.id)")
+				.get() as { n: number };
+			return { decisions: Number(d?.n ?? 0), turnSummaries: Number(t?.n ?? 0) };
+		} catch {
+			return { decisions: 0, turnSummaries: 0 };
+		}
+	}
+
 	async backfillVecTables(embedder: Embedder): Promise<{ decisions: number; turnSummaries: number }> {
 		const counts = { decisions: 0, turnSummaries: 0 };
 		if (!this.hasVecTables()) return counts;
+		// Steady state: nothing missing — skip the embedder entirely.
+		const pending = this.vecBackfillPending();
+		if (pending.decisions + pending.turnSummaries === 0) return counts;
 		try {
 			this.ensureVecDim((await embedder.embedQuery("dimension probe")).length);
 		} catch {
@@ -348,6 +370,7 @@ CREATE VIRTUAL TABLE IF NOT EXISTS turn_summaries_vec USING vec0(embedding float
 		} catch {
 			return [];
 		}
+		await this.healVecTables(embedder, vec);
 		return this.vecSearch("decisions_vec", vec, k, maxDistance);
 	}
 
@@ -359,9 +382,32 @@ CREATE VIRTUAL TABLE IF NOT EXISTS turn_summaries_vec USING vec0(embedding float
 		} catch {
 			return [];
 		}
+		await this.healVecTables(embedder, vec);
 		return this.vecSearch("turn_summaries_vec", vec, k, maxDistance);
 	}
 
+	/**
+	 * Self-heal at the point of recall (upstream #137), covering both failure
+	 * shapes a dim-mismatched or partially-empty vec table produces:
+	 *
+	 * 1. Tables built by another embedder: a dim-mismatched MATCH errors and
+	 *    silently returns nothing → recreate at the query's dim.
+	 * 2. Rows missing for any reason (e.g. a mid-session `recordDecisionVec`
+	 *    wiped the tables via `ensureVecDim` after the engine's one-shot
+	 *    backfill already ran) → restore them here, where the embedder is
+	 *    already in hand.
+	 *
+	 * Steady state costs two COUNT queries; the embedder is only touched when
+	 * something is actually wrong.
+	 */
+	private async healVecTables(embedder: Embedder, vec: readonly number[]): Promise<void> {
+		if (!this.hasVecTables()) return;
+		const declared = this.declaredVecDim();
+		if (declared !== null && declared !== vec.length) this.ensureVecDim(vec.length);
+		const pending = this.vecBackfillPending();
+		if (pending.decisions + pending.turnSummaries > 0) await this.backfillVecTables(embedder);
+	}
+
 	private vecSearch(table: string, vec: number[], k: number, maxDistance: number): number[] {
 		try {
 			const rows = this.db