pi-context-engine 0.1.3 → 0.2.0

package/src/indexer/pipeline.ts

@@ -10,14 +10,15 @@ import { promisify } from "node:util";
 import type { Config } from "../config.js";
 import { projectStorageDir, sha256Hex } from "../utils.js";
 import { Chunker, isAstLanguage, warmupLanguages } from "./chunker.js";
+import { applyContextHeaderToChunk, stripContextHeader } from "./context-header.js";
 import { Embedder, selectBackend } from "./embedder.js";
 import { EmbeddingCache } from "./embedding-cache.js";
-import { Manifest } from "./manifest.js";
+import { Manifest, CURRENT_SCHEMA_VERSION } from "./manifest.js";
 import { loadIgnorePatterns, matchesAny } from "./ignorefile.js";
 import { isSecretFile, redactSecrets } from "./secrets.js";
 import { LocalBackend } from "../storage/local-backend.js";
 import type { Chunk, ChunkType, GraphEdge, GraphNode, NodeType } from "../types.js";
-import { resolveOllamaUrl } from "../config.js";
+import { resolveOllamaUrl, ROOT_ONLY_IGNORE } from "../config.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -159,13 +160,16 @@ function cceignoreMatchesDir(relPosix: string, patterns: string[]): boolean {
  */
 function targetExcluded(
 	relPosix: string,
-	opts: { isDir: boolean; ignoreSet: Set<string>; redactSecrets: boolean; patterns: string[] },
+	opts: { isDir: boolean; ignoreSet: Set<string>; rootIgnoreSet: 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;
 	}
+	// Only the first segment is project-root level; root-only names must not
+	// reject nested paths like `src/storage/x.ts`.
+	if (opts.rootIgnoreSet.has(segments[0]!)) 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;
@@ -187,6 +191,7 @@ function* iterProjectFiles(
 	/** Project root: `.cceignore` patterns are matched against project-relative paths even when walking from a target. */
 	relRoot: string,
 	ignoreSet: Set<string>,
+	rootIgnoreSet: Set<string>,
 	opts: { redactSecrets: boolean; cceignorePatterns: string[] },
 ): Generator<string> {
 	const seen = new Set<string>();
@@ -200,7 +205,10 @@ function* iterProjectFiles(
 		}
 		entries.sort((a, b) => a.name.localeCompare(b.name));
 		for (const entry of entries) {
-			if (ignoreSet.has(entry.name)) continue;
+			// Root-only names (`storage`, `logs`, ...) only match at the project
+			// root — nested `src/storage/` is real source and must be indexed.
+			const atProjectRoot = directory === relRoot;
+			if (ignoreSet.has(entry.name) || (atProjectRoot && rootIgnoreSet.has(entry.name))) continue;
 			const full = path.join(directory, entry.name);
 			if (entry.isSymbolicLink()) continue;
 			let resolved: string;
@@ -411,12 +419,29 @@ async function runIndexingLocked(
 		cacheMisses: 0,
 	};
 
+	// PR #7 review fix: migrations below call manifest.clearEntries(), which
+	// also erases the file list pruneFilesNotIn() needs to detect files that
+	// vanished BEFORE this run. Snapshot the paths first so the prune step
+	// can still delete their indexed chunks instead of orphaning them.
+	const preMigrationPaths = Object.keys(manifest.fileEntries);
+
 	if (backend.metricRebuilt) {
 		manifest.clearEntries();
 		log?.("  [migration] vector index rebuilt (cosine metric) — reindexing all files");
 	}
 
+	// Index-format migrations (e.g. v3 added R1 context headers) change how
+	// chunk content is built WITHOUT changing the file on disk, so the content
+	// hash alone would leave a stale, header-less index behind forever.
+	if (manifest.schemaVersion !== CURRENT_SCHEMA_VERSION) {
+		log?.(
+			`  [migration] index format v${manifest.schemaVersion} → v${CURRENT_SCHEMA_VERSION} — reindexing all files`,
+		);
+		manifest.clearEntries();
+	}
+
 	const ignoreSet = new Set(config.indexerIgnore);
+	const rootIgnoreSet = new Set(ROOT_ONLY_IGNORE);
 	const cceignorePatterns = loadIgnorePatterns(projectDir);
 	if (cceignorePatterns.length > 0) log?.(`  [.cceignore] ${cceignorePatterns.length} pattern(s) loaded`);
 
@@ -449,6 +474,7 @@ async function runIndexingLocked(
 				targetExcluded(rel, {
 					isDir: false,
 					ignoreSet,
+					rootIgnoreSet,
 					redactSecrets: config.indexerRedactSecrets,
 					patterns: cceignorePatterns,
 				})
@@ -471,6 +497,7 @@ async function runIndexingLocked(
 			const excluded = targetExcluded(rel, {
 				isDir: true,
 				ignoreSet,
+				rootIgnoreSet,
 				redactSecrets: config.indexerRedactSecrets,
 				patterns: cceignorePatterns,
 			});
@@ -479,7 +506,7 @@ async function runIndexingLocked(
 				fileList = [];
 			} else {
 				fileList = [
-					...iterProjectFiles(target, projectDir, ignoreSet, {
+					...iterProjectFiles(target, projectDir, ignoreSet, rootIgnoreSet, {
 						redactSecrets: config.indexerRedactSecrets,
 						cceignorePatterns,
 					}),
@@ -507,7 +534,7 @@ async function runIndexingLocked(
 		}
 	} else {
 		fileList = [
-			...iterProjectFiles(projectDir, projectDir, ignoreSet, {
+			...iterProjectFiles(projectDir, projectDir, ignoreSet, rootIgnoreSet, {
 				redactSecrets: config.indexerRedactSecrets,
 				cceignorePatterns,
 			}),
@@ -522,6 +549,18 @@ async function runIndexingLocked(
 	}
 	if (languages.size > 0) await warmupLanguages(languages);
 
+	// R7: every rel path this run touches (changed or not) plus everything
+	// already indexed forms the resolution universe for import specifiers.
+	const knownFiles = new Set<string>(Object.keys(manifest.fileEntries));
+	for (const f of fileList) knownFiles.add(path.relative(projectDir, f).replace(/\\/g, "/"));
+	// R7: cross-file call-graph state, filled during the batch loop, emitted
+	// as chunk-to-chunk `calls` edges after ALL batches (so early files can
+	// call symbols defined in late ones — order-independent).
+	const runChunks: { id: string; filePath: string; identifiers: string[] }[] = [];
+	const symbolOwners = new Map<string, { id: string; filePath: string }[]>();
+	// PR #7 review: files whose chunks were (re)built this run, across ALL batches.
+	const changedRelPaths = new Set<string>();
+
 	// ── Lazy embedder + cache ─────────────────────────────────────────────
 	const holders: { embedder: Embedder | null; cache: EmbeddingCache | null } = {
 		embedder: runtime?.embedder ?? null,
@@ -603,13 +642,19 @@ async function runIndexingLocked(
 		const batchIndexed: string[] = [];
 
 		for (const item of toChunk) {
+			changedRelPaths.add(item.relPath);
 			let chunks: Chunk[] = [];
 			let importedModules: string[] = [];
+			let importSpecs: string[] = [];
 			try {
 				if (isAstLanguage(item.language)) {
-					const out = chunker.chunkWithImports(item.content, item.relPath, item.language);
+					const out = chunker.chunkWithImports(item.content, item.relPath, item.language, {
+							chunking: config.indexerChunking,
+							budgetChars: config.indexerChunkBudgetChars,
+						});
 					chunks = out.chunks;
 					importedModules = out.imports;
+					importSpecs = out.importSpecs;
 				}
 				if (chunks.length === 0) {
 					// Fallback: module-level chunk (upstream _fallback_chunk).
@@ -652,18 +697,27 @@ async function runIndexingLocked(
 				filePath: item.relPath,
 				properties: {},
 			});
-			for (const module of importedModules) {
-				batchEdges.push({
-					sourceId: fileNodeId,
-					targetId: `module_${module}`,
-					edgeType: "imports",
-					properties: {},
-				});
+			for (const spec of importSpecs) {
+				// R7: resolve relative specifiers to a real indexed file. Before this,
+				// edges pointed at `module_<spec>` nodes that were never created, so
+				// every imports-edge JOIN silently produced nothing and
+				// related_context / getRelatedFilePaths were dead code. Bare package
+				// imports ("react", "node:fs") stay out: they resolve to nothing in
+				// the index and would only add noise.
+				const resolved = resolveImportPath(spec, item.relPath, knownFiles);
+				if (resolved) {
+					batchEdges.push({
+						sourceId: fileNodeId,
+						targetId: `file_${resolved}`,
+						edgeType: "imports",
+						properties: {},
+					});
+				}
 			}
 			for (const chunk of chunks) {
-				const nodeName = chunk.content.includes("(")
-					? chunk.content.split("(")[0]!.split(":").pop()!.trim()
-					: chunk.id;
+				const nodeName =
+					(typeof chunk.metadata["unit"] === "string" && chunk.metadata["unit"]) ||
+					(chunk.content.includes("(") ? chunk.content.split("(")[0]!.split(":").pop()!.trim() : chunk.id);
 				batchNodes.push({
 					id: chunk.id,
 					nodeType: CHUNK_TO_NODE_TYPE[chunk.chunkType] ?? "module",
@@ -677,6 +731,31 @@ async function runIndexingLocked(
 					edgeType: "defines",
 					properties: {},
 				});
+				// R7 calls-graph collection (raw content, before the context header
+				// prepends file paths and `defines:` lists that would pollute the
+				// identifier set).
+				const unit = typeof chunk.metadata["unit"] === "string" ? chunk.metadata["unit"] : "";
+				if (chunk.chunkType === "function" || chunk.chunkType === "class") {
+					const short = unit.includes(".") ? unit.slice(unit.lastIndexOf(".") + 1) : unit;
+					if (short.length >= 3 && !CALL_GRAPH_STOPLIST.has(short)) {
+						let owners = symbolOwners.get(short);
+						if (!owners) symbolOwners.set(short, (owners = []));
+						owners.push({ id: chunk.id, filePath: item.relPath });
+					}
+				}
+				if (chunk.chunkType !== "module") {
+					runChunks.push({
+						id: chunk.id,
+						filePath: item.relPath,
+						identifiers: extractIdentifiers(chunk.content),
+					});
+				}
+			}
+			// R1 context headers go on LAST: graph node names above derive from raw
+			// content, and every downstream consumer (embed, FTS, compression,
+			// expand_chunk) reads `chunk.content`, so one prepend covers them all.
+			if (config.indexerContextHeaders) {
+				for (const chunk of chunks) applyContextHeaderToChunk(chunk, importedModules);
 			}
 			batchChunks.push(...chunks);
 			batchManifestUpdates.push([item.relPath, item.contentHash]);
@@ -709,6 +788,64 @@ async function runIndexingLocked(
 		result.skippedFiles.push(...toChunk.filter((t) => !batchIndexed.includes(t.relPath)).map((t) => t.relPath));
 	}
 
+	// ── R7: emit chunk→chunk calls edges ──────────────────────────────────
+	// Runs AFTER all batches so the symbol table is complete regardless of
+	// batch order. Cross-file only: intra-file structure is already covered
+	// by file/defines edges. Capped per chunk — a retrieval prior, not a
+	// faithful call graph.
+	{
+		// PR #7 review fix (incremental call graph): derive over ALL indexed
+		// files, not just this run's changes. deleteByFiles(changed) removes
+		// call edges touching changed chunk nodes in BOTH directions, so a
+		// run-only derivation silently dropped (a) changed files' calls into
+		// unchanged files and (b) unchanged callers' edges into changed files.
+		// Re-deriving from every indexed file recreates exactly the deleted
+		// edges; unchanged→unchanged duplicates collapse on the edge PK
+		// (INSERT OR REPLACE).
+		const callsEdges: GraphEdge[] = [];
+		const derivationSources = [...runChunks];
+		const changedThisRun = changedRelPaths;
+		for (const rel of Object.keys(manifest.fileEntries)) {
+			if (changedThisRun.has(rel)) continue;
+			for (const stored of backend.chunksByFile(rel, 500)) {
+				if (stored.chunkType === "module") continue;
+				derivationSources.push({
+					id: stored.id,
+					filePath: rel,
+					// Stored content carries the R1 context header; strip it so
+					// header tokens cannot pollute the identifier set.
+					identifiers: extractIdentifiers(stripContextHeader(stored.content)),
+				});
+			}
+		}
+		// Symbol owners over all files: run chunks first (fresh), then graph
+		// nodes of files that did not change (they are still valid).
+		for (const node of backend.listSymbolNodes()) {
+			if (changedThisRun.has(node.filePath)) continue;
+			const short = node.name.includes(".") ? node.name.slice(node.name.lastIndexOf(".") + 1) : node.name;
+			if (short.length < 3 || CALL_GRAPH_STOPLIST.has(short)) continue;
+			let owners = symbolOwners.get(short);
+			if (!owners) symbolOwners.set(short, (owners = []));
+			owners.push({ id: node.id, filePath: node.filePath });
+		}
+		for (const src of derivationSources) {
+			let out = 0;
+			for (const ident of src.identifiers) {
+				if (out >= CALLS_EDGES_PER_CHUNK) break;
+				for (const owner of symbolOwners.get(ident) ?? []) {
+					if (owner.filePath === src.filePath) continue;
+					callsEdges.push({ sourceId: src.id, targetId: owner.id, edgeType: "calls", properties: {} });
+					out += 1;
+					if (out >= CALLS_EDGES_PER_CHUNK) break;
+				}
+			}
+		}
+		if (callsEdges.length > 0) {
+				backend.ingest([], [], callsEdges);
+				log?.(`  [graph] ${callsEdges.length} cross-file call edge(s)`);
+			}
+	}
+
 	// ── Git history on full runs ──────────────────────────────────────────
 	if (full && !targetPath && fs.existsSync(path.join(projectDir, ".git"))) {
 		try {
@@ -731,7 +868,7 @@ async function runIndexingLocked(
 
 	// ── Prune files that vanished from disk ───────────────────────────────
 	if (!targetPath) {
-		const previousPaths = new Set(Object.keys(manifest.fileEntries));
+		const previousPaths = new Set([...Object.keys(manifest.fileEntries), ...preMigrationPaths]);
 		const removed = [...previousPaths].filter((rel) => !currentRelPaths.has(rel));
 		if (removed.length > 0) {
 			backend.deleteByFiles(removed);
@@ -767,3 +904,71 @@ function cceignoreMatchesFile(relPosix: string, patterns: string[]): boolean {
 	}
 	return false;
 }
+
+// ── R7 helpers: import resolution + call-graph vocabulary ─────────────────
+
+/** Cap per chunk for calls edges: a prior, not a faithful call graph. */
+const CALLS_EDGES_PER_CHUNK = 8;
+/** Max unique identifiers kept per chunk (first occurrences win). */
+const IDENTIFIERS_PER_CHUNK = 60;
+
+/** Words that name a chunk never worth a calls edge. */
+const CALL_GRAPH_STOPLIST = new Set([
+	"const", "let", "var", "function", "class", "return", "string", "number", "boolean", "object",
+	"void", "null", "undefined", "true", "false", "this", "import", "export", "default", "type",
+	"interface", "extends", "implements", "constructor", "static", "readonly", "public", "private",
+	"protected", "async", "await", "Promise", "Object", "Array", "String", "Number", "Boolean",
+	"Math", "JSON", "Error", "console", "process", "require", "module", "exports", "Map", "Set",
+	"Date", "Symbol", "Buffer", "path", "fs", "os", "unknown", "never", "text", "params", "options",
+	"value", "values", "result", "results", "data", "content", "item", "items", "name", "file", "files",
+	"line", "lines", "index", "length", "score", "query", "chunk", "chunks",
+]);
+
+/** Unique identifier-ish words in a chunk, capped (first occurrences win). */
+function extractIdentifiers(content: string): string[] {
+	const seen = new Set<string>();
+	const re = /[A-Za-z_$][A-Za-z0-9_$]*/g;
+	let m: RegExpExecArray | null;
+	while ((m = re.exec(content)) !== null && seen.size < IDENTIFIERS_PER_CHUNK) {
+		const w = m[0];
+		if (w.length >= 3 && !CALL_GRAPH_STOPLIST.has(w)) seen.add(w);
+	}
+	return [...seen];
+}
+
+/**
+ * Resolve a relative import specifier against the set of indexed files.
+ * Handles extensionless specs ("./chunker"), .js to .ts rewrites (TypeScript
+ * emits .js specifiers), and directory index files. Returns null for bare
+ * package imports and unresolvable specs.
+ */
+function resolveImportPath(spec: string, importerRel: string, knownFiles: Set<string>): string | null {
+	if (!spec.startsWith(".") && !spec.startsWith("/")) return null;
+	const dir = importerRel.includes("/") ? importerRel.slice(0, importerRel.lastIndexOf("/")) : "";
+	const joined = spec.startsWith("/") ? spec.slice(1) : `${dir}/${spec}`;
+	const stack = joined.split("/");
+	const outStack: string[] = [];
+	for (const part of stack) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") outStack.pop();
+		else outStack.push(part);
+	}
+	const base = outStack.join("/");
+	if (base === "") return null;
+	const candidates = [base];
+	const lower = base.toLowerCase();
+	if (lower.endsWith(".js")) {
+		candidates.push(base.slice(0, -3) + ".ts", base.slice(0, -3) + ".tsx");
+	} else if (lower.endsWith(".mjs") || lower.endsWith(".cjs")) {
+		candidates.push(base.slice(0, -4) + ".ts");
+	} else if (!/\.[a-z]+$/i.test(base)) {
+		candidates.push(base + ".ts", base + ".tsx", base + ".mts", base + ".js");
+	}
+	for (const c of candidates) {
+		if (knownFiles.has(c)) return c;
+	}
+	for (const ext of ["/index.ts", "/index.tsx", "/index.js"]) {
+		if (knownFiles.has(base + ext)) return base + ext;
+	}
+	return null;
+}

package/src/memory/db.ts

@@ -11,7 +11,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. */
@@ -170,6 +170,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;
@@ -210,6 +224,8 @@ export class MemoryDb {
 					this.db.exec(VEC_TRIGGERS);
 				}
 				this.db.exec(SCHEMA_V3);
+				this.applyV4Columns();
+				this.db.exec(SCHEMA_V4);
 				this.db
 					.prepare("INSERT INTO schema_versions (version, applied_at_epoch) VALUES (?, ?)")
 					.run(this.hasVec ? CURRENT_VERSION : 1, epochSeconds());
@@ -225,6 +241,10 @@ export class MemoryDb {
 				this.db.exec(VEC_TRIGGERS);
 			}
 			if (current < 3) this.db.exec(SCHEMA_V3);
+			if (current < 4) {
+				this.applyV4Columns();
+				this.db.exec(SCHEMA_V4);
+			}
 			if (current < 2 && !this.hasVec) return; // vec step still pending
 			this.db
 				.prepare("INSERT INTO schema_versions (version, applied_at_epoch) VALUES (?, ?)")
@@ -233,6 +253,113 @@ export class MemoryDb {
 		run();
 	}
 
+	/** v4 adds `decisions.tags` / `decisions.files` (JSON arrays); ALTER is 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;
+}