pi-plans 0.2.0 → 0.3.0

package/src/code-graph/identity.ts

@@ -0,0 +1,59 @@
+/** Deterministic function identity normalization for a parsed file. */
+
+import type { ParsedFile } from "./parser.ts";
+import type { FunctionRecord, RenderUnit } from "./types.ts";
+
+function spanKey(startByte: number, endByte: number): string {
+	return `${startByte}:${endByte}`;
+}
+
+function finalNames(functions: FunctionRecord[]): Map<string, string> {
+	const counts = new Map<string, number>();
+	const names = new Map<string, string>();
+	for (const fn of functions) {
+		const ordinal = (counts.get(fn.functionName) ?? 0) + 1;
+		counts.set(fn.functionName, ordinal);
+		const name = ordinal === 1 ? fn.functionName : `${fn.functionName}#${ordinal}`;
+		names.set(spanKey(fn.provenance.startByte, fn.provenance.endByte), name);
+	}
+	return names;
+}
+
+function renameUnits(units: RenderUnit[], names: Map<string, string>): RenderUnit[] {
+	return units.map((unit) => ({
+		...unit,
+		label: names.get(spanKey(unit.startByte, unit.endByte)) ?? unit.label,
+		children: unit.children ? renameUnits(unit.children, names) : unit.children,
+	}));
+}
+
+/**
+ * Normalize parser output before calls are resolved or rows are written. The
+ * parser order is structural and deterministic; provenance is only used to
+ * associate an existing render unit with its function record.
+ */
+export function normalizeFunctionIdentities(parsed: ParsedFile): ParsedFile {
+	const names = finalNames(parsed.functions);
+	const functions = parsed.functions.map((fn) => ({
+		...fn,
+		functionName: names.get(spanKey(fn.provenance.startByte, fn.provenance.endByte)) ?? fn.functionName,
+	}));
+	return {
+		...parsed,
+		functions,
+		renderUnits: renameUnits(parsed.renderUnits, names),
+	};
+}
+
+export function assertUniqueFunctionKeys(functions: FunctionRecord[], fileDir: string, fileName: string): void {
+	const seen = new Set<string>();
+	for (const fn of functions) {
+		const key = `${fileDir}\0${fileName}\0${fn.functionName}`;
+		if (seen.has(key)) {
+			throw new Error(
+				`duplicate normalized function identity for ${fileDir}/${fileName}/${fn.functionName} at ${fn.provenance.startByte}`,
+			);
+		}
+		seen.add(key);
+	}
+}

package/src/code-graph/indexer.ts

