pi-plans 0.2.0 → 0.3.0

package/src/code-graph/store.ts

@@ -0,0 +1,278 @@
+/**
+ * SQLite handle, prepared statements and BEGIN IMMEDIATE write transactions
+ * for the code-graph module.
+ */
+
+import type { DatabaseSync, StatementSync } from "node:sqlite";
+import { CURRENT_SCHEMA_VERSION, FUNCTION_RECORDS_VIEW, SCHEMA_STATEMENTS } from "./schema.ts";
+import { PathError } from "./paths.ts";
+import type { CodeGraphSnapshot, GraphMeta } from "./types.ts";
+
+export interface StoreOptions {
+	dbPath: string;
+	worktreeRoot: string;
+	gitCommonDir: string;
+	parserVersions?: Record<string, string>;
+	readonly?: boolean;
+}
+
+export class Store {
+	readonly db: DatabaseSync;
+	readonly dbPath: string;
+	readonly worktreeRoot: string;
+	readonly gitCommonDir: string;
+
+	private prepared: Map<string, StatementSync> = new Map();
+	private readonly mode: "rw" | "ro";
+
+	constructor(opts: StoreOptions, sqlite: typeof import("node:sqlite")) {
+		this.dbPath = opts.dbPath;
+		this.worktreeRoot = opts.worktreeRoot;
+		this.gitCommonDir = opts.gitCommonDir;
+		this.mode = opts.readonly ? "ro" : "rw";
+		this.db = new sqlite.DatabaseSync(opts.dbPath, {
+			open: true,
+			readOnly: opts.readonly === true,
+			enableForeignKeyConstraints: true,
+		});
+		this.bootstrap(opts);
+	}
+
+	private bootstrap(opts: StoreOptions): void {
+		this.db.exec("PRAGMA foreign_keys = ON");
+		this.db.exec("PRAGMA journal_mode = WAL");
+		this.db.exec("PRAGMA busy_timeout = 5000");
+		const existing = this.db
+			.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='graph_meta'")
+			.get();
+		if (!existing) {
+			this.applyMigrations();
+			this.upsertMeta({
+				schemaVersion: CURRENT_SCHEMA_VERSION,
+				worktreeRoot: opts.worktreeRoot,
+				gitCommonDir: opts.gitCommonDir,
+				parserVersions: opts.parserVersions ?? {},
+				updatedAt: new Date().toISOString(),
+			});
+			return;
+		}
+		const row = this.db.prepare("SELECT MAX(schema_version) AS v FROM graph_meta").get() as { v: number } | undefined;
+		const version = row?.v ?? 0;
+		if (version < CURRENT_SCHEMA_VERSION) {
+			this.applyIncrementalMigrations(version, opts);
+			this.upsertMeta({
+				schemaVersion: CURRENT_SCHEMA_VERSION,
+				worktreeRoot: opts.worktreeRoot,
+				gitCommonDir: opts.gitCommonDir,
+				parserVersions: opts.parserVersions ?? {},
+				updatedAt: new Date().toISOString(),
+			});
+		}
+	}
+
+	/** Step-level idempotent incremental migration: each step checks its target
+	 *  artifact (PRAGMA table_info / sqlite_master) before applying, so a crash
+	 *  mid-upgrade can be safely re-entered. schema_version advances only after
+	 *  all steps complete. */
+	private applyIncrementalMigrations(fromVersion: number, opts: StoreOptions): void {
+		this.tx(() => {
+			if (fromVersion < 2) {
+				const snapshotTable = this.db
+					.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='code_graph_snapshot'")
+					.get();
+				if (!snapshotTable) {
+					this.db.exec(
+						`CREATE TABLE code_graph_snapshot (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						head_commit TEXT NOT NULL,
+						uncommitted_paths TEXT NOT NULL,
+						recorded_at TEXT NOT NULL
+					)`,
+					);
+				}
+				const columns = this.db.prepare("PRAGMA table_info(files)").all() as Array<{ name: string }>;
+				if (!columns.some((column) => column.name === "pending_kind")) {
+					this.db.exec("ALTER TABLE files ADD COLUMN pending_kind TEXT");
+				}
+				const initialSnapshot = this.db
+					.prepare("SELECT COUNT(*) AS c FROM code_graph_snapshot")
+					.get() as { c: number };
+				if (initialSnapshot.c === 0) {
+					this.db
+						.prepare(
+							`INSERT INTO code_graph_snapshot (head_commit, uncommitted_paths, recorded_at)
+							 VALUES (?, ?, ?)`,
+						)
+						.run("", "[]", new Date().toISOString());
+				}
+			}
+			void opts;
+		});
+	}
+
+	private applyMigrations(): void {
+		for (const stmt of SCHEMA_STATEMENTS) this.db.exec(stmt);
+		this.db.exec(FUNCTION_RECORDS_VIEW);
+		this.db
+			.prepare(
+				`INSERT INTO graph_meta (schema_version, worktree_root, git_common_dir, parser_versions, updated_at)
+				 VALUES (?, ?, ?, ?, ?)
+				 ON CONFLICT(schema_version) DO UPDATE SET
+					worktree_root = excluded.worktree_root,
+					git_common_dir = excluded.git_common_dir,
+					parser_versions = excluded.parser_versions,
+					updated_at = excluded.updated_at`,
+			)
+			.run(
+				CURRENT_SCHEMA_VERSION,
+				this.worktreeRoot,
+				this.gitCommonDir,
+				JSON.stringify({}),
+				new Date().toISOString(),
+			);
+	}
+
+	upsertMeta(meta: GraphMeta): void {
+		this.db
+			.prepare(
+				`INSERT INTO graph_meta (schema_version, worktree_root, git_common_dir, parser_versions, updated_at)
+				 VALUES (?, ?, ?, ?, ?)
+				 ON CONFLICT(schema_version) DO UPDATE SET
+					worktree_root = excluded.worktree_root,
+					git_common_dir = excluded.git_common_dir,
+					parser_versions = excluded.parser_versions,
+					updated_at = excluded.updated_at`,
+			)
+			.run(
+				meta.schemaVersion,
+				meta.worktreeRoot,
+				meta.gitCommonDir,
+				JSON.stringify(meta.parserVersions),
+				meta.updatedAt,
+			);
+	}
+
+	upsertSnapshot(headCommit: string, uncommittedPaths: string[]): void {
+		this.tx(() => {
+			this.db
+				.prepare(
+					`INSERT INTO code_graph_snapshot (head_commit, uncommitted_paths, recorded_at)
+					 VALUES (?, ?, ?)`,
+				)
+				.run(headCommit, JSON.stringify(uncommittedPaths), new Date().toISOString());
+		});
+	}
+
+	readLatestSnapshot(): CodeGraphSnapshot | null {
+		const row = this.db
+			.prepare(
+					`SELECT id, head_commit, uncommitted_paths, recorded_at
+				 FROM code_graph_snapshot ORDER BY id DESC LIMIT 1`,
+			)
+			.get() as
+			| { id: number; head_commit: string; uncommitted_paths: string; recorded_at: string }
+			| undefined;
+		if (!row) return null;
+		return {
+			id: row.id,
+			headCommit: row.head_commit,
+			uncommittedPaths: JSON.parse(row.uncommitted_paths) as string[],
+			recordedAt: row.recorded_at,
+		};
+	}
+
+	readMeta(): GraphMeta | null {
+		const row = this.db
+			.prepare(
+				`SELECT schema_version, worktree_root, git_common_dir, parser_versions, updated_at
+				 FROM graph_meta ORDER BY schema_version DESC LIMIT 1`,
+			)
+			.get() as {
+			schema_version: number;
+			worktree_root: string;
+			git_common_dir: string;
+			parser_versions: string;
+			updated_at: string;
+		} | undefined;
+		if (!row) return null;
+		return {
+			schemaVersion: row.schema_version,
+			worktreeRoot: row.worktree_root,
+			gitCommonDir: row.git_common_dir,
+			parserVersions: JSON.parse(row.parser_versions) as Record<string, string>,
+			updatedAt: row.updated_at,
+		};
+	}
+
+	checkWorktree(currentWorktreeRoot: string, currentGitCommonDir: string): void {
+		const meta = this.readMeta();
+		if (!meta) return;
+		if (meta.worktreeRoot !== currentWorktreeRoot || meta.gitCommonDir !== currentGitCommonDir) {
+			throw new PathError(
+				`code_graph.db belongs to ${meta.worktreeRoot} (${meta.gitCommonDir}); current worktree is ${currentWorktreeRoot} (${currentGitCommonDir}). Refusing to share the DB across worktrees.`,
+			);
+		}
+	}
+
+	/** Run a function inside a write transaction. Uses BEGIN IMMEDIATE so that
+	 * reads cannot later upgrade to writes and bypass busy timeouts. */
+	tx<T>(fn: () => T): T {
+		if (this.mode === "ro") throw new Error("store is opened read-only; cannot begin a write transaction");
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const result = fn();
+			this.db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				this.db.exec("ROLLBACK");
+			} catch {
+				/* rollback failure is non-fatal after a write error */
+			}
+			throw error;
+		}
+	}
+
+	read<T>(fn: () => T): T {
+		this.db.exec("BEGIN");
+		try {
+			const result = fn();
+			this.db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				this.db.exec("ROLLBACK");
+			} catch {
+				/* ignore */
+			}
+			throw error;
+		}
+	}
+
+	prepare(key: string, sql: string): StatementSync {
+		let stmt = this.prepared.get(key);
+		if (!stmt) {
+			stmt = this.db.prepare(sql);
+			this.prepared.set(key, stmt);
+		}
+		return stmt;
+	}
+
+	close(): void {
+		try {
+			this.db.close();
+		} catch {
+			/* best effort */
+		}
+	}
+
+	exists(): boolean {
+		return true;
+	}
+}
+
+/** Helper for tests: run a function inside a fresh in-memory store. */
+export async function openStore(opts: StoreOptions): Promise<Store> {
+	const sqlite = await import("node:sqlite");
+	return new Store(opts, sqlite);
+}

