@linxiraos/pi-mnemopi 1.0.0

package/src/db.ts

@@ -0,0 +1,186 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { dbPath } from "./config";
+
+export type SqlitePageSize = number | "os";
+
+const MIN_SQLITE_PAGE_SIZE = 512;
+const MAX_SQLITE_PAGE_SIZE = 65536;
+let detectedSystemPageSize: number | null | undefined;
+
+function isValidPageSize(size: number): boolean {
+	return (
+		Number.isInteger(size) &&
+		size >= MIN_SQLITE_PAGE_SIZE &&
+		size <= MAX_SQLITE_PAGE_SIZE &&
+		(size & (size - 1)) === 0
+	);
+}
+
+function detectSystemPageSize(): number | undefined {
+	if (detectedSystemPageSize !== undefined) return detectedSystemPageSize ?? undefined;
+	try {
+		const proc = Bun.spawnSync(["getconf", "PAGE_SIZE"], { stdout: "pipe" });
+		if (proc.exitCode === 0) {
+			const size = Number(proc.stdout.toString().trim());
+			if (isValidPageSize(size)) {
+				detectedSystemPageSize = size;
+				return size;
+			}
+		}
+	} catch {
+		/* fall through */
+	}
+	detectedSystemPageSize = null;
+	return undefined;
+}
+
+function configuredPageSize(): SqlitePageSize | undefined {
+	const raw = process.env.MNEMOPI_DB_PAGE_SIZE?.trim();
+	if (!raw) return undefined;
+	if (raw.toLowerCase() === "os") return "os";
+	const size = Number(raw);
+	return isValidPageSize(size) ? size : undefined;
+}
+
+function resolvePageSize(requested?: SqlitePageSize): number | undefined {
+	const pageSize = requested ?? configuredPageSize();
+	if (pageSize === "os") return detectSystemPageSize();
+	return pageSize !== undefined && isValidPageSize(pageSize) ? pageSize : undefined;
+}
+
+function applyPageSize(db: Database, path: DatabasePath, requested?: SqlitePageSize): void {
+	if (path === ":memory:") return;
+	const pageSize = resolvePageSize(requested);
+	if (pageSize !== undefined) db.exec(`PRAGMA page_size=${pageSize}`);
+}
+
+export type DatabasePath = string | ":memory:";
+
+export interface OpenDatabaseOptions {
+	readonly create?: boolean;
+	readonly readwrite?: boolean;
+	readonly strict?: boolean;
+	readonly loadExtension?: string | readonly string[];
+	readonly pragmas?: boolean;
+	readonly pageSize?: SqlitePageSize;
+}
+
+interface TxState {
+	depth: number;
+}
+
+const TX_STATE = Symbol("mnemopi.txState");
+
+type TxDatabase = Database & { [TX_STATE]?: TxState };
+type ExtensionDatabase = Database & { loadExtension(path: string): void };
+
+export function openDatabase(path: DatabasePath = dbPath(), options: OpenDatabaseOptions = {}): Database {
+	if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+	const db = new Database(path, {
+		create: options.create ?? true,
+		readwrite: options.readwrite ?? true,
+		strict: options.strict ?? true,
+	});
+	if (options.pragmas !== false) enablePragmas(db, path, options.pageSize);
+	else if (options.readwrite !== false) applyPageSize(db, path, options.pageSize);
+	if (options.loadExtension !== undefined) loadExtensions(db, options.loadExtension);
+	return db;
+}
+
+export function enablePragmas(db: Database, path?: DatabasePath, pageSize?: SqlitePageSize): void {
+	db.exec("PRAGMA foreign_keys=ON");
+	db.exec("PRAGMA busy_timeout=5000");
+	if (path !== ":memory:") {
+		applyPageSize(db, path ?? dbPath(), pageSize);
+		db.exec("PRAGMA journal_mode=WAL");
+	}
+}
+
+export function loadExtensions(db: Database, extensions: string | readonly string[]): void {
+	if (typeof extensions === "string") {
+		if (extensions) (db as ExtensionDatabase).loadExtension(extensions);
+		return;
+	}
+	for (const extension of extensions) {
+		if (extension) (db as ExtensionDatabase).loadExtension(extension);
+	}
+}
+
+export function transaction<T>(db: Database, fn: () => T): T {
+	const txDb = db as TxDatabase;
+	let state = txDb[TX_STATE];
+	if (state !== undefined && state.depth > 0) {
+		state.depth++;
+		try {
+			return fn();
+		} finally {
+			state.depth--;
+		}
+	}
+
+	state = { depth: 1 };
+	txDb[TX_STATE] = state;
+	db.exec("BEGIN DEFERRED");
+	try {
+		const result = fn();
+		state.depth = 0;
+		db.exec("COMMIT");
+		return result;
+	} catch (error) {
+		state.depth = 0;
+		try {
+			db.exec("ROLLBACK");
+		} catch {
+			// Preserve the original error; rollback can fail if SQLite already closed the transaction.
+		}
+		throw error;
+	} finally {
+		delete txDb[TX_STATE];
+	}
+}
+
+export const deferredTransaction = transaction;
+
+export async function transactionAsync<T>(db: Database, fn: () => Promise<T>): Promise<T> {
+	const txDb = db as TxDatabase;
+	let state = txDb[TX_STATE];
+	if (state !== undefined && state.depth > 0) {
+		state.depth++;
+		try {
+			return await fn();
+		} finally {
+			state.depth--;
+		}
+	}
+
+	state = { depth: 1 };
+	txDb[TX_STATE] = state;
+	db.exec("BEGIN DEFERRED");
+	try {
+		const result = await fn();
+		state.depth = 0;
+		db.exec("COMMIT");
+		return result;
+	} catch (error) {
+		state.depth = 0;
+		try {
+			db.exec("ROLLBACK");
+		} catch {
+			// Preserve the original error; rollback can fail if SQLite already closed the transaction.
+		}
+		throw error;
+	} finally {
+		delete txDb[TX_STATE];
+	}
+}
+
+export function closeQuietly(db: Database | undefined | null): void {
+	if (db === undefined || db === null) return;
+	try {
+		db.close();
+	} catch {
+		// Best-effort cleanup.
+	}
+}