@@ -0,0 +1,281 @@
+/**
+ * Staged indexing pipeline: discovery → parse → resolve calls → write records
+ * inside a single SQLite write transaction. Each stage produces immutable
+ * snapshots so a parser crash cannot leave the DB in an inconsistent state.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { discoverFiles, type DiscoveredFile } from "./discovery.ts";
+import { Store } from "./store.ts";
+import type { ParserBackend } from "./parser.ts";
+import { hashText } from "./parser.ts";
+import type { Language } from "./types.ts";
+import { resolveCalls, type CallSite } from "./resolver.ts";
+import { assertUniqueFunctionKeys, normalizeFunctionIdentities } from "./identity.ts";
+
+export interface IndexerOptions {
+	store: Store;
+	worktreeRoot: string;
+	parsers: Record<Language, ParserBackend>;
+	reindex?: boolean;
+	/** When provided, only index these POSIX "dir/name" paths; paths that no
+	 *  longer exist on disk are purged from the DB (deletions and rename-old). */
+	paths?: string[];
+}
+
+export interface IndexReport {
+	filesScanned: number;
+	functionsIndexed: number;
+	edgesResolved: number;
+	edgesUnresolved: number;
+	conflicts: number;
+	durationMs: number;
+	reindexedPaths: string[];
+	purgedPaths: string[];
+}
+
+export async function runIndex(opts: IndexerOptions): Promise<IndexReport> {
+	const started = Date.now();
+	const files = discoverFiles({ worktreeRoot: opts.worktreeRoot });
+	const pathFilter = opts.paths ? new Set(opts.paths) : null;
+	if (pathFilter) {
+		for (const requested of pathFilter) {
+			if (!files.some((file) => `${file.fileDir}/${file.fileName}` === requested)) {
+				// Requested path no longer exists on disk (deletion or rename-old):
+				// purge its DB rows inside the same transaction below.
+				files.push({
+					absolutePath: path.join(opts.worktreeRoot, requested),
+					fileDir: requested.slice(0, requested.lastIndexOf("/")) || ".",
+					fileName: requested.slice(requested.lastIndexOf("/") + 1),
+					language: "javascript",
+				}) as DiscoveredFile;
+			}
+		}
+	}
+	const staged: Array<{
+		file: DiscoveredFile;
+		parsed: ReturnType<ParserBackend["parse"]>;
+		calls: CallSite[];
+		sourceText: string;
+		sourceHash: string;
+		exists: boolean;
+	}> = [];
+	let preflightConflict = 0;
+	const existingByFile = new Map<string, { sourceHash: string }>();
+	for (const row of opts.store
+		.read(() => opts.store.db.prepare("SELECT file_dir, file_name, source_hash FROM files").all()) as Array<{
+		file_dir: string;
+		file_name: string;
+		source_hash: string;
+	}>) {
+		existingByFile.set(`${row.file_dir}/${row.file_name}`, { sourceHash: row.source_hash });
+	}
+	for (const file of files) {
+		const relativeKey = `${file.fileDir}/${file.fileName}`;
+		if (pathFilter && !pathFilter.has(relativeKey)) continue;
+		let sourceText: string;
+		let exists = true;
+		try {
+			sourceText = fs.readFileSync(file.absolutePath, "utf8");
+		} catch {
+			if (pathFilter) {
+				// Path was requested but is gone from disk: stage a purge.
+				staged.push({ file, parsed: { functions: [], renderUnits: [] } as ReturnType<ParserBackend["parse"]>, calls: [], sourceText: "", sourceHash: "", exists: false });
+			}
+			continue;
+		}
+		const sourceHash = hashText(sourceText);
+		const backend = opts.parsers[file.language];
+		if (!backend) continue;
+		let parsed = backend.parse(sourceText);
+		parsed = normalizeFunctionIdentities(parsed);
+		parsed.functions.forEach((fn) => {
+			fn.fileDir = file.fileDir;
+			fn.fileName = file.fileName;
+		});
+		assertUniqueFunctionKeys(parsed.functions, file.fileDir, file.fileName);
+		const calls: CallSite[] = [];
+		for (const fn of parsed.functions) {
+			const fromText = fn.fullCode;
+			resolveCalls(fn.functionName, fromText, file, calls);
+		}
+		staged.push({ file, parsed, calls, sourceText, sourceHash, exists: true });
+	}
+	const now = new Date().toISOString();
+	const report: IndexReport = {
+		filesScanned: staged.filter((entry) => entry.exists).length,
+		functionsIndexed: 0,
+		edgesResolved: 0,
+		edgesUnresolved: 0,
+		conflicts: 0,
+		durationMs: 0,
+		reindexedPaths: [],
+		purgedPaths: [],
+	};
+	try {
+		opts.store.tx(() => {
+			for (const { file, parsed, calls, sourceText, sourceHash, exists } of staged) {
+				if (!exists) {
+					opts.store
+						.prepare("delete_functions_purge", `DELETE FROM functions WHERE file_dir = ? AND file_name = ?`)
+						.run(file.fileDir, file.fileName);
+					opts.store
+						.prepare("delete_entries_purge", `DELETE FROM file_entries WHERE file_dir = ? AND file_name = ?`)
+						.run(file.fileDir, file.fileName);
+					opts.store
+						.prepare("delete_edges_purge", `DELETE FROM call_edges WHERE from_file_dir = ? AND from_file_name = ?`)
+						.run(file.fileDir, file.fileName);
+					opts.store
+						.prepare("delete_file_purge", `DELETE FROM files WHERE file_dir = ? AND file_name = ?`)
+						.run(file.fileDir, file.fileName);
+					report.purgedPaths.push(`${file.fileDir}/${file.fileName}`);
+					continue;
+			}
+				report.reindexedPaths.push(`${file.fileDir}/${file.fileName}`);
+				const stmt = opts.store.prepare(
+					"insert_file",
+					`INSERT INTO files (file_dir, file_name, language, source_hash, source_text, updated_at)
+					 VALUES (?, ?, ?, ?, ?, ?)
+					 ON CONFLICT(file_dir, file_name) DO UPDATE SET
+						language = excluded.language,
+						source_hash = excluded.source_hash,
+						source_text = excluded.source_text,
+						updated_at = excluded.updated_at`,
+				);
+				stmt.run(file.fileDir, file.fileName, file.language, sourceHash, sourceText, now);
+				const oldHash = existingByFile.get(`${file.fileDir}/${file.fileName}`)?.sourceHash;
+				if (opts.reindex && oldHash && oldHash !== sourceHash) {
+					opts.store
+						.prepare(
+							"insert_conflict",
+							`INSERT INTO reindex_conflicts (file_dir, file_name, kind, detail, recorded_at)
+							 VALUES (?, ?, ?, ?, ?)`,
+						)
+						.run(file.fileDir, file.fileName, "external-change", `was ${oldHash}, now ${sourceHash}`, now);
+					report.conflicts++;
+				}
+				opts.store
+					.prepare("delete_functions", `DELETE FROM functions WHERE file_dir = ? AND file_name = ?`)
+					.run(file.fileDir, file.fileName);
+				opts.store
+					.prepare("delete_entries", `DELETE FROM file_entries WHERE file_dir = ? AND file_name = ?`)
+					.run(file.fileDir, file.fileName);
+				opts.store
+					.prepare("delete_edges", `DELETE FROM call_edges WHERE from_file_dir = ? AND from_file_name = ?`)
+					.run(file.fileDir, file.fileName);
+				const insertFn = opts.store.prepare(
+					"insert_function",
+					`INSERT INTO functions (
+						file_dir, file_name, function_name, language, kind,
+						full_code, full_code_hash, render_code, render_code_hash,
+						parent, container, move_supported, is_primary, overload_signatures,
+						provenance_start_byte, provenance_end_byte,
+						provenance_start_line, provenance_start_col,
+						provenance_end_line, provenance_end_col,
+						summary_description, summary_inputs, summary_outputs,
+						summary_status, summary_model, summary_schema_version,
+						summary_effective_effort, summary_error, summary_updated_at,
+						version
+					) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+				);
+				for (const fn of parsed.functions) {
+					const summary = fn.summary;
+					insertFn.run(
+						fn.fileDir,
+						fn.fileName,
+						fn.functionName,
+						fn.language,
+						fn.kind,
+						fn.fullCode,
+						fn.fullCodeHash,
+						fn.renderCode,
+						fn.renderCodeHash,
+						fn.parent ?? null,
+						fn.container ?? null,
+						fn.moveSupported ? 1 : 0,
+						fn.isPrimary ? 1 : 0,
+						fn.overloadSignatures ? JSON.stringify(fn.overloadSignatures) : null,
+						fn.provenance.startByte,
+						fn.provenance.endByte,
+						fn.provenance.startLine,
+						fn.provenance.startColumn,
+						fn.provenance.endLine,
+						fn.provenance.endColumn,
+						summary?.description ?? null,
+						summary ? JSON.stringify(summary.inputs) : null,
+						summary ? JSON.stringify(summary.outputs) : null,
+						summary?.status ?? null,
+						summary?.model ?? null,
+						summary?.schemaVersion ?? null,
+						summary?.effectiveEffort ?? null,
+						summary?.errorMessage ?? null,
+						summary?.updatedAt ?? null,
+						fn.version,
+					);
+					report.functionsIndexed++;
+				}
+				let ordinal = 0;
+				const insertEntry = opts.store.prepare(
+					"insert_entry",
+					`INSERT INTO file_entries (file_dir, file_name, ordinal, kind, function_name, start_byte, end_byte, text)
+					 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+				);
+				for (const unit of parsed.renderUnits) {
+					insertEntry.run(
+						file.fileDir,
+						file.fileName,
+						ordinal,
+						unit.kind,
+						unit.label ?? null,
+						unit.startByte,
+						unit.endByte,
+						unit.text ?? "",
+					);
+					ordinal++;
+				}
+				const insertEdge = opts.store.prepare(
+					"insert_edge",
+					`INSERT INTO call_edges (
+						from_file_dir, from_file_name, from_function,
+						to_file_dir, to_file_name, to_function,
+						to_callee_text, kind, resolution, reason,
+						provenance_start_byte, provenance_end_byte,
+						provenance_start_line, provenance_start_col,
+						provenance_end_line, provenance_end_col
+					) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+				);
+				for (const call of calls) {
+					insertEdge.run(
+						file.fileDir,
+						file.fileName,
+						call.fromFunction,
+						call.target?.fileDir ?? null,
+						call.target?.fileName ?? null,
+						call.target?.functionName ?? null,
+						call.calleeText,
+						call.kind,
+						call.resolution,
+						call.reason ?? null,
+						call.provenance.startByte,
+						call.provenance.endByte,
+						call.provenance.startLine,
+						call.provenance.startColumn,
+						call.provenance.endLine,
+						call.provenance.endColumn,
+					);
+					if (call.resolution === "resolved") report.edgesResolved++;
+					else report.edgesUnresolved++;
+				}
+			}
+		});
+	} catch (error) {
+		if (!opts.reindex && staged.length === 0) {
+			preflightConflict++;
+		}
+		throw error;
+	}
+	report.durationMs = Date.now() - started;
+	report.conflicts += preflightConflict;
+	return report;
+}

package/src/code-graph/materialize.ts

@@ -0,0 +1,166 @@
+/**
+ * DB-to-source materialization. `files.source_text` is the canonical content
+ * for every row. Files whose `pending_kind` is set (DB-first mutations) are
+ * applied with convergence semantics: 'update' writes/creates the file;
+ * 'delete' removes the disk file and purges its DB rows. Pending-NULL files
+ * keep the stale-hash guard and are never rewritten from manifest entries —
+ * render-unit texts are not a faithful mirror of the source (empty texts,
+ * overlapping spans), so reassembly from `file_entries` is unsafe.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { Store } from "./store.ts";
+
+export interface MaterializeOptions {
+	store: Store;
+	worktreeRoot: string;
+	force?: boolean;
+}
+
+export interface MaterializeReport {
+	files: Array<{
+		fileDir: string;
+		fileName: string;
+		absolutePath: string;
+		status: "ok" | "stale" | "error" | "deleted" | "skipped-missing";
+		reason?: string;
+	}>;
+}
+
+function loadSourceText(store: Store, fileDir: string, fileName: string): { text: string; hash: string } | null {
+	const row = store
+		.read(() =>
+			store.db
+				.prepare(
+					`SELECT source_text, source_hash FROM files WHERE file_dir = ? AND file_name = ?`,
+				)
+				.get(fileDir, fileName),
+		) as { source_text: string; source_hash: string } | undefined;
+	return row ? { text: row.source_text, hash: row.source_hash } : null;
+}
+
+function hashText(text: string): string {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < text.length; i++) {
+		h ^= text.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+export function materializeFile(
+	store: Store,
+	worktreeRoot: string,
+	fileDir: string,
+	fileName: string,
+	opts: { force?: boolean } = {},
+): { status: "ok" | "stale" | "error" | "deleted" | "skipped-missing"; reason?: string; written?: string } {
+	const file = loadSourceText(store, fileDir, fileName);
+	if (!file) return { status: "error", reason: "file not indexed" };
+	const absolute = path.join(worktreeRoot, fileDir === "." ? fileName : path.join(fileDir, fileName));
+	const pendingKind = store.read(() =>
+		store.db.prepare(`SELECT pending_kind FROM files WHERE file_dir = ? AND file_name = ?`).get(fileDir, fileName),
+	) as { pending_kind: string | null } | undefined;
+	const pending = pendingKind?.pending_kind ?? null;
+
+	if (pending === "delete") {
+		try {
+			if (fs.existsSync(absolute)) fs.rmSync(absolute);
+		} catch (error) {
+			return { status: "error", reason: (error as Error).message };
+		}
+		store.tx(() => {
+			store.db.prepare(`DELETE FROM file_entries WHERE file_dir = ? AND file_name = ?`).run(fileDir, fileName);
+			store.db.prepare(`DELETE FROM call_edges WHERE from_file_dir = ? AND from_file_name = ?`).run(fileDir, fileName);
+			store.db.prepare(`DELETE FROM functions WHERE file_dir = ? AND file_name = ?`).run(fileDir, fileName);
+			store.db.prepare(`DELETE FROM files WHERE file_dir = ? AND file_name = ?`).run(fileDir, fileName);
+		});
+		return { status: "deleted", written: absolute };
+	}
+
+	let currentText: string | null = null;
+	try {
+		currentText = fs.readFileSync(absolute, "utf8");
+	} catch {
+		currentText = null;
+	}
+	if (pending === "update") {
+		// DB-first convergence: files.source_text IS the canonical new content
+		// (mutations maintain it; the loop-end reindex rebuilds the manifest).
+		// Write (or create) regardless of the on-disk hash.
+		const write = writeAtomically(absolute, file.text);
+		if (write.error) return { status: "error", reason: write.error };
+		store.tx(() => {
+			store.db
+				.prepare(`UPDATE files SET pending_kind = NULL, updated_at = ? WHERE file_dir = ? AND file_name = ?`)
+				.run(new Date().toISOString(), fileDir, fileName);
+		});
+		return { status: "ok", written: absolute };
+	}
+	if (currentText === null) {
+		// Pending-NULL and missing on disk: never resurrect deletions.
+		return { status: "skipped-missing", reason: "file missing on disk and not pending; skipped (not resurrected)" };
+	}
+	const currentHash = hashText(currentText);
+	if (currentHash !== file.hash) {
+		if (!opts.force) {
+			return { status: "stale", reason: `current hash ${currentHash} != indexed hash ${file.hash}` };
+		}
+		// Force converge from the canonical DB content, not the manifest.
+		const write = writeAtomically(absolute, file.text);
+		if (write.error) return { status: "error", reason: write.error };
+		return { status: "ok", written: absolute };
+	}
+	// Disk already matches the canonical source_text: nothing to converge.
+	// Never rewrite pending-NULL files from manifest entries — render-unit
+	// texts are empty/overlapping for real indexes, so reassembly corrupts.
+	return { status: "ok" };
+}
+
+function writeAtomically(absolute: string, output: string): { error?: string } {
+	try {
+		fs.mkdirSync(path.dirname(absolute), { recursive: true });
+		const tmp = path.join(os.tmpdir(), `code-graph-apply-${process.pid}-${Date.now()}-${path.basename(absolute)}`);
+		fs.writeFileSync(tmp, output);
+		try {
+			fs.renameSync(tmp, absolute);
+		} catch (error) {
+			try {
+				fs.unlinkSync(tmp);
+			} catch {
+				/* ignore */
+			}
+			return { error: (error as Error).message };
+		}
+		return {};
+	} catch (error) {
+		return { error: (error as Error).message };
+	}
+}
+
+export function materialize(opts: MaterializeOptions): MaterializeReport {
+	const rows = opts.store
+		.read(() =>
+			opts.store.db
+				.prepare(
+					`SELECT file_dir, file_name FROM files ORDER BY file_dir, file_name`,
+				)
+				.all(),
+		) as Array<{ file_dir: string; file_name: string }>;
+	const files: MaterializeReport["files"] = [];
+	for (const row of rows) {
+		const result = materializeFile(opts.store, opts.worktreeRoot, row.file_dir, row.file_name, {
+			force: opts.force === true,
+		});
+		files.push({
+			fileDir: row.file_dir,
+			fileName: row.file_name,
+			absolutePath: path.join(opts.worktreeRoot, row.file_dir === "." ? row.file_name : path.join(row.file_dir, row.file_name)),
+			status: result.status,
+			reason: result.reason,
+		});
+	}
+	return { files };
+}

package/src/code-graph/mode.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared graph-enabled tri-state resolution. Both the graph-aware file-tool
+ * wrappers (tools/) and the execution prompt injection (src/exec.ts) must read
+ * the SAME state through this helper, so the injected guidance and the actual
+ * tool behavior can never diverge.
+ *
+ * Three states, deliberately not a boolean:
+ *   - "enabled"             — graph_enabled === true: wrappers and graph reads active.
+ *   - "off"                 — flag explicitly false/absent: native tools, no markers
+ *                             (the injected prompt already announces the disabled state).
+ *   - "config-unavailable"  — state root missing config or config.json unreadable:
+ *                             treated as an unexpected fallback and surfaced with a
+ *                             marker line (never silently collapsed into "off").
+ */
+
+import { loadConfig, resolveStateRootOrNull } from "../state.ts";
+
+export type GraphMode = "enabled" | "off" | "config-unavailable";
+
+export function resolveGraphMode(workdir: string): GraphMode {
+	const stateRoot = resolveStateRootOrNull(workdir);
+	if (!stateRoot) return "off";
+	try {
+		return loadConfig(stateRoot).graph_enabled === true ? "enabled" : "off";
+	} catch {
+		return "config-unavailable";
+	}
+}

package/src/code-graph/mutations.ts

@@ -0,0 +1,160 @@
+/**
+ * DB-first mutation core for the code_graph tool. Each mutation edits graph
+ * rows, marks the file pending_materialization, and appends to change_log.
+ * /apply-graph later converges the worktree to the DB state.
+ */
+
+import { Store } from "./store.ts";
+import { hashText } from "./parser.ts";
+import type { Language } from "./types.ts";
+
+export interface MutationResult {
+	ok: boolean;
+	reason?: string;
+	updated?: string;
+	pending?: "update" | "delete";
+	created?: boolean;
+}
+
+interface ManifestRow {
+	ordinal: number;
+	start_byte: number;
+	end_byte: number;
+	text: string;
+	function_name: string | null;
+}
+
+function loadManifest(store: Store, fileDir: string, fileName: string): ManifestRow[] {
+	return store.read(() =>
+		store.db
+			.prepare(
+				`SELECT ordinal, start_byte, end_byte, text, function_name FROM file_entries
+				 WHERE file_dir = ? AND file_name = ? ORDER BY ordinal ASC`,
+			)
+			.all(fileDir, fileName),
+	) as ManifestRow[];
+}
+
+export function updateFunction(
+	store: Store,
+	opts: { fileDir: string; fileName: string; functionName: string; fullCode: string },
+): MutationResult {
+	const fnRow = store.read(() =>
+		store.db
+			.prepare(
+				`SELECT provenance_start_byte, provenance_end_byte FROM functions
+				 WHERE file_dir = ? AND file_name = ? AND function_name = ? LIMIT 1`,
+			)
+			.get(opts.fileDir, opts.fileName, opts.functionName),
+	) as { provenance_start_byte: number; provenance_end_byte: number } | undefined;
+	if (!fnRow) return { ok: false, reason: "function not found" };
+
+	// Reads hoisted OUT of the tx: Store.read begins its own transaction.
+	const manifest = loadManifest(store, opts.fileDir, opts.fileName);
+	const fileRow = store.read(() =>
+		store.db.prepare(`SELECT source_text FROM files WHERE file_dir = ? AND file_name = ?`).get(opts.fileDir, opts.fileName),
+	) as { source_text: string } | undefined;
+	const matched = manifest.filter((row) => row.function_name === opts.functionName);
+	if (!fileRow || matched.length === 0) {
+		return {
+			ok: false,
+			reason: !fileRow
+				? "file row missing; run /update-graph first"
+				: "no manifest entry matched the function name (qualified/overload names like name#2 may differ); re-check via code_graph get-function",
+		};
+	}
+
+	const newHash = hashText(opts.fullCode);
+	const first = matched[0]!;
+	// Splice by the function's provenance byte range — the authoritative source
+	// of the callable's extent. Manifest entry texts from the current parser are
+	// empty, so reassembly-by-manifest cannot rebuild function bodies; the range
+	// splice is deterministic and reindex-independent.
+	const start = fnRow.provenance_start_byte;
+	const end = fnRow.provenance_end_byte;
+	const rebuilt = fileRow.source_text.slice(0, start) + opts.fullCode + fileRow.source_text.slice(end);
+	const delta = opts.fullCode.length - (end - start);
+	for (const row of manifest) {
+		if (row.ordinal === first.ordinal) row.text = opts.fullCode;
+		else if (row.start_byte >= end) {
+			// Persist the shift so later reassembly aligns; the loop-end reindex
+			// rebuilds entries authoritatively anyway.
+			row.start_byte += delta;
+			row.end_byte += delta;
+		}
+	}
+	store.tx(() => {
+		store.db
+			.prepare(
+				`UPDATE functions SET full_code = ?, full_code_hash = ?, render_code = ?, render_code_hash = ?
+				 WHERE file_dir = ? AND file_name = ? AND function_name = ?`,
+			)
+			.run(opts.fullCode, newHash, opts.fullCode, newHash, opts.fileDir, opts.fileName, opts.functionName);
+		for (const row of manifest) {
+			store.db
+				.prepare(`UPDATE file_entries SET text = ?, start_byte = ?, end_byte = ? WHERE file_dir = ? AND file_name = ? AND ordinal = ?`)
+				.run(row.text, row.start_byte, row.ordinal === first.ordinal ? row.end_byte + delta : row.end_byte, opts.fileDir, opts.fileName, row.ordinal);
+		}
+		store.db
+			.prepare(`UPDATE files SET source_text = ?, source_hash = ?, pending_kind = 'update', updated_at = ? WHERE file_dir = ? AND file_name = ?`)
+			.run(rebuilt, hashText(rebuilt), new Date().toISOString(), opts.fileDir, opts.fileName);
+		store.db
+			.prepare(`INSERT INTO change_log (kind, detail, recorded_at) VALUES (?, ?, ?)`)
+			.run("update-function", `${opts.fileDir}/${opts.fileName}:${opts.functionName}`, new Date().toISOString());
+	});
+	return { ok: true, updated: `${opts.fileDir}/${opts.fileName}:${opts.functionName}`, pending: "update" };
+}
+
+export function updateFile(
+	store: Store,
+	opts: { fileDir: string; fileName: string; text: string; language?: Language },
+): MutationResult {
+	const exists = store.read(() =>
+		store.db.prepare(`SELECT 1 AS one FROM files WHERE file_dir = ? AND file_name = ?`).get(opts.fileDir, opts.fileName),
+	);
+	const now = new Date().toISOString();
+	store.tx(() => {
+		if (exists) {
+			// Whole-file replace: entries would be stale; drop them so the
+			// materializer falls back to source_text. The loop-end reindex rebuilds.
+			store.db.prepare(`DELETE FROM file_entries WHERE file_dir = ? AND file_name = ?`).run(opts.fileDir, opts.fileName);
+			store.db
+				.prepare(`UPDATE files SET source_text = ?, source_hash = ?, pending_kind = 'update', updated_at = ? WHERE file_dir = ? AND file_name = ?`)
+				.run(opts.text, hashText(opts.text), now, opts.fileDir, opts.fileName);
+		} else {
+			store.db
+				.prepare(
+					`INSERT INTO files (file_dir, file_name, language, source_hash, source_text, pending_kind, updated_at)
+					 VALUES (?, ?, ?, ?, ?, 'update', ?)`,
+				)
+				.run(opts.fileDir, opts.fileName, opts.language ?? "javascript", hashText(opts.text), opts.text, now);
+		}
+		store.db
+			.prepare(`INSERT INTO change_log (kind, detail, recorded_at) VALUES (?, ?, ?)`)
+			.run("update-file", `${opts.fileDir}/${opts.fileName}`, now);
+	});
+	return { ok: true, updated: `${opts.fileDir}/${opts.fileName}`, pending: "update", created: !exists };
+}
+
+export function deleteFile(store: Store, opts: { fileDir: string; fileName: string }): MutationResult {
+	const exists = store.read(() =>
+		store.db.prepare(`SELECT 1 AS one FROM files WHERE file_dir = ? AND file_name = ?`).get(opts.fileDir, opts.fileName),
+	);
+	if (!exists) return { ok: false, reason: "file not indexed" };
+	store.tx(() => {
+		store.db.prepare(`UPDATE files SET pending_kind = 'delete' WHERE file_dir = ? AND file_name = ?`).run(opts.fileDir, opts.fileName);
+		store.db
+			.prepare(`INSERT INTO change_log (kind, detail, recorded_at) VALUES (?, ?, ?)`)
+			.run("delete-file", `${opts.fileDir}/${opts.fileName}`, new Date().toISOString());
+	});
+	return { ok: true, updated: `${opts.fileDir}/${opts.fileName}`, pending: "delete" };
+}
+
+export function listPending(store: Store): Array<{ path: string; kind: string }> {
+	const rows = store.read(() =>
+		store.db
+			.prepare(`SELECT file_dir, file_name, pending_kind FROM files WHERE pending_kind IS NOT NULL ORDER BY file_dir, file_name`)
+			.all(),
+	) as Array<{ file_dir: string; file_name: string; pending_kind: string }>;
+	return rows.map((row) => ({ path: `${row.file_dir}/${row.file_name}`, kind: row.pending_kind }));
+}