package/src/code-graph/summary.ts

@@ -0,0 +1,435 @@
+/**
+ * LLM screening pipeline for code-graph. Records explicit consent and
+ * gracefully degrades to pending/declined summaries when the host has no UI
+ * or no model.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { hashText } from "./parser.ts";
+import { Store } from "./store.ts";
+import type { FunctionRecord, SummaryRecord } from "./types.ts";
+
+export interface CompletionRequest {
+	messages: Array<{ role: "user"; content: string }>;
+}
+
+export interface CompletionHandle {
+	complete: (request: CompletionRequest) => Promise<{
+		content: Array<{ type: "text"; text: string }>;
+		stopReason?: string;
+	}>;
+	model?: () => { provider?: string; id?: string; api?: string; reasoning?: boolean };
+	thinkingLevel?: () => string | undefined;
+	hasUI?: boolean;
+	confirm?: (title: string, body: string) => Promise<boolean>;
+	notify?: (message: string, kind?: "info" | "warning" | "error") => void;
+}
+
+export interface SummaryOptions {
+	store: Store;
+	ctx: CompletionHandle;
+	batchTokens?: number;
+	skipConsent?: boolean;
+}
+
+export interface SummaryReport {
+	processed: number;
+	ok: number;
+	failed: number;
+	declined: number;
+	batches: number;
+}
+
+const SUMMARY_SCHEMA = {
+	type: "object",
+	properties: {
+		description: { type: "string", maxLength: 280 },
+		inputs: { type: "array", items: { type: "string", maxLength: 80 }, maxItems: 8 },
+		outputs: { type: "array", items: { type: "string", maxLength: 80 }, maxItems: 8 },
+	},
+	required: ["description", "inputs", "outputs"],
+	additionalProperties: false,
+} as const;
+
+/** Conservative default prompt budget per completion call. Provider token
+ * counts vary; character-based estimates here intentionally bias low so the
+ * system cannot exceed typical context windows even with prompt overhead. */
+const DEFAULT_BATCH_TOKENS = 8_000;
+/** Characters-per-token ratio used for the conservative estimate. */
+const CHARS_PER_TOKEN = 4;
+/** Per-entry overhead added to the estimate (path, name, separator). */
+const PER_ENTRY_OVERHEAD_TOKENS = 32;
+/** Maximum allowed characters for a persisted `summary_error` value. */
+const SUMMARY_ERROR_MAX_LENGTH = 240;
+
+const SYSTEM_PROMPT = `You summarize code functions in structured JSON. Each input block starts with a "ref:" line. For each input return exactly one JSON object matching {ref: string, description: string, inputs: string[], outputs: string[]} where ref is the exact ref line value copied verbatim, description <= 280 chars, and arrays of short strings (<= 80 chars, <= 8 entries). Do not include any explanation or additional fields. Output one JSON object per input.`;
+
+/** Opaque alignment key echoed back by the model. Built in ONE place so
+ * prompt, alignment, and DB writes can never disagree. */
+export function buildRef(fileDir: string, fileName: string, functionName: string): string {
+	return `${fileDir}/${fileName}::${functionName}`;
+}
+
+export interface PendingSummary {
+	fileDir: string;
+	fileName: string;
+	functionName: string;
+	fullCodeHash: string;
+	language: string;
+	fullCode: string;
+}
+
+export function pendingFunctions(store: Store): PendingSummary[] {
+	const rows = store
+		.read(() =>
+			store.db
+				.prepare(
+					`SELECT file_dir, file_name, function_name, full_code_hash, language, full_code
+					 FROM functions
+					 WHERE summary_status IS NULL OR summary_status = 'pending' OR summary_status = 'failed'`,
+				)
+				.all(),
+		) as Array<{ file_dir: string; file_name: string; function_name: string; full_code_hash: string; language: string; full_code: string }>;
+	return rows.map((row) => ({
+		fileDir: row.file_dir,
+		fileName: row.file_name,
+		functionName: row.function_name,
+		fullCodeHash: row.full_code_hash,
+		language: row.language,
+		fullCode: row.full_code,
+	}));
+}
+
+function cacheKey(input: PendingSummary): string {
+	return `${input.language}:${input.fullCodeHash}`;
+}
+
+interface CacheEntry {
+	summary: SummaryRecord;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+function boundedLength(value: string, max: number): string {
+	return value.length > max ? value.slice(0, max) : value;
+}
+
+function boundedErrorMessage(message: string): string {
+	const trimmed = message.replace(/[\r\n\t]+/g, " ").trim();
+	return boundedLength(trimmed, SUMMARY_ERROR_MAX_LENGTH);
+}
+
+function estimateEntryTokens(entry: PendingSummary): number {
+	const header = `${entry.fileDir}/${entry.fileName}::${entry.functionName}\n`;
+	const chars = header.length + entry.fullCode.length;
+	return Math.ceil(chars / CHARS_PER_TOKEN) + PER_ENTRY_OVERHEAD_TOKENS;
+}
+
+/** Greedy, deterministic batch builder. Each batch keeps a running token
+ * estimate; an entry that does not fit becomes the start of the next batch.
+ * A single oversized entry still forms its own batch (no batching progress
+ * must silently drop or split an entry). */
+export function buildBatches(pending: PendingSummary[], batchTokens: number): PendingSummary[][] {
+	const limit = Math.max(1, batchTokens | 0);
+	const batches: PendingSummary[][] = [];
+	let current: PendingSummary[] = [];
+	let currentTokens = 0;
+	for (const entry of pending) {
+		const entryTokens = estimateEntryTokens(entry);
+		if (current.length === 0) {
+			current = [entry];
+			currentTokens = entryTokens;
+			continue;
+		}
+		if (currentTokens + entryTokens <= limit) {
+			current.push(entry);
+			currentTokens += entryTokens;
+		} else {
+			batches.push(current);
+			current = [entry];
+			currentTokens = entryTokens;
+		}
+	}
+	if (current.length > 0) batches.push(current);
+	return batches;
+}
+
+function validate(record: unknown): SummaryRecord | null {
+	if (!record || typeof record !== "object") return null;
+	const obj = record as Record<string, unknown>;
+	if (typeof obj.description !== "string") return null;
+	if (!Array.isArray(obj.inputs) || !Array.isArray(obj.outputs)) return null;
+	if (!obj.inputs.every((s) => typeof s === "string")) return null;
+	if (!obj.outputs.every((s) => typeof s === "string")) return null;
+	const description = boundedLength(obj.description, 280);
+	const inputs = (obj.inputs as string[]).slice(0, 8).map((s) => boundedLength(s, 80));
+	const outputs = (obj.outputs as string[]).slice(0, 8).map((s) => boundedLength(s, 80));
+	return {
+		description,
+		inputs,
+		outputs,
+		status: "ok",
+		schemaVersion: 1,
+	};
+}
+
+/** Quote-aware balanced-brace scanner: extracts top-level {...} object
+ *  substrings from raw model output, tolerating pretty-printed objects that
+ *  span lines, multiple objects on one line, and garbage between objects.
+ *  A truncated final object is dropped (never mis-parsed). Strings and
+ *  escapes are skipped so braces inside literals cannot split an object. */
+export function parseSummaryObjects(raw: string): unknown[] {
+	const objects: unknown[] = [];
+	let depth = 0;
+	let start = -1;
+	let inString = false;
+	let escaped = false;
+	for (let i = 0; i < raw.length; i++) {
+		const ch = raw[i]!;
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === '"') inString = false;
+			continue;
+		}
+		if (ch === '"') {
+			inString = true;
+			continue;
+		}
+		if (ch === "{") {
+			if (depth === 0) start = i;
+			depth++;
+		} else if (ch === "}") {
+			if (depth > 0) {
+				depth--;
+				if (depth === 0 && start >= 0) {
+						try {
+							objects.push(JSON.parse(raw.slice(start, i + 1)));
+						} catch {
+							/* malformed object: skip */
+						}
+						start = -1;
+					}
+				}
+			}
+	}
+	return objects;
+}
+
+export interface AlignOutcome {
+	/** Per-input-function resolution, aligned with `updates` order. */
+	aligned: Array<{ entry: PendingSummary; record: unknown } | { entry: PendingSummary; record: null }>;
+	/** true when order fallback was used (zero ref-carrying records, count equal). */
+	orderFallback: boolean;
+}
+
+/** Align parsed records back to batch functions by their echoed `ref`.
+ *  Duplicates: first wins. Unknown refs are dropped (uncounted). When NO
+ *  record carries a usable ref AND counts match exactly, fall back to order
+ *  alignment (the pre-ref contract) so legacy responses keep working. */
+export function alignByRef(updates: PendingSummary[], records: unknown[]): AlignOutcome {
+	const byRef = new Map<string, unknown>();
+	let refRecords = 0;
+	for (const record of records) {
+		const ref = record && typeof record === "object" && typeof (record as Record<string, unknown>).ref === "string"
+			? (record as Record<string, unknown>).ref
+			: null;
+		if (ref === null) continue;
+		refRecords++;
+		if (!byRef.has(ref)) byRef.set(ref, record);
+	}
+	const orderFallback = refRecords === 0 && records.length === updates.length;
+	const aligned: AlignOutcome["aligned"] = updates.map((entry, index) => {
+		if (orderFallback) return { entry, record: records[index] ?? null };
+		return { entry, record: byRef.get(buildRef(entry.fileDir, entry.fileName, entry.functionName)) ?? null };
+	});
+	return { aligned, orderFallback };
+}
+
+function effectiveEffort(ctx: CompletionHandle): string | undefined {
+	const model = ctx.model?.();
+	if (!model) return undefined;
+	const api = model.api ?? "";
+	if (api.includes("openai-completions") || api.includes("openai-responses") || api.includes("anthropic")) {
+		return "low";
+	}
+	return undefined;
+}
+
+async function userConsent(opts: SummaryOptions, pending: PendingSummary[]): Promise<boolean> {
+	if (opts.skipConsent) return true;
+	if (!opts.ctx.hasUI) return false;
+	if (!opts.ctx.confirm) return false;
+	const model = opts.ctx.model?.();
+	const body = [
+		`Functions awaiting summary: ${pending.length}`,
+		`Model: ${model ? `${model.provider ?? "?"}/${model.id ?? "?"}` : "unknown"}`,
+		`Thinking level: ${opts.ctx.thinkingLevel?.() ?? "default"}`,
+		`Reasoning capability: ${model?.reasoning ? "yes" : "no"}`,
+		`Send source code for each function to the current model?`,
+	].join("\n");
+	return await opts.ctx.confirm("Generate code summaries with LLM?", body);
+}
+
+export async function generateSummaries(opts: SummaryOptions): Promise<SummaryReport> {
+	const pending = pendingFunctions(opts.store);
+	if (pending.length === 0) {
+		return { processed: 0, ok: 0, failed: 0, declined: 0, batches: 0 };
+	}
+	const consent = await userConsent(opts, pending);
+	if (!consent) {
+		markDeclined(opts.store, pending);
+		return { processed: pending.length, ok: 0, failed: 0, declined: pending.length, batches: 0 };
+	}
+	const effort = effectiveEffort(opts.ctx);
+	const batchTokens = opts.batchTokens ?? DEFAULT_BATCH_TOKENS;
+	const batches = buildBatches(pending, batchTokens);
+	const report: SummaryReport = {
+		processed: 0,
+		ok: 0,
+		failed: 0,
+		declined: 0,
+		batches: batches.length,
+	};
+	for (let index = 0; index < batches.length; index++) {
+		const updates = batches[index];
+		opts.ctx.notify?.(
+			`code-graph summary batch ${index + 1}/${batches.length} (${updates.length} function(s))`,
+			"info",
+		);
+		const prompts = updates
+			.map((entry) => `ref: ${buildRef(entry.fileDir, entry.fileName, entry.functionName)}\n${entry.fullCode}`)
+			.join("\n---\n");
+		try {
+			const response = await opts.ctx.complete({
+				messages: [{ role: "user", content: `${SYSTEM_PROMPT}\n\n${prompts}` }],
+			});
+			const texts = response.content
+				.filter((part) => part.type === "text")
+				.map((part) => part.text)
+				.join("\n");
+			const records = parseSummaryObjects(texts);
+			const { aligned, orderFallback } = alignByRef(updates, records);
+			if (orderFallback) {
+				opts.ctx.notify?.("code-graph summary: no refs echoed; aligned by order (legacy response shape)", "info");
+			}
+			const applied = applyAligned(opts.store, aligned, effort);
+			report.processed += applied.processed;
+			report.ok += applied.ok;
+			report.failed += applied.failed;
+		} catch (error) {
+			const message = boundedErrorMessage((error as Error).message || "completion failed");
+			markFailed(opts.store, updates, message);
+			report.processed += updates.length;
+			report.failed += updates.length;
+		}
+	}
+	return report;
+}
+
+function markDeclined(store: Store, pending: PendingSummary[]): void {
+	const stmt = store.prepare(
+		"update_declined",
+		`UPDATE functions SET summary_status = 'declined', summary_updated_at = ?,
+			summary_description = NULL, summary_inputs = NULL, summary_outputs = NULL
+		 WHERE file_dir = ? AND file_name = ? AND function_name = ?`,
+	);
+	store.tx(() => {
+		const now = new Date().toISOString();
+		for (const entry of pending) {
+			stmt.run(now, entry.fileDir, entry.fileName, entry.functionName);
+		}
+	});
+}
+
+function markFailed(store: Store, pending: PendingSummary[], message: string): void {
+	const stmt = store.prepare(
+		"update_failed",
+		`UPDATE functions SET summary_status = 'failed', summary_error = ?, summary_updated_at = ?
+		 WHERE file_dir = ? AND file_name = ? AND function_name = ?`,
+	);
+	const text = boundedErrorMessage(message);
+	store.tx(() => {
+		const now = new Date().toISOString();
+		for (const entry of pending) {
+			stmt.run(text, now, entry.fileDir, entry.fileName, entry.functionName);
+		}
+	});
+}
+
+function applyAligned(
+	store: Store,
+	aligned: AlignOutcome["aligned"],
+	effort: string | undefined,
+): { processed: number; ok: number; failed: number } {
+	const stmt = store.prepare(
+		"update_summary",
+		`UPDATE functions SET
+			summary_description = ?,
+			summary_inputs = ?,
+			summary_outputs = ?,
+			summary_status = ?,
+			summary_model = ?,
+			summary_schema_version = ?,
+			summary_effective_effort = ?,
+			summary_error = NULL,
+			summary_updated_at = ?
+		 WHERE file_dir = ? AND file_name = ? AND function_name = ?`,
+	);
+	const failStmt = store.prepare(
+		"update_failed_single",
+		`UPDATE functions SET summary_status = 'failed', summary_error = ?, summary_updated_at = ?
+		 WHERE file_dir = ? AND file_name = ? AND function_name = ?`,
+	);
+	let ok = 0;
+	let failed = 0;
+	store.tx(() => {
+		const now = new Date().toISOString();
+		for (const slot of aligned) {
+			const validated = slot.record === null ? null : validate(slot.record);
+			if (!validated) {
+				const ref = buildRef(slot.entry.fileDir, slot.entry.fileName, slot.entry.functionName);
+				const reason = slot.record === null
+					? `no aligned summary record for ${ref} (missing/unknown ref or unparseable object)`
+					: `invalid summary fields for ${ref}`;
+				failStmt.run(boundedErrorMessage(reason), now, slot.entry.fileDir, slot.entry.fileName, slot.entry.functionName);
+				failed++;
+				continue;
+			}
+			stmt.run(
+				validated.description,
+				JSON.stringify(validated.inputs),
+				JSON.stringify(validated.outputs),
+				"ok",
+				"(current-model)",
+				1,
+				effort ?? null,
+				now,
+				slot.entry.fileDir,
+				slot.entry.fileName,
+				slot.entry.functionName,
+			);
+			cache.set(cacheKey(slot.entry), { summary: validated });
+			ok++;
+		}
+	});
+	return { processed: aligned.length, ok, failed };
+}
+
+export function clearSummaryCache(): void {
+	cache.clear();
+}
+
+export function summaryCacheStats(): { size: number } {
+	return { size: cache.size };
+}
+
+export { SUMMARY_SCHEMA };
+
+// Minimal smoke: ensures the schema object remains usable as a JSON Schema
+// description for tests and documentation.
+if (process.env.PI_PLANS_GRAPH_DUMP_SCHEMA === "1") {
+	const dumpPath = path.join(fs.realpathSync("."), "code-graph-summary.schema.json");
+	fs.writeFileSync(dumpPath, JSON.stringify(SUMMARY_SCHEMA, null, 2));
+}