package/src/diagnose.ts

@@ -0,0 +1,174 @@
+import type { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { dataDir as configuredDataDir, dbPath as configuredDbPath } from "./config";
+import { initBeam } from "./core/beam";
+import { closeQuietly, openDatabase } from "./db";
+
+export interface DiagnosticEntry {
+	readonly ts: string;
+	readonly category: string;
+	readonly check: string;
+	readonly status: string;
+	readonly detail?: string;
+}
+
+export interface DiagnosticSummary {
+	readonly checks_total: number;
+	readonly checks_passed: number;
+	readonly checks_failed: number;
+	readonly key_findings: string[];
+	readonly entries: DiagnosticEntry[];
+	readonly database: string;
+}
+
+export interface DiagnosticOptions {
+	readonly db?: Database;
+	readonly dbPath?: string;
+	readonly dataDir?: string;
+	readonly initialize?: boolean;
+}
+
+type CountRow = { count: number };
+type IntegrityRow = { integrity_check: string };
+type TableRow = { name: string };
+type ColumnRow = { name: string };
+
+const REQUIRED_TABLES = [
+	"working_memory",
+	"episodic_memory",
+	"scratchpad",
+	"fts_working",
+	"fts_episodes",
+	"memoria_facts",
+	"memoria_timelines",
+	"memoria_kg",
+	"memoria_instructions",
+	"memoria_preferences",
+	"consolidation_log",
+	"annotations",
+	"triples",
+] as const;
+
+const REQUIRED_COLUMNS: Readonly<Record<string, readonly string[]>> = {
+	working_memory: ["id", "content", "source", "timestamp", "session_id", "importance"],
+	episodic_memory: ["id", "content", "source", "timestamp", "session_id", "importance"],
+	scratchpad: ["id", "content", "session_id"],
+	triples: ["id", "subject", "predicate", "object"],
+	annotations: ["id", "memory_id", "kind", "value"],
+};
+
+function nowIso(): string {
+	return new Date().toISOString();
+}
+
+function hasTable(db: Database, table: string): boolean {
+	return (
+		(db
+			.query("SELECT name FROM sqlite_master WHERE type IN ('table', 'view') AND name = ? LIMIT 1")
+			.get(table) as TableRow | null) !== null
+	);
+}
+
+function tableColumns(db: Database, table: string): Set<string> {
+	return new Set((db.query(`PRAGMA table_info(${table})`).all() as ColumnRow[]).map(row => row.name));
+}
+
+function safeCount(db: Database, table: string): number | null {
+	if (!hasTable(db, table)) return null;
+	return (db.query(`SELECT COUNT(*) AS count FROM ${table}`).get() as CountRow).count;
+}
+
+function safeEnv(name: string): string {
+	return process.env[name] ? "set" : "unset";
+}
+
+function passStatus(status: string): boolean {
+	return status === "OK" || status === "YES" || status === "set" || status === "0";
+}
+
+function failStatus(status: string): boolean {
+	return status === "MISSING" || status === "NO" || status === "ERROR" || status === "FAIL";
+}
+
+export function inspectDatabase(options: DiagnosticOptions = {}): DiagnosticSummary {
+	const path = options.dbPath ?? configuredDbPath();
+	const entries: DiagnosticEntry[] = [];
+	const log = (category: string, check: string, status: string, detail = ""): void => {
+		entries.push({ ts: nowIso(), category, check, status, detail });
+	};
+
+	log("env", "bun_version", Bun.version);
+	log("env", "platform", `${process.platform}-${process.arch}`);
+	log("env", "MNEMOPI_DATA_DIR", safeEnv("MNEMOPI_DATA_DIR"));
+	log("env", "MNEMOPI_VEC_TYPE", safeEnv("MNEMOPI_VEC_TYPE"));
+	log("db", "db_path", "OK", path);
+	log("db", "data_dir", "OK", options.dataDir ?? configuredDataDir());
+	log("db", "data_dir_parent", existsSync(dirname(path)) ? "OK" : "MISSING", dirname(path));
+
+	let db = options.db;
+	let owned = false;
+	try {
+		if (!db) {
+			db = openDatabase(path);
+			owned = true;
+		}
+		if (options.initialize !== false) initBeam(db);
+
+		const integrity = db.query("PRAGMA integrity_check").get() as IntegrityRow;
+		log("db", "integrity_check", integrity.integrity_check === "ok" ? "OK" : "FAIL", integrity.integrity_check);
+
+		for (const table of REQUIRED_TABLES) {
+			log("schema", `table:${table}`, hasTable(db, table) ? "OK" : "MISSING");
+		}
+		for (const table in REQUIRED_COLUMNS) {
+			if (!hasTable(db, table)) continue;
+			const columns = REQUIRED_COLUMNS[table];
+			if (!columns) continue;
+			const present = tableColumns(db, table);
+			const missing = columns.filter(column => !present.has(column));
+			log(
+				"schema",
+				`columns:${table}`,
+				missing.length === 0 ? "OK" : "MISSING",
+				missing.length === 0 ? `${present.size} columns` : `missing=${missing.join(",")}`,
+			);
+		}
+
+		for (const table of ["working_memory", "episodic_memory", "scratchpad", "triples", "annotations"] as const) {
+			const count = safeCount(db, table);
+			log("db", `${table}_count`, count === null ? "MISSING" : String(count));
+		}
+	} catch (error) {
+		log("db", "open_or_inspect", "ERROR", error instanceof Error ? error.message : String(error));
+	} finally {
+		if (owned) closeQuietly(db);
+	}
+
+	const keyFindings: string[] = [];
+	for (const entry of entries) {
+		if (entry.status === "MISSING") keyFindings.push(`${entry.check} missing`);
+		else if (entry.status === "FAIL" || entry.status === "ERROR") {
+			keyFindings.push(`${entry.check}: ${entry.detail ?? entry.status}`);
+		}
+	}
+
+	return {
+		checks_total: entries.length,
+		checks_passed: entries.filter(entry => passStatus(entry.status) || /^\d+$/.test(entry.status)).length,
+		checks_failed: entries.filter(entry => failStatus(entry.status)).length,
+		key_findings: keyFindings,
+		entries,
+		database: path,
+	};
+}
+
+export function runDiagnostics(options: DiagnosticOptions = {}): DiagnosticSummary {
+	return inspectDatabase(options);
+}
+if (import.meta.main) {
+	const summary = runDiagnostics();
+	console.log(JSON.stringify(summary, null, 2));
+	process.exit(summary.checks_failed === 0 ? 0 : 1);
+}

package/src/dr/index.ts

@@ -0,0 +1 @@
+export * from "./recovery";